@hegemonart/get-design-done 1.42.0 → 1.44.0

package/reference/components/radio.md

@@ -1,4 +1,4 @@
-# Radio — Benchmark Spec
+# Radio - Benchmark Spec
 
 **Harvested from**: Material 3, Carbon, Fluent 2, Mantine, WAI-ARIA APG, Polaris, Ant Design, Chakra UI
 **Wave**: 1 · **Category**: Inputs
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A radio button represents one option within a mutually exclusive group. Selecting one radio button deselects all others in the same group. Always wrap radio buttons in a `<fieldset>` + `<legend>` and group them with the same `name` attribute. Never use a single radio button — it creates an unresettable state. Use a checkbox for binary choices.
+A radio button represents one option within a mutually exclusive group. Selecting one radio button deselects all others in the same group. Always wrap radio buttons in a `<fieldset>` + `<legend>` and group them with the same `name` attribute. Never use a single radio button - it creates an unresettable state. Use a checkbox for binary choices.
 
 ---
 
@@ -44,7 +44,7 @@ A radio button represents one option within a mutually exclusive group. Selectin
 | Button group | Segmented-control appearance | Material 3, Fluent 2, Carbon |
 
 **Norm** (≥6/18): vertical stacking default; horizontal allowed for ≤3 short labels.
-**Diverge**: button-group vs. radio-card — visual styling differs but keyboard contract is identical.
+**Diverge**: button-group vs. radio-card - visual styling differs but keyboard contract is identical.
 
 ---
 
@@ -52,10 +52,10 @@ A radio button represents one option within a mutually exclusive group. Selectin
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| unselected | default | Empty circle | — |
+| unselected | default | Empty circle | - |
 | selected | user interaction / programmatic | Filled dot | `checked` attr |
-| hover | pointer over | Circle border darkens | — |
-| focus | keyboard (Tab into group) | 2px focus ring on currently selected / first | — |
+| hover | pointer over | Circle border darkens | - |
+| focus | keyboard (Tab into group) | 2px focus ring on currently selected / first | - |
 | disabled | `disabled` attr | 38% opacity | `aria-disabled="true"` |
 | error | group-level | Red border on legend/container | `aria-describedby` on `<fieldset>` |
 
@@ -71,14 +71,14 @@ A radio button represents one option within a mutually exclusive group. Selectin
 | Item spacing (vertical) | 8–12px | *(Carbon: 8px, Material 3: 8px)* |
 | Touch target | 44×44px via pseudo-element | `reference/surfaces.md` |
 
-Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern
+Cross-link: `reference/surfaces.md` - hit-area pseudo-element pattern
 
 ---
 
 ## Typography
 
-- Label: 14px/400 — same as body; option is a choice, not a heading
-- Legend: 14px/500 or 12px/600 uppercase — distinct from option labels
+- Label: 14px/400 - same as body; option is a choice, not a heading
+- Legend: 14px/500 or 12px/600 uppercase - distinct from option labels
 - Helper/error: 12px/400
 
 ---
@@ -91,7 +91,7 @@ Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/radio/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/radio/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -105,10 +105,10 @@ Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern
 
 ### Accessibility Rules
 
-- `<fieldset>` + `<legend>` MUST wrap the entire group — legend text is prepended to each option announcement
+- `<fieldset>` + `<legend>` MUST wrap the entire group - legend text is prepended to each option announcement
 - All radios in a group MUST share the same `name` attribute
-- Tab focuses the selected radio (or first, if none selected) — arrow keys navigate within the group
-- Never use a single radio button — it creates a state the user cannot unset; use a checkbox
+- Tab focuses the selected radio (or first, if none selected) - arrow keys navigate within the group
+- Never use a single radio button - it creates a state the user cannot unset; use a checkbox
 - Error state applies to the group: `aria-describedby` on the `<fieldset>` or `role="radiogroup"` container
 - `required`: apply to all radios in the group or use `aria-required` on the group container
 
@@ -122,7 +122,7 @@ Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern
 | Deselect | 80ms | ease | Dot scale 1→0 |
 | Hover border | 80ms | ease | Border colour only |
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip dot animation, show fill instantly
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: skip dot animation, show fill instantly
 
 ---
 
@@ -132,11 +132,11 @@ Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip dot animati
 - Always use `<fieldset>` + `<legend>` for the group *(WAI-ARIA APG, Carbon, Polaris)*
 - Use the same `name` attribute for all radios in a group *(HTML spec, all systems)*
 - Pre-select a default option where appropriate to reduce cognitive load *(Material 3, Polaris)*
-- Use arrow keys to navigate within a group — Tab moves to the group, not each item *(WAI-ARIA APG)*
+- Use arrow keys to navigate within a group - Tab moves to the group, not each item *(WAI-ARIA APG)*
 
 ### Don't
-- Don't use a single radio button — use a checkbox instead *(Material 3, Carbon, WAI-ARIA APG)*
-- Don't use radio buttons for mutually exclusive options that require confirmation — use a select *(Polaris)*
+- Don't use a single radio button - use a checkbox instead *(Material 3, Carbon, WAI-ARIA APG)*
+- Don't use radio buttons for mutually exclusive options that require confirmation - use a select *(Polaris)*
 - Don't mix radio and checkbox styles in the same group *(Carbon, Polaris)*
 - Don't require the user to make a selection before seeing other page content (premature required state) *(Polaris)*
 

package/reference/components/rich-text-editor.md

@@ -1,4 +1,4 @@
-# Rich-Text Editor — Benchmark Spec
+# Rich-Text Editor - Benchmark Spec
 
 **Harvested from**: Tiptap/ProseMirror, Lexical (Meta), Slate.js, Atlassian Fabric Editor
 **Wave**: 5 · **Category**: Advanced
@@ -30,7 +30,7 @@ A Rich-Text Editor (RTE) provides WYSIWYG content authoring with inline formatti
 | Editable area | Yes | `contenteditable="true"` + `role="textbox"` + `aria-multiline="true"` |
 | Toolbar | Yes (for formatting) | `role="toolbar"` + `aria-label`; groups via `role="group"` |
 | Toolbar buttons | Yes | `role="button"`; toggle buttons add `aria-pressed` |
-| Placeholder | No | CSS `[data-placeholder]::before` — NOT HTML attribute |
+| Placeholder | No | CSS `[data-placeholder]::before` - NOT HTML attribute |
 | Mention list | No | `role="listbox"` floating suggestion list triggered by `@` |
 | Character count | No | `aria-live="polite"` updated region |
 | Read-only overlay | No | `contenteditable="false"` + `aria-readonly="true"` |
@@ -56,10 +56,10 @@ A Rich-Text Editor (RTE) provides WYSIWYG content authoring with inline formatti
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Cursor; toolbar buttons at rest | — |
-| focused | Click or Tab into editable area | Focus ring on editable container | — |
+| default | - | Cursor; toolbar buttons at rest | - |
+| focused | Click or Tab into editable area | Focus ring on editable container | - |
 | toolbar button active | Text with formatting selected | `aria-pressed="true"` on toggle button | `aria-pressed="true"` |
-| placeholder | No content in editable area | Placeholder text via CSS ::before | — |
+| placeholder | No content in editable area | Placeholder text via CSS ::before | - |
 | read-only | `readOnly` prop | No cursor change; grayed toolbar | `aria-readonly="true"`, `contenteditable="false"` |
 | disabled | `disabled` prop | 38% opacity; no interaction | `aria-disabled="true"` |
 | mention-open | `@` typed | Floating listbox appears | `role="listbox"` visible |
@@ -77,18 +77,18 @@ A Rich-Text Editor (RTE) provides WYSIWYG content authoring with inline formatti
 
 **Norm**: Editor area grows with content (auto-height); enforce max-height with overflow scroll if needed. Toolbar buttons follow button-sm/md sizing with 8px gaps between groups *(Atlassian, Tiptap)*.
 
-Cross-link: `reference/surfaces.md` — toolbar button hit targets.
+Cross-link: `reference/surfaces.md` - toolbar button hit targets.
 
 ---
 
 ## Typography
 
 - Editor content: body-md, line-height 1.6 for readable long-form text
-- Heading 1: 2em; Heading 2: 1.5em; Heading 3: 1.25em — relative to editor base font
+- Heading 1: 2em; Heading 2: 1.5em; Heading 3: 1.25em - relative to editor base font
 - Code blocks: monospace, 0.9em, background token surface-code
 - Placeholder text: same size/font as body, secondary color via CSS
 
-Cross-link: `reference/typography.md` — heading scale, code font stack.
+Cross-link: `reference/typography.md` - heading scale, code font stack.
 
 ---
 
@@ -99,7 +99,7 @@ Cross-link: `reference/typography.md` — heading scale, code font stack.
 
 ### Keyboard Contract
 
-*Derived from WAI-ARIA APG toolbar pattern — https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/ — W3C — 2024, and standard contenteditable browser behavior*
+*Derived from WAI-ARIA APG toolbar pattern - https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/ - W3C - 2024, and standard contenteditable browser behavior*
 
 | Key | Action |
 |-----|--------|
@@ -120,15 +120,15 @@ Cross-link: `reference/typography.md` — heading scale, code font stack.
 
 ### Accessibility Rules
 
-- Editable area MUST have `role="textbox"` — bare `contenteditable` is announced as a generic region by most AT
-- `aria-multiline="true"` MUST be set — announces correct Enter-key behavior to screen readers
+- Editable area MUST have `role="textbox"` - bare `contenteditable` is announced as a generic region by most AT
+- `aria-multiline="true"` MUST be set - announces correct Enter-key behavior to screen readers
 - Toolbar toggle buttons (bold, italic, lists) MUST use `aria-pressed="true/false"` to reflect current selection state
-- Placeholder MUST use CSS `[data-placeholder]::before` content — not a `placeholder` HTML attribute on contenteditable (screen readers read it incorrectly or not at all)
-- Keyboard shortcuts MUST be documented in a tooltip or help section — not assumed
-- Read-only: set both `contenteditable="false"` AND `aria-readonly="true"` — contenteditable="false" alone is insufficient for AT
+- Placeholder MUST use CSS `[data-placeholder]::before` content - not a `placeholder` HTML attribute on contenteditable (screen readers read it incorrectly or not at all)
+- Keyboard shortcuts MUST be documented in a tooltip or help section - not assumed
+- Read-only: set both `contenteditable="false"` AND `aria-readonly="true"` - contenteditable="false" alone is insufficient for AT
 - Mention listbox MUST use `role="listbox"` with `role="option"` items; focused option uses `aria-selected="true"`
 
-Cross-link: `reference/accessibility.md` — contenteditable accessibility, toolbar pattern.
+Cross-link: `reference/accessibility.md` - contenteditable accessibility, toolbar pattern.
 
 ---
 
@@ -142,9 +142,9 @@ Cross-link: `reference/accessibility.md` — contenteditable accessibility, tool
 | Bubble toolbar appear | 150ms | ease-out | Fade in above selection |
 | Bubble toolbar dismiss | 80ms | ease-in | Fade out on deselect |
 
-**BAN**: Do not animate text reflow on formatting changes — typing performance is critical; any CSS transition on editor content causes visual jitter.
+**BAN**: Do not animate text reflow on formatting changes - typing performance is critical; any CSS transition on editor content causes visual jitter.
 
-Cross-link: `reference/motion.md` — reduced-motion: remove mention list slide; keep instant formatting toggle.
+Cross-link: `reference/motion.md` - reduced-motion: remove mention list slide; keep instant formatting toggle.
 
 ---
 
@@ -157,9 +157,9 @@ Cross-link: `reference/motion.md` — reduced-motion: remove mention list slide;
 - Document keyboard shortcuts in a tooltip or accessible help dialog *(Atlassian Fabric Editor)*
 
 ### Don't
-- Don't use bare `contenteditable` without `role="textbox"` — AT announces it as a generic landmark *(diverges from all 4 systems)*
-- Don't omit `aria-pressed` on toggle buttons — AT users cannot determine current formatting state *(WAI-ARIA APG)*
-- Don't use a `placeholder` HTML attribute on contenteditable — it is not a valid attribute and screen reader behavior is undefined *(MDN, Tiptap docs)*
+- Don't use bare `contenteditable` without `role="textbox"` - AT announces it as a generic landmark *(diverges from all 4 systems)*
+- Don't omit `aria-pressed` on toggle buttons - AT users cannot determine current formatting state *(WAI-ARIA APG)*
+- Don't use a `placeholder` HTML attribute on contenteditable - it is not a valid attribute and screen reader behavior is undefined *(MDN, Tiptap docs)*
 - Don't suppress `outline` on the editable area without a custom focus-visible ring *(WCAG 2.4.7)*
 
 ---
@@ -168,8 +168,8 @@ Cross-link: `reference/motion.md` — reduced-motion: remove mention list slide;
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-06 | contenteditable without role="textbox" — `reference/anti-patterns.md#ban-06` |
-| BAN-04 | transition: all on editor content causing reflow jank — `reference/anti-patterns.md#ban-04` |
+| BAN-06 | contenteditable without role="textbox" - `reference/anti-patterns.md#ban-06` |
+| BAN-04 | transition: all on editor content causing reflow jank - `reference/anti-patterns.md#ban-04` |
 
 ---
 
@@ -181,7 +181,7 @@ Cross-link: `reference/motion.md` — reduced-motion: remove mention list slide;
 | Toolbar toggle buttons need aria-pressed | WAI-ARIA APG toolbar pattern |
 | Placeholder via CSS ::before, not HTML attribute | Tiptap docs, Atlassian Fabric Editor |
 | Mention list uses role="listbox" + role="option" | Tiptap mention extension, Lexical mention plugin |
-| Ctrl/Cmd+B/I/U keyboard shortcuts are standard | Lexical, Tiptap, Slate — all implement these |
+| Ctrl/Cmd+B/I/U keyboard shortcuts are standard | Lexical, Tiptap, Slate - all implement these |
 
 Full system URLs: `connections/design-corpora.md`
 
@@ -221,6 +221,6 @@ grep -rn 'mention\|@mention\|MentionList' src/ | grep -v 'role="listbox"'
 </div>
 ```
 
-**Why it fails**: (1) Bare `contenteditable` is announced by most AT as a generic region, not a text input — users do not know they can type. (2) `placeholder` is not a valid HTML attribute on `<div>` — screen readers do not announce it. (3) Toolbar buttons have no `aria-pressed` — AT cannot determine if bold/italic is currently active. (4) `document.execCommand` is deprecated.
+**Why it fails**: (1) Bare `contenteditable` is announced by most AT as a generic region, not a text input - users do not know they can type. (2) `placeholder` is not a valid HTML attribute on `<div>` - screen readers do not announce it. (3) Toolbar buttons have no `aria-pressed` - AT cannot determine if bold/italic is currently active. (4) `document.execCommand` is deprecated.
 **Grep detection**: `grep -rn 'contenteditable="true"' src/ | grep -v 'role="textbox"'`
 **Fix**: Add `role="textbox"` + `aria-multiline="true"` + `aria-label="Post body"` to the editable div; implement placeholder via CSS `[data-empty]::before { content: attr(data-placeholder) }`; add `aria-pressed="true/false"` to toolbar toggle buttons; use a modern editor library (Tiptap, Lexical) instead of execCommand.

package/reference/components/select-combobox.md

@@ -1,4 +1,4 @@
-# Select / Combobox — Benchmark Spec
+# Select / Combobox - Benchmark Spec
 
 **Harvested from**: Radix UI, WAI-ARIA APG, Carbon, Headless UI, Mantine, Material 3, Ant Design, shadcn/ui
 **Wave**: 1 · **Category**: Inputs
@@ -44,14 +44,14 @@ Label *
 
 | Variant | Description | Systems |
 |---------|-------------|---------|
-| Native select | `<select>` — minimal, accessible, no custom styling | All (as baseline) |
+| Native select | `<select>` - minimal, accessible, no custom styling | All (as baseline) |
 | Custom select | Styled trigger + listbox; no filter | Radix, Carbon, shadcn |
 | Combobox | Trigger + text filter + listbox | Radix, Mantine, Headless UI, Ant |
 | Multi-select | Multiple `aria-selected="true"` options; tag display | Mantine, Ant, Carbon |
 | Async / searchable | Options loaded on query; loading state in listbox | Mantine, Ant, shadcn |
 
 **Norm** (≥5/18): custom select must replicate native keyboard behavior exactly.
-**Diverge**: tag vs. chip display for multi-select — Mantine uses tags, Ant uses chips, Carbon uses checkboxes in dropdown. Checkbox approach is most accessible (state is visible without removing focus from listbox).
+**Diverge**: tag vs. chip display for multi-select - Mantine uses tags, Ant uses chips, Carbon uses checkboxes in dropdown. Checkbox approach is most accessible (state is visible without removing focus from listbox).
 
 ---
 
@@ -59,7 +59,7 @@ Label *
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Resting trigger | `aria-expanded="false"` |
+| default | - | Resting trigger | `aria-expanded="false"` |
 | open | trigger activated | Dropdown visible | `aria-expanded="true"` |
 | option hovered | pointer | Option highlighted | `aria-activedescendant` updated |
 | option selected | Enter / click | Checkmark or filled circle | `aria-selected="true"` |
@@ -78,7 +78,7 @@ Label *
 | md (default) | 40px | 36px | 16px |
 | lg | 48px | 44px | 16px |
 
-Max dropdown height: 240px with internal scroll — prevents viewport overflow without pagination.
+Max dropdown height: 240px with internal scroll - prevents viewport overflow without pagination.
 Option min-height: 36px (md) for touch targets *(Material 3, Polaris)*
 
 ---
@@ -87,7 +87,7 @@ Option min-height: 36px (md) for touch targets *(Material 3, Polaris)*
 
 - Trigger value: same weight/size as input (14px/400)
 - Option text: 14px/400; selected option: 14px/500
-- Group label: 11px/600 uppercase, muted colour — not an option, not focusable
+- Group label: 11px/600 uppercase, muted colour - not an option, not focusable
 
 ---
 
@@ -96,9 +96,9 @@ Option min-height: 36px (md) for touch targets *(Material 3, Polaris)*
 > **WAI-ARIA role**: `combobox` on trigger (select pattern); `listbox` on dropdown; `option` on items
 > **Required attributes**: `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls` (trigger→listbox), `aria-activedescendant` (updated on option focus)
 
-### Keyboard Contract — Select (Listbox Pattern)
+### Keyboard Contract - Select (Listbox Pattern)
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/listbox/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/listbox/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -112,9 +112,9 @@ Option min-height: 36px (md) for touch targets *(Material 3, Polaris)*
 | Tab | Closes listbox; moves focus to next element |
 | Printable character | (Type-ahead) Moves focus to next option starting with typed character |
 
-### Keyboard Contract — Combobox
+### Keyboard Contract - Combobox
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/combobox/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/combobox/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -128,7 +128,7 @@ Option min-height: 36px (md) for touch targets *(Material 3, Polaris)*
 
 ### Accessibility Rules
 
-- `aria-activedescendant` on trigger MUST update as options are highlighted — screen readers follow this, not DOM focus
+- `aria-activedescendant` on trigger MUST update as options are highlighted - screen readers follow this, not DOM focus
 - Options must have unique `id` attributes (for `aria-activedescendant` reference)
 - Grouping: `role="group"` with `aria-label` wrapping grouped `role="option"` items
 - Empty state: announce via `aria-live="polite"` region when filter returns no results
@@ -144,7 +144,7 @@ Option min-height: 36px (md) for touch targets *(Material 3, Polaris)*
 | Dropdown close | 80ms | ease-in | Fade only |
 | Option highlight | 60ms | ease | Background colour only |
 
-Cross-link: `reference/motion.md` — `AnimatePresence` pattern for mount/unmount
+Cross-link: `reference/motion.md` - `AnimatePresence` pattern for mount/unmount
 
 ---
 
@@ -157,9 +157,9 @@ Cross-link: `reference/motion.md` — `AnimatePresence` pattern for mount/unmoun
 - Limit dropdown height to ~6–8 options; add scroll for more *(Carbon, Material 3)*
 
 ### Don't
-- Don't close the dropdown on every keystroke in combobox mode — only on selection or Escape *(WAI-ARIA APG)*
-- Don't use a select for navigation — use a nav + router *(Carbon, Primer)*
-- Don't disable scroll inside the listbox — virtualise instead for large lists *(Mantine, Ant)*
+- Don't close the dropdown on every keystroke in combobox mode - only on selection or Escape *(WAI-ARIA APG)*
+- Don't use a select for navigation - use a nav + router *(Carbon, Primer)*
+- Don't disable scroll inside the listbox - virtualise instead for large lists *(Mantine, Ant)*
 - Don't place interactive elements (links, buttons) inside `role="option"` *(WAI-ARIA APG)*
 
 ---
@@ -168,7 +168,7 @@ Cross-link: `reference/motion.md` — `AnimatePresence` pattern for mount/unmoun
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| Custom select without ARIA | `reference/anti-patterns.md` — ARIA role omission pattern |
+| Custom select without ARIA | `reference/anti-patterns.md` - ARIA role omission pattern |
 
 ---
 

package/reference/components/sidebar.md

@@ -1,4 +1,4 @@
-# Sidebar (Collapsible Side Navigation Panel) — Benchmark Spec
+# Sidebar (Collapsible Side Navigation Panel) - Benchmark Spec
 
 **Harvested from**: Material 3, Carbon, Polaris, Atlassian, UUPM (app-interface, MIT)
 **Wave**: 4 · **Category**: Navigation
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A sidebar provides persistent or collapsible secondary navigation along the vertical axis of an application. In expanded state it shows icon + label; in collapsed state it shows icon only (with a tooltip). It is distinct from a Drawer (which is a modal overlay — see `drawer.md`) and from a Navbar (primary horizontal navigation). Use a sidebar for application-level section switching and hierarchical settings navigation. *(Material 3 Navigation Drawer, Carbon UI Shell Left Nav, Atlassian SideNavigation, Polaris Navigation agree)*
+A sidebar provides persistent or collapsible secondary navigation along the vertical axis of an application. In expanded state it shows icon + label; in collapsed state it shows icon only (with a tooltip). It is distinct from a Drawer (which is a modal overlay - see `drawer.md`) and from a Navbar (primary horizontal navigation). Use a sidebar for application-level section switching and hierarchical settings navigation. *(Material 3 Navigation Drawer, Carbon UI Shell Left Nav, Atlassian SideNavigation, Polaris Navigation agree)*
 
 ---
 
@@ -59,9 +59,9 @@ A sidebar provides persistent or collapsible secondary navigation along the vert
 |-------|---------|--------|------|
 | expanded | default or toggle | Full width, labels visible | `aria-expanded="true"` on toggle |
 | collapsed | toggle click | Icon-only, labels hidden | `aria-expanded="false"` on toggle |
-| item-default | — | Resting fill | — |
-| item-hover | pointer over | 8% overlay | — |
-| item-focus | keyboard focus | 2px focus-visible ring | — |
+| item-default | - | Resting fill | - |
+| item-hover | pointer over | 8% overlay | - |
+| item-focus | keyboard focus | 2px focus-visible ring | - |
 | item-active | current route | Filled pill or left indicator bar | `aria-current="page"` |
 | subsection-open | button click | Children visible; chevron rotated 180° | `aria-expanded="true"` on section button |
 | subsection-closed | button click | Children hidden | `aria-expanded="false"` on section button |
@@ -74,7 +74,7 @@ A sidebar provides persistent or collapsible secondary navigation along the vert
 |-------|-------|-------------|----------------|
 | Expanded | 240–280px | 40px | 16px |
 | Collapsed | 48–64px | 40px | 12px (centered icon) |
-| Sub-item indent | — | 36px | 32px (16px base + 16px indent) |
+| Sub-item indent | - | 36px | 32px (16px base + 16px indent) |
 
 **Norm**: 240px expanded width (Carbon, Atlassian, Polaris). 40px item height matches button defaults.
 
@@ -84,10 +84,10 @@ A sidebar provides persistent or collapsible secondary navigation along the vert
 
 - Nav item label: body-sm (13–14px), weight 400; active item weight 500 or 600
 - Sub-section heading (if present): label-xs (11–12px), uppercase, weight 600, `color: --text-subtle`
-- Tooltip: body-xs (11–12px) — concise, matches item label exactly in collapsed state
-- Never truncate nav item labels — resize the sidebar or abbreviate the label intentionally
+- Tooltip: body-xs (11–12px) - concise, matches item label exactly in collapsed state
+- Never truncate nav item labels - resize the sidebar or abbreviate the label intentionally
 
-Cross-link: `reference/typography.md` — label scale, body-sm
+Cross-link: `reference/typography.md` - label scale, body-sm
 
 ---
 
@@ -98,7 +98,7 @@ Cross-link: `reference/typography.md` — label scale, body-sm
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -116,7 +116,7 @@ Cross-link: `reference/typography.md` — label scale, body-sm
 - In collapsed state, each icon-only item MUST have a tooltip AND `aria-label` (tooltip is not a substitute for accessible name)
 - `aria-current="page"` MUST be present on the currently active item
 
-Cross-link: `reference/accessibility.md` — landmark labelling, disclosure pattern
+Cross-link: `reference/accessibility.md` - landmark labelling, disclosure pattern
 
 ---
 
@@ -130,9 +130,9 @@ Cross-link: `reference/accessibility.md` — landmark labelling, disclosure patt
 | Chevron rotate | 150ms | ease-in-out | 0° → 180° on open |
 | Label fade in | 100ms | ease-out | Delay until width ≥ 140px to prevent overlap |
 
-**BAN**: Animating sidebar width using `transition: all` — catches unrelated property changes and causes jank.
+**BAN**: Animating sidebar width using `transition: all` - catches unrelated property changes and causes jank.
 
-Cross-link: `reference/motion.md` — layout transitions, BAN-04
+Cross-link: `reference/motion.md` - layout transitions, BAN-04
 
 ---
 
@@ -145,7 +145,7 @@ Cross-link: `reference/motion.md` — layout transitions, BAN-04
 - Use `aria-expanded` on sub-section toggles *(WAI-ARIA APG disclosure pattern)*
 
 ### Don't
-- Don't use `<a href="#">` for items that don't navigate — breaks bookmark/open-in-new-tab expectations *(Carbon, WAI-ARIA)*
+- Don't use `<a href="#">` for items that don't navigate - breaks bookmark/open-in-new-tab expectations *(Carbon, WAI-ARIA)*
 - Don't hide sub-items with `display: none` without also removing them from tab order *(WCAG 2.1.1)*
 - Don't use the same `aria-label` on both sidebar nav and top navbar *(WAI-ARIA landmark uniqueness)*
 - Don't collapse the sidebar below 44px touch target width on mobile *(WCAG 2.5.5)*
@@ -156,7 +156,7 @@ Cross-link: `reference/motion.md` — layout transitions, BAN-04
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-04 | `transition: all` on interactive elements — `reference/anti-patterns.md#ban-04` |
+| BAN-04 | `transition: all` on interactive elements - `reference/anti-patterns.md#ban-04` |
 
 ---
 

package/reference/components/skeleton.md

@@ -1,4 +1,4 @@
-# Skeleton — Benchmark Spec
+# Skeleton - Benchmark Spec
 
 **Harvested from**: Polaris, Carbon, Atlassian, Mantine
 **Wave**: 3 · **Category**: Feedback
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A skeleton screen is a loading placeholder that mirrors the shape of the content it will replace — text lines, images, cards, avatars. It reduces perceived wait time by showing the structural layout before real data arrives, preventing the jarring reflow that occurs when content suddenly appears. Use skeleton when the content shape is known; use an indeterminate spinner or progress bar when shape is unknown. *(Polaris, Carbon, Atlassian, Mantine agree: skeleton = shape-matched placeholder, not generic spinner)*
+A skeleton screen is a loading placeholder that mirrors the shape of the content it will replace - text lines, images, cards, avatars. It reduces perceived wait time by showing the structural layout before real data arrives, preventing the jarring reflow that occurs when content suddenly appears. Use skeleton when the content shape is known; use an indeterminate spinner or progress bar when shape is unknown. *(Polaris, Carbon, Atlassian, Mantine agree: skeleton = shape-matched placeholder, not generic spinner)*
 
 ---
 
@@ -67,18 +67,18 @@ A skeleton screen is a loading placeholder that mirrors the shape of the content
 | Image block | Match target image aspect ratio | 16:9, 1:1, 4:3 common |
 | Gap between text lines | 8px | Matches body line-height rhythm |
 
-**Norm**: Match exact pixel dimensions of the content being replaced — layout shift score is zero when skeleton matches final content size *(Polaris, Mantine)*.
+**Norm**: Match exact pixel dimensions of the content being replaced - layout shift score is zero when skeleton matches final content size *(Polaris, Mantine)*.
 
 ---
 
 ## Typography
 
-Skeleton shapes are purely visual — no typography content. However:
+Skeleton shapes are purely visual - no typography content. However:
 - Text-line height should match the `line-height` of the real text it replaces
 - Heading skeleton height should match the heading's `font-size` + leading
-- Do NOT use placeholder text ("Loading…") inside skeleton shapes — use `aria-label` on the container instead
+- Do NOT use placeholder text ("Loading…") inside skeleton shapes - use `aria-label` on the container instead
 
-Cross-link: `reference/typography.md` — line-height scale for matching skeleton dimensions
+Cross-link: `reference/typography.md` - line-height scale for matching skeleton dimensions
 
 ---
 
@@ -89,7 +89,7 @@ Cross-link: `reference/typography.md` — line-height scale for matching skeleto
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -99,13 +99,13 @@ Skeleton elements must not receive focus. The container is not focusable unless
 
 ### Accessibility Rules
 
-- Every skeleton shape element MUST have `aria-hidden="true"` — blank shapes announced by screen readers ("image", "text") confuse users *(Polaris, Carbon)*
+- Every skeleton shape element MUST have `aria-hidden="true"` - blank shapes announced by screen readers ("image", "text") confuse users *(Polaris, Carbon)*
 - The container MUST have `aria-busy="true"` while loading, set to `false` (or removed) when content appears *(WAI-ARIA APG)*
-- The container MUST have `aria-label="Loading…"` or equivalent — this is what screen readers announce while `aria-busy="true"` *(WAI-ARIA APG)*
-- Do NOT use skeleton as the only loading indicator for screen reader users — announce loading state via live region if the transition is programmatic *(Carbon)*
-- Shimmer animation MUST be suppressed under `prefers-reduced-motion` — use static fill instead *(WCAG 2.3.3)*
+- The container MUST have `aria-label="Loading…"` or equivalent - this is what screen readers announce while `aria-busy="true"` *(WAI-ARIA APG)*
+- Do NOT use skeleton as the only loading indicator for screen reader users - announce loading state via live region if the transition is programmatic *(Carbon)*
+- Shimmer animation MUST be suppressed under `prefers-reduced-motion` - use static fill instead *(WCAG 2.3.3)*
 
-Cross-link: `reference/accessibility.md` — `aria-busy`, `prefers-reduced-motion`
+Cross-link: `reference/accessibility.md` - `aria-busy`, `prefers-reduced-motion`
 
 ---
 
@@ -114,15 +114,15 @@ Cross-link: `reference/accessibility.md` — `aria-busy`, `prefers-reduced-motio
 | Transition | Duration | Easing | Notes |
 |------------|----------|--------|-------|
 | Shimmer sweep | 1.5s | ease-in-out | 130° gradient: transparent → surface-highlight → transparent |
-| Loop delay | 0.5s | — | Pause between sweeps to avoid strobing |
+| Loop delay | 0.5s | - | Pause between sweeps to avoid strobing |
 | Skeleton → content | 200ms | ease-out | Fade-in real content over skeleton |
 
-Shimmer gradient direction: 130 degrees (roughly top-left to bottom-right) — matches natural reading direction.
+Shimmer gradient direction: 130 degrees (roughly top-left to bottom-right) - matches natural reading direction.
 Background: `surface-variant` token (slightly darker than background surface, lighter than border).
 
-**BAN**: High-contrast shimmer (e.g. white → gray on dark) — too visually noisy. Do NOT use spinner animation inside a skeleton shape. Under `prefers-reduced-motion`, remove the sweep entirely and use static fill.
+**BAN**: High-contrast shimmer (e.g. white → gray on dark) - too visually noisy. Do NOT use spinner animation inside a skeleton shape. Under `prefers-reduced-motion`, remove the sweep entirely and use static fill.
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: static fill, no gradient sweep
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: static fill, no gradient sweep
 
 ---
 
@@ -135,10 +135,10 @@ Cross-link: `reference/motion.md` — `prefers-reduced-motion`: static fill, no
 - Set `aria-busy="true"` + `aria-label="Loading…"` on the container *(WAI-ARIA APG)*
 
 ### Don't
-- Don't use a spinner when content shape is known — skeleton is always preferred for layout-bearing slots *(Carbon, Polaris)*
-- Don't use strong contrast for shimmer — use `surface-variant` (low contrast) *(Atlassian, Mantine)*
-- Don't animate shimmer under `prefers-reduced-motion` — use static fill *(WCAG 2.3.3)*
-- Don't add visible "Loading…" text inside skeleton shapes — put it on the container via `aria-label` *(Carbon)*
+- Don't use a spinner when content shape is known - skeleton is always preferred for layout-bearing slots *(Carbon, Polaris)*
+- Don't use strong contrast for shimmer - use `surface-variant` (low contrast) *(Atlassian, Mantine)*
+- Don't animate shimmer under `prefers-reduced-motion` - use static fill *(WCAG 2.3.3)*
+- Don't add visible "Loading…" text inside skeleton shapes - put it on the container via `aria-label` *(Carbon)*
 
 ---