@adia-ai/web-components 0.3.1 → 0.3.3

package/README.md

@@ -110,7 +110,7 @@ file using **two-block `@scope`**:
 }
 ```
 
-Authoring rules (enforced by `coherence-audit`):
+Authoring rules (enforced by `ui-audit-coherence`):
 
 1. **No raw colors** in component CSS — every color goes through a token.
 2. **Variants change tokens, modes change layout.** A selector that sets

package/components/nav-group/nav-group.css

@@ -9,6 +9,7 @@
     --nav-group-font-size:     var(--a-ui-size);
     --nav-group-font-size-sm:  var(--a-ui-sm);
     --nav-group-font-size-lg:  var(--a-ui-lg);
+    --nav-group-font-weight:   var(--a-font-weight-normal);
     --nav-group-fg:            var(--a-fg);
     --nav-group-fg-hover:      var(--a-fg-strong);
     --nav-group-fg-muted:      var(--a-fg-muted);
@@ -27,6 +28,7 @@
     flex-direction: column;
     gap: var(--nav-gap);
     position: relative;
+    font-weight: var(--nav-group-text-weight);
   }
 
   /* Continuous indent rail */

package/components/nav-item/nav-item.css

@@ -15,7 +15,6 @@ nav-item-ui:hover [slot="icon"] {
 nav-item-ui[selected] {
   background: var(--nav-item-bg-selected);
   color: var(--nav-item-fg-selected);
-  font-weight: var(--nav-item-selected-weight);
 }
 nav-item-ui[selected] [slot="icon"] {
   color: var(--nav-item-icon-fg-selected);
@@ -40,6 +39,7 @@ nav-item-ui[selected] [slot="icon"]:empty::before {
     --nav-item-font-size:       var(--a-ui-size);
     --nav-item-font-size-sm:    var(--a-ui-sm);
     --nav-item-font-size-lg:    var(--a-ui-lg);
+    --nav-item-font-weight:     var(--a-font-weight-normal);
     --nav-item-fg:              var(--a-ui-text-subtle);
     --nav-item-fg-hover:        var(--a-ui-text-hover);
     --nav-item-fg-selected:     var(--a-ui-text-selected);
@@ -68,6 +68,7 @@ nav-item-ui[selected] [slot="icon"]:empty::before {
       background var(--nav-duration-fast) var(--nav-easing),
       color var(--nav-duration-fast) var(--nav-easing);
     outline: none;
+    font-weight: var(--nav-item-font-weight);
   }
 
   :scope:focus-visible {

package/components/table-toolbar/table-toolbar.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/TableToolbar.json",
   "title": "TableToolbar",
-  "description": "Header / companion bar for a sibling table-ui. Renders title + count badge, filter / sort / columns popovers, and a search input — all wired to the target table via an [for] id-ref. Modeled on chart-legend-ui's [for] binding pattern. Drop next to (or above) any table-ui to add the standard data-grid toolbar without re-implementing search, filter, sort, or column visibility. Filter rows auto-pick a primitive per column: ≤ 50 distinct values → multi- select (searchable above 12 options), id-like keys → free-text contains. The column descriptor's `filter` field overrides the auto-detect: `'select'` forces multi-select even on high-cardinality columns; `'text'` forces a contains input even on small enums.",
+  "description": "Header / companion bar for a sibling table-ui. Renders title + count badge, filter / sort / columns popovers, and a search input — all wired to the target table via an [for] id-ref. Modeled on chart-legend-ui's [for] binding pattern. Drop next to (or above) any table-ui to add the standard data-grid toolbar without re-implementing search, filter, sort, or column visibility. Filter rows auto-pick a primitive per column: ≤ 50 distinct values → multi- select (searchable when ≥ 12 options), id-like keys → free-text contains. The column descriptor's `filter` field overrides the auto-detect: `'select'` forces multi-select even on high-cardinality columns; `'text'` forces a contains input even on small enums.",
   "type": "object",
   "allOf": [
     {
@@ -52,7 +52,7 @@
       "default": "Search..."
     },
     "text": {
-      "description": "Title text shown on the left. Alternative to slotted heading content.",
+      "description": "Title text shown on the left.",
       "type": "string",
       "default": ""
     },
@@ -117,9 +117,6 @@
       "popover"
     ],
     "slots": {
-      "default": {
-        "description": "Optional title content. Used when [text] is empty."
-      },
       "actions": {
         "description": "Trailing action area — primary buttons (e.g. \"New row\") rendered after the search input."
       }
@@ -163,30 +160,6 @@
       "--table-toolbar-gap": {
         "description": "Gap between toolbar clusters"
       },
-      "--table-toolbar-popover-bg": {
-        "description": "Popover background"
-      },
-      "--table-toolbar-popover-border": {
-        "description": "Popover border"
-      },
-      "--table-toolbar-popover-fg": {
-        "description": "Popover text color"
-      },
-      "--table-toolbar-popover-gap": {
-        "description": "Popover content gap"
-      },
-      "--table-toolbar-popover-min": {
-        "description": "Popover minimum width"
-      },
-      "--table-toolbar-popover-pad": {
-        "description": "Popover padding"
-      },
-      "--table-toolbar-popover-radius": {
-        "description": "Popover radius"
-      },
-      "--table-toolbar-popover-shadow": {
-        "description": "Popover shadow"
-      },
       "--table-toolbar-px": {
         "description": "Horizontal padding"
       },

package/components/table-toolbar/table-toolbar.css

@@ -22,29 +22,10 @@
     --table-toolbar-search-min:    14rem;
     --table-toolbar-search-max:    22rem;
 
-    /* ── Popover ── */
-    --table-toolbar-popover-bg:           var(--a-canvas);
-    --table-toolbar-popover-fg:           var(--a-canvas-text);
-    --table-toolbar-popover-border:       var(--a-border);
-    --table-toolbar-popover-radius:       var(--a-radius-lg);
-    --table-toolbar-popover-shadow:       var(--a-shadow-lg);
-    --table-toolbar-popover-pad:          var(--a-space-2);
-    --table-toolbar-popover-gap:          var(--a-space-1);
-    --table-toolbar-popover-min:          16rem;
-    --table-toolbar-popover-head-fg:      var(--a-fg-muted);
-    --table-toolbar-popover-head-size:    var(--a-ui-tiny);
-    --table-toolbar-popover-head-pad:     var(--a-space-2);
-    --table-toolbar-popover-row-pad:      var(--a-space-2);
-    --table-toolbar-popover-row-radius:   var(--a-radius-sm);
-    --table-toolbar-popover-row-bg-hover: var(--a-bg-hover);
-    --table-toolbar-popover-input-bg:     var(--a-bg-subtle);
-    --table-toolbar-popover-input-border: var(--a-border-subtle);
-    --table-toolbar-popover-input-radius: var(--a-radius-sm);
-    --table-toolbar-popover-input-py:     var(--a-space-1);
-    --table-toolbar-popover-input-px:     var(--a-space-2);
-    --table-toolbar-popover-input-size:   var(--a-ui-sm);
-    --table-toolbar-popover-action-fg:    var(--a-accent);
-    --table-toolbar-popover-action-size:  var(--a-ui-sm);
+    /* Popover tokens removed — popover escapes to top layer and
+       cannot inherit @scope tokens. Raw --a-* tokens are used
+       directly in the unscoped popover rules below (see comment
+       at the rules block). */
   }
 
   /* ═══════ Base ═══════ */

package/components/table-toolbar/table-toolbar.yaml

@@ -11,7 +11,7 @@ description: >-
   pattern. Drop next to (or above) any table-ui to add the standard data-grid
   toolbar without re-implementing search, filter, sort, or column visibility.
   Filter rows auto-pick a primitive per column: ≤ 50 distinct values → multi-
-  select (searchable above 12 options), id-like keys → free-text contains. The
+  select (searchable when ≥ 12 options), id-like keys → free-text contains. The
   column descriptor's `filter` field overrides the auto-detect: `'select'`
   forces multi-select even on high-cardinality columns; `'text'` forces a
   contains input even on small enums.
@@ -22,7 +22,7 @@ props:
     default: ""
     reflect: true
   text:
-    description: Title text shown on the left. Alternative to slotted heading content.
+    description: Title text shown on the left.
     type: string
     default: ""
   count:
@@ -75,8 +75,6 @@ events:
   columns-change:
     description: "Column visibility changed. Detail: { hiddenColumns }."
 slots:
-  default:
-    description: Optional title content. Used when [text] is empty.
   actions:
     description: Trailing action area — primary buttons (e.g. "New row") rendered after the search input.
 states:
@@ -102,22 +100,6 @@ tokens:
     description: Title font size
   --table-toolbar-title-weight:
     description: Title font weight
-  --table-toolbar-popover-bg:
-    description: Popover background
-  --table-toolbar-popover-fg:
-    description: Popover text color
-  --table-toolbar-popover-border:
-    description: Popover border
-  --table-toolbar-popover-radius:
-    description: Popover radius
-  --table-toolbar-popover-shadow:
-    description: Popover shadow
-  --table-toolbar-popover-pad:
-    description: Popover padding
-  --table-toolbar-popover-gap:
-    description: Popover content gap
-  --table-toolbar-popover-min:
-    description: Popover minimum width
 a2ui:
   rules: []
 anti_patterns: []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "AdiaUI web components \u2014 vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "exports": {

package/styles/README.md

@@ -0,0 +1,286 @@
+# AdiaUI Token Surface
+
+Consumable design-token reference for component authors.
+
+> **Rule of thumb:** Components consume **L3 semantic aliases** (`--a-fg`, `--a-bg-hover`, `--a-accent`). They never reference L1 primitives (`--a-neutral-50`) directly. The L3 layer maps to L2 families (`--a-canvas-text`), which map to L1 primitives (`--a-neutral-50`).
+
+---
+
+## Token layers
+
+| Layer | Files | When to use |
+|-------|-------|-------------|
+| **L1 — Primitives** | `colors/parameters.css`, `colors/primitives.css` | Token system authors only. OKLCH base values, hue ramps, neutral scales. |
+| **L2 — Families** | `colors/semantics.css` | Component authors building *new* semantic aliases not yet in L3. Maps primitives to semantic meaning (`--a-canvas-text`, `--a-danger-muted`). |
+| **L3 — Semantic aliases** | `colors/semantics.css` (short-alias section) | **All component CSS.** The stable public API: `--a-fg`, `--a-bg`, `--a-accent`, `--a-border-subtle`. |
+| **Dynamic / Theme** | `themes.css`, `colors/surfaces.css` | Theme authors. Per-theme hue shifts, density, radius overrides. |
+| **Typography** | `typography.css` | Component authors for font-size, weight, leading, tracking. |
+| **Spacing** | `tokens.css` | Component authors for padding, margin, gap. |
+| **Chrome** | `tokens.css` | Shell / layout authors for chrome dimensions (header/footer/toolbar heights). |
+| **Shadows** | `tokens.css` | Elevation authors. `--a-shadow-sm/md/lg`. |
+| **Timing** | `tokens.css` | Motion authors. `--a-duration`, `--a-easing`. |
+
+---
+
+## L3 Color API (the tokens components consume)
+
+### Neutral surfaces (`--a-canvas-*` → `--a-bg-*` / `--a-fg-*`)
+
+| Token | Purpose | Example use |
+|-------|---------|-------------|
+| `--a-bg` | Default surface (page bg, panel bg) | `body { background: var(--a-bg); }` |
+| `--a-bg-subtle` | Alternating rows, card backgrounds | `.card { background: var(--a-bg-subtle); }` |
+| `--a-bg-muted` | Disabled / inactive surfaces | `[disabled] { background: var(--a-bg-muted); }` |
+| `--a-bg-strong` | Active track, selected chips | `.track-active { background: var(--a-bg-strong); }` |
+| `--a-bg-hover` | Hover state backgrounds | `:hover { background: var(--a-bg-hover); }` |
+| `--a-bg-active` | Pressed / active state | `:active { background: var(--a-bg-active); }` |
+| `--a-bg-selected` | Selected item background | `[aria-selected="true"] { background: var(--a-bg-selected); }` |
+| `--a-bg-disabled` | Disabled state background | `[disabled] { background: var(--a-bg-disabled); }` |
+| `--a-bg-invalid` | Invalid / error state background | `[aria-invalid="true"] { background: var(--a-bg-invalid); }` |
+| `--a-bg-scrim` | Modal overlay backdrop | `.modal-overlay { background: var(--a-bg-scrim); }` |
+| `--a-fg` | Default text | `body { color: var(--a-fg); }` |
+| `--a-fg-subtle` | Secondary text, descriptions | `.description { color: var(--a-fg-subtle); }` |
+| `--a-fg-muted` | Placeholder text, timestamps | `.timestamp { color: var(--a-fg-muted); }` |
+| `--a-fg-strong` | Headings, emphasized text | `h1 { color: var(--a-fg-strong); }` |
+| `--a-fg-inverse` | Text on dark/brand buttons | `.button-primary { color: var(--a-fg-inverse); }` |
+
+### Borders
+
+| Token | Purpose |
+|-------|---------|
+| `--a-border-subtle` | Dividers, hairlines |
+| `--a-border` | Default borders, input outlines |
+| `--a-border-strong` | Focus rings, active borders |
+| `--a-border-hover` | Hover state borders |
+| `--a-border-active` | Active/pressed borders |
+| `--a-border-selected` | Selected item borders |
+| `--a-border-invalid` | Error state borders |
+| `--a-border-disabled` | Disabled borders |
+
+### Accent (interactive)
+
+| Token | Purpose |
+|-------|---------|
+| `--a-accent` | Primary accent color (buttons, links, active states) |
+| `--a-accent-hover` | Accent hover state |
+| `--a-accent-active` | Accent pressed state |
+| `--a-accent-muted` | Subtle accent (tinted backgrounds) |
+| `--a-accent-bg` | Accent-filled surface |
+| `--a-accent-bg-hover` | Accent-filled hover |
+| `--a-accent-bg-active` | Accent-filled active |
+| `--a-accent-fg` | Text on accent surfaces |
+| `--a-accent-border` | Accent borders |
+
+### Brand
+
+Same matrix as accent (`--a-brand`, `--a-brand-hover`, `--a-brand-bg`, `--a-brand-fg`, etc.) for brand-color surfaces. Used in marketing contexts, headers, hero sections.
+
+### Status colors
+
+| Token family | Use case |
+|--------------|----------|
+| `--a-danger-*` | Errors, destructive actions, deletions |
+| `--a-warning-*` | Warnings, caution states |
+| `--a-success-*` | Success confirmations, completed states |
+| `--a-info-*` | Informational highlights, tips |
+
+Each status family mirrors the accent matrix: `-bg`, `-bg-hover`, `-bg-active`, `-fg`, `-border`, `-muted`, etc.
+
+### Data visualization (`--a-data-0` … `--a-data-9`)
+
+Chromatic data colors for charts, graphs, status indicators. Ten slots distinguishable by hue shift.
+
+| Token | Default hue | Use |
+|-------|-------------|-----|
+| `--a-data-0` | 225° | Primary data series |
+| `--a-data-1` | 247° | Secondary series |
+| `--a-data-2` | 269° | Tertiary |
+| … | … | … |
+| `--a-data-9` | 335° | Tenth series |
+
+Individual hue overrides: `--a-data-N-hue: 180;` to pin a specific slot.
+
+---
+
+## Typography API
+
+### Scale tokens (use these directly)
+
+| Token | Purpose |
+|-------|---------|
+| `--a-body-size` | Running text (paragraphs, descriptions) |
+| `--a-heading-size` | Sub-headings |
+| `--a-section-size` | Section headings |
+| `--a-title-size` | Page titles |
+| `--a-display-size` | Hero numbers, big stats |
+| `--a-deck-size` | Lead paragraphs, hero copy |
+| `--a-caption-size` | Captions, metadata, footnotes |
+| `--a-code-size` | Monospace code blocks |
+| `--a-label-size` | Form labels, badges |
+| `--a-ui-size` | UI chrome text (buttons, tabs) |
+| `--a-metric-size` | Dashboard metrics, KPIs |
+| `--a-kicker-size` | Overlines, eyebrow text |
+
+Each has `-sm`, `-md`, `-lg` variants (e.g., `--a-body-sm`, `--a-body-lg`).
+
+### Font families
+
+| Token | Purpose |
+|-------|---------|
+| `--a-font-family-body` | Prose blocks |
+| `--a-font-family-heading` | Headings |
+| `--a-font-family-display` | Hero / display |
+| `--a-font-family-code` | Monospace |
+| `--a-font-family-ui` | Buttons, inputs, chrome |
+| `--a-font-family-control` | Form controls |
+| `--a-font-family-editorial` | Marketing / long-form |
+| `--a-font-family-text` | Fallback generic text |
+
+### Weight & tracking
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--a-weight-thin` | 300 | Hero numbers, elegant display |
+| `--a-weight-light` | 400 | Body text |
+| `--a-weight-normal` | 500 | Default UI |
+| `--a-weight-medium` | 600 | Slightly emphasized |
+| `--a-weight-semibold` | 700 | Headings |
+| `--a-weight-bold` | 800 | Strong emphasis |
+| `--a-tracking-tight` | -0.02em | Display / headlines |
+| `--a-tracking-normal` | 0 | Body |
+| `--a-tracking-wide` | 0.03em | Labels, uppercase |
+| `--a-tracking-wider` | 0.06em | Kickers, overlines |
+
+---
+
+## Spacing API
+
+### Base tokens (parametric: value = `base × --a-density`)
+
+| Token | Base value | Use |
+|-------|-----------|-----|
+| `--a-space-0` | 0 | None |
+| `--a-space-0-5` | 0.125rem (2px) | Hairline |
+| `--a-space-1` | 0.25rem (4px) | Tight padding |
+| `--a-space-2` | 0.5rem (8px) | Default gap |
+| `--a-space-3` | 0.75rem (12px) | Comfortable gap |
+| `--a-space-4` | 1rem (16px) | Card padding |
+| `--a-space-5` | 1.25rem (20px) | Section padding |
+| `--a-space-6` | 1.5rem (24px) | Large gap |
+| `--a-space-7` | 1.75rem (28px) | Extra large |
+| `--a-space-8` | 2rem (32px) | Section gutters |
+| `--a-space-10` | 2.5rem (40px) | Page gutters |
+| `--a-space-12` | 3rem (48px) | Major sections |
+| `--a-space-16` | 4rem (64px) | Hero spacing |
+
+### Composite gap tokens
+
+| Token | Maps to | Use |
+|-------|---------|-----|
+| `--a-gap-sm` | `--a-space-3` | Tight component groups |
+| `--a-gap-md` | `--a-space-4` | Default component groups |
+| `--a-gap-lg` | `--a-space-6` | Loose component groups |
+
+---
+
+## Chrome dimensions
+
+| Token | Value | Element |
+|-------|-------|---------|
+| `--a-chrome-app-header-height` | 48px | App-level header |
+| `--a-chrome-app-toolbar-height` | 48px | App-level toolbar |
+| `--a-chrome-app-footer-height` | 48px | App-level footer |
+| `--a-chrome-pane-header-height` | 36px | Pane / panel header |
+| `--a-chrome-pane-toolbar-height` | 36px | Pane / panel toolbar |
+| `--a-chrome-pane-footer-height` | 36px | Pane / panel footer |
+
+---
+
+## Radius & density
+
+| Token | Type | Default | Effect |
+|-------|------|---------|--------|
+| `--a-density` | `@property <number>` | 1 | Scales ALL spacing, padding, gaps, component heights |
+| `--a-radius-k` | `@property <number>` | 1 | Scales ALL corner rounding |
+| `--a-radius-sm` | length | 0.375rem | Small corners (inputs, buttons) |
+| `--a-radius-md` | length | 0.5rem | Medium corners (cards, popovers) |
+| `--a-radius-lg` | length | 0.75rem | Large corners (modals, drawers) |
+| `--a-radius-full` | length | 9999px | Pills, chips, avatars |
+
+Set `--a-density` and `--a-radius-k` on `:root` for global effect, or on `[density="tight"]` / `[density="comfortable"]` for scoped regions.
+
+---
+
+## Shadows
+
+| Token | Default | Use |
+|-------|---------|-----|
+| `--a-shadow-sm` | `0 1px 2px` | Subtle lift (cards at rest) |
+| `--a-shadow-md` | `0 4px 8px` | Elevated (dropdowns, popovers) |
+| `--a-shadow-lg` | `0 8px 24px` | Highest elevation (modals, drawers) |
+| `--a-shadow-intensity` | 1 | Multiplier for shadow opacity |
+
+---
+
+## Timing
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--a-duration-fast` | 120ms | Hover states, micro-interactions |
+| `--a-duration` | 250ms | Default transition |
+| `--a-duration-slow` | 300ms | Page transitions, large movements |
+| `--a-easing` | `cubic-bezier(0.25, 0.1, 0.25, 1)` | Default ease |
+| `--a-easing-out` | `cubic-bezier(0.16, 1, 0.3, 1)` | Exit / snap animations |
+
+---
+
+## How to add a new token
+
+1. **Need a new semantic color?** Add it in `colors/semantics.css` L3 section, mapping to an L2 family. Example:
+   ```css
+   --a-bg-ghost: var(--a-canvas-0); /* new variant */
+   ```
+2. **Need a new primitive hue?** Extend `colors/parameters.css` hue ramp.
+3. **Need a new spacing step?** Add to `tokens.css` spacing scale.
+4. **Never** add tokens directly in component CSS. Always add to the token system first, then consume.
+
+---
+
+## File inventory
+
+```
+styles/
+├── tokens.css              # Spacing, chrome, shadows, timing, density, radius
+├── typography.css          # Font families, type scale, weights, trackings
+├── themes.css              # 8 named themes + light/dark scheme overrides
+├── colors/
+│   ├── index.css           # Barrel: parameters → primitives → surfaces → scrims → semantics
+│   ├── parameters.css      # L1: hue definitions, OKLCH ramp parameters
+│   ├── primitives.css      # L1: OKLCH color values
+│   ├── surfaces.css        # L2: canvas ramps (--a-canvas-0 … 6)
+│   ├── scrims.css          # L2: overlay transparency values
+│   └── semantics.css       # L2 families + L3 aliases (the consumable API)
+├── prose.css               # Opt-in article typography
+├── resets.css              # Minimal CSS reset
+├── fonts.css               # @font-face declarations
+├── components.css          # Component-specific rules (progress bars, etc.)
+├── elevation.examples.html # Shadow demo page
+├── icons.examples.html     # Icon demo page
+└── spacing.examples.html   # Spacing demo page
+```
+
+---
+
+## Token count (approximate)
+
+| Layer | File(s) | ~Tokens |
+|-------|---------|---------|
+| L1 Primitives | `colors/parameters.css`, `colors/primitives.css` | ~80 |
+| L2 Families | `colors/semantics.css` (family section) | ~60 |
+| L3 Semantic aliases | `colors/semantics.css` (alias section) | ~150 |
+| Typography | `typography.css` | ~80 |
+| Spacing | `tokens.css` | ~25 |
+| Chrome | `tokens.css` | ~10 |
+| Shadows | `tokens.css` | ~4 |
+| Timing | `tokens.css` | ~5 |
+| **Total** | | **~410** |

package/traits/CATEGORIES.md

@@ -0,0 +1,139 @@
+# AdiaUI Traits — Categories Index
+
+**Auto-generated** from `packages/web-components/traits/_catalog.json`. Run `npm run build:traits` to refresh.
+
+**56 traits across 9 categories.**
+
+Traits are cross-cutting capabilities — orthogonal to the 93 primitives. Any primitive can opt into any trait by adding `data-*` attributes; traits hydrate via `defineTrait()` calls in the trait's `<name>.js`.
+
+## At a glance
+
+| Category | Count | Domain |
+| --- | --- | --- |
+| `animation-feedback` | 7 | Reactive visual feedback to user input or state changes — shake on error, pulse on attention. |
+| `audio-haptics-sensory` | 6 | Non-visual feedback channels — sound, vibration, haptics — used for accessibility and delight. |
+| `forms-data` | 4 | Form-centric behaviors — submission flow, field-level validation, dirty tracking. |
+| `input-interaction` | 7 | Pointer + touch input behaviors — clickability, drag, multi-select, hover affordances. |
+| `interaction-delight` | 3 | Optional flourishes that enhance perceived quality — confetti, sparkles, reveal animations. |
+| `keyboard-navigation` | 8 | Keyboard-first patterns — focus rings, type-ahead, arrow-key roving, shortcut handling. |
+| `layout-measurement` | 6 | Geometry observers — element-resize, intersection, container-query awareness. |
+| `motion-positioning` | 10 | Element positioning + motion — sticky, parallax, snap-scroll, magnetic alignment. |
+| `visual-dynamics` | 5 | Theme-aware visual responses — color shifts, gradient drift, light/dark adaptation. |
+
+## Per-category trait list
+
+### `animation-feedback` (7)
+
+_Reactive visual feedback to user input or state changes — shake on error, pulse on attention._
+
+- **`error-shake`** — Horizontal lateral oscillation on validation failure
+- **`fade-presence`** — Enter/exit fade with lifecycle
+- **`ripple`** — Material-style press ripple effect
+- **`scale-press`** — Subtle scale transform on press
+- **`spring-animate`** — Spring-based motion transitions
+- **`success-checkmark`** — Stroke-draw checkmark on validation success
+- **`tilt-hover`** — Tilt based on pointer position
+
+### `audio-haptics-sensory` (6)
+
+_Non-visual feedback channels — sound, vibration, haptics — used for accessibility and delight._
+
+- **`announcer`** — aria-live mirror for AT — announces host state changes via singleton polite/assertive regions
+- **`attention-pulse`** — Periodic pulse to draw attention
+- **`count-up`** — Animated numeric transitions
+- **`haptic-feedback`** — Vibration API feedback
+- **`sound-feedback`** — Synthesized tones via Web Audio API
+- **`typewriter`** — Animated text reveal character by character
+
+### `forms-data` (4)
+
+_Form-centric behaviors — submission flow, field-level validation, dirty tracking._
+
+- **`dirty-state`** — Tracks modified vs initial value
+- **`input-mask`** — Locale-aware as-you-type formatter (phone, credit-card, date, currency)
+- **`resettable`** — Snaps the host value back to its initial value on form reset
+- **`validation`** — Validation rules: required, minlength, pattern, email
+
+### `input-interaction` (7)
+
+_Pointer + touch input behaviors — clickability, drag, multi-select, hover affordances._
+
+- **`active-state`** — Tracks pointer-down / active interaction state
+- **`droppable`** — Marks an element as a drop target for draggable-list-item; emits dnd-drop-enter / leave / receive
+- **`droppable-collection`** — Coordinates droppable children; re-emits drops as dnd-collection-drop
+- **`focusable`** — Keyboard-only focus ring, ignores pointer focus
+- **`hoverable`** — Pointer hover enter/leave state tracking
+- **`long-press`** — Press-and-hold trigger: fires after configurable duration with progress events
+- **`pressable`** — Normalizes click/tap/keyboard into a single "press" event
+
+### `interaction-delight` (3)
+
+_Optional flourishes that enhance perceived quality — confetti, sparkles, reveal animations._
+
+- **`confetti`** — Radial particle burst on press
+- **`confetti-burst`** — Upward fountain particle burst — fires on each `press` event
+- **`magnetic-hover`** — Element subtly follows cursor
+
+### `keyboard-navigation` (8)
+
+_Keyboard-first patterns — focus rings, type-ahead, arrow-key roving, shortcut handling._
+
+- **`arrow-grid-nav`** — 2D arrow-key navigation for grids, calendars, menubars (APG grid pattern)
+- **`focus-restore`** — Capture previously-focused element on connect, restore focus on disconnect
+- **`focus-trap`** — Traps Tab/Shift+Tab within a container
+- **`hotkey`** — Global or scoped keyboard shortcuts
+- **`keyboard-nav`** — Arrow keys, Enter, Escape — semantic navigation events
+- **`keyboard-reorderable`** — Keyboard alternative to draggable-list-item: arrow keys + Space to lift / drop / Esc to cancel
+- **`roving-tabindex`** — Focus management within composite widgets
+- **`typeahead`** — Incremental search within a collection
+
+### `layout-measurement` (6)
+
+_Geometry observers — element-resize, intersection, container-query awareness._
+
+- **`anchor-positioning`** — Positions relative to an anchor element
+- **`intersection-observer`** — Visibility detection (viewport)
+- **`portal`** — Renders content in a different DOM root
+- **`resize-observer`** — Reacts to element size changes
+- **`scroll-lock`** — Disables background scrolling
+- **`scroll-progress`** — Page or element scroll progress as 0..1 attribute + CSS variable + event
+
+### `motion-positioning` (10)
+
+_Element positioning + motion — sticky, parallax, snap-scroll, magnetic alignment._
+
+- **`drag-ghost`** — Ghost clone at origin during drag
+- **`draggable`** — Pointer drag to reposition
+- **`draggable-list-item`** — Pointer drag for list reordering; emits dnd-lift/drop-target-change/drop/drop-cancel
+- **`drop-target`** — Declarative drop zone: hit-testing, accept-reject, drag-over feedback
+- **`inertia-drag`** — Momentum-based dragging, smooth deceleration
+- **`layout-animation`** — FLIP-style layout transition: animate from old to new bounds without explicit coordinates
+- **`resizable`** — Drag edges/corners to resize
+- **`snap-to-grid`** — Snaps position to configurable grid
+- **`tossable`** — Flick with momentum + viewport bounce
+- **`view-transition`** — Wraps document.startViewTransition() for morph animations between DOM states
+
+### `visual-dynamics` (5)
+
+_Theme-aware visual responses — color shifts, gradient drift, light/dark adaptation._
+
+- **`glow-focus`** — Animated pulsing glow on focus
+- **`gradient-shift`** — Animated rainbow gradient backgrounds
+- **`noise-texture`** — Procedural grain overlay
+- **`parallax`** — Layered motion relative to pointer
+- **`shimmer-loading`** — Skeleton shimmer effect
+
+## See also
+
+- [`docs/specs/traits.md`](../../../docs/specs/traits.md) — trait system architecture
+- [`packages/web-components/traits/<name>/<name>.js`](.) — per-trait source (5 files: `.js .html .examples.html .examples.js .test.js`)
+- [`_catalog.json`](./_catalog.json) — generated catalog (do not hand-edit)
+- [`_api-table.js`](./_api-table.js) — generated API surface (do not hand-edit)
+
+## Authoring a new trait
+
+1. `mkdir packages/web-components/traits/<name>/` (use lowercase + hyphens)
+2. Author 5 files: `<name>.js`, `<name>.html`, `<name>.examples.html`, `<name>.examples.js`, `<name>.test.js`
+3. Pick the most-fitting of the 9 categories above (avoid creating new ones; if you must, document why in the journal)
+4. Run `npm run build:traits` to regenerate `_catalog.json` and `_api-table.js`
+5. Run `npm run verify:traits` — must report 100% coverage