agemon 0.1.0 → 6.3.0

package/assets/skills/design/agemon-design/references/review.md

@@ -0,0 +1,340 @@
+# UI Review & Critique
+
+Systematic methodology for reviewing interface quality — visual design, interaction, accessibility, and performance.
+
+---
+
+## Feedback Hierarchy
+
+Evaluate in order: Value → Ease of Use → Delight. Aesthetic feedback that arrives before Value and Ease is feedback misallocation — it tells the team to polish a thing that may not be solving the right problem, or polish a thing the user can't actually use.
+
+### 1. Value — does this solve the problem the user came for?
+
+- Confirm the surface answers the user's question (cite the brief.md success metric if available).
+- Test against the primary user (also from brief.md) — does the path from arrival to outcome exist, and is it the shortest path the design allows?
+- Findings here block all subsequent feedback. If Value fails, the visual review is not yet useful.
+- Examples of Value findings:
+  - "User cannot find the report they came to read — search is hidden in a settings menu."
+  - "The empty state is decorative but doesn't explain how to add the first item."
+  - "Primary CTA leads somewhere unexpected — clicked Save, taken to a list view, no confirmation."
+
+### 2. Ease of Use — can the user accomplish the task?
+
+- Path length: count clicks/taps from arrival to outcome. Compare against the user's expectation.
+- State coverage: every state the user encounters has explicit affordance (loading, empty, error, partial, success).
+- Friction points: where does the user need to think, type, or wait? Each friction point earns a finding.
+- Accessibility floor: if a path is unusable for a keyboard or screen-reader user, it's an Ease of Use failure (not a Delight failure — defer this in your head before promoting).
+- Cross-ref: `accessibility.md`, `state-design.md`, `forms.md`.
+
+### 3. Delight — does it feel polished?
+
+- This is the layer most reviews start with — and most reviews stay here, missing the failures above.
+- Delight findings are real and valuable, but they are **the last 20% of leverage**, not the first.
+- The full Delight pass is the Finish Bar (`finish-bar.md` — 10 passes).
+- Common Delight findings: hierarchy ratios off, type weights inconsistent, motion missing, microcopy generic, surface stack flat.
+
+### How to triage
+
+- Start by reading the surface against the brief (Value).
+- If Value findings exist, write them as the first section of the report. Recommend the team fix Value before considering Delight feedback. **Do not include Delight findings in a report where Value is failing — it dilutes the signal.**
+- If Value passes, evaluate Ease of Use. Same rule: surface Ease findings before Delight.
+- If Value and Ease both pass, run the Finish Bar.
+- The brief's principles can downgrade or defer findings (e.g., a brief that records "speed over completeness" defers some Ease findings about progressive disclosure).
+
+### When to skip Value-first
+
+- Pure visual review at the request of design (e.g., "review this hero animation") — the user has explicitly scoped to Delight. Honor it; note in the report header that Value was not assessed.
+- Library/component reviews where the component is generic and Value depends on consumer code. Run Ease and Delight only.
+- Brand/marketing surfaces where conversion is the metric — Value is "did the user do the conversion action?" — apply the hierarchy but the bar shifts.
+
+---
+
+## How to Use
+
+- **`/agemon-design review <file>`** — UX critique, flag issues, no code changes
+- **`/agemon-design audit <file>`** — Technical audit (a11y, perf, responsive), severity-ranked
+- **`/agemon-design polish <file>`** — Apply the Polish Pass compound details directly
+
+---
+
+## Review Output Format
+
+For file reviews, use terse findings:
+
+```
+file:line - [category] description of issue → fix
+```
+
+Example:
+```
+components/modal.tsx:45 - [animation] Exit 400ms exceeds 300ms limit → reduce to 200ms
+components/button.css:12 - [interaction] Missing :active transform → add scale(0.97)
+```
+
+---
+
+## Critique Methodology (for screenshots or deep review)
+
+Follow this sequence. Each section is a separate lens.
+
+### Step 0: Context
+- **What is this?** (app type, screen purpose, target user)
+- **Emotional context?** (stressful? casual? high-stakes? routine?)
+
+### Step 1: Anti-Slop Detection (CRITICAL)
+
+Run the Anti-Slop Test from [core-rules.md](core-rules.md) (Critical → Major → Minor). Every item present is a finding.
+
+**The test**: "If someone said AI made this, would they believe it immediately?"
+
+### Step 2: First Impressions
+One paragraph on gut reaction. Be honest and direct. This is the "noticing" step — seeing what's actually there, not what you expect.
+
+### Step 3: Visual Design
+
+| Dimension | What to Look For |
+|-----------|-----------------|
+| Color intentionality | Every color purposeful? Too many competing backgrounds/accents? |
+| Typographic hierarchy | Clear scale from most to least important? Count distinct sizes/weights |
+| Shadow & stroke quality | Crisp or muddy? Borders competing with content? |
+| Visual weight vs importance | Heaviest elements = most important? Decorative stealing attention? |
+| Spacing & alignment | Consistent? Clear grid? Excess padding? |
+| Icon consistency | Same family, weight, stroke width, optical size? |
+
+For each issue:
+> **[Issue name]** — [Specific factual observation]. [Impact on user]. [What it could be instead.]
+
+Be precise. Count things. Quote text. Name colors. Measure relative sizes.
+
+### Step 4: Interface Design
+
+| Dimension | What to Look For |
+|-----------|-----------------|
+| Focusing mechanism | Clear where to look first? Visual entry point? |
+| Progressive disclosure | Complexity revealed gradually? 40 things when 5 would suffice? |
+| Information density | Appropriate for context? |
+| Expectation setting | User knows what happens next? Progress communicated? |
+| Feedback & reward | Actions acknowledged? Completed items celebrated? |
+| Redundancy | Labels repeating known information? Can anything be removed? |
+
+Frame as missed opportunities:
+> "We're missing an opportunity to [reward progress / reduce cognitive load / etc.]"
+
+### Step 5: Consistency & Conventions
+
+| Dimension | What to Look For |
+|-----------|-----------------|
+| Pattern consistency | Similar actions handled the same way? |
+| Platform conventions | Follows established patterns? Deviations intentional? |
+| Component reuse | Elements that should be same component but aren't? |
+| Visual language cohesion | Feels like one designer or assembled from different kits? |
+
+### Step 6: User Context
+- **How does this make the user feel?** Name the emotion.
+- **User's likely state of mind?** Anxious? Focused? Under pressure?
+- **Does the interface respect that state?**
+- **What would "uncommon care" look like here?**
+
+---
+
+## Evidence Gate
+
+A finding only counts once it clears three bars. Anything missing one of these is a **candidate**, not a finding — drop it or keep investigating, but don't write it into the report as-is.
+
+1. **Cite the rule.** Name the specific rule or decision the issue violates — a line from this file, from `brief.md`, from the token spine, from an explicit accessibility requirement. "This feels off" is not a citation.
+2. **Prove it reaches the rendered surface.** Trace the real path — file:line through the actual render, import, or token-resolution chain — that gets you from the code you're pointing at to the pixels the user sees. Two components sharing a name, or a token that merely looks related, is not proof; grep proximity is not proof. If you can't walk the chain, you don't have a finding yet.
+3. **One concrete fix.** Exactly one, specific enough to apply directly — not a menu of options, not "consider revisiting."
+
+**Falsification pass.** Before the report goes out, re-open the evidence for every candidate and actively try to disprove it — check whether the cited rule actually applies in this context, whether the traced path really executes, whether the fix could break something the candidate didn't account for. Only candidates that survive an honest attempt to kill them get written up.
+
+**Signal cap.** Rank surviving findings by impact × confidence and report the ones that matter — roughly the top 3-5, not an exhaustive list. Say explicitly what else was observed and cut, so the reader knows the noise was filtered, not missed. A short, high-confidence report beats an exhaustive, noisy one.
+
+**Scope discipline.** A review or audit pass fixes what it found — it does not refactor unrelated code, swap libraries or frameworks, or add ARIA and abstraction layers where native semantics already solve the problem. The smallest change that resolves the finding is the correct one.
+
+---
+
+## Craft Report
+
+Every review, polish, audit, or refine pass ends with a Craft Report — a receipt of the run. This is non-negotiable: **a pass that changes nothing still produces the report.** "Everything checked out" is a finding, and the most important one to surface — a silent no-op reads as the tool doing nothing, while a receipt turns the same no-op into validation the user can act on.
+
+Sections may be omitted when empty, except **Checked** and **Verdict** — those two always appear, even on a pure pass.
+
+- **Checked** — which dimensions or rule sets actually ran (anti-slop scan, hierarchy, type, color/contrast, motion, a11y, states…) and over what scope (which files or surfaces). Never imply coverage broader than what actually ran.
+- **Passed** — what was inspected and found sound, with a word on the evidence behind it (e.g. "focus states present on all interactive elements in nav + forms," not "looks fine"). This is the payload when little or nothing changed — treat it with the same rigor as a finding, not as filler.
+- **Changed** — each change, one line, with a file reference and the rule or decision it serves. Every entry here already cleared the Evidence Gate above — no changes ship without a citation and a fix.
+- **Left alone** — deliberate non-changes: things that look unusual but are intentional or brand, things technically correct so untouched, things out of scope or that need a user decision. One line each with the why — this is what separates "didn't notice" from "noticed, chose not to touch."
+- **Verdict** — one sentence: overall state, plus the single highest-leverage next step if one exists (or "no open findings in what was checked" if none does). Never a ship or no-ship ruling.
+
+Keep it honest and short. The report reflects what this run actually inspected — no padding, no invented coverage, no claiming a dimension was checked because it usually is.
+
+---
+
+## Comprehensive Audit Checklist
+
+### Animation Audit
+- [ ] No `transition: all` — properties listed explicitly
+- [ ] No `scale(0)` entry — starts from `scale(0.95)` with `opacity: 0`
+- [ ] No `ease-in` on UI elements — use `ease-out` or custom curve
+- [ ] No `transform-origin: center` on popovers — set to trigger location (modals exempt)
+- [ ] No animation on keyboard actions
+- [ ] No duration > 300ms on UI elements
+- [ ] No hover animation without `@media (hover: hover) and (pointer: fine)`
+- [ ] No keyframes on rapidly-triggered elements — use CSS transitions
+- [ ] Animation library uses compositor-promoted properties under load
+- [ ] Exit faster than enter
+- [ ] Stagger delays ≤ 50ms per item
+- [ ] `prefers-reduced-motion` respected
+- [ ] No entrance animation on first paint for default-state elements (`initial={false}` on `AnimatePresence`)
+
+### Interaction Audit
+
+Full checklist lives in `accessibility.md` (**Quick Checklist** + **Forms**). Fast pass:
+
+- [ ] Full keyboard navigation (WAI-ARIA APG)
+- [ ] Visible focus rings (`:focus-visible`)
+- [ ] Hit targets ≥ 24px (44px mobile)
+- [ ] URL reflects state (filters, tabs, pagination)
+- [ ] Links use `<a>`/`<Link>`, not `<div onClick>`
+- [ ] Destructive actions confirmed or Undo provided
+- [ ] Loading buttons show spinner + keep label
+- [ ] Forms: paste not blocked, errors inline, autocomplete set
+- [ ] `overscroll-behavior: contain` in modals/drawers
+- [ ] `touch-action: manipulation` on controls
+
+### Layout Audit
+- [ ] Optical alignment (±1px adjustments where needed)
+- [ ] Deliberate grid/baseline/edge alignment
+- [ ] Responsive: mobile, laptop, ultra-wide verified
+- [ ] Safe areas respected
+- [ ] No unwanted scrollbars
+- [ ] Flex children have `min-w-0` for truncation
+- [ ] Text containers handle long content
+- [ ] Empty states handled
+
+### Design Audit
+- [ ] Layered shadows (ambient + direct)
+- [ ] Nested radii: child ≤ parent
+- [ ] Hue-consistent borders/shadows on colored backgrounds
+- [ ] APCA contrast met
+- [ ] Interactions increase contrast
+- [ ] `color-scheme: dark` on html in dark themes
+- [ ] `theme-color` matches background
+- [ ] `tabular-nums` for number comparisons
+- [ ] `text-wrap: balance` on headings
+- [ ] Images have inset outline `black/10` (light) / `white/10` (dark) — never tinted
+- [ ] `-webkit-font-smoothing: antialiased` on root (macOS)
+
+### Performance Audit
+- [ ] Only compositor props animated (`transform`, `opacity`)
+- [ ] No layout thrashing (interleaved reads/writes)
+- [ ] Large lists virtualized (>50 items)
+- [ ] Images: preload above-fold, lazy rest, explicit dimensions
+- [ ] Re-renders minimized
+- [ ] CSS variables not animated on deep trees
+- [ ] `will-change` used temporarily and surgically
+- [ ] Blur ≤ 8px, never continuous, never on large surfaces
+
+---
+
+## Output Format for Critiques
+
+```
+## Context
+[1-2 sentences]
+
+## Anti-Slop Tells
+[Each tell present, with the element and viewport; "none found" if clean]
+
+## First Impressions
+[1 paragraph, direct]
+
+## Visual Design
+[Issues as: **Issue Name** — observation. Impact. Opportunity.]
+
+## Interface Design
+[Issues framed as missed opportunities]
+
+## Consistency & Conventions
+[Pattern issues]
+
+## User Context
+[Empathy-driven observations]
+
+## Top Opportunities
+[Ranked 3-5 highest-impact changes, one sentence each]
+```
+
+---
+
+## Voice Rules
+
+### BE:
+- **Specific** — "There are six columns per row" not "a lot of data"
+- **Decisive** — "This is overwhelming" not "might feel overwhelming"
+- **Factual first** — State what you see before judging
+- **Impact-aware** — Connect observation to user impact
+- **Constructive** — Every problem paired with opportunity
+- **Quantitative** — Count elements, name colors, measure sizes
+
+### DO NOT:
+- Hedge ("maybe", "perhaps")
+- Apologize ("unfortunately")
+- Be vague ("feels off" without specifics)
+- Add praise padding (no manufactured positivity)
+- Prescribe without reasoning
+
+### Severity Priority
+1. **Structural** — information architecture, mental model, missing functionality
+2. **Behavioral** — response, flow, communication
+3. **Visual** — color, type, spacing, shadows
+
+---
+
+## Polish Pass (Compound Details)
+
+The difference between "correct" and "crafted" is 20 small things done right. Run this checklist after the UI works (required when CRAFT_LEVEL is 8+):
+
+- **Brand names use `&nbsp;`** — prevent "UI" on one line and "Craft" on the next
+- **Confirmation feedback is visual, not just color** — swap icon to checkmark, not just green tint
+- **One visual anchor per text-heavy page** — a code block, screenshot, or diagram breaks monotony
+- **Headings sit closer to their content than to the previous section** — unequal spacing creates grouping
+- **Footer earns its space or disappears** — generic "Built by Name" adds nothing
+- **Test on mobile before declaring done** — drag interactions, overflow, label overlap, touch targets
+- **Secondary actions don't compete with primary** — outline/ghost for secondary, solid for primary
+- **Data-heavy content uses monospace or tabular-nums** — even in casual contexts
+- **Images inside interactive containers can't be natively dragged** — kills slider/carousel UX
+- **Every `<section>` on a landing page answers one question** — if it answers two, split it
+
+---
+
+## Common Issues (What We See in Real Projects)
+
+When reviewing or polishing existing UI, these are the most frequent problems:
+
+| Issue | How to spot it | Fix |
+|-------|---------------|-----|
+| Everything is the same shade of gray | Squint test — no visual hierarchy | Darken headings to 900, lighten secondary to 500, add one accent |
+| Cards all look identical | 4+ cards with same border, radius, shadow | Differentiate primary card, vary content types, break the grid |
+| Hover states missing or default | Buttons/cards don't respond to cursor | Add translateY(-1px) + shadow on cards, bg darken on buttons |
+| Spacing is uniform everywhere | Same gap between all sections | Vary: tighter within groups, looser between sections |
+| No loading/empty/error states | Only the happy path is designed | Add skeleton, empty state with CTA, inline errors |
+
+---
+
+## Component Craft
+
+- **Interactive elements have three states minimum** — rest, hover/focus, active/pressed. If it looks the same when you click it, it feels broken.
+- **Button hierarchy guides action** — primary = solid, secondary = outline/ghost, destructive = red outline. Only ONE primary per view section.
+- **Feedback must be visual, not just color** — swap icon to checkmark, show inline confirmation, animate the state change. Color alone fails colorblind users.
+- **Metric cards vary treatment** — if 3+ cards share structure, differentiate the primary (heavier weight, slightly larger number, subtle bg tint — never thick colored borders).
+- **Price typography splits weight** — dollar sign lighter/smaller than the number, period label ("/month") in secondary color.
+- **Prevent native image drag** on interactive overlays — `user-drag: none; -webkit-user-drag: none; pointer-events: none` on images inside sliders/carousels.
+- **Placeholders are visual, not text** — skeleton bars, subtle grid lines, muted pattern. "Chart would render here" looks unfinished.
+
+**Hover & interaction micro-details** (gate behind `@media (hover: hover) and (pointer: fine)`):
+
+- Cards: `transform: translateY(-1px)` + shadow increase — `transition: transform 200ms ease-out, box-shadow 200ms ease-out` / Tailwind: `hover:-translate-y-px hover:shadow-md transition-[transform,box-shadow] duration-200`
+- Buttons: slight bg darkening, not a full color swap — `transition: background 150ms ease-out` / Tailwind: `hover:bg-accent/90 transition-colors duration-150`
+- Table rows: subtle bg — `hover:bg-gray-50` / Tailwind: `hover:bg-slate-50/50`
+- Links: `text-underline-offset: 2px; text-decoration-skip-ink: auto` / Tailwind: `underline-offset-2 decoration-skip-ink-auto`
+- Active/pressed: `transform: scale(0.98)` on buttons for tactile feedback

package/assets/skills/design/agemon-design/references/routing.md

@@ -0,0 +1,143 @@
+# Routing detail
+
+The ladder, intent table and reference tiers that used to sit in `SKILL.md`. Use it when a request does not map cleanly to a track or action. The reference map in [SKILL.md](../SKILL.md) is the short version.
+
+## The Ladder (use this when explaining agemon-design to the user)
+
+One progression, three rungs. Never describe agemon-design as "layers" or "modes" — use these rung names, and name the rung the user is on before suggesting an action.
+
+| Rung | User wants | They do | They get | Effort |
+|------|-----------|---------|----------|--------|
+| **0 · Ask** | better UI, zero effort | ask for UI as always | taste by default: real hierarchy, system tokens, no slop | none |
+| **1 · Direct** | control one pass | `/agemon-design build`, `review`, `polish`, `harden`, `audit`, `animate` | a focused pass on one surface | one request |
+| **2 · Persist** | consistency across sessions | `/agemon-design brief`, `/agemon-design tokens` | durable design context every future session reads | write once |
+
+When a pass finishes, name the natural next step (`build` → `review`, `brief` → `tokens`, `audit` → `harden`).
+
+## Intent routing
+
+Invoke an action as `/agemon-design <action>`, or just say what you want in plain words — "review this page", "write the brief", "harden the settings form" route the same way. The actions are `brief`, `tokens`, `build`, `review`, `polish`, `harden`, `audit` and `animate`; each is defined in [actions.md](actions.md). Anything else routes by the table below.
+
+| Intent | Pass / Reference |
+|--------|------------------|
+| Pre-build: write the project's design brief | Action `brief` → [actions.md](actions.md#brief), format in [brief.md](brief.md) |
+| Pre-build: establish or audit token spine | Action `tokens` → [actions.md](actions.md#tokens), contract in [tokens.md](tokens.md) |
+| Build a whole surface in one shot | Action `build <surface>` → [actions.md](actions.md#build); outcome recipes: [recipe-dashboard.md](recipe-dashboard.md), [recipe-landing.md](recipe-landing.md), [recipe-auth.md](recipe-auth.md) |
+| Pick a ready-made theme (no token system exists) | [themes.md](themes.md) — 4 production token presets |
+| Building new UI | **Build pass** (rung 0/1) — [stage-build.md](stage-build.md) + relevant references |
+| Adding/fixing animations | Action `animate` → [actions.md](actions.md#animate) + **Motion pass** — [motion.md](motion.md) |
+| Reviewing existing UI, UX critique, no code changes | Action `review` → [actions.md](actions.md#review) + **Review pass** — [review.md](review.md), [inspiration.md](inspiration.md) — ends with a Craft Report |
+| Polishing existing UI | Action `polish` → [actions.md](actions.md#polish) + [review.md](review.md) Polish Pass — ends with a Craft Report |
+| Multi-stage animations | [motion.md](motion.md) — choreography and stagger |
+| Layout / spacing | [layout.md](layout.md) |
+| Typography | [typography.md](typography.md) |
+| Color / theming / dark mode | [color.md](color.md) |
+| Accessibility / technical audit | Action `audit` → [actions.md](actions.md#audit) + [accessibility.md](accessibility.md) |
+| Production hardening (states, i18n, edge cases) | Action `harden` → [actions.md](actions.md#harden) + [state-design.md](state-design.md) |
+| Amplify personality ("make it bolder") or tone down ("quieter", "more restrained") | [craft-intent.md](craft-intent.md) — raise or lower DESIGN_VARIANCE and MOTION_INTENSITY |
+| Purposeful micro-interactions | [motion.md](motion.md) |
+| Animation performance | [motion.md](motion.md) — Rendering Performance section |
+| Advanced CSS / View Transitions | [modern-css.md](modern-css.md) |
+| Sound design | [sound.md](sound.md) |
+| UX copy / voice / tone / microcopy | [copy.md](copy.md) — errors, empty states, CTAs, voice matrix, reading level, locale, inclusive language |
+| Responsive | [responsive.md](responsive.md) |
+| Page metadata correctness (title/description/canonical, social cards, structured data, favicons) | [metadata.md](metadata.md) |
+| Three.js / GSAP / Motion | [stack.md](stack.md) — **OPT-IN ONLY — do not load unless the user chose Motion/GSAP/Three.js during intake** |
+| PM-ready, severity-ranked heuristic critique | Action `review`, heuristic review → [heuristics.md](heuristics.md) + [personas.md](personas.md) |
+| State-first design (before happy path) | [state-design.md](state-design.md) |
+| Data visualization / charts / dashboards | [dataviz.md](dataviz.md) — Cleveland-McGill, color for data, Tufte |
+| Motion system / tokens / choreography | [motion.md](motion.md) — duration + easing scale, motion budget |
+| Wireframe-first: lay out states and content before coding | [state-design.md](state-design.md) — state lattice + content inventory |
+| AI / chat / streaming surfaces | [ai-chat.md](ai-chat.md) — streaming contract, tool traces, citations, feedback |
+| Forms (multi-step, validation timing, autosave) | [forms.md](forms.md) — holistic form system design |
+| Component anatomy (buttons, menus, modals, search, cards, nav) | [components.md](components.md) — contracts below the surface level |
+| Pre-ship: full finishing bar before merge | [finish-bar.md](finish-bar.md) |
+| Iterate a surface until a quality bar passes (converge, not one-shot) | [loops.md](loops.md) — loop engine + presets |
+| Remember a design correction (record as a learned constraint) | [brief.md](brief.md) — Self-Correction |
+| Ambiguous | Ask which action |
+
+**Overlap with other skills:** defer marketing copy to a copywriting skill; defer SEO strategy to an SEO skill — agemon-design covers the correctness of metadata already being emitted ([metadata.md](metadata.md)), not keyword or ranking strategy. agemon-design is the visual and interaction layer.
+
+**Out of scope.** These are surface classes the recipes do not help with. Say so, name the right tool, and still apply agemon-design to the web surfaces around them — a brief containing one of these is rarely only that.
+
+| Not this | Use instead |
+|---|---|
+| Code editor surfaces (syntax, gutters, diff views) | Monaco or CodeMirror with their own theming API |
+| Native mobile apps | Apple HIG or Material directly — agemon-design covers web |
+| Realtime collaboration UI (presence, live cursors, conflict states) | Liveblocks, or Yjs / Automerge if you own the sync layer — the recipes assume a single actor |
+| HTML email | MJML or a dedicated email framework — the CSS rules here are void in mail clients |
+
+Refusing with a pointer beats confident bad output. Silence produces the second one.
+
+## Reference Files
+
+Tiered by signal. Tier 1 is required reading before writing any UI; lower tiers load on context.
+
+### Tier 1 — Always load before writing UI
+
+Two entries, because two is what a build actually loads. This list used to hold seven; build evals showed a passing dashboard opened one of them and a passing landing opened two, while both reached for the surface recipe that was filed a tier below. A required list that nobody reads is not a standard, it is a wish — so the list now names what carries the build, and everything else below states the trigger that pulls it in.
+
+| Reference | When to Read |
+|-----------|--------------|
+| [craft-intent.md](craft-intent.md) | Craft Read, DESIGN_VARIANCE, signature bets, product + marketing build patterns. The one reference every full-surface build needs. |
+| **The surface recipe** | [recipe-dashboard.md](recipe-dashboard.md) · [recipe-landing.md](recipe-landing.md) · [recipe-auth.md](recipe-auth.md) — whichever matches what you are building. Every numeric limit that keeps a surface off template grammar lives here (hero subtext ≤20 words, eyebrow budget, form column width, acceptance bar). Skipping it does not soften those limits, it removes them. |
+
+### Tier 1b — Load on trigger
+
+Same references as before, same weight when their trigger fires. Only the claim changed: these are conditional, and pretending otherwise made the whole Tier-1 label unreliable — including for the two above.
+
+| Reference | Trigger |
+|-----------|---------|
+| [brief.md](brief.md) | `.design/brief.md` or an older `.ui-craft/brief.md` exists — then read it first, it anchors every decision and its learned constraints override skill defaults. Absent: run `/agemon-design brief` or proceed from [stage-intake.md](stage-intake.md). |
+| [tokens.md](tokens.md) | The project has a token system to respect or extend, or you are establishing one. With neither, derive tokens from the brief; [themes.md](themes.md) offers presets only when the user asks for one or no direction exists. |
+| [accessibility.md](accessibility.md) | Any form, any custom interactive control, any focus or keyboard work. The a11y floor in [core-rules.md](core-rules.md) is the minimum; this is the detail. |
+| [color.md](color.md) | Choosing or changing a palette, building dark mode, or auditing accent budget. Not needed to apply a preset the user asked for. |
+| [layout.md](layout.md) | Composing a surface from scratch, or a spacing/hierarchy pass. Not needed when a recipe already prescribes the composition. |
+| [inspiration.md](inspiration.md) | Highest-signal reference in the skill. Read it when the build needs an archetype or a signature detail, and whenever the result feels generic. |
+
+> **What this measured, and what it did not.** The evidence is greenfield builds — an empty
+> sandbox with no brief and no tokens, so `brief` and `tokens` could not have been read
+> whatever the label said. It shows the label was not causing loads. It does **not** show the
+> references are unnecessary: `layout` and `color` govern craft that automated checks
+> barely cover, so a build can pass every check with mediocre spacing rhythm. Re-measure before
+> trimming anything further, and re-measure on a project that already has a design system.
+
+### Tier 2 — Surface-specific (read when building this surface)
+
+| Reference | When to Read |
+|-----------|--------------|
+| [spec.md](spec.md) | Durable composition spec at `.design/spec.md` — the "what". Read after `brief.md` when a spec exists for the surface being built. |
+| **Outcome recipes** | Promoted to Tier 1 — see *Always load*. Listed there and not here so the recipe has one home; two descriptions of the same requirement is how one of them goes stale. |
+| [themes.md](themes.md) | 4 named production token presets (Graphite, Porcelain, Carbon, Signal). Load only when the user asks for a preset or no design direction exists. |
+| [dashboard.md](dashboard.md) | Dashboards, metric cards, charts, tables, sidebar, filters. |
+| [forms.md](forms.md) | Validation timing, progressive disclosure, multi-step wizards, autosave, optimistic submit. |
+| [components.md](components.md) | Component anatomy contracts: buttons (padding ratio, icon-side semantics), menus (5-option threshold, scroll affordance), modals (verb labels, ways out), search, content cards, nav bar. |
+| [ai-chat.md](ai-chat.md) | Streaming contract, 7-state affordance model for AI surfaces, tool traces, citations, generative UI. |
+| [review.md](review.md) | Critique methodology, Polish Pass, common issues, component craft. Load when reviewing or refining. |
+| [finish-bar.md](finish-bar.md) | 10-pass finishing protocol. Load at CRAFT_LEVEL ≥ 8, or when the user asks for a full pre-ship pass. |
+| [loops.md](loops.md) | Loop engine: read→evaluate→fix-one→re-evaluate→stop contract + 3 presets. Load when the user asks to iterate a surface or a token audit until a bar passes. |
+| [principles-catalog.md](principles-catalog.md) | 42 example design principles across 8 product categories. Load during the `/agemon-design brief` principles workshop branch as conversation seed. |
+
+### Tier 3 — Foundations (read for the relevant discipline)
+
+| Reference | When to Read |
+|-----------|--------------|
+| [typography.md](typography.md) | Scale, font choice, readability, weight — scoped per script and role. |
+| [motion.md](motion.md) | Decision ladder, duration + easing scales with perceptual grounding, interaction rules, motion-gap audit. |
+| [modern-css.md](modern-css.md) | View Transitions, scroll timelines, container queries, `@starting-style`. |
+| [responsive.md](responsive.md) | Mobile/tablet/desktop, breakpoints, touch zones. |
+| [metadata.md](metadata.md) | Title/description/canonical consistency, deterministic metadata, social cards, noindex on staging, structured data honesty, favicons. |
+| [tells-2026-11.md](tells-2026-11.md) | Checking your own palette, type and layout plan against what generated interfaces converge on. Calibration only: it never overrides a brand or a brief. |
+| [copy.md](copy.md) | Voice/tone matrix, reading level (Flesch ≥70), terminology, inclusive language, errors, empty states, CTAs. |
+| [sound.md](sound.md) | Web Audio, UI sound, appropriateness matrix. Rare — load when explicitly building audio feedback. |
+
+### Tier 4 — Opt-in (only on explicit request or specific commands)
+
+| Reference | When to Read |
+|-----------|--------------|
+| [stack.md](stack.md) | Three.js / GSAP / Motion — **opt-in only — do not load unless the user chose Motion/GSAP/Three.js during intake.** |
+| [heuristics.md](heuristics.md) | Nielsen's 10 + 6 design laws (Fitts, Hick, Doherty, Cleveland-McGill, Miller, Tesler) as a checklist. Load for the heuristic review of `/agemon-design review`. |
+| [personas.md](personas.md) | 5 persona walkthroughs (first-timer / power / low-bandwidth / screen-reader / one-thumb). Load when a heuristic review names a persona. |
+| [state-design.md](state-design.md) | State lattice — idle / loading / empty / error / partial / conflict / offline. Load for `/agemon-design harden` and state-first design. |
+| [dataviz.md](dataviz.md) | Cleveland-McGill perceptual hierarchy, chart selection matrix, ColorBrewer/Okabe-Ito palettes, Tufte, direct labeling. Load when designing charts. |
+

package/assets/skills/design/agemon-design/references/sound.md

@@ -0,0 +1,150 @@
+# Sound Design for UI
+
+Web Audio API best practices, UI sound appropriateness, and implementation.
+
+---
+
+## When Sound is Appropriate
+
+| Interaction | Sound? | Reason |
+|-------------|--------|--------|
+| Payment success | Yes | Significant confirmation |
+| Form submission | Yes | User needs assurance |
+| Error state | Yes | Can't be overlooked |
+| Notification | Yes | User may not be looking |
+| Significant button | Maybe | Only for important actions |
+| Typing | **No** | Too frequent |
+| Hover | **No** | Decorative only |
+| Scroll | **No** | Too frequent |
+| Navigation | **No** | Keyboard nav would be noisy |
+
+---
+
+## Accessibility Rules
+
+- Every audio cue MUST have a visual equivalent — sound never replaces visual feedback
+- Provide explicit toggle to disable sounds in settings
+- Respect `prefers-reduced-motion` as a default proxy for sound sensitivity, AND provide an explicit independent sound toggle. **Why caveat:** the proxy is imperfect — some users tolerate visual motion but not audio (vestibular conditions, hearing aids), some users tolerate audio but not motion. Always offer a sound toggle separate from motion preference; reduced-motion is the default-off, not the only signal.
+- Allow volume adjustment independent of system volume
+- Never add sound to high-frequency interactions
+- Sound should inform, not punish — avoid harsh sounds for mistakes
+
+---
+
+## Web Audio API Implementation
+
+### Single AudioContext
+
+Single AudioContext per page. Never create new AudioContext per sound. **Why critical:** browsers limit AudioContext instances (typically 6 per page); exhausting them silently fails new sounds. A shared AudioContext also synchronizes timing across rapid-fire UI feedback (typing keystrokes, button clicks within 50ms) — independent contexts desync.
+
+```ts
+let audioContext: AudioContext | null = null;
+function getAudioContext(): AudioContext {
+  if (!audioContext) audioContext = new AudioContext();
+  return audioContext;
+}
+```
+
+### Resume Suspended Context
+```ts
+if (ctx.state === "suspended") ctx.resume();
+```
+
+### Clean Up Nodes
+```ts
+source.onended = () => { source.disconnect(); gain.disconnect(); };
+```
+
+---
+
+## Sound Design Patterns
+
+### Clicks/Taps (Percussion) — Use Filtered Noise
+```ts
+const buffer = ctx.createBuffer(1, ctx.sampleRate * 0.008, ctx.sampleRate);
+const data = buffer.getChannelData(0);
+for (let i = 0; i < data.length; i++) {
+  data[i] = (Math.random() * 2 - 1) * Math.exp(-i / 50);
+}
+
+const filter = ctx.createBiquadFilter();
+filter.type = "bandpass";
+filter.frequency.value = 4000;  // 3000-6000Hz range
+filter.Q.value = 3;             // 2-5 for focused but not harsh
+source.connect(filter).connect(gain).connect(ctx.destination);
+```
+
+### Confirmations/Pops (Tonal) — Use Oscillators
+```ts
+const osc = ctx.createOscillator();
+osc.frequency.setValueAtTime(400, t);
+osc.frequency.exponentialRampToValueAtTime(600, t + 0.04);
+```
+
+### Envelope
+
+Use exponential decay (not linear) for sound envelopes. **Why:** linear decay produces an audible click as the envelope hits zero — the abrupt stop creates a high-frequency artifact at the cutoff. Exponential decay mimics natural acoustic decay (room reverberation, string damping) — it reaches zero asymptotically, no click.
+
+```ts
+gain.gain.setValueAtTime(0.3, t);  // set initial value first
+gain.gain.exponentialRampToValueAtTime(0.001, t + 0.05);  // never target 0
+```
+
+---
+
+## Parameters
+
+| Parameter | Range | Notes |
+|-----------|-------|-------|
+| Click duration | 5-15ms | Quick and percussive |
+| Filter frequency | 3000-6000Hz | For click sounds |
+| Filter Q | 2-5 | Focused but not harsh |
+| Gain | ≤ 1.0 | Prevent clipping |
+| Default volume | 0.3 | Subtle, not loud |
+| "too harsh" | → lower filter frequency, reduce Q | |
+| "too muffled" | → higher filter frequency | |
+| "too long" | → shorter duration, faster decay | |
+| "cuts off" | → use exponential decay | |
+| "more mechanical" | → higher Q, faster decay | |
+| "softer" | → lower gain, triangle wave | |
+
+---
+
+## Weight Matching
+
+Sound weight should match action importance:
+- **Subtle click** for toggle switches
+- **Soft pop** for adding items
+- **Rich confirmation** for purchases/payments
+- **Brief alert** for errors
+
+Sound duration should match action duration:
+- **50ms** for clicks/taps
+- **100-200ms** for confirmations
+- **Longer** for uploads/completions
+
+---
+
+## Preloading
+
+```ts
+const sounds = {
+  success: new Audio("/sounds/success.mp3"),
+  error: new Audio("/sounds/error.mp3"),
+};
+Object.values(sounds).forEach(audio => audio.load());
+
+// Reset before replay for rapid triggering
+function play(sound: HTMLAudioElement) {
+  sound.currentTime = 0;
+  sound.play();
+}
+```
+
+---
+
+## Cross-Refs
+
+- `accessibility.md` — the full reduced-motion contract; `prefers-reduced-motion` as a sound-sensitivity proxy lives there.
+- `motion.md` — sound duration should match the duration of the action it accompanies, the same pairing rule as interaction timing.
+- `state-design.md` — sound cues for state transitions (error, success) must never be the only signal; pair with the visual state.