@hegemonart/get-design-done 1.42.0 → 1.44.0

package/reference/components/card.md

@@ -1,4 +1,4 @@
-# Card — Benchmark Spec
+# Card - Benchmark Spec
 
 **Harvested from**: Material 3, Polaris, Carbon, Atlassian, Mantine, shadcn/ui, Ant Design, Fluent 2
 **Wave**: 2 · **Category**: Containers
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A card is a contained surface that groups related information and actions. It is a visual container, not a navigation element by default — only make the entire card clickable when the primary action is navigation and there is a single dominant action. Mixed-content cards with multiple actions should not be entirely clickable. *(Material 3, Polaris, Carbon all agree on this boundary)*
+A card is a contained surface that groups related information and actions. It is a visual container, not a navigation element by default - only make the entire card clickable when the primary action is navigation and there is a single dominant action. Mixed-content cards with multiple actions should not be entirely clickable. *(Material 3, Polaris, Carbon all agree on this boundary)*
 
 ---
 
@@ -48,7 +48,7 @@ A card is a contained surface that groups related information and actions. It is
 | Compact | Dense layout; no media | Carbon, Fluent |
 
 **Norm** (≥5/18): outlined or elevated; ≤2 actions per card.
-**Diverge**: elevation vs. outline — both are valid; use elevated for content that needs to float (dashboards), outlined for dense lists (tables of cards).
+**Diverge**: elevation vs. outline - both are valid; use elevated for content that needs to float (dashboards), outlined for dense lists (tables of cards).
 
 ---
 
@@ -56,10 +56,10 @@ A card is a contained surface that groups related information and actions. It is
 
 | State | Trigger | Visual | ARIA/HTML |
 |-------|---------|--------|-----------|
-| default | — | Resting surface | — |
-| hover (clickable) | pointer | Shadow deepens or border darkens | — |
-| focus (clickable) | keyboard | 2px focus ring on outer card | — |
-| active (clickable) | mousedown | Scale 0.99 | — |
+| default | - | Resting surface | - |
+| hover (clickable) | pointer | Shadow deepens or border darkens | - |
+| focus (clickable) | keyboard | 2px focus ring on outer card | - |
+| active (clickable) | mousedown | Scale 0.99 | - |
 | selected | programmatic | Border + background tint | `aria-selected="true"` |
 | loading | async content | Skeleton placeholder | `aria-busy="true"` |
 | disabled | programmatic | 38% opacity | `aria-disabled="true"` |
@@ -77,7 +77,7 @@ A card is a contained surface that groups related information and actions. It is
 | Max width | 480px (typical) | Grid controls actual width; max-width is a guideline |
 | Gap between cards | 16px (sm grid), 24px (md grid) | |
 
-Cross-link: `reference/surfaces.md` — concentric radius, 3-layer shadow formula, elevation tokens
+Cross-link: `reference/surfaces.md` - concentric radius, 3-layer shadow formula, elevation tokens
 
 ---
 
@@ -96,14 +96,14 @@ Cross-link: `reference/surfaces.md` — concentric radius, 3-layer shadow formul
 
 ### Clickable Card Rules
 
-*Per WAI-ARIA APG link + button patterns — W3C — 2024*
+*Per WAI-ARIA APG link + button patterns - W3C - 2024*
 
 | Invocation | Element | Key |
 |------------|---------|-----|
 | Navigate to new page | `<a href>` wrapping or inside card | Enter |
 | Trigger action in context | `<button>` wrapping or inside card | Enter, Space |
 
-- **Do not wrap an entire card in `<a>` if it contains other interactive elements** (links, buttons inside) — nested interactive elements are inaccessible by keyboard
+- **Do not wrap an entire card in `<a>` if it contains other interactive elements** (links, buttons inside) - nested interactive elements are inaccessible by keyboard
 - Use the "card with primary action + secondary actions" pattern: one `<a>` stretched via `::after` pseudo-element to fill the card; secondary action buttons sit above in stacking context
 
 ### Accessibility Rules
@@ -123,7 +123,7 @@ Cross-link: `reference/surfaces.md` — concentric radius, 3-layer shadow formul
 | press scale | 80ms | ease | 1→0.99 (subtle; card is large) |
 | skeleton shimmer | 1.5s | linear loop | Respect `prefers-reduced-motion` |
 
-Cross-link: `reference/motion.md` — Skeleton shimmer pattern, `prefers-reduced-motion`
+Cross-link: `reference/motion.md` - Skeleton shimmer pattern, `prefers-reduced-motion`
 
 ---
 
@@ -139,7 +139,7 @@ Cross-link: `reference/motion.md` — Skeleton shimmer pattern, `prefers-reduced
 - Don't wrap the entire card in `<a>` if it contains other interactive elements *(WAI-ARIA APG)*
 - Don't use `<div>` as a clickable card without `role="button"` or `role="link"` + keyboard handler *(WAI-ARIA APG)*
 - Don't place the entire card title in a plain `<span>` when it could be `<h2>/<h3>` *(Atlassian, Carbon)*
-- Don't use more than 2 primary actions per card — extract to a detail view *(Material 3, Polaris)*
+- Don't use more than 2 primary actions per card - extract to a detail view *(Material 3, Polaris)*
 
 ---
 
@@ -197,4 +197,4 @@ grep -rn 'class.*card' src/ | xargs grep -L 'h[1-6]\|aria-label' 2>/dev/null
 
 **Why it fails**: Nested `<button>` inside `<a>` is invalid HTML. Keyboard users pressing Tab inside the link may reach the button, but Enter on the button may also trigger the link. Screen reader behavior is unpredictable.
 **Grep detection**: `grep -rn '<a.*href' src/ | xargs grep -l '<button' 2>/dev/null`
-**Fix**: Use the stretched-link pattern — `<h3><a href="/product/42">Product Name</a></h3>` with `::after { position: absolute; inset: 0; }` on the `<a>`, and position the "Add to cart" button above via `position: relative; z-index: 1`.
+**Fix**: Use the stretched-link pattern - `<h3><a href="/product/42">Product Name</a></h3>` with `::after { position: absolute; inset: 0; }` on the `<a>`, and position the "Add to cart" button above via `position: relative; z-index: 1`.

package/reference/components/checkbox.md

@@ -1,4 +1,4 @@
-# Checkbox — Benchmark Spec
+# Checkbox - Benchmark Spec
 
 **Harvested from**: Material 3, Carbon, Polaris, Ant Design, WAI-ARIA APG, Mantine, Chakra UI, Atlassian
 **Wave**: 1 · **Category**: Inputs
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A checkbox allows the user to select or deselect a binary option, or to represent an indeterminate state (partially selected group). Checkboxes are independent — selecting one does not affect others. Use radio buttons for mutually exclusive choices within a group. Always group related checkboxes in a `<fieldset>` with a `<legend>`.
+A checkbox allows the user to select or deselect a binary option, or to represent an indeterminate state (partially selected group). Checkboxes are independent - selecting one does not affect others. Use radio buttons for mutually exclusive choices within a group. Always group related checkboxes in a `<fieldset>` with a `<legend>`.
 
 ---
 
@@ -31,7 +31,7 @@ Group:
 | Part | Required | Notes |
 |------|----------|-------|
 | Input / control | Yes | Native `<input type="checkbox">` preferred |
-| Label | Yes | `<label for="id">` — click zone includes label text |
+| Label | Yes | `<label for="id">` - click zone includes label text |
 | Fieldset + legend | Yes (group) | Required when ≥2 related checkboxes |
 | Helper text | No | Below label; `aria-describedby` |
 | Error message | Conditional | Field-level or group-level |
@@ -49,8 +49,8 @@ Group:
 | Group | ≥2 checkboxes in `<fieldset>` | All |
 | With description | Label + helper text below | Material 3, Polaris, Carbon |
 
-**Norm** (≥6/18): indeterminate state is a visual-only UI state — the underlying `checked` value is still boolean; set via DOM `.indeterminate` property, not HTML attribute.
-**Diverge**: size — Material 3 uses 18px; Carbon 16px; Polaris 16px; Ant 14–16px. 16px is the de-facto norm.
+**Norm** (≥6/18): indeterminate state is a visual-only UI state - the underlying `checked` value is still boolean; set via DOM `.indeterminate` property, not HTML attribute.
+**Diverge**: size - Material 3 uses 18px; Carbon 16px; Polaris 16px; Ant 14–16px. 16px is the de-facto norm.
 
 ---
 
@@ -61,8 +61,8 @@ Group:
 | unchecked | default | Empty box | `aria-checked="false"` |
 | checked | user interaction | Checkmark | `aria-checked="true"` |
 | indeterminate | set via JS | Dash / minus | `aria-checked="mixed"` |
-| hover | pointer over | Box border darkens | — |
-| focus | keyboard | 2px focus ring around box | — |
+| hover | pointer over | Box border darkens | - |
+| focus | keyboard | 2px focus ring around box | - |
 | disabled unchecked | `disabled` | 38% opacity | `aria-disabled="true"` |
 | disabled checked | `disabled` | 38% opacity + check | `aria-disabled="true"` |
 | error | validation | Red box border | `aria-invalid="true"` |
@@ -79,14 +79,14 @@ Group:
 | Group item spacing | 8px vertical between items | *(Carbon, Material 3)* |
 | Indentation (nested) | 24px | When showing hierarchical groups |
 
-Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern (44×44px minimum touch target)
+Cross-link: `reference/surfaces.md` - hit-area pseudo-element pattern (44×44px minimum touch target)
 
 ---
 
 ## Typography
 
-- Label: 14px/400; same weight as body — checkboxes are options, not headings
-- Legend: 14px/500 or 12px/600 uppercase — distinguishes group from items
+- Label: 14px/400; same weight as body - checkboxes are options, not headings
+- Legend: 14px/500 or 12px/600 uppercase - distinguishes group from items
 - Helper/error: 12px/400
 
 ---
@@ -98,20 +98,20 @@ Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern (44×44p
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
 | Tab | Moves focus to the checkbox |
 | Space | Toggles the checkbox state (checked / unchecked / indeterminate) |
 
-Within a group: Tab moves between checkboxes (not arrow keys — checkboxes are independent).
+Within a group: Tab moves between checkboxes (not arrow keys - checkboxes are independent).
 
 ### Accessibility Rules
 
-- Label MUST be associated via `<label for="id">` — clicking the label must toggle the checkbox
-- `<fieldset>` + `<legend>` MUST wrap every group of related checkboxes — the legend provides group context to screen readers
-- Indeterminate state MUST be set via JS `.indeterminate = true` — there is no HTML attribute; `aria-checked="mixed"` must be set simultaneously on `role="checkbox"` elements
+- Label MUST be associated via `<label for="id">` - clicking the label must toggle the checkbox
+- `<fieldset>` + `<legend>` MUST wrap every group of related checkboxes - the legend provides group context to screen readers
+- Indeterminate state MUST be set via JS `.indeterminate = true` - there is no HTML attribute; `aria-checked="mixed"` must be set simultaneously on `role="checkbox"` elements
 - Disabled checkboxes: use native `disabled` attribute for form semantics; `aria-disabled="true"` if the element must remain in tab order (e.g. with explanatory tooltip)
 - Error state: `aria-invalid="true"` on the control; group-level error on the `<fieldset>` via `aria-describedby`
 
@@ -125,7 +125,7 @@ Within a group: Tab moves between checkboxes (not arrow keys — checkboxes are
 | indeterminate dash | 120ms | ease | Width animation of dash element |
 | hover border | 80ms | ease | Border colour only |
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip path animation, show fill instantly
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: skip path animation, show fill instantly
 
 ---
 
@@ -138,10 +138,10 @@ Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip path animat
 - Align label text to the top of the control in multiline label scenarios *(Carbon)*
 
 ### Don't
-- Don't use checkboxes for mutually exclusive options — use radio buttons *(Material 3, Carbon, Polaris)*
+- Don't use checkboxes for mutually exclusive options - use radio buttons *(Material 3, Carbon, Polaris)*
 - Don't use a custom `<div>` checkbox without `role="checkbox"` and keyboard handler *(WAI-ARIA APG)*
-- Don't set `aria-checked="mixed"` via HTML attribute — it must be set dynamically *(WAI-ARIA APG)*
-- Don't rely on colour alone for checked state — always include a visible checkmark *(WCAG 1.4.1)*
+- Don't set `aria-checked="mixed"` via HTML attribute - it must be set dynamically *(WAI-ARIA APG)*
+- Don't rely on colour alone for checked state - always include a visible checkmark *(WCAG 1.4.1)*
 
 ---
 
@@ -195,7 +195,7 @@ grep -rn 'indeterminate' src/ | grep 'setAttribute\|attr(' | grep '"true"'
 </div>
 ```
 
-**Why it fails**: Screen readers announce each option without the group context ("Email — checkbox") — users don't know what these options belong to without reading surrounding text.
+**Why it fails**: Screen readers announce each option without the group context ("Email - checkbox") - users don't know what these options belong to without reading surrounding text.
 **Grep detection**: `grep -B5 'type="checkbox"' src/ | grep -v 'fieldset\|role="group"'`
 **Fix**:
 ```html

package/reference/components/chip.md

@@ -1,4 +1,4 @@
-# Chip / Tag — Benchmark Spec
+# Chip / Tag - Benchmark Spec
 
 **Harvested from**: Material 3, Carbon, Atlassian, Mantine
 **Wave**: 3 · **Category**: Feedback
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A chip (or tag) is a compact, interactive label that represents an attribute, filter, or selection. It is commonly used for multi-select filter interfaces, tag-input fields (user-generated labels), one-time suggestion prompts, and static display labels. Each variant has distinct interaction semantics — filter chips toggle on/off, input chips are removable, suggestion chips trigger a one-time action, and display chips are static. *(Material 3, Carbon, Atlassian, Mantine agree on the four-variant taxonomy)*
+A chip (or tag) is a compact, interactive label that represents an attribute, filter, or selection. It is commonly used for multi-select filter interfaces, tag-input fields (user-generated labels), one-time suggestion prompts, and static display labels. Each variant has distinct interaction semantics - filter chips toggle on/off, input chips are removable, suggestion chips trigger a one-time action, and display chips are static. *(Material 3, Carbon, Atlassian, Mantine agree on the four-variant taxonomy)*
 
 *UUPM app-interface: filter chips in search/filter UIs and tag input patterns (MIT attribution)*
 
@@ -51,13 +51,13 @@ A chip (or tag) is a compact, interactive label that represents an attribute, fi
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Rest fill + label | — |
-| hover | pointer over chip | Background tint (+8%) | — |
-| focus | keyboard focus on chip | focus-visible ring (2px) | — |
+| default | - | Rest fill + label | - |
+| hover | pointer over chip | Background tint (+8%) | - |
+| focus | keyboard focus on chip | focus-visible ring (2px) | - |
 | selected (filter) | click / Enter / Space | Filled background; checkmark icon | `aria-pressed="true"` |
 | unselected (filter) | click / Enter / Space | Outline style | `aria-pressed="false"` |
 | disabled | `disabled` / `aria-disabled` | 38% opacity; cursor not-allowed | `aria-disabled="true"` |
-| remove focus | Tab to × button | Focus ring on × | — |
+| remove focus | Tab to × button | Focus ring on × | - |
 
 ---
 
@@ -79,11 +79,11 @@ A chip (or tag) is a compact, interactive label that represents an attribute, fi
 
 ## Typography
 
-- Label: body-sm (13–14px/400) — same scale as form labels
-- No bold weight — chip label is a tag, not a heading or CTA
+- Label: body-sm (13–14px/400) - same scale as form labels
+- No bold weight - chip label is a tag, not a heading or CTA
 - Truncate with ellipsis only when chip is in a fixed-width container; prefer wrapping chip set to natural width
 
-Cross-link: `reference/typography.md` — body-sm definition
+Cross-link: `reference/typography.md` - body-sm definition
 
 ---
 
@@ -94,7 +94,7 @@ Cross-link: `reference/typography.md` — body-sm definition
 
 ### Keyboard Contract
 
-*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 |
 |-----|--------|
@@ -106,14 +106,14 @@ Cross-link: `reference/typography.md` — body-sm definition
 
 ### Accessibility Rules
 
-- Filter chip used as standalone toggle MUST have `aria-pressed="true|false"` — absence means screen readers cannot report toggle state *(WAI-ARIA APG)*
+- Filter chip used as standalone toggle MUST have `aria-pressed="true|false"` - absence means screen readers cannot report toggle state *(WAI-ARIA APG)*
 - Filter chips inside a multi-select group SHOULD use `role="option"` inside `role="listbox"` with `aria-multiselectable="true"` *(WAI-ARIA APG)*
-- Remove button MUST have an independent `aria-label` describing what it removes: `aria-label="Remove Python tag"` — the × glyph alone is not an accessible name *(WAI-ARIA APG, Material 3)*
+- Remove button MUST have an independent `aria-label` describing what it removes: `aria-label="Remove Python tag"` - the × glyph alone is not an accessible name *(WAI-ARIA APG, Material 3)*
 - Remove button MUST be a separate focusable element, NOT a click handler on the chip label *(Carbon, Atlassian)*
 - Touch target for remove button MUST be ≥ 32×32px via padding even if the visual × is 16–20px *(WCAG 2.5.5)*
-- Display chips have no role — they are presentational; if they carry meaningful status, use `role="status"` or integrate into an Alert *(Atlassian Lozenge guidance)*
+- Display chips have no role - they are presentational; if they carry meaningful status, use `role="status"` or integrate into an Alert *(Atlassian Lozenge guidance)*
 
-Cross-link: `reference/accessibility.md` — `aria-pressed`, `listbox`, touch targets
+Cross-link: `reference/accessibility.md` - `aria-pressed`, `listbox`, touch targets
 
 ---
 
@@ -126,9 +126,9 @@ Cross-link: `reference/accessibility.md` — `aria-pressed`, `listbox`, touch ta
 | Chip add (expand width) | 150ms | ease-out | Width expands from 0 |
 | Hover background | 80ms | ease-out | Subtle tint only |
 
-**BAN**: Full-page reflow animation when removing a chip — collapse width inline; do not shift unrelated page sections. Do not use `transition: all` (catches unintended border/shadow changes).
+**BAN**: Full-page reflow animation when removing a chip - collapse width inline; do not shift unrelated page sections. Do not use `transition: all` (catches unintended border/shadow changes).
 
-Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip width animation, instant add/remove
+Cross-link: `reference/motion.md` - `prefers-reduced-motion`: skip width animation, instant add/remove
 
 ---
 
@@ -141,10 +141,10 @@ Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip width anima
 - Ensure touch target ≥ 32px height; extend remove button via padding *(WCAG 2.5.5)*
 
 ### Don't
-- Don't put filter chips without `aria-pressed` — screen readers cannot report selected state *(WAI-ARIA APG)*
-- Don't use the same click handler for chip label and remove — remove must be independently focusable *(Carbon, Atlassian)*
-- Don't truncate chip label in narrow containers without a tooltip — truncated tags lose meaning *(Polaris, Mantine)*
-- Don't use display chips for dynamic statuses that change — use Alert or Badge instead *(Atlassian)*
+- Don't put filter chips without `aria-pressed` - screen readers cannot report selected state *(WAI-ARIA APG)*
+- Don't use the same click handler for chip label and remove - remove must be independently focusable *(Carbon, Atlassian)*
+- Don't truncate chip label in narrow containers without a tooltip - truncated tags lose meaning *(Polaris, Mantine)*
+- Don't use display chips for dynamic statuses that change - use Alert or Badge instead *(Atlassian)*
 
 ---
 

package/reference/components/command-palette.md

@@ -1,4 +1,4 @@
-# Command Palette — Benchmark Spec
+# Command Palette - Benchmark Spec
 
 **Harvested from**: Linear, Raycast, Radix CMDK, GitHub Primer, UUPM (app-interface, MIT)
 **Wave**: 4 · **Category**: Navigation & Data
@@ -64,7 +64,7 @@ A command palette is a keyboard-first global launcher that lets users search acr
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| closed | — | Dialog hidden | — |
+| closed | - | Dialog hidden | - |
 | open | Cmd/Ctrl+K | Dialog visible; input focused | `aria-expanded="true"` on combobox |
 | empty | no query | Placeholder or recent items | `aria-expanded="true"` |
 | searching | typing | Results update in real-time | `aria-live="polite"` on results region |
@@ -97,7 +97,7 @@ A command palette is a keyboard-first global launcher that lets users search acr
 - Section heading: label-xs (11px), uppercase, weight 600, `color: --text-subtle`, `aria-hidden="true"` if role="group" handles it
 - Keyboard shortcut hints: label-xs (11px), `color: --text-subtle`, right-aligned, `aria-hidden="true"`
 
-Cross-link: `reference/typography.md` — body-md, label scale
+Cross-link: `reference/typography.md` - body-md, label scale
 
 ---
 
@@ -108,7 +108,7 @@ Cross-link: `reference/typography.md` — body-md, label scale
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/combobox/ and https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/combobox/ and https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -123,14 +123,14 @@ Cross-link: `reference/typography.md` — body-md, label scale
 
 ### Accessibility Rules
 
-- Dialog MUST have `aria-modal="true"` — prevents AT from reading content outside the palette
+- Dialog MUST have `aria-modal="true"` - prevents AT from reading content outside the palette
 - `role="combobox"` input MUST have `aria-controls` pointing to the `role="listbox"` `id`
 - `aria-live="polite"` on the results region ensures AT announces result count changes and empty state
 - Focus MUST be trapped within the dialog while it is open (Tab/Shift+Tab cycle inside)
 - On close, focus MUST return to the element that triggered the palette (not body)
-- Keyboard shortcut hints (`⌘K`, `↵`) MUST be `aria-hidden="true"` — the shortcut must be registered separately
+- Keyboard shortcut hints (`⌘K`, `↵`) MUST be `aria-hidden="true"` - the shortcut must be registered separately
 
-Cross-link: `reference/accessibility.md` — dialog focus trap, combobox pattern, live regions
+Cross-link: `reference/accessibility.md` - dialog focus trap, combobox pattern, live regions
 
 ---
 
@@ -144,9 +144,9 @@ Cross-link: `reference/accessibility.md` — dialog focus trap, combobox pattern
 | Backdrop fade in | 150ms | ease-out | Opacity 0→0.5 |
 | Item selection flash | 80ms | ease-out | Brief fill before execute |
 
-**BAN**: Do not animate result item reordering as the user types — causes visual instability and is disorienting for AT users with animations enabled.
+**BAN**: Do not animate result item reordering as the user types - causes visual instability and is disorienting for AT users with animations enabled.
 
-Cross-link: `reference/motion.md` — dialog entry, BAN-04
+Cross-link: `reference/motion.md` - dialog entry, BAN-04
 
 ---
 
@@ -159,10 +159,10 @@ Cross-link: `reference/motion.md` — dialog entry, BAN-04
 - Use `role="group"` + `aria-label` for result sections *(WAI-ARIA APG, Linear, Raycast)*
 
 ### Don't
-- Don't build a custom overlay without `role="dialog"` + `aria-modal` — screen readers will read background content *(WCAG 1.3.1)*
-- Don't omit `aria-controls` on the combobox — AT cannot associate input with results *(WAI-ARIA APG combobox)*
-- Don't open on hover or auto-focus — Cmd/Ctrl+K is the expected trigger *(Linear, Raycast convention)*
-- Don't dismiss on every Escape keypress inside nested command flows — first Escape should exit sub-level, second closes palette *(Raycast, Linear)*
+- Don't build a custom overlay without `role="dialog"` + `aria-modal` - screen readers will read background content *(WCAG 1.3.1)*
+- Don't omit `aria-controls` on the combobox - AT cannot associate input with results *(WAI-ARIA APG combobox)*
+- Don't open on hover or auto-focus - Cmd/Ctrl+K is the expected trigger *(Linear, Raycast convention)*
+- Don't dismiss on every Escape keypress inside nested command flows - first Escape should exit sub-level, second closes palette *(Raycast, Linear)*
 
 ---
 
@@ -170,7 +170,7 @@ Cross-link: `reference/motion.md` — dialog entry, BAN-04
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-04 | `transition: all` on results list — `reference/anti-patterns.md#ban-04` |
+| BAN-04 | `transition: all` on results list - `reference/anti-patterns.md#ban-04` |
 
 ---
 
@@ -223,6 +223,6 @@ grep -rn 'command.*palette\|cmd.*results\|cmdk' src/ | grep 'results\|listbox' |
 </div>
 ```
 
-**Why it fails**: No `role="dialog"` — AT does not treat this as a modal, and screen readers continue reading background content; no focus trap; input lacks `role="combobox"` and `aria-controls`; results have no `role="listbox"`; items have no `role="option"` or `aria-selected`; no `aria-live` region for result updates.
+**Why it fails**: No `role="dialog"` - AT does not treat this as a modal, and screen readers continue reading background content; no focus trap; input lacks `role="combobox"` and `aria-controls`; results have no `role="listbox"`; items have no `role="option"` or `aria-selected`; no `aria-live` region for result updates.
 **Grep detection**: `grep -rn 'command.*palette\|cmdk\|command-menu' src/ | grep '<div' | grep -v 'role='`
 **Fix**: Use `role="dialog"` + `aria-modal="true"` on the overlay; implement focus trap; add `role="combobox"` + `aria-controls` to input; add `role="listbox"` to results container; add `role="option"` + `aria-selected` to each item; add `aria-live="polite"` to results region.

package/reference/components/date-picker.md

@@ -1,4 +1,4 @@
-# Date Picker — Benchmark Spec
+# Date Picker - Benchmark Spec
 
 **Harvested from**: Material 3, Carbon Design System, Atlassian Design System, Mantine DatePicker
 **Wave**: 5 · **Category**: Advanced
@@ -31,7 +31,7 @@ Range variant adds a second input field for end date.
 | Part | Required | Notes |
 |------|----------|-------|
 | Text input | Yes | Shows selected date; accepts direct keyboard entry |
-| Format hint label | Yes | Visible "MM/DD/YYYY" supplement — NOT placeholder only |
+| Format hint label | Yes | Visible "MM/DD/YYYY" supplement - NOT placeholder only |
 | Calendar trigger button | Yes | Opens/closes popover; `aria-label="Open calendar"` |
 | Popover (dialog) | Yes | `role="dialog"` + `aria-modal="true"` + focus trap |
 | Month navigation | Yes | Previous/next month buttons; keyboard Page Up/Down |
@@ -59,13 +59,13 @@ Range variant adds a second input field for end date.
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Resting input + trigger icon | — |
+| default | - | Resting input + trigger icon | - |
 | open | Trigger click or input focus + Enter | Popover visible, focus moves inside | `aria-expanded="true"` on trigger |
-| day hover | Pointer over day | Background highlight | — |
-| day focus | Keyboard navigation | Focus-visible ring on day button | — |
+| day hover | Pointer over day | Background highlight | - |
+| day focus | Keyboard navigation | Focus-visible ring on day button | - |
 | day selected | Enter/Space or click | Filled background (brand color) | `aria-pressed="true"` on day button |
-| range-in-progress | Start selected, end not yet | Partial fill from start | — |
-| range-complete | Both start and end selected | Full highlight between dates | — |
+| range-in-progress | Start selected, end not yet | Partial fill from start | - |
+| range-complete | Both start and end selected | Full highlight between dates | - |
 | disabled date | Date excluded by min/max/filter | Muted; `tabindex="-1"` | `aria-disabled="true"` on day button |
 | error | Invalid date typed | Red border + error message | `aria-invalid="true"` on input |
 
@@ -82,7 +82,7 @@ Range variant adds a second input field for end date.
 **Norm**: 288px popover width fits a standard 7-column month grid with comfortable padding *(Carbon, Mantine)*.
 Day cells must be ≥32px to meet minimum touch-target guidance; prefer 40px for mixed pointer/touch contexts.
 
-Cross-link: `reference/surfaces.md` — minimum 44×44px accessible tap target via padding.
+Cross-link: `reference/surfaces.md` - minimum 44×44px accessible tap target via padding.
 
 ---
 
@@ -91,9 +91,9 @@ Cross-link: `reference/surfaces.md` — minimum 44×44px accessible tap target v
 - Input text: body-md weight 400; monospace or tabular-nums variant for date digits aids alignment
 - Day numbers: body-sm, center-aligned within cell
 - Month/year header: body-md weight 600
-- Format hint ("MM/DD/YYYY"): caption-sm, secondary color — attached as visible `<label>` supplement or `<span aria-hidden="true">` paired with `aria-describedby` on the input
+- Format hint ("MM/DD/YYYY"): caption-sm, secondary color - attached as visible `<label>` supplement or `<span aria-hidden="true">` paired with `aria-describedby` on the input
 
-Cross-link: `reference/typography.md` — tabular-nums for date/time fields.
+Cross-link: `reference/typography.md` - tabular-nums for date/time fields.
 
 ---
 
@@ -104,7 +104,7 @@ Cross-link: `reference/typography.md` — tabular-nums for date/time fields.
 
 ### Keyboard Contract
 
-*Adapted from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ and grid pattern — W3C — 2024*
+*Adapted from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ and grid pattern - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
@@ -122,7 +122,7 @@ Cross-link: `reference/typography.md` — tabular-nums for date/time fields.
 
 ### Accessibility Rules
 
-- Calendar popover MUST use `role="dialog"` + `aria-modal="true"` — do not use a plain `<div>` overlay
+- Calendar popover MUST use `role="dialog"` + `aria-modal="true"` - do not use a plain `<div>` overlay
 - Focus MUST be trapped inside the open calendar; Escape closes and returns focus to the trigger
 - Each selectable day MUST be a `<button>` (or element with `role="button"`) so keyboard and AT users can activate it
 - Date format hint MUST be visible text, not only a placeholder (placeholder disappears on input and is not consistently announced)
@@ -130,7 +130,7 @@ Cross-link: `reference/typography.md` — tabular-nums for date/time fields.
 - Range variant: announce selected range via `aria-label` on day buttons (e.g., `aria-label="April 15, 2025, start of range"`)
 - Mobile: provide native `<input type="date">` fallback when touch device detected or user preference set
 
-Cross-link: `reference/accessibility.md` — focus-trap pattern, dialog role requirements.
+Cross-link: `reference/accessibility.md` - focus-trap pattern, dialog role requirements.
 
 ---
 
@@ -144,9 +144,9 @@ Cross-link: `reference/accessibility.md` — focus-trap pattern, dialog role req
 | Day selection | 80ms | ease-out | Fill background color |
 | Range fill | 150ms | ease-out | Animate fill between dates |
 
-**BAN**: Do not animate the calendar grid with a full-page slide — disorienting for keyboard users navigating by month.
+**BAN**: Do not animate the calendar grid with a full-page slide - disorienting for keyboard users navigating by month.
 
-Cross-link: `reference/motion.md` — reduced-motion: omit slide, keep instant day selection.
+Cross-link: `reference/motion.md` - reduced-motion: omit slide, keep instant day selection.
 
 ---
 
@@ -155,14 +155,14 @@ Cross-link: `reference/motion.md` — reduced-motion: omit slide, keep instant d
 ### Do
 - Show the date format as visible text ("MM/DD/YYYY") near the input *(Carbon, Atlassian)*
 - Ensure keyboard users can navigate the entire calendar without a pointer *(WAI-ARIA APG)*
-- Allow direct text entry in the input field — some users know the date and do not need the calendar *(Mantine, Carbon)*
+- Allow direct text entry in the input field - some users know the date and do not need the calendar *(Mantine, Carbon)*
 - Support locale-aware first day of week (Sunday vs. Monday) and locale month/day names *(Material 3, Mantine)*
 
 ### Don't
-- Don't use `<table>` with click-only cells — add `role="grid"` and full keyboard navigation *(WCAG 2.1 §2.1.1)*
-- Don't use placeholder text alone to convey the date format — placeholder vanishes on input *(Carbon, Atlassian)*
-- Don't trap focus permanently — Escape must always close the popover and restore focus *(WAI-ARIA APG)*
-- Don't omit the native `<input type="date">` for mobile — custom calendars are unusable on small touch screens *(Material 3)*
+- Don't use `<table>` with click-only cells - add `role="grid"` and full keyboard navigation *(WCAG 2.1 §2.1.1)*
+- Don't use placeholder text alone to convey the date format - placeholder vanishes on input *(Carbon, Atlassian)*
+- Don't trap focus permanently - Escape must always close the popover and restore focus *(WAI-ARIA APG)*
+- Don't omit the native `<input type="date">` for mobile - custom calendars are unusable on small touch screens *(Material 3)*
 
 ---
 
@@ -170,8 +170,8 @@ Cross-link: `reference/motion.md` — reduced-motion: omit slide, keep instant d
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-07 | Placeholder as only label/hint — `reference/anti-patterns.md#ban-07` |
-| BAN-12 | Custom overlay without focus trap — `reference/anti-patterns.md#ban-12` |
+| BAN-07 | Placeholder as only label/hint - `reference/anti-patterns.md#ban-07` |
+| BAN-12 | Custom overlay without focus trap - `reference/anti-patterns.md#ban-12` |
 
 ---
 

package/reference/components/drawer.md

@@ -1,4 +1,4 @@
-# Drawer / Sheet — Benchmark Spec
+# Drawer / Sheet - Benchmark Spec
 
 **Harvested from**: Material 3, Polaris (Sheet), Carbon, Atlassian, Mantine, shadcn/ui, Headless UI, Apple HIG
 **Wave**: 2 · **Category**: Containers
@@ -7,7 +7,7 @@
 
 ## Purpose
 
-A drawer (or sheet) is a panel that slides in from an edge of the viewport. It is less disruptive than a modal for workflows that benefit from co-existing with the background — detail panels, navigation menus, filter sidebars, multi-step flows. Like a modal, it traps focus and requires Escape to close. Unlike a modal, the backdrop is optional and can be semi-transparent. *(Material 3, Carbon, Polaris all position drawer as less disruptive than modal)*
+A drawer (or sheet) is a panel that slides in from an edge of the viewport. It is less disruptive than a modal for workflows that benefit from co-existing with the background - detail panels, navigation menus, filter sidebars, multi-step flows. Like a modal, it traps focus and requires Escape to close. Unlike a modal, the backdrop is optional and can be semi-transparent. *(Material 3, Carbon, Polaris all position drawer as less disruptive than modal)*
 
 ---
 
@@ -55,13 +55,13 @@ Bottom sheet (mobile):
 | Partial height | 60–80vh, overlays | Mobile bottom sheet | Apple HIG, Material 3 |
 
 **Norm** (≥5/18): right-side is default; bottom sheet for mobile.
-**Diverge**: backdrop-click-to-close — same debate as modal; for navigation drawers, backdrop click should close; for form/detail drawers, configurable.
+**Diverge**: backdrop-click-to-close - same debate as modal; for navigation drawers, backdrop click should close; for form/detail drawers, configurable.
 
 ---
 
 ## States
 
-Same as Modal/Dialog — see `modal-dialog.md`. Key differences:
+Same as Modal/Dialog - see `modal-dialog.md`. Key differences:
 
 | State | Drawer-specific |
 |-------|-----------------|
@@ -80,7 +80,7 @@ Same as Modal/Dialog — see `modal-dialog.md`. Key differences:
 | Bottom sheet | 60–100vh | Drag handle at 12px × 36px |
 | Padding | 20–24px | Match modal padding |
 
-Cross-link: `reference/surfaces.md` — shadow on drawer edge (unilateral shadow)
+Cross-link: `reference/surfaces.md` - shadow on drawer edge (unilateral shadow)
 
 ---
 
@@ -94,21 +94,21 @@ Cross-link: `reference/surfaces.md` — shadow on drawer edge (unilateral shadow
 
 ## Keyboard & Accessibility
 
-> **WAI-ARIA role**: `dialog` (same as modal — drawer is a type of dialog)
+> **WAI-ARIA role**: `dialog` (same as modal - drawer is a type of dialog)
 > **Required attributes**: `aria-modal="true"`, `aria-labelledby` (title id)
 
 ### Keyboard Contract
 
-*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ — W3C — 2024*
+*Quoted verbatim from WAI-ARIA APG - https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ - W3C - 2024*
 
 Same Tab/Shift+Tab/Escape contract as modal (see `modal-dialog.md`).
 
 ### Drawer-specific Accessibility Rules
 
-- Focus trap: MUST trap focus inside the drawer while open — same as modal
+- Focus trap: MUST trap focus inside the drawer while open - same as modal
 - On open: focus moves to first focusable element (or close button if no primary action)
 - On close: focus MUST return to the element that triggered the drawer open
-- Navigation drawer (`role="navigation"`): if the drawer IS the main nav, use `role="navigation"` + `aria-label="Main"` instead of `role="dialog"`; different keyboard contract (no focus trap — it IS a landmark)
+- Navigation drawer (`role="navigation"`): if the drawer IS the main nav, use `role="navigation"` + `aria-label="Main"` instead of `role="dialog"`; different keyboard contract (no focus trap - it IS a landmark)
 - Background `inert`: set `inert` attribute (or equivalent) on background content when drawer is open
 
 ---
@@ -123,23 +123,23 @@ Same Tab/Shift+Tab/Escape contract as modal (see `modal-dialog.md`).
 | Backdrop fade | 200ms | ease | opacity 0→0.4 |
 
 Swipe-to-close (bottom sheet): detect `pointerup` with velocity + displacement threshold.
-Cross-link: `reference/motion.md` — spring bounce=0, `prefers-reduced-motion` (disable slide, instant toggle)
+Cross-link: `reference/motion.md` - spring bounce=0, `prefers-reduced-motion` (disable slide, instant toggle)
 
 ---
 
 ## Do / Don't
 
 ### Do
-- Trap focus inside the drawer when open — same rule as modal *(WAI-ARIA APG)*
+- Trap focus inside the drawer when open - same rule as modal *(WAI-ARIA APG)*
 - Return focus to the trigger element on close *(WAI-ARIA APG, Radix, Mantine)*
 - Use right-side drawer for content-detail panels; left-side for navigation *(Material 3, Carbon)*
 - Support swipe-to-close on bottom sheets for mobile *(Apple HIG, Material 3)*
 
 ### Don't
-- Don't use `role="navigation"` for content drawers — only for navigation-purpose drawers *(WAI-ARIA APG)*
+- Don't use `role="navigation"` for content drawers - only for navigation-purpose drawers *(WAI-ARIA APG)*
 - Don't let Tab escape the drawer while it's open *(WAI-ARIA APG)*
 - Don't disable background scroll without setting `overflow:hidden` on body *(all systems)*
-- Don't slide from top for content — top drawers conflict with browser UI and notifications *(Material 3)*
+- Don't slide from top for content - top drawers conflict with browser UI and notifications *(Material 3)*
 
 ---