@hegemonart/get-design-done 1.41.5 → 1.43.0

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

package/reference/components/file-upload.md

@@ -1,4 +1,4 @@
-# File Upload — Benchmark Spec
+# File Upload - Benchmark Spec
 
 **Harvested from**: Polaris (DropZone), Carbon (FileUploader), Atlassian Design System, Material 3
 **Wave**: 5 · **Category**: Advanced
@@ -34,7 +34,7 @@ File list (appears after selection):
 | Part | Required | Notes |
 |------|----------|-------|
 | Drop zone container | Yes | Dashed border; drag-over changes fill + border color |
-| `<input type="file">` | Yes | MUST be accessible (not `display:none`) — keyboard fallback |
+| `<input type="file">` | Yes | MUST be accessible (not `display:none`) - keyboard fallback |
 | Browse trigger button | Yes | Visually activates the file input; must be a `<button>` or `<label>` |
 | File list | Yes (when files selected) | Per-file name, size, status, progress bar, remove button |
 | Progress bar | Yes (during upload) | `role="progressbar"` + `aria-valuenow` per file or overall |
@@ -62,11 +62,11 @@ File list (appears after selection):
 
 | State | Trigger | Visual | ARIA |
 |-------|---------|--------|------|
-| default | — | Dashed border, instructional text | — |
+| default | - | Dashed border, instructional text | - |
 | drag-over | File dragged over zone | Filled background + solid border color change | `aria-dropeffect="copy"` (deprecated but still useful) |
-| drag-invalid | Wrong file type dragged over | Error border color; tooltip/message | — |
+| drag-invalid | Wrong file type dragged over | Error border color; tooltip/message | - |
 | uploading | File being sent | Per-file progress bar animating | `aria-valuenow` on progressbar |
-| upload-done | Transfer complete | Check icon; status text "Done" | — |
+| upload-done | Transfer complete | Check icon; status text "Done" | - |
 | upload-error | Transfer failed | Error icon; error message per file | `aria-live="assertive"` error region |
 | disabled | `disabled` prop | 38% opacity; drag events ignored | `aria-disabled="true"` on zone |
 
@@ -80,9 +80,9 @@ File list (appears after selection):
 | md (default) | 128px | 8px | 14px |
 | lg | 200px | 12px | 16px |
 
-**Norm**: Drop zone should be large enough that it is comfortably hittable — 128px minimum height for default. File list rows are 48–56px tall for accessible remove-button target size *(Carbon, Polaris)*.
+**Norm**: Drop zone should be large enough that it is comfortably hittable - 128px minimum height for default. File list rows are 48–56px tall for accessible remove-button target size *(Carbon, Polaris)*.
 
-Cross-link: `reference/surfaces.md` — minimum 44×44px touch targets for remove buttons.
+Cross-link: `reference/surfaces.md` - minimum 44×44px touch targets for remove buttons.
 
 ---
 
@@ -94,7 +94,7 @@ Cross-link: `reference/surfaces.md` — minimum 44×44px touch targets for remov
 - File size: caption-sm, secondary color
 - Status text (Done / Error): caption-sm, success or error semantic color
 
-Cross-link: `reference/typography.md` — truncation rules.
+Cross-link: `reference/typography.md` - truncation rules.
 
 ---
 
@@ -105,12 +105,12 @@ Cross-link: `reference/typography.md` — truncation rules.
 
 ### Keyboard Contract
 
-*Derived from native `<input type="file">` behavior and WAI-ARIA APG button pattern — W3C — 2024*
+*Derived from native `<input type="file">` behavior and WAI-ARIA APG button pattern - W3C - 2024*
 
 | Key | Action |
 |-----|--------|
 | Tab | Move focus to browse button / file input |
-| Enter / Space | Activate browse button — opens native file picker dialog |
+| Enter / Space | Activate browse button - opens native file picker dialog |
 | Tab (in file list) | Move through file items and remove buttons |
 | Enter / Space (on remove button) | Remove file from list |
 
@@ -118,15 +118,15 @@ Drag-and-drop is pointer-only; keyboard users MUST be able to complete the entir
 
 ### Accessibility Rules
 
-- `<input type="file">` MUST NOT use `display:none` or `visibility:hidden` — use `opacity:0` positioned absolutely with dimensions matching the trigger, OR keep a visible file input alongside the drop zone
+- `<input type="file">` MUST NOT use `display:none` or `visibility:hidden` - use `opacity:0` positioned absolutely with dimensions matching the trigger, OR keep a visible file input alongside the drop zone
 - The browse trigger MUST be a `<button>` or `<label for="file-input">` so it is keyboard-focusable and activates the input
-- Remove buttons MUST have `aria-label="Remove [filename]"` — an icon-only ✕ with no accessible name fails AT users
-- Upload errors MUST be announced via `aria-live="assertive"` — do not rely solely on visual indicators
+- Remove buttons MUST have `aria-label="Remove [filename]"` - an icon-only ✕ with no accessible name fails AT users
+- Upload errors MUST be announced via `aria-live="assertive"` - do not rely solely on visual indicators
 - Progress bars MUST keep `aria-valuenow` updated throughout upload
 - `accept` attribute MUST match the visible allowed-types hint text so users are not surprised by rejection
 - File list additions/removals should be announced via `aria-live="polite"` on the list container
 
-Cross-link: `reference/accessibility.md` — aria-live regions, accessible file input patterns.
+Cross-link: `reference/accessibility.md` - aria-live regions, accessible file input patterns.
 
 ---
 
@@ -140,9 +140,9 @@ Cross-link: `reference/accessibility.md` — aria-live regions, accessible file
 | Progress bar fill | continuous | linear | Matches upload byte progress |
 | Upload complete tick | 200ms | ease-out | Check icon draw animation |
 
-**BAN**: Do not animate progress bar with CSS only at a fixed pace — progress MUST reflect actual upload percentage via `aria-valuenow`.
+**BAN**: Do not animate progress bar with CSS only at a fixed pace - progress MUST reflect actual upload percentage via `aria-valuenow`.
 
-Cross-link: `reference/motion.md` — reduced-motion: skip slide/collapse animations; keep progress bar updates.
+Cross-link: `reference/motion.md` - reduced-motion: skip slide/collapse animations; keep progress bar updates.
 
 ---
 
@@ -155,10 +155,10 @@ Cross-link: `reference/motion.md` — reduced-motion: skip slide/collapse animat
 - Announce upload errors via `aria-live="assertive"` *(WCAG 2.1 §4.1.3 Status Messages)*
 
 ### Don't
-- Don't use `display:none` on the file input — keyboard and AT users cannot trigger the picker *(WCAG 2.1 §2.1.1)*
-- Don't omit the `accept` hint text — users should know allowed types before selecting *(Polaris, Carbon)*
-- Don't show only drag-drop UI with no browse button — drag is inaccessible to keyboard users *(Carbon, Atlassian)*
-- Don't use a generic `aria-label="Remove"` on remove buttons — AT users cannot identify which file *(Carbon)*
+- Don't use `display:none` on the file input - keyboard and AT users cannot trigger the picker *(WCAG 2.1 §2.1.1)*
+- Don't omit the `accept` hint text - users should know allowed types before selecting *(Polaris, Carbon)*
+- Don't show only drag-drop UI with no browse button - drag is inaccessible to keyboard users *(Carbon, Atlassian)*
+- Don't use a generic `aria-label="Remove"` on remove buttons - AT users cannot identify which file *(Carbon)*
 
 ---
 
@@ -166,8 +166,8 @@ Cross-link: `reference/motion.md` — reduced-motion: skip slide/collapse animat
 
 | Anti-pattern | Entry |
 |--------------|-------|
-| BAN-08 | File input hidden with display:none — keyboard inaccessible — `reference/anti-patterns.md#ban-08` |
-| BAN-13 | Icon-only action button without aria-label — `reference/anti-patterns.md#ban-13` |
+| BAN-08 | File input hidden with display:none - keyboard inaccessible - `reference/anti-patterns.md#ban-08` |
+| BAN-13 | Icon-only action button without aria-label - `reference/anti-patterns.md#ban-13` |
 
 ---