@hegemonart/get-design-done 1.15.0 → 1.18.0

package/reference/components/file-upload.md

@@ -0,0 +1,219 @@
+# File Upload — Benchmark Spec
+
+**Harvested from**: Polaris (DropZone), Carbon (FileUploader), Atlassian Design System, Material 3
+**Wave**: 5 · **Category**: Advanced
+**Spec file**: `reference/components/file-upload.md`
+
+---
+
+## Purpose
+
+A File Upload component lets users attach one or more files by dragging them onto a drop zone or clicking to open the native file picker. It must work for all users: keyboard-only users activate the hidden-but-accessible `<input type="file">`, while pointer users can drag-drop. A file list tracks upload progress, status, and provides remove actions. *(Polaris, Carbon, Atlassian agree: drop zone + accessible file input + per-file status list is the canonical pattern.)*
+
+---
+
+## Anatomy
+
+```
+┌─────────────────────────────────┐
+│  Drop zone                      │
+│  [ Cloud icon ]                 │
+│  "Drag files here or"           │
+│  [ Browse files ] ← triggers    │
+│    <input type="file">          │
+└─────────────────────────────────┘
+
+File list (appears after selection):
+┌────────────────────────────────────────────────┐
+│ 📄 report.pdf  245 KB  [========   ] 80%  [✕] │
+│ 📄 photo.jpg   1.2 MB  ✓ Done             [✕] │
+│ 📄 data.csv    88 KB   ✗ Error            [✕] │
+└────────────────────────────────────────────────┘
+```
+
+| 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 |
+| 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 |
+| Remove button | Yes | `aria-label="Remove [filename]"` |
+| Error region | Yes (on error) | `aria-live="assertive"` for upload errors |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Drop zone | Large dashed-border target area with drag-and-drop | Polaris, Carbon, Atlassian, Material 3 |
+| Compact / inline | Small "Attach file" button only; no large drop area | Carbon (FileUploaderItem), Atlassian |
+| Avatar/image uploader | Circular or rectangular crop zone for single image | Material 3, Polaris |
+| Multi-file | `multiple` attr; list of uploaded files | All systems |
+| Single-file | No `multiple`; replaces previous selection | Carbon, Polaris |
+
+**Norm** (≥3/4 systems agree): drop zone + browse button + file list is the standard desktop pattern; progress bar per file during upload.
+**Diverge**: Polaris auto-starts upload on drop; Carbon shows "Add files" button after initial selection to allow adding more; Material 3 defers to app logic.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| 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 | — |
+| uploading | File being sent | Per-file progress bar animating | `aria-valuenow` on progressbar |
+| 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 |
+
+---
+
+## Sizing & Spacing
+
+| Size | Drop Zone Min Height | Border Radius | Font |
+|------|---------------------|---------------|------|
+| sm | 80px | 4px | 13px |
+| 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)*.
+
+Cross-link: `reference/surfaces.md` — minimum 44×44px touch targets for remove buttons.
+
+---
+
+## Typography
+
+- Drop zone instruction: body-md, centered, secondary color
+- "Browse files" link/button: body-md, primary link or button style
+- File name in list: body-sm, truncated with ellipsis (max-width on container), full name in `title` attribute
+- File size: caption-sm, secondary color
+- Status text (Done / Error): caption-sm, success or error semantic color
+
+Cross-link: `reference/typography.md` — truncation rules.
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `button` (browse trigger); `progressbar` (upload progress); `status` or `log` (file list updates)
+> **Required attributes**: `aria-label="Remove [filename]"` on remove buttons; `aria-valuenow` + `aria-valuemin` + `aria-valuemax` on progressbar; `aria-live="assertive"` on error region
+
+### Keyboard Contract
+
+*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 |
+| Tab (in file list) | Move through file items and remove buttons |
+| Enter / Space (on remove button) | Remove file from list |
+
+Drag-and-drop is pointer-only; keyboard users MUST be able to complete the entire task via the file input alone.
+
+### 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
+- 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
+- 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.
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Drop zone drag-over | 100ms | ease-out | Background fill + border color |
+| File list item enter | 200ms | ease-out | Slide-in from top or fade-in |
+| File list item remove | 150ms | ease-in | Fade + collapse height |
+| 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`.
+
+Cross-link: `reference/motion.md` — reduced-motion: skip slide/collapse animations; keep progress bar updates.
+
+---
+
+## Do / Don't
+
+### Do
+- Keep `<input type="file">` accessible at all times (opacity:0 trick or visible) *(WAI-ARIA, Polaris, Carbon)*
+- Provide `aria-label="Remove [filename]"` on every remove button *(Carbon, Atlassian)*
+- Show file name, size, and status in the file list *(Polaris, Carbon, Atlassian)*
+- 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)*
+
+---
+
+## Anti-patterns Cross-links
+
+| 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` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| input type="file" must not be display:none | WCAG 2.1 §2.1.1, Carbon, Polaris accessibility guides |
+| Remove button needs aria-label="Remove [filename]" | Carbon FileUploader, Atlassian, Polaris |
+| Upload errors need aria-live="assertive" | WCAG 2.1 §4.1.3, Material 3 |
+| Progress bar needs aria-valuenow updates | WAI-ARIA progressbar role spec |
+| Drag-over state: background fill + border change | Polaris, Carbon, Atlassian drop zone specs |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# File input hidden with display:none (keyboard inaccessible)
+grep -rn 'type="file"' src/ | grep -v 'opacity\|position.*absolute' | grep 'display.*none\|visibility.*hidden'
+
+# Remove button missing aria-label (icon-only, no accessible name)
+grep -rn 'remove.*button\|btn.*remove\|✕\|×' src/ | grep -v 'aria-label'
+
+# Progress bar missing aria-valuenow
+grep -rn 'role="progressbar"' src/ | grep -v 'aria-valuenow'
+
+# Upload error region without aria-live
+grep -rn 'upload.*error\|file.*error\|error.*upload' src/ | grep -v 'aria-live'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: drop zone with display:none on the actual <input> — keyboard and AT users can't trigger file picker -->
+<div class="drop-zone" ondrop="handleDrop(event)" ondragover="handleDragOver(event)">
+  <p>Drag files here</p>
+  <input type="file" id="file-input" style="display:none" onchange="handleFiles(event)">
+  <button onclick="document.getElementById('file-input').click()">Browse</button>
+</div>
+```
+
+**Why it fails**: `display:none` removes the input from accessibility tree and tab order. The JavaScript `.click()` workaround does not work reliably with all AT. Keyboard users pressing Enter/Space on "Browse" may get inconsistent behavior across browsers. Screen reader users cannot discover or activate the file input directly.
+**Grep detection**: `grep -rn 'type="file".*display.*none\|display.*none.*type="file"' src/`
+**Fix**: Use `opacity:0; position:absolute; width:100%; height:100%` on the input (matching the browse button dimensions), or place a visible `<input type="file">` and style the button as a `<label for="file-input">` so clicking the label activates the input natively without JavaScript.

package/reference/components/input.md

@@ -0,0 +1,208 @@
+# Input — Benchmark Spec
+
+**Harvested from**: Material 3, Carbon, Ant Design, Mantine, Polaris, Fluent 2, Atlassian, shadcn/ui
+**Wave**: 1 · **Category**: Inputs
+
+---
+
+## Purpose
+
+A single-line text input collects short textual data from the user. It always has an associated visible label (never placeholder-only), optionally shows a helper text or character count below, and surfaces error state with an accessible message. Multi-line content belongs in a textarea; structured data (dates, phones) may warrant a specialised input type.
+
+---
+
+## Anatomy
+
+```
+Label *                     ← <label for="id"> — always visible
+┌─────────────────────────┐
+│ placeholder / value     │  ← <input type="text"> or type="search" / "email" / etc.
+└─────────────────────────┘
+  Helper text / Error msg  ← aria-describedby linked
+  Character count (opt.)   ← aria-live="polite" region
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Label | Yes | Visible; never placeholder-only |
+| Input element | Yes | Native `<input>` preferred; `type` set explicitly |
+| Helper text | No | Persistent instructional text below input |
+| Error message | Conditional | Shown on invalid state; replaces or joins helper text |
+| Character count | No | `aria-live="polite"` region; announced on pause |
+| Required indicator | No | `*` with `aria-required="true"` on input; legend explains `*` |
+| Leading icon / adornment | No | 16–20px; left-inset with 12px gap from text |
+| Trailing icon / clear button | No | Clear action must be keyboard-accessible |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Outlined | Border box with floating/static label | Material 3, Ant, Mantine, shadcn |
+| Filled | Filled background, underline only | Material 3, Carbon |
+| Underline / Simple | Bottom border only | Carbon (fluid), Fluent |
+| Search | Leading search icon; clear button on value | All systems |
+| Password | Trailing show/hide toggle | All systems |
+| Number | `type="number"` or `inputmode="numeric"` | Material 3, Ant, Mantine |
+
+**Norm** (≥6/18): outlined with floating or static label is the most-cited default.
+**Diverge**: floating vs. static label — Material 3 uses floating; Carbon, Polaris, Atlassian use static (above). Static label is safer for a11y (floating requires JavaScript + ARIA management).
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Resting border | — |
+| hover | pointer over | Border lightens 20% | — |
+| focus | keyboard / click | 2px focus-visible ring or thickened border | — |
+| filled | has value | Label lifts (floating) or stays static | — |
+| disabled | `disabled` attr | 38% opacity; cursor: not-allowed | `disabled` attr |
+| read-only | `readonly` attr | No border change; cursor: default | `readonly` attr |
+| error | invalid | Red/error border + icon + error message | `aria-invalid="true"` + `aria-describedby` |
+| success | valid (opt.) | Green border + check icon | — |
+
+---
+
+## Sizing & Spacing
+
+| Size | Height | Padding H | Font | Label size |
+|------|--------|-----------|------|------------|
+| sm | 32px | 12px | 13px | 12px |
+| md (default) | 40px | 16px | 14px | 14px |
+| lg | 48px | 16px | 16px | 16px |
+
+**Norm**: 40px default height (Carbon, Polaris, Fluent, Atlassian confirm).
+Minimum width: 200px — narrower inputs invite input truncation and frustrate users.
+
+Cross-link: `reference/surfaces.md` — hit area ≥44px via padding; `reference/typography.md` — label sizing.
+
+---
+
+## Typography
+
+- Label: 14px/500 above input; 12px when floating in focus/filled state
+- Placeholder: 14px/400; color at 40% contrast minimum — never the only label
+- Helper/error: 12px/400; full contrast for error messages
+- **Placeholder is not a label**: it disappears on type, fails contrast, and cannot be announced by screen readers as a persistent label
+
+Cross-link: `reference/typography.md` — text-wrap, font-smoothing rules
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `textbox` (implicit on `<input type="text">`)
+> **Required attributes**: `id` + matching `<label for>`, or `aria-label`; `aria-describedby` linking error/helper
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/textbox/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Any printable character | Types character into field |
+| Backspace / Delete | Removes character |
+| Home | Moves caret to start |
+| End | Moves caret to end |
+| Ctrl+A | Selects all |
+| Tab | Moves focus to next element |
+| Shift+Tab | Moves focus to previous element |
+
+Password toggle and clear button must be keyboard accessible (Enter/Space activate).
+
+### Accessibility Rules
+
+- Label MUST be associated via `<label for="id">` or `aria-label` — `placeholder` alone is not sufficient
+- Error message MUST be linked via `aria-describedby` and triggered before or alongside visual indicator
+- `aria-invalid="true"` MUST be set on the input when in error state
+- `aria-required="true"` for required fields (supplement with visual `*` + legend)
+- Character count region: `aria-live="polite"` to avoid over-announcing on every keystroke
+
+Cross-link: `reference/accessibility.md`
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| label float | 150ms | ease-out | Floating label only; avoid if complex JS needed |
+| border colour | 100ms | ease | Focus/error state border change |
+| error message in | 150ms | ease-out | Slide-down + fade; respect prefers-reduced-motion |
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion` guard required on label float
+
+---
+
+## Do / Don't
+
+### Do
+- Always show a visible label above or beside the input *(Carbon, Polaris, Atlassian, WAI-ARIA APG)*
+- Show inline error messages immediately below the failing field *(Material 3, Carbon, Polaris)*
+- Associate helper text and errors via `aria-describedby` *(WAI-ARIA APG)*
+- Use `autocomplete` attributes for common fields (name, email, address) *(Polaris, Fluent)*
+
+### Don't
+- Don't use `placeholder` as the only label — it disappears and fails contrast *(Carbon, Polaris, Atlassian)*
+- Don't show error state before the user has had a chance to input (premature validation) *(Polaris)*
+- Don't remove the label on focus to create space — floating labels break screen readers *(Atlassian)*
+- Don't use `type="number"` for things that aren't math operands (phone, ZIP) — use `inputmode` instead *(Mantine, Carbon)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Placeholder-as-label | `reference/anti-patterns.md` — no dedicated BAN yet; cross-ref accessibility.md |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| 40px default height | Carbon, Polaris, Fluent 2, Atlassian |
+| Placeholder not a label | Carbon, Polaris, Atlassian, WAI-ARIA APG |
+| aria-describedby for errors | WAI-ARIA APG, Carbon, Mantine |
+| Static label safer than floating | Atlassian, Carbon, Polaris |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Placeholder-as-label (no <label> associated)
+grep -rn 'placeholder=' src/ | grep -v 'aria-label\|<label'
+
+# Missing aria-invalid on error state
+grep -rn 'error\|invalid' src/ | grep '<input' | grep -v 'aria-invalid'
+
+# Missing aria-describedby on input with helper/error
+grep -rn '<input' src/ | grep -v 'aria-describedby'
+
+# type="number" on non-numeric semantic fields
+grep -rn 'type="number"' src/ | grep -i 'phone\|zip\|postal\|card'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: placeholder as label — disappears on type, fails contrast, not announced persistently -->
+<input type="text" placeholder="Email address" />
+```
+
+**Why it fails**: Placeholder has 40% opacity (below 4.5:1 AA), disappears when user types, and screen readers do not treat it as a persistent label.
+**Grep detection**: `grep -rn '<input' src/ | grep 'placeholder=' | grep -v 'aria-label\|id='`
+**Fix**:
+```html
+<label for="email">Email address</label>
+<input type="email" id="email" autocomplete="email" />
+```

package/reference/components/label.md

@@ -0,0 +1,200 @@
+# Label — Benchmark Spec
+
+**Harvested from**: WAI-ARIA APG, Carbon, Material 3, Mantine, Polaris, Atlassian, Fluent 2, shadcn/ui
+**Wave**: 1 · **Category**: Inputs
+
+---
+
+## Purpose
+
+A label is the visible text that identifies a form control to the user and to assistive technology. It is the most critical accessibility primitive in forms — every input, select, checkbox, radio, and switch MUST have an associated label. Labels are distinct from placeholders (which disappear) and from hints (which supplement but do not replace). *(WAI-ARIA APG, Carbon, Polaris, Atlassian all agree)*
+
+---
+
+## Anatomy
+
+```
+Label text *          ← <label for="id"> (static, above control)
+┌──────────────────┐
+│ Input            │  ← <input id="id">
+└──────────────────┘
+  Helper text
+
+Alternative (legend for group):
+<fieldset>
+  <legend>Group label</legend>  ← <legend> replaces <label> for groups
+  ...controls...
+</fieldset>
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Label text | Yes | Visible; descriptive; ≤40 chars preferred |
+| Required indicator | Conditional | `*` or "(required)"; always explained near form |
+| Optional indicator | Conditional | "(optional)" text is clearer than required asterisk |
+| Helper text | No | Below control; `aria-describedby` |
+| `for` / `id` association | Yes | OR `aria-label` / `aria-labelledby` on control |
+| Legend (groups) | Yes (groups) | Replaces `<label>` for `<fieldset>` groups |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Static label (above) | Fixed position above control — most accessible | Carbon, Polaris, Atlassian, Fluent |
+| Floating label | Starts inside control, floats up on focus/fill | Material 3, Mantine, shadcn |
+| Inline label | Label beside control (radio/checkbox) | All |
+| Legend | Group label inside `<fieldset>` | WAI-ARIA APG, all (for groups) |
+| Visually hidden | Accessible but not visible (e.g., search icon button) | WAI-ARIA APG, Carbon |
+
+**Norm** (≥5/18): static label above the control is the most accessible and implementation-simple approach — recommended as the default.
+**Diverge**: floating label — Material 3 and Mantine use it; Carbon, Polaris, Atlassian explicitly recommend static labels for a11y predictability. Floating labels require JavaScript, break if JS fails, and require careful `aria-*` management.
+
+---
+
+## States
+
+Labels are not interactive — they have no hover/focus states of their own. However:
+
+| Control State | Label Behaviour |
+|---------------|-----------------|
+| error | Label colour may shift to error colour (optional); error text replaces/appends helper |
+| disabled | Label at 38% opacity alongside disabled control |
+| required | Required indicator (`*`) added — never remove from DOM |
+| focus (on control) | Label may shift colour to primary (Material 3 floating) |
+
+---
+
+## Sizing & Spacing
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Font size | 14px (static); 12px (floating — small state) | |
+| Weight | 500 | Slightly heavier than body to distinguish |
+| Gap: label → control | 4–8px | *(Carbon: 4px, Material 3: 8px)* |
+| Required asterisk gap | 2px left of asterisk | |
+| Width | Match control width | Labels should not exceed their control |
+
+Cross-link: `reference/typography.md` — label sizing rules
+
+---
+
+## Typography
+
+- Label text: 14px/500 — slightly heavier than body 400; distinguishes from surrounding content
+- Required `*`: same size, colour matches error or primary brand colour
+- Visually-hidden labels: use CSS `.sr-only` pattern (clip + overflow: hidden + absolute), never `display:none` or `visibility:hidden`
+
+```css
+/* sr-only — label hidden visually but present for screen readers */
+.sr-only {
+  position: absolute;
+  width: 1px; height: 1px;
+  padding: 0; margin: -1px;
+  overflow: hidden;
+  clip: rect(0,0,0,0);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `label` (implicit on `<label>`)
+> **Required attributes**: `for="control-id"` on `<label>`, matching `id` on control
+
+### Association Methods (in order of preference)
+
+*Per WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/ — W3C — 2024*
+
+1. **`<label for="id">`** — native HTML; best browser + AT support; clicking label focuses control
+2. **`aria-labelledby="label-id"`** — when label cannot use `for` (complex composites)
+3. **`aria-label="string"`** — when no visible label is possible (icon-only controls); last resort
+4. **`<legend>` inside `<fieldset>`** — for groups of related controls; not replaceable by `aria-label`
+
+### Accessibility Rules
+
+- NEVER use `placeholder` as the only label — it disappears on input and fails colour contrast *(WAI-ARIA APG, WCAG 1.3.1)*
+- Required fields: mark with `aria-required="true"` on the control AND `*` visually; provide a form-level note explaining the `*` convention
+- Optional fields: prefer marking optional fields with "(optional)" text over marking every required field with `*` — reduces asterisk clutter in long forms *(Polaris, Carbon)*
+- Group labels: `<legend>` inside `<fieldset>` is the ONLY proper group label technique — `aria-label` on a `<div>` group is inadequate for radio/checkbox groups in most AT
+- Visually hidden labels: use `.sr-only` CSS — never `display:none` (removes from AT tree) or `visibility:hidden`
+
+---
+
+## Do / Don't
+
+### Do
+- Place labels above controls, not beside them, for forms wider than 240px *(Carbon, Polaris, Atlassian)*
+- Use `<label for="id">` — the click zone extends to the full label, improving usability *(WAI-ARIA APG, all)*
+- Explain the `*` required indicator once near the top of the form *(Polaris, Carbon)*
+- Use `<legend>` for groups — it is read before each option in the group *(WAI-ARIA APG)*
+
+### Don't
+- Don't use `placeholder` as the only label — it fails at 3 accessibility criteria *(WAI-ARIA APG, WCAG 1.3.1, 1.4.3)*
+- Don't use `display:none` on labels — removes them from the AT accessibility tree *(WAI-ARIA APG)*
+- Don't write labels as questions ("What is your name?") — prefer noun phrases ("Full name") *(Polaris, Carbon)*
+- Don't truncate label text — ellipsis hides required information from all users *(Atlassian, Carbon)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Placeholder-as-label | `reference/anti-patterns.md` |
+| display:none on accessible label | `reference/anti-patterns.md` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| `<label for>` clicking focuses control | HTML spec, WAI-ARIA APG |
+| legend for group labels (not aria-label) | WAI-ARIA APG, Carbon |
+| Static label above preferred over floating | Carbon, Polaris, Atlassian |
+| .sr-only pattern for hidden labels | WAI-ARIA APG, Carbon, Tailwind |
+| placeholder fails 3 a11y criteria | WAI-ARIA APG, WCAG 1.3.1, 1.4.3 |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Input with no associated label (no for/id, no aria-label)
+grep -rn '<input' src/ | grep -v 'type="hidden"\|type="submit"\|type="button"' \
+  | grep -v 'id=\|aria-label\|aria-labelledby'
+
+# Label using display:none (removed from AT tree)
+grep -rn 'display:\s*none\|display:none' src/ | grep -i 'label\|<label'
+
+# Placeholder used without separate label
+grep -rn 'placeholder=' src/ | grep -v 'aria-label\|<label\|aria-labelledby'
+
+# Group without fieldset/legend
+grep -rn 'type="radio"\|type="checkbox"' src/ | grep -v 'fieldset\|legend'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: label using display:none — completely removed from accessibility tree -->
+<label for="search" style="display:none">Search</label>
+<input type="text" id="search" placeholder="Search…">
+```
+
+**Why it fails**: `display:none` removes the label from the DOM accessibility tree. Screen readers see only the placeholder (which disappears on type and has low contrast). The input has no persistent accessible name.
+**Grep detection**: `grep -rn 'display:.*none' src/ | grep '<label\|label.*for'`
+**Fix**:
+```html
+<label for="search" class="sr-only">Search</label>
+<input type="text" id="search" placeholder="Search products…">
+```