# 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 95 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
