ada-agent 0.2.0 → 0.3.0

package/skills/component-library/SKILL.md

@@ -1,23 +1,23 @@
----
-name: component-library
-description: Build a reusable, composable, accessible component library in the shadcn/ui style with design tokens.
-category: ui-design
----
-
-# Component Library
-
-Reach for this when an app has accumulated copy-pasted, drifting UI and needs one coherent, themeable set of primitives that compose cleanly.
-
-1. Establish the token layer first: define semantic CSS custom properties (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, `--ring`, radii, spacing) so theming/dark mode is a variable swap, not a rewrite.
-2. Build on accessible headless primitives (Radix UI / React Aria) for behavior — focus management, ARIA, keyboard — and own only the styling layer, shadcn/ui style (copy-in components you can edit, not a locked dependency).
-3. Manage variants with a typed API via `cva` (class-variance-authority): explicit `variant` and `size` props, a single source of truth for every visual state, sane defaults.
-4. Make composition the contract: forward refs, spread `...props`, expose `asChild` (Radix Slot) so a `Button` can render as a link, and prefer slots over a sea of boolean props.
-5. Define every interactive state in the recipe — hover, active, `focus-visible` ring, `disabled`, loading, invalid — and wire motion to your shared duration/easing tokens.
-6. Document with live examples (Storybook or an MDX kitchen-sink page) and lock visual regressions; every component ships with usage + a11y notes.
-
-## Rules
-- Components are unopinionated about layout — no fixed margins; spacing belongs to the parent. They size to context.
-- Accessibility is non-negotiable: keyboard-operable, correct roles/labels, `focus-visible` rings, contrast ≥4.5:1 for text.
-- One token system; a hard-coded hex or pixel value inside a component is a leak to fix, not ship.
-- Prefer composition over configuration — when prop count explodes, split the component or expose subcomponents (`Card.Header`).
-- Keep the bundle lean: tree-shakeable exports, no kitchen-sink barrel that drags in everything.
+---
+name: component-library
+description: Build a reusable, composable, accessible component library in the shadcn/ui style with design tokens.
+category: ui-design
+---
+
+# Component Library
+
+Reach for this when an app has accumulated copy-pasted, drifting UI and needs one coherent, themeable set of primitives that compose cleanly.
+
+1. Establish the token layer first: define semantic CSS custom properties (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, `--ring`, radii, spacing) so theming/dark mode is a variable swap, not a rewrite.
+2. Build on accessible headless primitives (Radix UI / React Aria) for behavior — focus management, ARIA, keyboard — and own only the styling layer, shadcn/ui style (copy-in components you can edit, not a locked dependency).
+3. Manage variants with a typed API via `cva` (class-variance-authority): explicit `variant` and `size` props, a single source of truth for every visual state, sane defaults.
+4. Make composition the contract: forward refs, spread `...props`, expose `asChild` (Radix Slot) so a `Button` can render as a link, and prefer slots over a sea of boolean props.
+5. Define every interactive state in the recipe — hover, active, `focus-visible` ring, `disabled`, loading, invalid — and wire motion to your shared duration/easing tokens.
+6. Document with live examples (Storybook or an MDX kitchen-sink page) and lock visual regressions; every component ships with usage + a11y notes.
+
+## Rules
+- Components are unopinionated about layout — no fixed margins; spacing belongs to the parent. They size to context.
+- Accessibility is non-negotiable: keyboard-operable, correct roles/labels, `focus-visible` rings, contrast ≥4.5:1 for text.
+- One token system; a hard-coded hex or pixel value inside a component is a leak to fix, not ship.
+- Prefer composition over configuration — when prop count explodes, split the component or expose subcomponents (`Card.Header`).
+- Keep the bundle lean: tree-shakeable exports, no kitchen-sink barrel that drags in everything.

package/skills/dark-mode/SKILL.md

@@ -1,24 +1,24 @@
----
-name: dark-mode
-description: Implement a polished dark mode via semantic tokens and prefers-color-scheme, not naive color inversion
-category: ui-design
----
-
-# Dark Mode
-
-Use this to add a dark theme that looks designed rather than inverted. Good dark mode is a parallel palette tuned for a dark substrate — it's not `filter: invert()`.
-
-1. Theme through semantic tokens only: components read `--bg`, `--surface`, `--text`, `--border`, `--accent`. Dark mode redefines those aliases; component CSS doesn't change.
-2. Avoid pure black (`#000`) backgrounds — use a very dark neutral (~oklch 0.18–0.22) so OLED smearing and harsh contrast soften, and so elevation can read.
-3. Signal elevation with lighter surfaces, not shadows: raised cards get a slightly lighter `--surface-raised`. Shadows mostly disappear on dark; lightness becomes the depth cue.
-4. Soften text: don't use `#fff` for body — drop to ~85–90% lightness to reduce halation, and re-check that muted text still clears 4.5:1 against the dark surface.
-5. Reduce accent chroma slightly and verify it on dark — saturated hues that pop on white can vibrate on dark; tune `--accent` and `--accent-fg` per theme.
-6. Wire it up: default to `@media (prefers-color-scheme: dark)`, allow a manual override via `[data-theme="dark"]` on `<html>`, persist the choice, and set `<meta name="color-scheme">` to avoid a white flash.
-7. Dim large imagery/illustration in dark (e.g. slightly lower brightness) and provide dark-tuned shadows/borders so nothing glows.
-
-## Rules
-- Re-check contrast in dark independently — passing in light guarantees nothing.
-- No pure `#000` background and no pure `#fff` text; both fatigue the eye.
-- Convey depth with surface lightness, not drop shadows, in dark.
-- Respect system preference by default, but let users override and persist it.
-- Theme via token redefinition; never fork component styles per mode.
+---
+name: dark-mode
+description: Implement a polished dark mode via semantic tokens and prefers-color-scheme, not naive color inversion
+category: ui-design
+---
+
+# Dark Mode
+
+Use this to add a dark theme that looks designed rather than inverted. Good dark mode is a parallel palette tuned for a dark substrate — it's not `filter: invert()`.
+
+1. Theme through semantic tokens only: components read `--bg`, `--surface`, `--text`, `--border`, `--accent`. Dark mode redefines those aliases; component CSS doesn't change.
+2. Avoid pure black (`#000`) backgrounds — use a very dark neutral (~oklch 0.18–0.22) so OLED smearing and harsh contrast soften, and so elevation can read.
+3. Signal elevation with lighter surfaces, not shadows: raised cards get a slightly lighter `--surface-raised`. Shadows mostly disappear on dark; lightness becomes the depth cue.
+4. Soften text: don't use `#fff` for body — drop to ~85–90% lightness to reduce halation, and re-check that muted text still clears 4.5:1 against the dark surface.
+5. Reduce accent chroma slightly and verify it on dark — saturated hues that pop on white can vibrate on dark; tune `--accent` and `--accent-fg` per theme.
+6. Wire it up: default to `@media (prefers-color-scheme: dark)`, allow a manual override via `[data-theme="dark"]` on `<html>`, persist the choice, and set `<meta name="color-scheme">` to avoid a white flash.
+7. Dim large imagery/illustration in dark (e.g. slightly lower brightness) and provide dark-tuned shadows/borders so nothing glows.
+
+## Rules
+- Re-check contrast in dark independently — passing in light guarantees nothing.
+- No pure `#000` background and no pure `#fff` text; both fatigue the eye.
+- Convey depth with surface lightness, not drop shadows, in dark.
+- Respect system preference by default, but let users override and persist it.
+- Theme via token redefinition; never fork component styles per mode.

package/skills/dashboard-ui/SKILL.md

@@ -1,23 +1,23 @@
----
-name: dashboard-ui
-description: Design a clean, scannable data dashboard — clear hierarchy, restrained color, and fast comprehension.
-category: ui-design
----
-
-# Dashboard UI
-
-Reach for this when building an analytics or operations dashboard, where the job is to surface signal fast and let users act without hunting.
-
-1. Lead with the answer: a top row of 3–5 KPI stat cards (big number, label, trend delta with direction color), then supporting charts, then granular tables — most important, top-left.
-2. Lay out on a 12-column grid with consistent gutters and an 8px spacing rhythm; use container queries so cards reflow by their own width, not just the viewport.
-3. Keep the palette near-monochrome for chrome (neutral surfaces, one muted border token) and reserve saturated color strictly for data and semantic states (up/down, success/warn/error) so meaning pops.
-4. Set an information density that fits the user: align numbers right, use tabular figures (`font-variant-numeric: tabular-nums`), and tighten line-height in tables while keeping comfortable card padding.
-5. Make charts honest and minimal: drop chartjunk, label directly over legends where possible, start bar axes at zero, and cap each chart to one clear question.
-6. Provide structural states — loading skeletons matching card shapes, empty states with a next action, and persistent filters that don't reset on navigation.
-
-## Rules
-- Color carries data meaning; never decorate the UI with the same hues you use for series, or users misread the charts.
-- Whitespace is a feature — resist cramming; a scannable dashboard beats a complete-but-dense one.
-- Use semantic green/red for trends but never rely on color alone — pair with arrows/signs for color-blind users (contrast ≥3:1).
-- Numbers are the hero: tabular figures, right alignment, sensible rounding and units; no jittering digit widths.
-- Keep the navigation/chrome quiet so the data is the brightest thing on screen.
+---
+name: dashboard-ui
+description: Design a clean, scannable data dashboard — clear hierarchy, restrained color, and fast comprehension.
+category: ui-design
+---
+
+# Dashboard UI
+
+Reach for this when building an analytics or operations dashboard, where the job is to surface signal fast and let users act without hunting.
+
+1. Lead with the answer: a top row of 3–5 KPI stat cards (big number, label, trend delta with direction color), then supporting charts, then granular tables — most important, top-left.
+2. Lay out on a 12-column grid with consistent gutters and an 8px spacing rhythm; use container queries so cards reflow by their own width, not just the viewport.
+3. Keep the palette near-monochrome for chrome (neutral surfaces, one muted border token) and reserve saturated color strictly for data and semantic states (up/down, success/warn/error) so meaning pops.
+4. Set an information density that fits the user: align numbers right, use tabular figures (`font-variant-numeric: tabular-nums`), and tighten line-height in tables while keeping comfortable card padding.
+5. Make charts honest and minimal: drop chartjunk, label directly over legends where possible, start bar axes at zero, and cap each chart to one clear question.
+6. Provide structural states — loading skeletons matching card shapes, empty states with a next action, and persistent filters that don't reset on navigation.
+
+## Rules
+- Color carries data meaning; never decorate the UI with the same hues you use for series, or users misread the charts.
+- Whitespace is a feature — resist cramming; a scannable dashboard beats a complete-but-dense one.
+- Use semantic green/red for trends but never rely on color alone — pair with arrows/signs for color-blind users (contrast ≥3:1).
+- Numbers are the hero: tabular figures, right alignment, sensible rounding and units; no jittering digit widths.
+- Keep the navigation/chrome quiet so the data is the brightest thing on screen.

package/skills/design-system/SKILL.md

@@ -1,24 +1,24 @@
----
-name: design-system
-description: Build a cohesive design system from tokens up to components, with one source of truth and zero magic numbers
-category: ui-design
----
-
-# Design System
-
-Reach for this when a UI has grown inconsistent — drifting spacings, one-off colors, copy-pasted buttons — or when starting a product that needs to scale past a few screens.
-
-1. Audit what exists: screenshot every surface, list every distinct color, font size, radius, shadow, and spacing in use. The sprawl you find is the problem statement.
-2. Define the token layer first (see the design-tokens skill): primitives (`--blue-500`), then semantic aliases (`--color-accent`, `--bg-surface`, `--text-muted`). Components reference semantics only, never primitives.
-3. Lock the foundations: a modular type scale (1.2–1.25 ratio), a 4px spacing base, a radius set (sm/md/lg/full), and 2–3 elevation shadows. Everything downstream composes from these.
-4. Build primitives as composable components: Button (variant × size × state), Input, Card, Badge. Encode every visual decision as a token, so a theme swap is a token swap.
-5. Codify states explicitly — default, hover, focus-visible, active, disabled, loading. A system that only specifies the resting state isn't a system.
-6. Document usage with live examples and do/don't pairs (Storybook or an MDX page). A token nobody knows about gets bypassed.
-7. Ship with lint guardrails: reject raw hex and arbitrary px in PRs so drift can't creep back in.
-
-## Rules
-- One source of truth: a value lives in exactly one token; if you typed a hex or px in a component, it's a bug.
-- Two-tier tokens always — primitive then semantic — so re-theming touches the alias layer only.
-- Name by role, not by look: `--color-danger`, not `--color-red` (red may become orange later).
-- Every interactive component must define focus-visible and disabled, not just hover.
-- Prefer composition over variant explosion; if a component has 12 boolean props, split it.
+---
+name: design-system
+description: Build a cohesive design system from tokens up to components, with one source of truth and zero magic numbers
+category: ui-design
+---
+
+# Design System
+
+Reach for this when a UI has grown inconsistent — drifting spacings, one-off colors, copy-pasted buttons — or when starting a product that needs to scale past a few screens.
+
+1. Audit what exists: screenshot every surface, list every distinct color, font size, radius, shadow, and spacing in use. The sprawl you find is the problem statement.
+2. Define the token layer first (see the design-tokens skill): primitives (`--blue-500`), then semantic aliases (`--color-accent`, `--bg-surface`, `--text-muted`). Components reference semantics only, never primitives.
+3. Lock the foundations: a modular type scale (1.2–1.25 ratio), a 4px spacing base, a radius set (sm/md/lg/full), and 2–3 elevation shadows. Everything downstream composes from these.
+4. Build primitives as composable components: Button (variant × size × state), Input, Card, Badge. Encode every visual decision as a token, so a theme swap is a token swap.
+5. Codify states explicitly — default, hover, focus-visible, active, disabled, loading. A system that only specifies the resting state isn't a system.
+6. Document usage with live examples and do/don't pairs (Storybook or an MDX page). A token nobody knows about gets bypassed.
+7. Ship with lint guardrails: reject raw hex and arbitrary px in PRs so drift can't creep back in.
+
+## Rules
+- One source of truth: a value lives in exactly one token; if you typed a hex or px in a component, it's a bug.
+- Two-tier tokens always — primitive then semantic — so re-theming touches the alias layer only.
+- Name by role, not by look: `--color-danger`, not `--color-red` (red may become orange later).
+- Every interactive component must define focus-visible and disabled, not just hover.
+- Prefer composition over variant explosion; if a component has 12 boolean props, split it.

package/skills/design-tokens/SKILL.md

@@ -1,24 +1,24 @@
----
-name: design-tokens
-description: Define color, space, type, radius, and shadow tokens as layered CSS custom properties with semantic roles
-category: ui-design
----
-
-# Design Tokens
-
-Use this to turn scattered hardcoded values into a small, principled set of variables that every component reads from — the foundation under any design system or theme.
-
-1. Split into two tiers: a primitive scale (`--gray-50`…`--gray-950`, `--blue-500`) that names raw values, and a semantic layer (`--bg`, `--surface`, `--text`, `--border`, `--accent`) that maps roles onto primitives.
-2. Build space on a 4px base as a scale, not ad-hoc: `--space-1: 4px` … `--space-8: 32px`. Components only ever use scale steps, killing 13px and 27px outliers.
-3. Define type tokens from a ratio (see typography): `--text-sm/base/lg/xl/2xl` plus `--leading-tight/normal/relaxed` and `--tracking-tight`. Pair each size with a sensible line-height.
-4. Standardize radius (`--radius-sm/md/lg/full`) and elevation (`--shadow-sm/md/lg`) as layered, low-alpha shadows — never a single harsh `0 2px 4px #000`.
-5. Express color in `oklch()` for perceptually even ramps and easy lightness flips; provide `--color-*` semantic aliases so dark mode redefines the alias, not the component.
-6. Scope tokens to `:root`, override per-theme via `[data-theme]` or `@media (prefers-color-scheme)`, and expose only semantic tokens to component code.
-7. Generate platform outputs (CSS vars, Tailwind config, JSON) from one source file (e.g. Style Dictionary) so web and native never diverge.
-
-## Rules
-- Components consume semantic tokens only; primitives are private implementation detail.
-- No naked values in component CSS — every color, space, radius, and shadow is a `var(--…)`.
-- Name tokens by purpose (`--text-muted`) not appearance (`--gray-400`).
-- Keep each scale short (5–9 steps); an infinite ramp invites inconsistency.
-- Use `oklch()`/`hsl()` over hex so you can derive hover/active states by nudging lightness.
+---
+name: design-tokens
+description: Define color, space, type, radius, and shadow tokens as layered CSS custom properties with semantic roles
+category: ui-design
+---
+
+# Design Tokens
+
+Use this to turn scattered hardcoded values into a small, principled set of variables that every component reads from — the foundation under any design system or theme.
+
+1. Split into two tiers: a primitive scale (`--gray-50`…`--gray-950`, `--blue-500`) that names raw values, and a semantic layer (`--bg`, `--surface`, `--text`, `--border`, `--accent`) that maps roles onto primitives.
+2. Build space on a 4px base as a scale, not ad-hoc: `--space-1: 4px` … `--space-8: 32px`. Components only ever use scale steps, killing 13px and 27px outliers.
+3. Define type tokens from a ratio (see typography): `--text-sm/base/lg/xl/2xl` plus `--leading-tight/normal/relaxed` and `--tracking-tight`. Pair each size with a sensible line-height.
+4. Standardize radius (`--radius-sm/md/lg/full`) and elevation (`--shadow-sm/md/lg`) as layered, low-alpha shadows — never a single harsh `0 2px 4px #000`.
+5. Express color in `oklch()` for perceptually even ramps and easy lightness flips; provide `--color-*` semantic aliases so dark mode redefines the alias, not the component.
+6. Scope tokens to `:root`, override per-theme via `[data-theme]` or `@media (prefers-color-scheme)`, and expose only semantic tokens to component code.
+7. Generate platform outputs (CSS vars, Tailwind config, JSON) from one source file (e.g. Style Dictionary) so web and native never diverge.
+
+## Rules
+- Components consume semantic tokens only; primitives are private implementation detail.
+- No naked values in component CSS — every color, space, radius, and shadow is a `var(--…)`.
+- Name tokens by purpose (`--text-muted`) not appearance (`--gray-400`).
+- Keep each scale short (5–9 steps); an infinite ramp invites inconsistency.
+- Use `oklch()`/`hsl()` over hex so you can derive hover/active states by nudging lightness.

package/skills/empty-states/SKILL.md

@@ -1,23 +1,23 @@
----
-name: empty-states
-description: Design empty, loading, and error states that orient the user and offer a clear next action.
-category: ui-design
----
-
-# Empty States
-
-Reach for this whenever a view can have no data, be loading, or fail — these states are most of the real experience and deserve the same care as the happy path.
-
-1. Distinguish the three cases and design each: first-run empty (no data yet), cleared empty (filters/search returned nothing), and error (something broke) — they need different copy and actions.
-2. For first-run, make it a launchpad: a short encouraging line, a focused illustration or icon, and one primary CTA that creates the first item — turn the void into onboarding.
-3. For "no results", explain why and give an out: echo the active query/filters and offer "clear filters" or a broader suggestion, not a generic shrug.
-4. For errors, be specific and recoverable: plain-language cause, a "Try again" action, and a path to support — never expose a raw stack trace or a bare "Something went wrong".
-5. Match the layout to the eventual content so the page doesn't jump when data arrives, and keep tone consistent with the product's voice (helpful, not cute-at-the-user's-expense).
-6. Respect hierarchy and restraint: one illustration, one heading, one action; muted supporting text; accessible contrast and a real `role`/announcement for error states.
-
-## Rules
-- Every empty/error state offers at least one obvious next step — a dead end with no action is a bug.
-- Error copy names what happened and what to do; "Oops!" with no recovery path is failure theater.
-- Don't reuse the first-run empty state for "no search results" — they imply different user situations.
-- Keep illustrations subtle and on-brand; they support the message, they aren't the message.
-- Announce errors to assistive tech (`aria-live="assertive"` / `role="alert"`) and keep focus recoverable.
+---
+name: empty-states
+description: Design empty, loading, and error states that orient the user and offer a clear next action.
+category: ui-design
+---
+
+# Empty States
+
+Reach for this whenever a view can have no data, be loading, or fail — these states are most of the real experience and deserve the same care as the happy path.
+
+1. Distinguish the three cases and design each: first-run empty (no data yet), cleared empty (filters/search returned nothing), and error (something broke) — they need different copy and actions.
+2. For first-run, make it a launchpad: a short encouraging line, a focused illustration or icon, and one primary CTA that creates the first item — turn the void into onboarding.
+3. For "no results", explain why and give an out: echo the active query/filters and offer "clear filters" or a broader suggestion, not a generic shrug.
+4. For errors, be specific and recoverable: plain-language cause, a "Try again" action, and a path to support — never expose a raw stack trace or a bare "Something went wrong".
+5. Match the layout to the eventual content so the page doesn't jump when data arrives, and keep tone consistent with the product's voice (helpful, not cute-at-the-user's-expense).
+6. Respect hierarchy and restraint: one illustration, one heading, one action; muted supporting text; accessible contrast and a real `role`/announcement for error states.
+
+## Rules
+- Every empty/error state offers at least one obvious next step — a dead end with no action is a bug.
+- Error copy names what happened and what to do; "Oops!" with no recovery path is failure theater.
+- Don't reuse the first-run empty state for "no search results" — they imply different user situations.
+- Keep illustrations subtle and on-brand; they support the message, they aren't the message.
+- Announce errors to assistive tech (`aria-live="assertive"` / `role="alert"`) and keep focus recoverable.

package/skills/hero-section/SKILL.md

@@ -1,23 +1,23 @@
----
-name: hero-section
-description: Design a striking, conversion-focused hero with one clear message, sharp hierarchy, and a single CTA.
-category: ui-design
----
-
-# Hero Section
-
-Reach for this for the first screen of a landing page — the hero has ~3 seconds to land the value proposition and drive one action.
-
-1. Lock the message architecture: one eyebrow/kicker (optional), one headline stating the outcome (not the feature), one subhead clarifying, one primary CTA. Cut everything else.
-2. Build a real type scale with `clamp()` — e.g. headline `clamp(2.5rem, 5vw + 1rem, 5rem)`, tight `line-height: 1.05`, and `letter-spacing: -0.02em` on large display text for an editorial feel.
-3. Establish hierarchy through contrast, not just size: the CTA is the highest-contrast element on screen; the subhead sits in a muted foreground; supporting visuals never out-shout the headline.
-4. Give it breathing room — generous vertical rhythm on an 8px scale, a constrained measure (~60ch) on the subhead, and asymmetry (off-center text + image) to avoid a sterile centered template.
-5. Add one tasteful motion beat on load: staggered fade-rise of headline → subhead → CTA (40–60ms apart, ease-out, ≤400ms total). Subtle, once, never looping.
-6. Engineer for performance and LCP: the headline is real text (not an image), hero media is `priority`/preloaded and properly sized, and the layout is reserved to prevent CLS.
-
-## Rules
-- One primary CTA. A secondary "Learn more" can exist as a quieter ghost/text link, never a competing button.
-- The headline sells the outcome to the user; if it could appear on a competitor's site verbatim, rewrite it.
-- Maintain ≥4.5:1 contrast for headline text over any image/gradient — add a scrim or duotone rather than risk legibility.
-- Don't center everything by reflex; intentional asymmetry and a strong grid read as designed, not default.
-- Hero must be legible and complete above the fold on a 360px phone before you polish desktop.
+---
+name: hero-section
+description: Design a striking, conversion-focused hero with one clear message, sharp hierarchy, and a single CTA.
+category: ui-design
+---
+
+# Hero Section
+
+Reach for this for the first screen of a landing page — the hero has ~3 seconds to land the value proposition and drive one action.
+
+1. Lock the message architecture: one eyebrow/kicker (optional), one headline stating the outcome (not the feature), one subhead clarifying, one primary CTA. Cut everything else.
+2. Build a real type scale with `clamp()` — e.g. headline `clamp(2.5rem, 5vw + 1rem, 5rem)`, tight `line-height: 1.05`, and `letter-spacing: -0.02em` on large display text for an editorial feel.
+3. Establish hierarchy through contrast, not just size: the CTA is the highest-contrast element on screen; the subhead sits in a muted foreground; supporting visuals never out-shout the headline.
+4. Give it breathing room — generous vertical rhythm on an 8px scale, a constrained measure (~60ch) on the subhead, and asymmetry (off-center text + image) to avoid a sterile centered template.
+5. Add one tasteful motion beat on load: staggered fade-rise of headline → subhead → CTA (40–60ms apart, ease-out, ≤400ms total). Subtle, once, never looping.
+6. Engineer for performance and LCP: the headline is real text (not an image), hero media is `priority`/preloaded and properly sized, and the layout is reserved to prevent CLS.
+
+## Rules
+- One primary CTA. A secondary "Learn more" can exist as a quieter ghost/text link, never a competing button.
+- The headline sells the outcome to the user; if it could appear on a competitor's site verbatim, rewrite it.
+- Maintain ≥4.5:1 contrast for headline text over any image/gradient — add a scrim or duotone rather than risk legibility.
+- Don't center everything by reflex; intentional asymmetry and a strong grid read as designed, not default.
+- Hero must be legible and complete above the fold on a 360px phone before you polish desktop.

package/skills/micro-interactions/SKILL.md

@@ -1,23 +1,23 @@
----
-name: micro-interactions
-description: Add tasteful hover/press/focus micro-interactions and feedback that feel responsive without distracting.
-category: ui-design
----
-
-# Micro-Interactions
-
-Reach for this when a UI feels static or unresponsive — buttons, toggles, cards, and inputs should acknowledge every interaction within ~100ms.
-
-1. Map the three states for each interactive element: rest, hover, active/press, plus a `:focus-visible` ring for keyboard users — never style all four identically.
-2. Set durations by intent: 80–120ms for press/feedback, 150–200ms for hover, and pair with `transition-timing-function: cubic-bezier(0.2, 0, 0, 1)` (ease-out) so motion settles fast.
-3. On press, apply a subtle `transform: scale(0.97)` or 1px translate — physical, not bouncy. Reserve a gentle overshoot spring only for playful toggles/likes.
-4. Telegraph intent with secondary cues: shift `background`, lift with `box-shadow`, or nudge an icon — change 2 properties max so it reads as one motion.
-5. Confirm async actions inline: swap label → spinner → checkmark, then settle. Use optimistic UI where the success rate is high.
-6. Respect `@media (prefers-reduced-motion: reduce)` — drop transforms, keep instant color/opacity feedback so the cue survives.
-
-## Rules
-- Hover effects are progressive enhancement; the element must be fully usable and legible without them (touch + keyboard).
-- Animate `transform` and `opacity` only on the hot path — never `width`, `top`, or `box-shadow` in tight loops (they trigger layout/paint).
-- Keep focus rings visible and ≥3:1 contrast against the adjacent surface; never `outline: none` without a replacement.
-- One signature interaction per surface — if everything wiggles, nothing reads as special.
-- Feedback latency budget is 100ms; beyond that, show a loading state instead of a delayed jump.
+---
+name: micro-interactions
+description: Add tasteful hover/press/focus micro-interactions and feedback that feel responsive without distracting.
+category: ui-design
+---
+
+# Micro-Interactions
+
+Reach for this when a UI feels static or unresponsive — buttons, toggles, cards, and inputs should acknowledge every interaction within ~100ms.
+
+1. Map the three states for each interactive element: rest, hover, active/press, plus a `:focus-visible` ring for keyboard users — never style all four identically.
+2. Set durations by intent: 80–120ms for press/feedback, 150–200ms for hover, and pair with `transition-timing-function: cubic-bezier(0.2, 0, 0, 1)` (ease-out) so motion settles fast.
+3. On press, apply a subtle `transform: scale(0.97)` or 1px translate — physical, not bouncy. Reserve a gentle overshoot spring only for playful toggles/likes.
+4. Telegraph intent with secondary cues: shift `background`, lift with `box-shadow`, or nudge an icon — change 2 properties max so it reads as one motion.
+5. Confirm async actions inline: swap label → spinner → checkmark, then settle. Use optimistic UI where the success rate is high.
+6. Respect `@media (prefers-reduced-motion: reduce)` — drop transforms, keep instant color/opacity feedback so the cue survives.
+
+## Rules
+- Hover effects are progressive enhancement; the element must be fully usable and legible without them (touch + keyboard).
+- Animate `transform` and `opacity` only on the hot path — never `width`, `top`, or `box-shadow` in tight loops (they trigger layout/paint).
+- Keep focus rings visible and ≥3:1 contrast against the adjacent surface; never `outline: none` without a replacement.
+- One signature interaction per surface — if everything wiggles, nothing reads as special.
+- Feedback latency budget is 100ms; beyond that, show a loading state instead of a delayed jump.

package/skills/motion-design/SKILL.md

@@ -1,23 +1,23 @@
----
-name: motion-design
-description: Define a coherent motion system — duration tokens, easing curves, and clear rules for when to animate.
-category: ui-design
----
-
-# Motion Design
-
-Reach for this before adding any animation to a product, so motion is a designed system with tokens rather than one-off magic numbers scattered across components.
-
-1. Define a duration scale as CSS custom properties: `--dur-1: 100ms` (micro), `--dur-2: 200ms` (UI), `--dur-3: 320ms` (entrances), `--dur-4: 500ms` (large/page). Scale duration with travel distance and element size.
-2. Define an easing token set: `--ease-out: cubic-bezier(0.2, 0, 0, 1)` for enters, `--ease-in: cubic-bezier(0.4, 0, 1, 1)` for exits, `--ease-spring` for emphasis. Default to ease-out — elements decelerate into place.
-3. Assign each animation a role: arrival (fade+rise), exit (fade+fall), state change, or attention. Different roles get different curves/durations — don't reuse one transition everywhere.
-4. Orchestrate groups with a stagger of 30–60ms per item so lists cascade; cap total sequence length near 500ms so it never feels slow.
-5. Prefer transform-driven motion (translate/scale) and physics-based springs (Framer Motion `type: "spring"`, sensible stiffness/damping) over linear tweens for anything interactive.
-6. Provide a global `prefers-reduced-motion` fallback that collapses movement to opacity-only, and document the tokens so the team reuses them.
-
-## Rules
-- Motion must communicate (where did this come from, what changed), never decorate for its own sake.
-- Never use `ease-in-out` for entrances — it starts slow and feels sluggish; reserve it for looping/ambient motion.
-- Exits are faster than entrances (~0.7×); users have already decided, so get out of the way.
-- No transition longer than ~500ms on an interaction the user is waiting on.
-- One token set, imported everywhere — a stray `transition: all 0.3s` is a bug, not a shortcut.
+---
+name: motion-design
+description: Define a coherent motion system — duration tokens, easing curves, and clear rules for when to animate.
+category: ui-design
+---
+
+# Motion Design
+
+Reach for this before adding any animation to a product, so motion is a designed system with tokens rather than one-off magic numbers scattered across components.
+
+1. Define a duration scale as CSS custom properties: `--dur-1: 100ms` (micro), `--dur-2: 200ms` (UI), `--dur-3: 320ms` (entrances), `--dur-4: 500ms` (large/page). Scale duration with travel distance and element size.
+2. Define an easing token set: `--ease-out: cubic-bezier(0.2, 0, 0, 1)` for enters, `--ease-in: cubic-bezier(0.4, 0, 1, 1)` for exits, `--ease-spring` for emphasis. Default to ease-out — elements decelerate into place.
+3. Assign each animation a role: arrival (fade+rise), exit (fade+fall), state change, or attention. Different roles get different curves/durations — don't reuse one transition everywhere.
+4. Orchestrate groups with a stagger of 30–60ms per item so lists cascade; cap total sequence length near 500ms so it never feels slow.
+5. Prefer transform-driven motion (translate/scale) and physics-based springs (Framer Motion `type: "spring"`, sensible stiffness/damping) over linear tweens for anything interactive.
+6. Provide a global `prefers-reduced-motion` fallback that collapses movement to opacity-only, and document the tokens so the team reuses them.
+
+## Rules
+- Motion must communicate (where did this come from, what changed), never decorate for its own sake.
+- Never use `ease-in-out` for entrances — it starts slow and feels sluggish; reserve it for looping/ambient motion.
+- Exits are faster than entrances (~0.7×); users have already decided, so get out of the way.
+- No transition longer than ~500ms on an interaction the user is waiting on.
+- One token set, imported everywhere — a stray `transition: all 0.3s` is a bug, not a shortcut.

package/skills/page-transitions/SKILL.md

@@ -1,23 +1,23 @@
----
-name: page-transitions
-description: Add smooth route/page transitions with the View Transitions API or Framer that preserve context.
-category: ui-design
----
-
-# Page Transitions
-
-Reach for this when route changes feel abrupt — a well-crafted transition maintains spatial continuity so users keep their place between views.
-
-1. Pick the mechanism: native View Transitions API (`document.startViewTransition`, or `@view-transition { navigation: auto }` for MPAs) where supported; Framer Motion `AnimatePresence` with `mode="wait"` for React SPAs.
-2. Default to a fast crossfade (~200–300ms) for unrelated routes; it's invisible-but-smooth and the safest baseline.
-3. For shared elements (a card → its detail page), give both a matching `view-transition-name` (or Framer `layoutId`) so the element morphs in place — this is the high-value move.
-4. Tune the generated pseudo-elements: style `::view-transition-old(root)` / `::view-transition-new(root)` with your easing tokens; clip-path or slide for directional hierarchy (forward = in from right, back = out to right).
-5. Avoid layout shift mid-transition: hold scroll position or restore it explicitly, and ensure the incoming page's above-fold content is ready (Suspense/loaded data) before revealing.
-6. Always ship a no-transition fallback for unsupported browsers (feature-detect `startViewTransition`) and honor `prefers-reduced-motion` with an instant swap.
-
-## Rules
-- A transition must orient the user, not entertain — if it makes navigation feel slower, shorten or cut it.
-- Keep durations ≤300ms; users navigate constantly and a flashy 600ms transition becomes friction by the tenth click.
-- Shared-element transitions need stable, unique names — duplicated `view-transition-name` on one page throws and breaks the animation.
-- Never animate during the transition something that also triggers data fetching — wait for the new view's critical content first.
-- Test back/forward and rapid navigation; transitions must be interruptible and not queue/stack.
+---
+name: page-transitions
+description: Add smooth route/page transitions with the View Transitions API or Framer that preserve context.
+category: ui-design
+---
+
+# Page Transitions
+
+Reach for this when route changes feel abrupt — a well-crafted transition maintains spatial continuity so users keep their place between views.
+
+1. Pick the mechanism: native View Transitions API (`document.startViewTransition`, or `@view-transition { navigation: auto }` for MPAs) where supported; Framer Motion `AnimatePresence` with `mode="wait"` for React SPAs.
+2. Default to a fast crossfade (~200–300ms) for unrelated routes; it's invisible-but-smooth and the safest baseline.
+3. For shared elements (a card → its detail page), give both a matching `view-transition-name` (or Framer `layoutId`) so the element morphs in place — this is the high-value move.
+4. Tune the generated pseudo-elements: style `::view-transition-old(root)` / `::view-transition-new(root)` with your easing tokens; clip-path or slide for directional hierarchy (forward = in from right, back = out to right).
+5. Avoid layout shift mid-transition: hold scroll position or restore it explicitly, and ensure the incoming page's above-fold content is ready (Suspense/loaded data) before revealing.
+6. Always ship a no-transition fallback for unsupported browsers (feature-detect `startViewTransition`) and honor `prefers-reduced-motion` with an instant swap.
+
+## Rules
+- A transition must orient the user, not entertain — if it makes navigation feel slower, shorten or cut it.
+- Keep durations ≤300ms; users navigate constantly and a flashy 600ms transition becomes friction by the tenth click.
+- Shared-element transitions need stable, unique names — duplicated `view-transition-name` on one page throws and breaks the animation.
+- Never animate during the transition something that also triggers data fetching — wait for the new view's critical content first.
+- Test back/forward and rapid navigation; transitions must be interruptible and not queue/stack.

package/skills/pricing-page/SKILL.md

@@ -1,23 +1,23 @@
----
-name: pricing-page
-description: Design a clear, persuasive pricing page that steers users to the right plan and reduces decision anxiety.
-category: ui-design
----
-
-# Pricing Page
-
-Reach for this when designing or fixing a pricing page — clarity converts, and confusion kills more deals than price does.
-
-1. Limit to 3–4 tiers and anchor with one recommended plan, visually elevated (border accent, "Most popular" badge, slight scale) — the decoy/anchor frames the others.
-2. Make the price unmissable: large tabular number, `/mo` qualifier muted beside it, and a monthly↔annual toggle that shows the savings ("2 months free") to nudge annual.
-3. Build a feature comparison that scales by inclusion, not repetition: list the delta each tier adds, use a clean check matrix for full comparison, and put the highest-value differentiator first.
-4. Give each tier one CTA with consistent verbs; the recommended plan gets the solid primary button, others get quieter ghost buttons. Keep button widths and card heights aligned on the grid.
-5. Defuse risk near the buttons: "no credit card", "cancel anytime", money-back guarantee, and a short FAQ for the predictable objections (overage, downgrades, taxes).
-6. Polish hierarchy and motion: 8px rhythm, equal-height cards, a subtle hover lift on the recommended tier, and `prefers-reduced-motion` respected.
-
-## Rules
-- One recommended plan, clearly signaled — an undifferentiated row of equal cards makes users bounce.
-- Show the real total: surface annual-vs-monthly math and any per-seat/usage cost; hidden pricing erodes trust fast.
-- CTA verbs match commitment ("Start free trial" vs "Contact sales"), never a generic "Submit" everywhere.
-- Lead each tier with value/outcomes, not a feature dump; the comparison table is for buyers who already want detail.
-- Keep contrast and legibility on badges/accents ≥4.5:1 — the "popular" highlight must not sacrifice readability.
+---
+name: pricing-page
+description: Design a clear, persuasive pricing page that steers users to the right plan and reduces decision anxiety.
+category: ui-design
+---
+
+# Pricing Page
+
+Reach for this when designing or fixing a pricing page — clarity converts, and confusion kills more deals than price does.
+
+1. Limit to 3–4 tiers and anchor with one recommended plan, visually elevated (border accent, "Most popular" badge, slight scale) — the decoy/anchor frames the others.
+2. Make the price unmissable: large tabular number, `/mo` qualifier muted beside it, and a monthly↔annual toggle that shows the savings ("2 months free") to nudge annual.
+3. Build a feature comparison that scales by inclusion, not repetition: list the delta each tier adds, use a clean check matrix for full comparison, and put the highest-value differentiator first.
+4. Give each tier one CTA with consistent verbs; the recommended plan gets the solid primary button, others get quieter ghost buttons. Keep button widths and card heights aligned on the grid.
+5. Defuse risk near the buttons: "no credit card", "cancel anytime", money-back guarantee, and a short FAQ for the predictable objections (overage, downgrades, taxes).
+6. Polish hierarchy and motion: 8px rhythm, equal-height cards, a subtle hover lift on the recommended tier, and `prefers-reduced-motion` respected.
+
+## Rules
+- One recommended plan, clearly signaled — an undifferentiated row of equal cards makes users bounce.
+- Show the real total: surface annual-vs-monthly math and any per-seat/usage cost; hidden pricing erodes trust fast.
+- CTA verbs match commitment ("Start free trial" vs "Contact sales"), never a generic "Submit" everywhere.
+- Lead each tier with value/outcomes, not a feature dump; the comparison table is for buyers who already want detail.
+- Keep contrast and legibility on badges/accents ≥4.5:1 — the "popular" highlight must not sacrifice readability.

package/skills/scroll-animation/SKILL.md

@@ -1,23 +1,23 @@
----
-name: scroll-animation
-description: Build scroll-triggered and scroll-linked animations (GSAP/Framer Motion) that stay smooth and jank-free.
-category: ui-design
----
-
-# Scroll Animation
-
-Reach for this when content should reveal, pin, or parallax as the user scrolls — done well it adds depth; done badly it stutters and hijacks the page.
-
-1. Decide trigger vs. scrub: reveal-on-enter (fire once when in view) vs. scroll-linked (progress tied to scroll position). Most sections want reveal; reserve scrubbing for hero/storytelling.
-2. For reveals, prefer the native `IntersectionObserver` (or Framer Motion `whileInView` with `viewport={{ once: true }}`) — cheap and battery-friendly. Add a `rootMargin` so it triggers slightly before the element hits the fold.
-3. For scrubbed/pinned sequences use GSAP ScrollTrigger with `scrub: true` (or a small smoothing number); animate only `transform`/`opacity` and let GSAP batch reads/writes.
-4. Build the parallax/depth illusion with differential `translateY` on layers via transform — never animate `background-position` or `top` during scroll.
-5. Stagger grouped reveals (40–80ms) and keep per-element distance small (16–40px rise) — large travel reads as laggy and forces reflow into view.
-6. Disable scroll effects (or make them instant) under `prefers-reduced-motion`, and lazy-init heavy ScrollTriggers below the fold so first paint stays fast.
-
-## Rules
-- Never block or rubber-band native scroll; smooth-scroll libraries (Lenis) are opt-in and must respect reduced-motion.
-- Keep work off the scroll thread: no layout-triggering properties, no `getBoundingClientRect` per frame in your own handlers — let IO/ScrollTrigger do it.
-- Content must be fully readable with JS disabled or before the observer fires — start visible, animate enhancement, never hide-until-scripted as the only path.
-- Test on a mid-tier phone at 60fps; if you see dropped frames, reduce simultaneous animated elements before tweaking easing.
-- `will-change: transform` only on elements actively animating, and remove it after — leaving it on bloats the compositor.
+---
+name: scroll-animation
+description: Build scroll-triggered and scroll-linked animations (GSAP/Framer Motion) that stay smooth and jank-free.
+category: ui-design
+---
+
+# Scroll Animation
+
+Reach for this when content should reveal, pin, or parallax as the user scrolls — done well it adds depth; done badly it stutters and hijacks the page.
+
+1. Decide trigger vs. scrub: reveal-on-enter (fire once when in view) vs. scroll-linked (progress tied to scroll position). Most sections want reveal; reserve scrubbing for hero/storytelling.
+2. For reveals, prefer the native `IntersectionObserver` (or Framer Motion `whileInView` with `viewport={{ once: true }}`) — cheap and battery-friendly. Add a `rootMargin` so it triggers slightly before the element hits the fold.
+3. For scrubbed/pinned sequences use GSAP ScrollTrigger with `scrub: true` (or a small smoothing number); animate only `transform`/`opacity` and let GSAP batch reads/writes.
+4. Build the parallax/depth illusion with differential `translateY` on layers via transform — never animate `background-position` or `top` during scroll.
+5. Stagger grouped reveals (40–80ms) and keep per-element distance small (16–40px rise) — large travel reads as laggy and forces reflow into view.
+6. Disable scroll effects (or make them instant) under `prefers-reduced-motion`, and lazy-init heavy ScrollTriggers below the fold so first paint stays fast.
+
+## Rules
+- Never block or rubber-band native scroll; smooth-scroll libraries (Lenis) are opt-in and must respect reduced-motion.
+- Keep work off the scroll thread: no layout-triggering properties, no `getBoundingClientRect` per frame in your own handlers — let IO/ScrollTrigger do it.
+- Content must be fully readable with JS disabled or before the observer fires — start visible, animate enhancement, never hide-until-scripted as the only path.
+- Test on a mid-tier phone at 60fps; if you see dropped frames, reduce simultaneous animated elements before tweaking easing.
+- `will-change: transform` only on elements actively animating, and remove it after — leaving it on bloats the compositor.