@hegemonart/get-design-done 1.15.0 → 1.18.0

package/reference/components/card.md

@@ -0,0 +1,200 @@
+# Card — Benchmark Spec
+
+**Harvested from**: Material 3, Polaris, Carbon, Atlassian, Mantine, shadcn/ui, Ant Design, Fluent 2
+**Wave**: 2 · **Category**: Containers
+
+---
+
+## 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)*
+
+---
+
+## Anatomy
+
+```
+┌────────────────────────────┐  ← card surface (border/shadow/background)
+│ [Media / Image]            │  ← optional, always with alt text
+│────────────────────────────│
+│ Eyebrow / Category         │  ← optional; 12px/600 uppercase
+│ Title                      │  ← primary label; ≥16px
+│ Description                │  ← supporting text; 14px/400
+│────────────────────────────│
+│ [Action 1] [Action 2]      │  ← optional action area
+└────────────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Container | Yes | `<article>` for standalone content; `<div>` for layout |
+| Title | Yes | Descriptive; h2/h3 depending on hierarchy |
+| Content | Yes | Body text, metadata, or media |
+| Media / image | No | Always provide `alt`; decorative images use `alt=""` |
+| Actions | No | Keep ≤2 primary actions per card |
+| Footer / metadata | No | 12px/400; secondary information |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Elevated | Drop shadow; floats above surface | Material 3, shadcn |
+| Outlined | Border, no shadow | Material 3, Carbon, Polaris |
+| Filled | Filled background, no shadow or border | Material 3, Mantine |
+| Clickable / Interactive | Entire card is a link or button | Material 3, Polaris, Carbon |
+| Horizontal | Media left, content right | Carbon, Polaris, Atlassian |
+| 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).
+
+---
+
+## States
+
+| 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 | — |
+| selected | programmatic | Border + background tint | `aria-selected="true"` |
+| loading | async content | Skeleton placeholder | `aria-busy="true"` |
+| disabled | programmatic | 38% opacity | `aria-disabled="true"` |
+
+---
+
+## Sizing & Spacing
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Padding | 16px (sm), 20px (md), 24px (lg) | *(Carbon: 16px default, Material 3: 16px)* |
+| Border radius | Use token; match `reference/surfaces.md` concentric rule | |
+| Media aspect ratio | 16:9 (landscape), 1:1 (square) | `object-fit: cover` |
+| Min width | 240px | Prevents content collapse |
+| 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
+
+---
+
+## Typography
+
+- Title: 16–20px/600 depending on card prominence (h2/h3 in DOM hierarchy)
+- Eyebrow: 11px/600 uppercase, muted colour
+- Body: 14px/400
+- Metadata: 12px/400 muted
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: No specific card role. Use `<article>` for independent pieces of content; `<li>` in a list of cards; `<div>` for layout grouping.
+
+### Clickable Card Rules
+
+*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
+- 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
+
+- Card with image: always provide `alt`; use `alt=""` for decorative images
+- Clickable card: heading inside card should be the accessible name (via `aria-labelledby` or the stretched-link pattern)
+- Card grid: use `role="list"` on the grid container and `role="listitem"` on each card, or a semantic `<ul>/<li>` structure, so screen readers announce item count
+- Loading skeleton: add `aria-busy="true"` on the card container; remove when content loads
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| hover shadow | 150ms | ease-out | Elevation increase |
+| 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`
+
+---
+
+## Do / Don't
+
+### Do
+- Use `<article>` when the card is an independent, self-contained piece of content *(Carbon, Polaris)*
+- Keep clickable cards to a single primary action; surface secondary actions as explicit buttons *(Material 3, Polaris)*
+- Use the stretched-link (`::after`) pattern for clickable cards with nested links/buttons *(Carbon, Bootstrap pattern)*
+- Provide `alt` text for all card images, or `alt=""` for decorative images *(WCAG 1.1.1)*
+
+### Don't
+- 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)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Nested interactive elements in clickable container | `reference/anti-patterns.md` |
+| Missing alt on card media | `reference/anti-patterns.md` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| ≤2 actions per card | Material 3, Polaris, Carbon |
+| Stretched-link pattern for nested interactivity | Carbon, Bootstrap |
+| article element for standalone card content | Carbon, Polaris |
+| 16px default padding | Carbon, Material 3 |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Entire card wrapped in <a> with nested buttons/links
+grep -rn '<a ' src/ | grep -i 'card' | xargs grep -l 'button\|<a ' 2>/dev/null
+
+# Clickable div without role
+grep -rn 'class.*card\|data-testid.*card' src/ | grep 'onClick\|on:click' | grep -v 'role='
+
+# Card image without alt
+grep -rn '<img' src/ | grep -i 'card' | grep -v 'alt='
+
+# Missing heading hierarchy in card
+grep -rn 'class.*card' src/ | xargs grep -L 'h[1-6]\|aria-label' 2>/dev/null
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: entire card is <a> but contains a button — button is inaccessible by keyboard in most AT -->
+<a href="/product/42" class="card">
+  <img src="product.jpg" />
+  <h3>Product Name</h3>
+  <p>Description…</p>
+  <button onclick="addToCart(42)">Add to cart</button>
+</a>
+```
+
+**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`.

package/reference/components/checkbox.md

@@ -0,0 +1,207 @@
+# Checkbox — Benchmark Spec
+
+**Harvested from**: Material 3, Carbon, Polaris, Ant Design, WAI-ARIA APG, Mantine, Chakra UI, Atlassian
+**Wave**: 1 · **Category**: Inputs
+
+---
+
+## 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>`.
+
+---
+
+## Anatomy
+
+```
+┌──┐  Label text
+│✓ │  ← <input type="checkbox" id="x"> (or role="checkbox")
+└──┘  Helper text (opt.)
+      Error message (opt.)
+
+Group:
+<fieldset>
+  <legend>Preferences</legend>
+  [checkbox] Option A
+  [checkbox] Option B
+  [checkbox] Option C (indeterminate)
+</fieldset>
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Input / control | Yes | Native `<input type="checkbox">` preferred |
+| 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 |
+| Indeterminate indicator | Conditional | Dash/minus mark; set via `.indeterminate = true` (JS) |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default | Binary checked / unchecked | All |
+| Indeterminate | Partial selection indicator (parent of group) | Material 3, Carbon, Ant, Mantine |
+| Standalone | Single checkbox (e.g. "I agree to terms") | All |
+| 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.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| 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 | — |
+| 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"` |
+
+---
+
+## Sizing & Spacing
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Control size | 16×16px (20px touch target via pseudo-element) | *(Carbon, Polaris, Material 3)* |
+| Gap: control → label | 8px | |
+| Label min click zone | Full row width | Increases tap target |
+| 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)
+
+---
+
+## Typography
+
+- 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
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `checkbox` (implicit on `<input type="checkbox">`)
+> **Required attributes**: `aria-checked` (if not native); `aria-describedby` for helper/error
+
+### Keyboard Contract
+
+*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).
+
+### 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
+- 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`
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| check fill | 120ms | ease-out | SVG path draw or scale from center |
+| 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
+
+---
+
+## Do / Don't
+
+### Do
+- Use `<fieldset>` + `<legend>` for every group *(WAI-ARIA APG, Carbon, Polaris)*
+- Set indeterminate via `.indeterminate = true` AND `aria-checked="mixed"` *(WAI-ARIA APG, Mantine)*
+- Make the entire label row clickable, not just the box *(Material 3, Carbon, Polaris)*
+- 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 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)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Custom checkbox without role | `reference/anti-patterns.md` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| Space toggles checkbox | WAI-ARIA APG §3.5 |
+| fieldset+legend required for group | WAI-ARIA APG, Carbon, Polaris |
+| .indeterminate = true (JS only) | WAI-ARIA APG, MDN |
+| 16px control size | Carbon, Polaris, Material 3 |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Custom checkbox div/span without role="checkbox"
+grep -rn 'class.*checkbox\|type.*checkbox' src/ | grep '<div\|<span' | grep -v 'role='
+
+# Missing label association
+grep -rn 'type="checkbox"' src/ | grep -v 'id=\|aria-label'
+
+# Group without fieldset
+grep -rn 'checkbox' src/ | grep -v 'fieldset\|role="group"'
+
+# Indeterminate set via attribute instead of JS
+grep -rn 'indeterminate' src/ | grep 'setAttribute\|attr(' | grep '"true"'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: checkboxes in a group without fieldset/legend — group context lost for screen readers -->
+<div>
+  <p>Notification preferences</p>
+  <input type="checkbox" id="email"> <label for="email">Email</label>
+  <input type="checkbox" id="sms"> <label for="sms">SMS</label>
+</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.
+**Grep detection**: `grep -B5 'type="checkbox"' src/ | grep -v 'fieldset\|role="group"'`
+**Fix**:
+```html
+<fieldset>
+  <legend>Notification preferences</legend>
+  <input type="checkbox" id="email"> <label for="email">Email</label>
+  <input type="checkbox" id="sms"> <label for="sms">SMS</label>
+</fieldset>
+```

package/reference/components/chip.md

@@ -0,0 +1,209 @@
+# Chip / Tag — Benchmark Spec
+
+**Harvested from**: Material 3, Carbon, Atlassian, Mantine
+**Wave**: 3 · **Category**: Feedback
+
+---
+
+## 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)*
+
+*UUPM app-interface: filter chips in search/filter UIs and tag input patterns (MIT attribution)*
+
+---
+
+## Anatomy
+
+```
+┌───────────────────────────────┐
+│ [icon?]  Label text  [✕ remove?] │
+└───────────────────────────────┘
+↑ role varies by variant
+↑ touch target ≥ 32px height
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Label text | Yes | Concise (1–3 words typical) |
+| Container | Yes | Interactive element; role/type depends on variant |
+| Leading icon | No | 16px; left-aligned; 8px gap to label |
+| Remove button | Conditional | Required on input/tag chips; independent focusable element |
+| Selected state indicator | Conditional | Checkmark or filled style on toggled filter chips |
+
+---
+
+## Variants
+
+| Variant | Interaction | Role | Systems |
+|---------|-------------|------|---------|
+| Filter | Toggleable; multi-select | `aria-pressed` or `role="option"` in `role="listbox"` | Material 3, Carbon, Atlassian, Mantine |
+| Input / Tag | User-generated; removable via × button | `role="option"` in combobox; or `role="listbox"` child | Material 3, Atlassian, Mantine |
+| Suggestion | One-time select; fires an action then typically disappears | `role="button"` | Material 3, Mantine |
+| Display | Static label; no interaction | No role needed (or `role="listitem"`) | Atlassian (Lozenge), Carbon (Tag), Mantine |
+
+**Norm** (≥4/18 systems agree): filter chip uses `aria-pressed` for standalone toggles; input chip requires independent remove button with its own `aria-label`; display chip is decorative/static.
+**Diverge**: Material 3 calls static chips "Suggestion chips" when one-time-action and "Assist chips" for shortcut actions; Atlassian separates "Tag" (removable) from "Lozenge" (static status label); Carbon calls them "Tag" uniformly with a `filter` prop.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| 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 × | — |
+
+---
+
+## Sizing & Spacing
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Height | 32px (min touch target) | Do not reduce below 32px |
+| Padding-x | 12px | Each side; 8px when leading icon present |
+| Gap (icon → label) | 8px | |
+| Gap (label → remove ×) | 4px | |
+| Remove button size | 20×20px (visual); 32×32px (touch) | Extend touch area with padding |
+| Border radius | 16–20px (full pill) | *(Material 3: full-radius pill; Carbon: 4px; Atlassian: 2px)* |
+| Font size | 13–14px / 400 | |
+
+**Norm**: pill shape (full-radius) for filter and input chips *(Material 3, Mantine)*; Touch target ≥ 32px height *(WCAG 2.5.5, Material 3)*.
+
+---
+
+## 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
+- 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
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `button` (filter standalone, suggestion); `option` inside `listbox` (filter group, input chips)
+> **Required attributes**: `aria-pressed` on standalone filter chip; `aria-label` on remove button; `aria-selected` if `role="option"`
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/listbox/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | Moves focus to the chip or to the remove (×) button |
+| Enter / Space | Toggles filter chip (pressed/unpressed); activates suggestion chip |
+| Delete / Backspace | Removes an input/tag chip (when chip or its remove button has focus) |
+| Arrow Left / Right | Navigates between chips when inside a `role="listbox"` group |
+| Escape | Collapses chip group if it was expanded (e.g. overflow +N pattern) |
+
+### 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 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 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)*
+
+Cross-link: `reference/accessibility.md` — `aria-pressed`, `listbox`, touch targets
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Toggle selected (background fill) | 100ms | ease-out | Background + checkmark appear |
+| Chip remove (collapse width) | 150ms | ease-in | Width collapses to 0, siblings shift |
+| 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).
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip width animation, instant add/remove
+
+---
+
+## Do / Don't
+
+### Do
+- Add `aria-pressed` to standalone filter chips *(WAI-ARIA APG)*
+- Give remove buttons an independent `aria-label`: "Remove [label] tag" *(WAI-ARIA APG, Material 3)*
+- Use `role="listbox"` + `role="option"` for multi-select filter chip groups *(WAI-ARIA APG)*
+- 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)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Filter chip without aria-pressed | `reference/anti-patterns.md#ban-aria-pressed` |
+| Remove button without aria-label | `reference/anti-patterns.md#ban-aria-label` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| aria-pressed on standalone filter chip | WAI-ARIA APG, Material 3, Carbon |
+| Remove button independent aria-label | WAI-ARIA APG, Material 3, Atlassian |
+| role="option" inside role="listbox" for group | WAI-ARIA APG |
+| Touch target ≥ 32px height | WCAG 2.5.5, Material 3 |
+| Delete/Backspace removes input chip | Material 3, Atlassian, Mantine |
+| UUPM filter/tag-input patterns | UUPM app-interface (MIT) |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Filter chip missing aria-pressed
+grep -rn 'chip\|Chip\|filter-tag\|filterChip' src/ | grep -i 'filter\|toggle' | grep -v 'aria-pressed'
+
+# Remove button on chip missing aria-label
+grep -rn 'chip.*remove\|tag.*remove\|remove.*chip\|remove.*tag' src/ | grep -v 'aria-label'
+
+# Chip remove button without independent tab stop (not a separate button element)
+grep -rn 'chip\|tag' src/ | grep '×\|&times;\|✕\|close' | grep -v '<button\|role="button"'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: filter chip with no aria-pressed — screen readers cannot report toggle state -->
+<div class="chip chip--filter" onclick="toggleFilter(this)">
+  Python
+</div>
+```
+
+**Why it fails**: `<div>` is not keyboard reachable. No `aria-pressed` means screen readers cannot determine if the filter is active or inactive. No `role="button"` or `tabindex` so keyboard users skip it entirely. No focus-visible ring.
+**Grep detection**: `grep -rn 'chip--filter\|filterChip\|chip.*filter' src/ | grep -v 'aria-pressed'`
+**Fix**:
+```html
+<button class="chip chip--filter"
+        aria-pressed="false"
+        onclick="toggleFilter(this)">
+  Python
+</button>
+```
+Update `aria-pressed` to `"true"` when selected.