@hegemonart/get-design-done 1.41.5 → 1.43.0

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)*
 
 ---
 

package/reference/components/slider.md

@@ -1,4 +1,4 @@
-# Slider — Benchmark Spec
+# Slider - Benchmark Spec
 
 **Harvested from**: WAI-ARIA APG Slider pattern, Material 3, Radix Slider, Carbon Design System
 **Wave**: 5 · **Category**: Advanced
@@ -8,7 +8,7 @@
 
 ## Purpose
 
-A Slider lets users select a numeric value (or range of values) by dragging a thumb along a track. It is appropriate when the range of values is meaningful as a continuum — volume, price, opacity, temperature — and the exact numeric value matters less than relative position. For precise numeric entry, pair the slider with a text input. For a range, use two thumbs. *(Material 3, Carbon, Radix agree: slider = continuous or discrete value selection with visual track.)*
+A Slider lets users select a numeric value (or range of values) by dragging a thumb along a track. It is appropriate when the range of values is meaningful as a continuum - volume, price, opacity, temperature - and the exact numeric value matters less than relative position. For precise numeric entry, pair the slider with a text input. For a range, use two thumbs. *(Material 3, Carbon, Radix agree: slider = continuous or discrete value selection with visual track.)*
 
 ---
 
@@ -56,10 +56,10 @@ Range:
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Track + thumb at resting position | `aria-valuenow` reflects current value |
-| hover | Pointer over thumb | Thumb expands or shows halo | — |
-| focus | Keyboard focus on thumb | Focus-visible ring on thumb | — |
-| dragging / active | Mousedown / touch on thumb | Value tooltip visible; thumb slightly enlarged | — |
+| default | - | Track + thumb at resting position | `aria-valuenow` reflects current value |
+| hover | Pointer over thumb | Thumb expands or shows halo | - |
+| focus | Keyboard focus on thumb | Focus-visible ring on thumb | - |
+| dragging / active | Mousedown / touch on thumb | Value tooltip visible; thumb slightly enlarged | - |
 | disabled | `disabled` / `aria-disabled` | 38% opacity; cursor: not-allowed | `aria-disabled="true"` |
 
 ---
@@ -74,7 +74,7 @@ Range:
 
 **Norm**: 4px track height (Material 3, Carbon). Thumb visual diameter 20px with ::before/::after expanding the touch target to ≥44px without inflating layout.
 
-Cross-link: `reference/surfaces.md` — 44×44px touch-target minimum; use padding trick, not enlarged visual.
+Cross-link: `reference/surfaces.md` - 44×44px touch-target minimum; use padding trick, not enlarged visual.
 
 ---
 
@@ -84,7 +84,7 @@ Cross-link: `reference/surfaces.md` — 44×44px touch-target minimum; use paddi
 - Tick labels: caption-xs, secondary color, centered below tick mark
 - Min/Max endpoint labels: caption-sm, secondary color, flush with track ends
 
-Cross-link: `reference/typography.md` — tabular-nums on value tooltip so digits don't shift width during drag.
+Cross-link: `reference/typography.md` - tabular-nums on value tooltip so digits don't shift width during drag.
 
 ---
 
@@ -95,7 +95,7 @@ Cross-link: `reference/typography.md` — tabular-nums on value tooltip so digit
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/slider/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/slider/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -112,12 +112,12 @@ Cross-link: `reference/typography.md` — tabular-nums on value tooltip so digit
 
 - Every slider thumb MUST have `aria-valuenow`; update it continuously during drag
 - `aria-valuetext` MUST be provided when raw number is not human-readable (e.g., "Low", "Medium", "High" for a quality setting, or "$45" for a price)
-- Range slider: label each thumb distinctly (e.g., `aria-label="Minimum price"` and `aria-label="Maximum price"`) — identical labels confuse screen readers
+- Range slider: label each thumb distinctly (e.g., `aria-label="Minimum price"` and `aria-label="Maximum price"`) - identical labels confuse screen readers
 - Thumb touch target MUST be ≥44×44px; use `::before`/`::after` pseudo-element padding if visual thumb is smaller
-- Do not use `<input type="range">` hidden behind a custom div without ARIA — the native element is preferable when no custom styling is required
+- Do not use `<input type="range">` hidden behind a custom div without ARIA - the native element is preferable when no custom styling is required
 - Disabled sliders: use `aria-disabled="true"`; keep thumb in tab order so AT can announce the current value
 
-Cross-link: `reference/accessibility.md` — slider role, aria-valuetext guidance.
+Cross-link: `reference/accessibility.md` - slider role, aria-valuetext guidance.
 
 ---
 
@@ -125,15 +125,15 @@ Cross-link: `reference/accessibility.md` — slider role, aria-valuetext guidanc
 
 | Transition | Duration | Easing | Notes |
 |------------|----------|--------|-------|
-| Thumb drag | 0ms | — | No easing on drag — follows pointer exactly |
+| Thumb drag | 0ms | - | No easing on drag - follows pointer exactly |
 | Keyboard step | 80ms | ease-out | Smooth snap to new position |
 | Value tooltip appear | 100ms | ease-out | Fade in on focus/drag |
 | Value tooltip dismiss | 150ms | ease-in | Fade out on blur |
 | Tick mark appear | 120ms | ease-out | When switching to discrete mode |
 
-**BAN**: Do not add momentum or inertia easing to thumb drag — feels broken and breaks accessibility (thumb does not match pointer).
+**BAN**: Do not add momentum or inertia easing to thumb drag - feels broken and breaks accessibility (thumb does not match pointer).
 
-Cross-link: `reference/motion.md` — reduced-motion: remove keyboard-step animation; thumb jumps instantly.
+Cross-link: `reference/motion.md` - reduced-motion: remove keyboard-step animation; thumb jumps instantly.
 
 ---
 
@@ -146,9 +146,9 @@ Cross-link: `reference/motion.md` — reduced-motion: remove keyboard-step anima
 - Show tick marks only for discrete sliders with ≤10 steps *(Material 3, Carbon)*
 
 ### Don't
-- Don't build a slider from `<div>` with mouse events only — no keyboard, no ARIA *(diverges from all 4 systems)*
-- Don't omit `aria-valuenow` updates during drag — AT users hear a stale value *(WAI-ARIA APG)*
-- Don't let the visual thumb area be smaller than 12px with no hit-area expansion — fails WCAG 2.5.8 *(Material 3)*
+- Don't build a slider from `<div>` with mouse events only - no keyboard, no ARIA *(diverges from all 4 systems)*
+- Don't omit `aria-valuenow` updates during drag - AT users hear a stale value *(WAI-ARIA APG)*
+- Don't let the visual thumb area be smaller than 12px with no hit-area expansion - fails WCAG 2.5.8 *(Material 3)*
 - Don't use identical `aria-label` for both range thumbs *(WAI-ARIA APG)*
 
 ---
@@ -157,8 +157,8 @@ Cross-link: `reference/motion.md` — reduced-motion: remove keyboard-step anima
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-09 | Custom interactive widget with mouse events only, no keyboard — `reference/anti-patterns.md#ban-09` |
-| BAN-11 | Touch target below 44px without padding expansion — `reference/anti-patterns.md#ban-11` |
+| BAN-09 | Custom interactive widget with mouse events only, no keyboard - `reference/anti-patterns.md#ban-09` |
+| BAN-11 | Touch target below 44px without padding expansion - `reference/anti-patterns.md#ban-11` |
 
 ---