astrolabe/.claude/skills/council/SKILL.md

name, description, disable-model-invocation

name	description	disable-model-invocation
council	Consult the design council — the external interaction, content, and accessibility canon (IBM Carbon, GOV.UK Design System, WAI-ARIA APG, Nielsen Norman) — before committing a user-facing design decision. Auto-invoke when writing user-facing error / empty-state / notification copy, or when designing the keyboard / focus / ARIA behavior of an interactive widget (modal, menu, listbox, toast, splitter, disclosure). Also invokable on demand for any interaction, content, accessibility, or usability decision.	false

Design Council

A standing panel of external design authorities, consulted the way we already consult Carbon: local corpora, grepped — not WebFetched. The council advises; Astrolabe's own contract decides. When a source conflicts with SOUL.md, docs/architecture/09-visual-design.md (visual contract), or docs/architecture/10-interaction-and-feedback.md (interaction contract), our contract wins — note the divergence and move on.

Scope: a steady-state mechanism, with a one-off debt to clear

The council's standing job is pointwise — consult on the decision in front of you (the routing table below), at authoring time. New user-facing work is checked as it's written, so it never accrues the drift the council exists to prevent. This is the default, and what the auto-triggers fire.

The backfill is not a second mode — it's tech debt with an end. Code written before the council existed was never checked against the roster; reconciling it is a one-off sweep (every pre-council widget vs. APG, every user-facing string vs. GOV.UK/Carbon content rules, every data surface vs. the loading/empty/error triad), emitting fixes + a gap list into docs/architecture/10. Done once, pointwise keeps it honest — there is no recurring audit. The only thing that reopens it is an event, never a schedule: seating a new member (its principles have never touched existing code) or a source's breaking revision — see Adding a seat. A light glance at a milestone boundary is a fair safety net for what the heuristic auto-trigger missed, but that's the same one-off sweep, not a standing mode.

How to convene (the routing rule)

Pull the minimal relevant member(s) for the decision at hand — do not sweep all four; that wastes tokens and dilutes the answer. Map the decision to its seat(s):

Decision in front of you	Primary seat → then
Error / failure / empty-state / notification copy	GOV.UK → Carbon notifications → NN/g heuristic #9
Keyboard / focus / ARIA roles of an interactive widget	WAI-ARIA APG → Carbon component
Latency / feedback / loading / progress budgets	NN/g response-time limits → Carbon loading pattern
Forms / validation / destructive-action flow	GOV.UK → Carbon
General usability gut-check on a flow	NN/g 10 heuristics
Visual styling (type, spacing, colour, component look)	Carbon + our docs/architecture/09
Which chart for the data/intent (chart-type choice)	FT Visual Vocabulary + Datawrapper

Then: read the cited file(s), extract the specific principle, and report it back with a citation (member + file path) and a one-line "how it lands in Astrolabe." Don't paraphrase the whole source — quote the rule that decides the question.

The roster

All paths are under /Users/oleh/code/reference/. Treat clones as inspiration, not law — they drift; the published guidance is the truth, the clone is the fast index.

Member	Path	Authoritative for	How to query
IBM Carbon	carbon-website/src/pages/	Notification taxonomy, status levels, empty/loading states, content basics, data-viz styling	grep .mdx under components/notification, patterns/{empty-states,loading,status-indicator}-pattern, guidelines/content
GOV.UK Design System	govuk-design-system/src/	Error & validation messages, failure pages, forms, plain-language content, accessibility	index.md under components/{error-message,error-summary,notification-banner}, patterns/{problem-with-the-service-pages,service-unavailable-pages,check-answers}, accessibility/
WAI-ARIA APG	aria-practices/content/patterns/	Keyboard interaction, focus management, ARIA roles/states for widgets	<pattern>/<pattern>-pattern.html — e.g. dialog-modal, alertdialog, alert, listbox, menu-button, disclosure, switch, tabs, tooltip, windowsplitter
Nielsen Norman (distilled)	principles/nielsen-norman.md	10 usability heuristics; response-time / feedback budgets (0.1s / 1s / 10s)	read directly — it is short and curated
FT Visual Vocabulary	chart-doctor/visual-vocabulary/	Chart choice: data-relationship taxonomy (Magnitude, Correlation, Change-over-Time, Ranking, Distribution, Deviation, Part-to-whole, Spatial, Flow) → chart type	read README.md — the taxonomy is prose; each category gives a "use when…" definition + recommended chart types
Datawrapper (distilled)	principles/datawrapper.md	Chart choice in plain language; practical rules of thumb (bar-is-safe-default, line-vs-column, circles hard to compare, size = quantity)	read directly — short and curated; pairs with the FT clone

Close the loop

The council exists so we don't re-derive the same decision twice. When a consultation settles a recurring question (not a one-off), capture the resolution into our own contract — docs/architecture/10-interaction-and-feedback.md for interaction/feedback, 09-visual-design.md for visual — via the /doc-update skill. Upstream canon informs; the downstream contract records. A code site that embeds such a rule should cite our contract, not the external source.

Adding a seat

1. If it's an open-source repo, shallow-clone it into /Users/oleh/code/reference/ (git clone --depth 1 …). If it's articles/blogs (not cloneable), distill the stable parts into reference/principles/<source>.md with attribution + links, like the NN/g note.
2. Add one row to the roster and one routing entry above.
3. Keep it lean — a seat earns its place only if it's authoritative for a decision the others don't cover well.
4. Backfill once. Reconcile the existing codebase against the new seat — its principles have never been applied before. This is the one event that reopens the one-off sweep (see Scope); after it, pointwise maintains the new seat like the rest.

Candidate future seats (not yet seated): Shopify Polaris (UX-writing depth), web.dev (perceived performance / PWA / offline UX — seat at M6 per the plan).

Seated at M4 (chart choice — our domain): FT Visual Vocabulary (clone) + Datawrapper (distilled). Backfill is scoped to the Chart Builder itself (new surface — no pre-existing chart-choice code to reconcile), so the seating debt is discharged by building the builder against this canon rather than a separate sweep.