@hegemonart/get-design-done 1.15.0 → 1.16.0

package/reference/components/tooltip.md

@@ -0,0 +1,201 @@
+# Tooltip — Benchmark Spec
+
+**Harvested from**: WAI-ARIA APG, Radix UI, Material 3, Carbon, Mantine, Fluent 2, Atlassian, Apple HIG
+**Wave**: 2 · **Category**: Containers
+
+---
+
+## Purpose
+
+A tooltip is a small, non-interactive label that appears on hover or keyboard focus to provide supplemental context for an element (typically an icon button or truncated text). It disappears on mouse-out, blur, or Escape. Tooltips MUST NOT contain interactive content (buttons, links, form elements). For interactive overlay content, use Popover. *(WAI-ARIA APG, Radix, Carbon all enforce this boundary)*
+
+---
+
+## Anatomy
+
+```
+[Icon button]  ← hover or focus triggers tooltip
+      │
+      ▼  (after 300ms delay)
+┌────────────┐
+│  Label     │  ← role="tooltip"; 12px; no interactive content
+└────────────┘
+     ▲  (optional 6px arrow caret)
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Trigger | Yes | Usually a button or interactive element |
+| Tooltip container | Yes | `role="tooltip"` + unique `id` |
+| Label text | Yes | Short (≤60 chars), descriptive |
+| Arrow | No | 6–8px caret indicating anchor |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default | Hover + focus triggered | All |
+| Delayed | 300ms show delay; 0ms hide | All (WAI-ARIA APG recommended) |
+| Instant | No delay (icon toolbars, dense UIs) | Material 3, Carbon |
+| Dark | Dark background regardless of theme | Most systems |
+| Light | Light background | Mantine (inverted) |
+
+**Norm** (≥7/18): 300ms show delay, 0ms hide; max-width 240px; never interactive content.
+**Diverge**: delay duration — Carbon recommends 100ms for toolbars; WAI-ARIA APG recommends ≤500ms. 300ms is the safe default.
+
+---
+
+## States
+
+| State | Trigger | ARIA |
+|-------|---------|------|
+| hidden | default | `role="tooltip"` hidden (not in tab order) |
+| visible (hover) | `mouseenter` (after delay) | `aria-describedby` on trigger points to tooltip id |
+| visible (focus) | `focusin` on trigger | same |
+| dismissed | `mouseleave`, `blur`, Escape | Tooltip hidden |
+
+---
+
+## Sizing & Spacing
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Max width | 240px | *(Material 3: 200px, Carbon: 288px, Fluent: 240px)* |
+| Padding | 6px 12px | |
+| Font size | 12px/400 | Smaller than body to signal supplemental role |
+| Border radius | 4–6px | Tight radius vs. card; feels like label |
+| Offset from trigger | 6–8px | |
+
+---
+
+## Typography
+
+- 12px/400 — tooltip text is supplemental; smaller weight and size distinguish it from primary content
+- No bold, no headings inside tooltip — it is a single line of text (≤60 chars preferred)
+- Multi-line: allowed if content genuinely requires it; still no interactive elements
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `tooltip`
+> **Trigger attributes**: `aria-describedby="tooltip-id"` — links the supplemental label
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | (on trigger) Shows tooltip when trigger receives focus |
+| Escape | Hides the tooltip |
+| Tab / Shift+Tab | Hides tooltip when focus leaves the trigger |
+
+Tooltip does NOT receive focus. It is purely a visual label attached to the trigger.
+
+### Accessibility Rules
+
+- Trigger MUST have `aria-describedby` pointing to the tooltip's `id` — screen readers read tooltip content as supplemental description
+- Tooltip is `role="tooltip"` — NOT `role="dialog"` (no interactivity, no focus trap)
+- Tooltip MUST appear on keyboard focus, not only on hover — keyboard-only users need access too *(WCAG 1.3.3, 2.1.1)*
+- Do NOT put interactive content inside a tooltip — use Popover (`reference/components/popover.md`)
+- Do NOT use tooltip as the only accessible name for a control — use `aria-label` on the trigger instead; tooltip supplements, not replaces, the accessible name
+- Escape MUST dismiss the tooltip without removing focus from the trigger *(WAI-ARIA APG)*
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Show | 100ms | ease-out | Fade only; no scale (too flashy for a label) |
+| Hide | 80ms | ease | Fade only; immediate on Escape |
+| Delay | 300ms | — | CSS `transition-delay` or JS timeout |
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip fade, instant show/hide
+
+---
+
+## Do / Don't
+
+### Do
+- Show on keyboard focus AND hover — not hover-only *(WAI-ARIA APG, WCAG 2.1.1)*
+- Use `aria-describedby` to link trigger to tooltip *(WAI-ARIA APG)*
+- Limit tooltip content to ≤60 chars — longer content belongs in a popover *(Carbon, Material 3)*
+- Apply 300ms show delay to prevent accidental triggers while cursor passes *(WAI-ARIA APG, Carbon)*
+
+### Don't
+- Don't put interactive elements inside a tooltip *(WAI-ARIA APG — this makes it a popover)*
+- Don't use tooltip as the only accessible name — `aria-describedby` supplements, not replaces, `aria-label` *(WAI-ARIA APG)*
+- Don't trigger tooltip on click — use a popover *(Radix, WAI-ARIA APG)*
+- Don't use tooltip for critical information — it's supplemental; users on touch devices may miss it *(Material 3, Polaris)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Interactive content inside tooltip | `reference/anti-patterns.md` |
+| Hover-only tooltip (not focus-triggered) | `reference/anti-patterns.md` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="tooltip" not role="dialog" | WAI-ARIA APG |
+| Show on focus AND hover | WAI-ARIA APG, WCAG 2.1.1 |
+| Escape dismisses without removing focus | WAI-ARIA APG §3.2 |
+| 300ms delay | WAI-ARIA APG, Carbon |
+| 240px max-width | Material 3, Fluent 2 |
+| No interactive content | WAI-ARIA APG (all systems agree) |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Tooltip triggered only on hover (not focus) — missing focusin handler
+grep -rn 'tooltip\|Tooltip' src/ | grep 'mouseenter\|onHover' | grep -v 'focus\|onFocus'
+
+# Interactive content inside tooltip
+grep -rn 'role="tooltip"' src/ | xargs grep -l 'button\|<a \|input' 2>/dev/null
+
+# Trigger missing aria-describedby
+grep -rn 'role="tooltip"' src/ | grep -v 'aria-describedby'
+
+# Tooltip without id (aria-describedby target requires id)
+grep -rn 'role="tooltip"' src/ | grep -v ' id='
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: tooltip shows on hover only, no focus trigger, no ARIA linkage -->
+<button class="icon-btn" onmouseenter="showTooltip()" onmouseleave="hideTooltip()">
+  <svg><!-- settings icon --></svg>
+</button>
+<div class="tooltip">Settings</div>
+```
+
+**Why it fails**: Keyboard users never see the tooltip. Screen readers receive no supplemental description. The `<div>` has no `role="tooltip"` and no `id`, so `aria-describedby` cannot link to it.
+**Grep detection**: `grep -rn 'mouseenter\|onHover' src/ | grep -i 'tooltip' | grep -v 'focus'`
+**Fix**:
+```html
+<button aria-describedby="settings-tip"
+        onmouseenter="show()" onmouseleave="hide()"
+        onfocusin="show()" onfocusout="hide()"
+        onkeydown="e.key==='Escape'&&hide()">
+  <svg aria-hidden="true"><!-- icon --></svg>
+  <span class="sr-only">Settings</span>
+</button>
+<div role="tooltip" id="settings-tip">Manage account settings</div>
+```

package/reference/registry.json

@@ -259,6 +259,108 @@
       "path": "reference/data/google-fonts.csv",
       "type": "data",
       "description": "Google Fonts catalog (representative sample of 1923-row UUPM data set)"
+    },
+    {
+      "name": "components-README",
+      "path": "reference/components/README.md",
+      "type": "taxonomy",
+      "description": "Component Benchmark Corpus index — Wave 1–5 tables, coverage summary, harvesting procedure"
+    },
+    {
+      "name": "components-TEMPLATE",
+      "path": "reference/components/TEMPLATE.md",
+      "type": "schema",
+      "description": "Locked 12-section spec shape for component benchmarks (Purpose → Failing example)"
+    },
+    {
+      "name": "component-accordion",
+      "path": "reference/components/accordion.md",
+      "type": "component-spec",
+      "description": "Accordion component spec — h2–h6 header, aria-expanded on trigger, CSS grid height animation"
+    },
+    {
+      "name": "component-button",
+      "path": "reference/components/button.md",
+      "type": "component-spec",
+      "description": "Button component spec — primary/secondary/ghost/destructive/icon-only; WAI-ARIA Enter/Space contract"
+    },
+    {
+      "name": "component-card",
+      "path": "reference/components/card.md",
+      "type": "component-spec",
+      "description": "Card component spec — stretched-link pattern, article semantics, nested interactive anti-pattern"
+    },
+    {
+      "name": "component-checkbox",
+      "path": "reference/components/checkbox.md",
+      "type": "component-spec",
+      "description": "Checkbox component spec — fieldset+legend, indeterminate state, aria-checked=mixed"
+    },
+    {
+      "name": "component-drawer",
+      "path": "reference/components/drawer.md",
+      "type": "component-spec",
+      "description": "Drawer component spec — focus trap, swipe-to-close, nav vs content role distinction"
+    },
+    {
+      "name": "component-input",
+      "path": "reference/components/input.md",
+      "type": "component-spec",
+      "description": "Input component spec — placeholder-as-label anti-pattern, aria-describedby error linking"
+    },
+    {
+      "name": "component-label",
+      "path": "reference/components/label.md",
+      "type": "component-spec",
+      "description": "Label component spec — 4 association methods, .sr-only pattern, legend for groups"
+    },
+    {
+      "name": "component-link",
+      "path": "reference/components/link.md",
+      "type": "component-spec",
+      "description": "Link component spec — a[href] vs button boundary, WCAG 1.4.1 underline, rel=noopener"
+    },
+    {
+      "name": "component-modal-dialog",
+      "path": "reference/components/modal-dialog.md",
+      "type": "component-spec",
+      "description": "Modal dialog spec — focus trap, Escape contract, aria-modal, aria-labelledby, scroll-lock"
+    },
+    {
+      "name": "component-popover",
+      "path": "reference/components/popover.md",
+      "type": "component-spec",
+      "description": "Popover spec — Floating UI middlewares, non-modal, aria-expanded+aria-controls"
+    },
+    {
+      "name": "component-radio",
+      "path": "reference/components/radio.md",
+      "type": "component-spec",
+      "description": "Radio component spec — arrow-key auto-advance, Tab-as-group-unit, single-radio anti-pattern"
+    },
+    {
+      "name": "component-select-combobox",
+      "path": "reference/components/select-combobox.md",
+      "type": "component-spec",
+      "description": "Select/combobox spec — WAI-ARIA listbox + combobox contracts, aria-activedescendant"
+    },
+    {
+      "name": "component-switch",
+      "path": "reference/components/switch.md",
+      "type": "component-spec",
+      "description": "Switch component spec — role=switch, spring thumb, pill track, immediate-action rule"
+    },
+    {
+      "name": "component-tabs",
+      "path": "reference/components/tabs.md",
+      "type": "component-spec",
+      "description": "Tabs component spec — roving tabindex, arrow-key nav, automatic vs manual activation"
+    },
+    {
+      "name": "component-tooltip",
+      "path": "reference/components/tooltip.md",
+      "type": "component-spec",
+      "description": "Tooltip spec — no interactive content, hover+focus trigger, 300ms delay, aria-describedby"
     }
   ]
 }

package/reference/registry.schema.json

@@ -37,7 +37,8 @@
               "emotional-design",
               "experience",
               "palette",
-              "style-vocabulary"
+              "style-vocabulary",
+              "component-spec"
             ]
           },
           "tier": { "enum": ["L0", "L1", "L2"] },

package/skills/benchmark/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: gdd-benchmark
+description: Harvest and synthesize per-component design benchmarks from 18 design systems. Produces canonical specs at reference/components/<name>.md.
+argument-hint: "<component> | --wave <N> | --list | --refresh <component>"
+tools: Read, Write, Bash, Grep, Glob, Task, WebFetch
+---
+
+# /gdd:benchmark
+
+Harvest per-component design knowledge from 18 design systems and synthesize canonical
+specs at `reference/components/<name>.md`.
+
+## Invocation Modes
+
+| Invocation | Action |
+|------------|--------|
+| `/gdd:benchmark <component>` | Harvest + synthesize a single component |
+| `/gdd:benchmark --wave <N>` | Run a full wave (1 = Inputs, 2 = Containers, etc.) |
+| `/gdd:benchmark --list` | Show corpus coverage — which specs exist, which are pending |
+| `/gdd:benchmark --refresh <component>` | Re-harvest a spec (for design-system version bumps) |
+
+## Single-Component Flow (`/gdd:benchmark <component>`)
+
+1. **Check if spec exists** — `Glob("reference/components/<component>.md")`.
+   If found and `--refresh` was not passed, confirm before overwriting.
+
+2. **Harvest** — spawn `component-benchmark-harvester` with:
+   ```
+   Task("component-benchmark-harvester", """
+   <required_reading>
+   @connections/design-corpora.md
+   </required_reading>
+
+   Harvest design-system excerpts for component: <component>
+   Emit raw harvest to: .planning/benchmarks/raw/<component>.md
+   Consume any relevant content from: .planning/research/impeccable-salvage/
+
+   Acceptance: .planning/benchmarks/raw/<component>.md exists with ≥4 source sections.
+   """)
+   ```
+
+3. **Synthesize** — spawn `component-benchmark-synthesizer` with:
+   ```
+   Task("component-benchmark-synthesizer", """
+   <required_reading>
+   @.planning/benchmarks/raw/<component>.md
+   @reference/components/TEMPLATE.md
+   @reference/anti-patterns.md
+   </required_reading>
+
+   Synthesize the raw harvest into a canonical spec.
+   Output: reference/components/<component>.md
+   Update: reference/components/README.md (add entry in correct category)
+
+   Acceptance: spec exists, ≤350 lines, cites ≥4 systems, has TEMPLATE.md sections,
+   WAI-ARIA keyboard contract present, failing-example block present.
+   """)
+   ```
+
+4. **Report** — print spec path, line count, systems cited.
+
+## Wave Mode (`/gdd:benchmark --wave <N>`)
+
+Read the wave definition from `reference/components/README.md` and run each component
+in the wave sequentially (not parallel — each harvest is network-bound and the raw files
+are large).
+
+| Wave | Components |
+|------|-----------|
+| 1 | button, input, select-combobox, checkbox, radio, switch, link, label |
+| 2 | card, modal-dialog, drawer, popover, tooltip, accordion, tabs |
+
+Print progress per component: `[N/total] harvesting <component>…`
+
+## List Mode (`/gdd:benchmark --list`)
+
+Read `reference/components/README.md` and diff against `reference/components/*.md` files.
+Print a table:
+
+```
+Component        Status   Wave  Lines
+button           ✓        1     248
+input            ✓        1     312
+select-combobox  ✓        1     295
+...
+toast            pending  3     —
+```
+
+## Refresh Mode (`/gdd:benchmark --refresh <component>`)
+
+Same as single-component flow but skips the "already exists" guard. Use when a design
+system ships a breaking update to a component's spec.
+
+## Source List
+
+`connections/design-corpora.md` — 18 design systems with canonical URLs, licensing, and
+fallback chain (canonical → archive.org → Refero MCP → Pinterest MCP).
+
+## Output Artifacts
+
+| Artifact | Purpose |
+|----------|---------|
+| `.planning/benchmarks/raw/<component>.md` | Raw multi-source harvest (input only) |
+| `reference/components/<component>.md` | Canonical spec (distributed with plugin) |
+| `reference/components/README.md` | Corpus index (updated by synthesizer) |