agemon 0.1.0 → 6.3.0

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

@@ -0,0 +1,91 @@
+# Component Contracts
+
+Anatomy-level rules for the workhorse components: buttons, menus, modals, search, cards, nav. Surface-level composition lives in the recipes; form fields live in [forms.md](forms.md); metric cards and tables in [dashboard.md](dashboard.md). This file is the layer below: what makes an individual component read as designed.
+
+---
+
+## Buttons
+
+**Anatomy:**
+
+- Horizontal padding ≈ 2× vertical padding. Floors: 16px horizontal, 10px vertical. Equal padding on all sides makes a button read as a tile, not an action.
+- Heights: 44-48px on touch, 32-40px acceptable on desktop-only surfaces. **Why:** pointer precision — a mouse hits a 32px target reliably; a thumb doesn't. **When it breaks:** any desktop surface that also ships to touch (most do) — then 44px is the floor everywhere. Hit-area expansion for smaller visuals: [accessibility.md](accessibility.md).
+- Label 14-17px. Check the height/font pair for clean vertical centering: a 32px button with 17px text can't center on whole pixels — pick value pairs whose difference is even, or the label sits visibly off-center.
+- Inline groups order left→right by importance, and every state (default, hover, pressed, loading, disabled) is distinguishable without being a costume change — one property shift per state transition is usually enough.
+
+**Icon placement carries meaning:**
+
+- Icon **left** of label = aids scanning, communicates the action type at a glance (add, edit, download).
+- Icon **right** of label = consequence or destination ("Log out →", "Continue →", external-link marker).
+- Don't decorate with an icon that repeats the label without adding either.
+
+**Depth:** flat or one subtle shadow pair ([layout.md](layout.md)). Gradient fills and inner shadows on buttons are expressive opt-ins for branded marketing surfaces — inside the product they read as 2015. Anti-slop rules apply.
+
+**Tiers and their contracts:**
+
+- One primary per context — two solid CTAs in one view is a tie, and ties stall. Secondary = outline at ≥3:1 contrast (a light-gray outline button is indistinguishable from disabled). Tertiary = text + underline — the underline is an accessibility requirement for color-blind recognition, not decoration.
+- **Avoid disabled buttons.** They can't explain themselves, give nothing on press, and assistive tech often skips them. Alternatives, in order: keep enabled and validate on press with errors; remove the action and say why; lock icon + explanation on press. If one survives anyway, pair it with visible inline text saying what unlocks it.
+- Icon weight matches text weight, icon size matches text size; if an icon overpowers its label, fix it with a lighter stroke, not a washed-out color.
+
+**Destructive actions — friction proportional to blast radius:**
+
+- Low (recoverable, undo exists): act immediately + undo toast. Friction here is rude.
+- Medium (recoverable with effort): confirmation dialog with verb buttons + the affected items named and highlighted.
+- High (irreversible, shared, or bulk): confirmation + explicit acknowledgment — type the resource name or tick a checkbox before the destructive button activates. A misclick must not be able to complete the flow.
+- Destructive buttons get LOW visual prominence (tertiary/outline) in the normal UI — prominence belongs to the actions you want repeated. Inside the confirm dialog the destructive verb is the filled one, in the danger color.
+
+## Text Links
+
+- **The link affordance is exclusive.** Underline + link color mean "this navigates" — nothing else gets that costume. A colored, underlined heading that isn't a link is a broken promise; an icon styled like a button that does nothing is the same lie. Decoration must never impersonate function.
+- Inline links inside body text need the underline (color alone fails color-blind users); standalone links in chrome (nav, footers) may drop it when context already signals interactivity.
+
+## Icon Labels
+
+- **Prefer a visible text label next to icons.** Only universally-learned glyphs survive alone (search, close, play); everything else is a guess that costs a tap to verify. Icon-only buttons require `aria-label` + tooltip as the floor ([accessibility.md](accessibility.md)) — but visible labels beat both.
+
+## Menus & Dropdowns
+
+- **≤5 options: don't use a dropdown.** Radios or a visible segmented control — one less click, options scannable without interaction. The dropdown earns its collapse only past ~5 (6-10 still favors radios when vertical space allows; >10 wants type-ahead — full selection ladder in [forms.md](forms.md) Field Layout).
+- **Long lists get a scroll container with an affordance:** visible scrollbar plus the last visible item partially cut by the container edge or faded. A list that ends exactly at the container edge looks complete — users never scroll. Cutting an item mid-row is the strongest "there's more" signal available.
+- **Very long lists (countries, currencies, assignees) escalate to a searchable sheet/popover** — type-ahead beats scrolling past ~20 items, especially on mobile.
+- Multi-select: each selected option visibly marked in the list + a one-step "clear all". Nested options: signal children before expansion (chevron, count).
+- Power-user menus show keyboard shortcuts inline, right-aligned, in muted mono — see the Command composition in [recipe-dashboard.md](recipe-dashboard.md).
+- On low-contrast minimal surfaces, an open menu needs a hairline stroke and/or shadow pair to separate from the page — whitespace alone can't establish the overlay plane.
+
+## Modals
+
+- **A modal is for decisions that interrupt for good reason** — destructive confirmations, flows that must not lose context. Minor errors and notices stay inline. If putting a task in a modal adds steps versus doing it in-flow, it doesn't belong in a modal.
+- **Three ways out, always:** visible close button, an explicit cancel action, and overlay click (escape key too — [accessibility.md](accessibility.md) focus-trap rules).
+- **Confirmation buttons are verbs, never Yes/No.** "Delete project" / "Cancel" — the button restates the consequence. Yes/No forces re-reading the question, and a negatively-phrased question ("Don't you want to keep…?") plus Yes/No produces wrong clicks under time pressure.
+- Multi-step flows inside a modal show progress (step count). If the flow grows past ~3 steps, question the modal — promote to a page.
+
+## Search
+
+- Input ≥44px tall with a defined boundary (border or fill) — a search field users can't find is a navigation failure.
+- Placeholder shows example queries or the dominant content type ("Search projects, people, docs…"), not the word "Search" the icon already says.
+- Type-ahead suggestions as the user types; recent searches with individual remove + clear-all when the product is revisit-heavy.
+- **The no-results state is a fork, not a wall:** show spelling-adjacent alternatives, popular queries, or a scoped-search escape ("search all workspaces instead"). A bare "no results found" ends the session — design it like any other empty state ([state-design.md](state-design.md)).
+
+## Cards (content cards)
+
+Metric cards have their own contract in [dashboard.md](dashboard.md). For content/preview cards in grids:
+
+- **Variable-length content must not break grid rhythm.** Either clamp text (line-clamp + optional tooltip for the full string) or set a shared min-height per row. Mixed card heights in one grid read as unfinished.
+- Identical image aspect ratio across every card in the grid — one off-ratio image breaks the set.
+- Card CTA at the bottom (the reading endpoint), with hover + active states on desktop and a full-card tap target on touch.
+- Internal padding 16-24px; grid gap 16-40px scaled by [VISUAL_DENSITY]. Multi-column grids want short content; single-column (mobile) tolerates longer — the card is the whole viewport there.
+
+## Navigation (top bar)
+
+- Logo top-left links home. Universal recovery convention — breaking it strands lost users.
+- Active page visibly marked; hover states on every link.
+- One CTA in the nav, visually distinct from both the plain links and the page's own primary CTA — three levels that must not tie.
+- **Sticky nav needs a plane separator once content scrolls under it:** 1px hairline at low contrast, or backdrop blur (20-32px) over a 50-80% opacity fill. Without it the nav and content occupy the same visual plane and collide.
+- **Transparent/blurred navs must be contrast-checked against every background they'll scroll over** — the hero may pass and the white section below fail. Provide a scrolled variant (solid fill) that activates past the hero.
+- Overflow: collapse low-priority links into a "More" menu or push them to the footer; never shrink the type to fit.
+
+---
+
+## Cross-Refs
+
+[forms.md](forms.md) inputs and validation · [accessibility.md](accessibility.md) hit areas, focus, keyboard · [dashboard.md](dashboard.md) metric cards, tables, toolbars · [state-design.md](state-design.md) empty/error states · [motion.md](motion.md) state-transition timing

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

@@ -0,0 +1,300 @@
+# UX Copy & Writing
+
+Voice, tone, reading level, terminology, inclusive language, locale handling, and tactical microcopy (errors, empty states, CTAs). Clear, human interface writing.
+
+---
+
+## Voice vs Tone
+
+**Voice is constant. Tone varies.** Voice is the product's personality — how it sounds whether you're reading onboarding, an error, or a paywall. Tone is how that voice adjusts to context: warmer in onboarding, restrained in success, explicit in destructive confirms. A product with a consistent voice but responsive tone reads as designed; a product with shifting voice reads as written by 12 people.
+
+### Voice Matrix
+
+Pick three axes. Lock a position on each. Deviations are deliberate (brand campaigns, April Fools), never accidental.
+
+| Axis | Endpoints | What to lock down |
+|------|-----------|-------------------|
+| Formality | Formal ↔ Casual | Pick a position; document with one sample sentence at the chosen point and one at each extreme |
+| Reverence | Reverent ↔ Irreverent | Reverent treats the user task as serious; irreverent allows wit and acknowledges absurdity. Pick one. |
+| Expertise | Expert ↔ Beginner-friendly | Expert assumes vocabulary; beginner-friendly defines on first use. Mixed within a product is acceptable when the surfaces serve different audiences. |
+
+Document the positions. "Casual-but-respectful, beginner-friendly, mildly irreverent" is a brief a writer can execute against. "Friendly" is not.
+
+### Tone by Context
+
+Voice is fixed; tone moves along these contexts. Each row below assumes a default voice of "casual-professional, beginner-friendly, restrained."
+
+| Context | Tone | Example |
+|---------|------|---------|
+| Onboarding | Warm + specific | "Let's get your first project in. Takes 60 seconds." |
+| Error — user-recoverable | Honest + actionable | "We couldn't save your draft. Retry, or copy the error for support: `abc-123`." |
+| Error — system outage | Honest + transparent | "Search is down. We're investigating. Your data is safe." |
+| Success | Restrained | "Changes saved." — not "Amazing work!" |
+| Destructive confirm | Explicit about consequences | "Delete 3 items? You'll have 30 days to restore them from Trash." |
+| Empty state | Action-oriented | "No integrations yet. Connect Slack, GitHub, or Linear to get started." |
+| Paywall / limit | Informational, not shaming | "You're at 5/5 free projects. Upgrade to create more." |
+| Danger zone (settings) | Neutral + precise | "Deleting the workspace removes all 47 projects and invalidates all API keys." |
+| Waiting / latency | Honest about duration | "Generating report. Usually 20-40 seconds." |
+
+**Never:** exclamation points on errors. Emoji in enterprise contexts. Celebratory copy on routine saves.
+
+---
+
+## Reading Level
+
+Target ~8th-grade reading level (Flesch-Kincaid ~70+, grade ~8). Rules of thumb:
+
+- Sentences ≤ 20 words.
+- Paragraphs ≤ 3 sentences.
+- Concrete nouns over abstractions ("invoice" beats "billing artifact").
+- Active voice ("You signed in" beats "Sign-in was completed").
+- One idea per sentence.
+- **Front-load.** The key word or fact opens the sentence, heading, and notification — readers and screen-reader users decide whether to continue from the first words. Inverted pyramid for blocks: conclusion → support → background.
+- **Abbreviations are a tax.** Spell terms out; if an acronym must repeat, define it on first use ("estimated arrival (ETA)") and stay consistent after.
+
+**Example rewrite:**
+
+| Before (grade 14) | After (grade 7) |
+|-------------------|-----------------|
+| "Upon successful authentication, users will be redirected to their personalized dashboard interface." | "You'll see your dashboard after you sign in." |
+| "In the event that the operation is unsuccessful, please re-attempt the transmission." | "If it fails, try again." |
+| "Configuration modifications will be persisted upon form submission." | "Your changes save when you click Save." |
+
+Automate: [hemingwayapp.com](https://hemingwayapp.com/) for spot checks; the [`flesch` npm package](https://www.npmjs.com/package/flesch) for build-time linting. `write-good` (npm) flags weasel words, passive voice, lexical illusions. `alex` (npm) is an inclusive-language linter.
+
+---
+
+## Terminology Consistency
+
+Every product needs a glossary. Same concept → same word, everywhere.
+
+**Common pitfalls:**
+- `user` / `member` / `account` / `seat` — pick one per concept and stick.
+- `project` / `workspace` / `board` — pick one per level of hierarchy.
+- `delete` / `remove` / `archive` / `trash` — these mean different things; don't alias.
+- `sign in` / `log in` — both are standard; pick one and never mix.
+- `save` / `publish` / `update` — same action under three names in three surfaces is a finding.
+
+**Red flag:** in a review, grep the codebase for every verb on every button. If `Save` / `Update` / `Apply` appear on forms that do the same thing, file it.
+
+---
+
+## Inclusive Language
+
+Swap the loaded term for the neutral one. Keep the list tight — don't moralize, just fix.
+
+| Replace | With |
+|---------|------|
+| blacklist / whitelist | blocklist / allowlist |
+| master / slave | primary / replica |
+| sanity check | quick check |
+| grandfathered | legacy |
+| he / she (generic) | they |
+| manhours / manpower | work hours / team capacity |
+| man-in-the-middle | on-path attack |
+| dummy value | placeholder value |
+| first-class citizen | fully supported |
+
+Don't soften to the point of vagueness — "on-path attack" is still precise; "bad thing happens in network" is not.
+
+---
+
+## Locale-Aware Strings
+
+Rules agents routinely ignore. Every one is shippable to production the day the product adds a second locale.
+
+- **Dates.** `Intl.DateTimeFormat(locale, options)`. Never hardcode `MM/DD/YYYY` unless the audience is exclusively US. Use `new Date().toLocaleDateString(locale, { dateStyle: 'medium' })` for user-facing dates.
+- **Numbers and currency.** `Intl.NumberFormat(locale, { style: 'currency', currency })`. Decimal and thousands separators differ: `1,234.56` (US) vs `1.234,56` (DE) vs `1 234,56` (FR).
+- **Plurals.** `Intl.PluralRules(locale)`. English has 2 forms; Russian has 3; Arabic has 6. Never `n === 1 ? "1 item" : n + " items"` — breaks in Polish, Arabic, Welsh.
+- **Length tolerance.** German ≈ 1.3× English; Russian ≈ 1.2×; Chinese ≈ 0.5×. Don't fix widths to English copy. Test with `de-DE` pseudo-locale.
+- **RTL readiness.** Use logical CSS properties (`margin-inline-start`, `padding-inline-end`, `border-inline-start`), not `margin-left`. `dir="rtl"` at the root should flip the UI without additional CSS.
+- **Time zones.** Store UTC, display in the user's zone. Never assume server time is user time. Use `Intl.DateTimeFormat(locale, { timeZone })`.
+- **Sorting.** `Intl.Collator(locale)` — alphabetical order is locale-dependent (Swedish sorts `å` after `z`, German doesn't).
+
+---
+
+## Core Principles (Tactical)
+
+1. **Be specific**: "Enter email" not "Enter value"
+2. **Be concise**: Cut unnecessary words (don't sacrifice clarity)
+3. **Be active**: "Save changes" not "Changes will be saved"
+4. **Be human**: "Something went wrong" not "System error encountered"
+5. **Be helpful**: Tell users what to do, not just what happened
+6. **Be consistent**: Same terms throughout — don't vary for variety
+
+---
+
+## CTAs & Buttons
+
+**Verb + noun.** Never `Submit`, `OK`, `Click here`, `Continue`.
+
+| Generic | Specific |
+|---------|----------|
+| Submit | Create project |
+| OK | Got it |
+| Continue | Next: billing |
+| Click here | Download invoice (PDF, 84KB) |
+| Delete | Delete workspace |
+
+- Describe the action specifically (verb + noun). Active voice.
+- **Destructive actions include the object:** "Delete `project-alpha`" — user confirms the thing, not a generic verb. Typing the name for irreversible operations is the gold standard.
+- **Action reveals consequence.** "Send invite" tells the user exactly what happens. "Submit form" does not.
+- **One primary per view section** — solid for primary, outline/ghost for secondary.
+- **Disabled states explain why** — not just grayed out, never rely on color alone.
+- **One label per intent, page-wide.** "Get in touch", "Contact us", and "Let's talk" on the same page are one action wearing three names — each variant dilutes the conversion path. Pick one label per intent (contact, signup, view-work) and reuse it in nav, hero, and footer. Same for "Try free" / "Get started" / "Sign up free".
+- **CTA labels fit one line at desktop.** A primary CTA that wraps to two lines is broken — shorten the label (≤3 words for primaries) or widen the button; never constrain a CTA's width artificially.
+- **An action keeps its name through the whole flow.** The button that says "Publish" produces a toast that says "Published" — not "Success!" or "Your post is live". Confirmation dialogs, progress states, and completion messages all conjugate the same verb the trigger used. Interface vocabulary is signposting; renaming an action mid-flow makes the user re-verify they did the right thing.
+
+---
+
+## Numbers & Control Labels
+
+- Numerals, never spelled out: "245", not "two hundred forty-five" — numerals have distinct shapes and scan faster. Group thousands ("12,400"); huge numbers go hybrid ("1 billion", "2.4M") so nobody counts zeros.
+- Form labels drop possessives: "Email", not "My email" or "Your email" — the possessive adds a word and an ambiguity (whose?).
+- Button labels are verb + noun ("Save post", "Delete message"): readable out of context, which is exactly how screen-reader users jumping between controls hear them.
+- **Fake-precise numbers are a tell.** "92%", "4.1×", "13.4 lb" either come from real data (brief, brand, public metrics), are explicitly labeled as sample data, or get cut. Invented engineering precision the brand never claimed reads as fabricated the moment anyone checks.
+
+---
+
+## Copy Self-Audit (before any surface ships)
+
+Re-read **every visible string** — headlines, eyebrows, button labels, body copy, captions, alt text, footer, error messages. Flag and rewrite anything that is:
+
+- **Grammatically broken** or has an unclear referent ("we plan to stay that way" with no antecedent).
+- **Forced cleverness** — wordplay that doesn't track, mock-poetic labels ("Field notes", "On our desks", "Loose plates" for a testimonials section), performative humility ("Quietly trusted by…"). Use the plain functional label: "Testimonials", "Trusted by", "Latest writing".
+- **Generic step scaffolding** — "Step 1 / Step 2 / Step 3", "Phase 01". The step's verb is the label: "Install", "Configure", "Ship".
+- **Separator flooding** — ration the middle dot to one per metadata line ("foo · bar · baz · qux" is a tell; use line breaks or columns). Avoid the em-dash in UI strings (labels, buttons, captions) — restructure with a period, comma, or colon instead.
+
+If a string might not make sense, replace it with a plain functional sentence. Boring copy beats broken-clever copy every time.
+
+---
+
+## Error Messages
+
+Three parts, in order: **what happened** + **why** + **what to do**.
+
+- "Upload failed. The file is 62MB; the limit is 50MB. Try compressing it or splitting into parts."
+- "We couldn't reach the server. Your internet looks offline. We'll retry automatically when you're back online."
+- "Can't create the project. The name `beta` is already taken in this workspace. Try another name."
+
+**Missing pieces = bad error.** "Something went wrong" has none. "Invalid input" has only the first.
+
+### Rules
+- Explain what went wrong in plain language
+- Suggest how to fix it
+- Don't blame the user
+- Include examples when helpful
+- Link to help/support if applicable
+
+**Bad**: "Error 403: Forbidden" → **Good**: "You don't have permission to view this page. Contact your admin for access."
+**Bad**: "Invalid input" → **Good**: "Email addresses need an @ symbol. Try: name@example.com"
+
+---
+
+## Empty States
+
+**Bad**: "No items" → **Good**: "No projects yet. Create your first project to get started."
+
+- Explain why it's empty (if not obvious)
+- Show next action clearly
+- Make it welcoming, not a dead-end
+
+---
+
+## Loading & Success States
+
+**Loading** — Bad: "Loading..." (for 30+ seconds). Good: "Analyzing your data... this usually takes 30-60 seconds."
+- Set expectations, explain what's happening, show progress, offer "Cancel".
+
+**Success** — Bad: "Success". Good: "Settings saved! Your changes will take effect immediately."
+- Confirm what happened, explain what's next, be brief but complete.
+
+---
+
+## Confirmation Dialogs
+
+**Bad**: "Are you sure?" → **Good**: "Delete 'Project Alpha'? This can't be undone."
+
+- State the specific action
+- Explain consequences (especially destructive)
+- Clear button labels ("Delete project" not "Yes")
+- Only for risky actions
+
+---
+
+## Form Labels & Microcopy
+
+- Clear, specific labels (not generic placeholders)
+- Placeholders are examples, not labels — labels exist separately, placeholders end with `…`
+- Explain why you're asking (when not obvious)
+- Instructions before the field, not after
+- Never use placeholders as the only labels
+
+**Tooltips** — Bad: "This is the username field". Good: "Choose a username. You can change this later in Settings."
+- Add value (don't repeat the label), answer "What is this?" or "Why?", inline help first, tooltips as last resort.
+
+---
+
+## Formatting Rules
+
+- **Ellipsis for loading/follow-ups**: "Loading…", "Rename…"
+- **Use `…` character** not three dots `...`
+- **Curly quotes**: " " not " "
+- **Non-breaking spaces**: `10 MB`, `⌘ K`
+- **Numerals for counts**: "8 deployments" not "eight deployments"
+- **Active voice**: "Install the CLI" not "The CLI will be installed"
+- **Default to positive language**: encourage, don't blame
+- **`<title>` reflects current context**
+
+---
+
+## Content & States
+
+Every UI must design for the full range of content and states, not just the happy path:
+
+- **Design all states**: empty, sparse, dense, error, loading, success
+- **Skeletons mirror final content** exactly — prevent layout shift
+- **No dead ends** — always offer next step or recovery
+- **Empty states** guide toward action, not just "nothing here"
+- **Accessible names** exist even when visuals omit labels
+- **Resilient to user-generated content**: short, average, very long
+
+---
+
+## Banned Patterns (Dark UX)
+
+UX sins, not style choices.
+
+- **Confirmshaming.** "No thanks, I don't care about security." Ship: "No thanks" as a plain link.
+- **Fake urgency.** "Only 2 seats left!" when it's always 2. Ship: real counters or no counter.
+- **Fake scarcity.** "87% of users upgraded" with no source. Ship: named, verifiable stats or omit.
+- **Roach motel.** Easy signup, impossible cancellation. Ship: cancel in the same number of clicks as signup.
+- **Dark toggles.** Opt-in checkboxes pre-checked for marketing emails. Ship: unchecked by default, unambiguous label.
+- **Bait-and-switch pricing.** "$9/mo" that's actually "$9/mo, billed $108 annually, with a $29 setup fee." Ship: the total visible at decision time.
+
+---
+
+## Never
+
+- Use jargon without explanation
+- Blame users
+- Be vague without specifics
+- Use passive voice unnecessarily
+- Use humor for errors (be empathetic)
+- Assume technical knowledge
+- Vary terminology (pick one term, stick with it)
+- Repeat information (headers restating intros)
+- Use placeholders as the only labels
+- Exclamation points on errors
+- Celebratory copy on routine saves
+
+---
+
+## Sources
+
+- Nielsen, J. "How Users Read on the Web." Nielsen Norman Group.
+- Mailchimp Content Style Guide — [styleguide.mailchimp.com](https://styleguide.mailchimp.com/).
+- Shopify Polaris — Content Guidelines.
+- Atlassian Design System — Writing Style.
+- Flesch, R. "A New Readability Yardstick." *Journal of Applied Psychology*, 1948.
+- Unicode CLDR — locale data for dates, numbers, plurals.

package/assets/skills/design/agemon-design/references/core-rules.md

@@ -0,0 +1,166 @@
+# Core rules
+
+The detail behind the hard rules in [SKILL.md](../SKILL.md). Load this when building or reviewing a whole surface. Brand and brief always win over anything here; the accessibility floor wins over both.
+
+## Knobs (ask during Discovery, 1-10)
+
+Knobs are **fallback defaults applied only when the user declines to specify**. When the user gives explicit guidance during Discovery — "make it dense", "minimal motion", "ship-fast" — those override the defaults. Knobs are not a starting position; they are a graceful fallback.
+
+- **CRAFT_LEVEL** (default 7) — refinement depth. 3 ships fast, 9 is pixel-perfect.
+- **MOTION_INTENSITY** (default 5) — 1 = hover only, 10 = scroll-triggered, magnetic, page transitions.
+- **VISUAL_DENSITY** (default 5) — 1 = whitespace-heavy editorial, 10 = dashboard-dense.
+- **DESIGN_VARIANCE** (default by surface — see [craft-intent.md](craft-intent.md)) — 1 = symmetric/safe layout, 10 = experimental composition. Dashboards default 4; landings 7; portfolios 8. Gates layout risk separately from density.
+
+Behavior: **CRAFT_LEVEL 8+** → run Polish Pass ([review.md](review.md)). **≤4** → skip it. **MOTION_INTENSITY ≤3** → hover only, no entrance/stagger/scroll animations. **4-7** → standard entrances + hover, one scroll reveal max per section. **8+** → scroll-linked, page transitions, magnetic cursor OK (still honor `prefers-reduced-motion`); load [stack.md](stack.md) if user opts in. **VISUAL_DENSITY ≤3** → wide spacing, 1-2 items/row. **8+** → dashboard-dense ([dashboard.md](dashboard.md)). **DESIGN_VARIANCE ≤4** → symmetric grids, safe product layouts. **5-7** → split heroes, alternating rows, one layout break. **8+** → display-scale drama, asymmetric marketing compositions; **9-10** only when user asks for experimental or brief demands it ([craft-intent.md](craft-intent.md)).
+
+## Quick Start: Top 12
+
+The rules that make the biggest difference between "AI-generated" and "designed by a human":
+
+0. **Read before assuming** — never default accent, font, or style. Analyze the project, then ask as [stage-intake.md](stage-intake.md) says. In a non-interactive run, proceed and log assumptions. Use Knob defaults only when the user declines to specify or nobody can answer.
+1. **Sentence case by default** — uppercase = template. Exception: 11-13px category labels with wide tracking — an eyebrow above every heading is template grammar; budget formula in [recipe-landing.md](recipe-landing.md) (Eyebrow budget).
+2. **Commit to a palette strategy that fits the subject** — mostly-neutral with one accent is one option, not the default; the brief and brand decide ([color.md](color.md) Commitment Axis). NEVER *default* to blue — if your brand is blue, that's different.
+3. **Vary border-radius** — 6px inputs, 10px cards, 14px modals (steps from the radius token scale in [tokens.md](tokens.md)); uniform radii look stamped out.
+4. **Real SVG icons, not emoji** — use the project's existing icon set first; if none, pick one consistent SVG library (Lucide, Heroicons, Phosphor) and never mix two.
+5. **Tight letter-spacing on large headings** — `tracking-tight` or `-0.02em`+ above 24px.
+6. **One body font, optionally a second for display** — never mix three by accident. Use the project's fonts. With none, choose from the brief's subject and say why; a font you reach for on every project is a default, not a choice.
+7. **Layered shadows over flat borders** — ambient + direct light.
+8. **Exit faster than enter** — ~75% of entrance duration.
+9. **Plain secondary text for comparisons** — "+12.5% from last month", not a colored pill.
+10. **Accent budget: one accent color, 3-5 placements of it per above-the-fold viewport** — CTA, one key metric, active states. **Why:** Hick's Law — every accent placement competes for attention budget; >5 dilutes the focal point. Modals and overlays count as their own viewport.
+11. **Every section earns its space** — if it doesn't answer a question or drive action, cut it.
+12. **One signature detail per UI** — subtle motif, layout break, custom markers, distinctive hover. When building a whole surface (`/agemon-design build`), pick and **build** it in the first pass ([craft-intent.md](craft-intent.md)) — not only at polish.
+
+> **Before writing ANY code:** For non-trivial projects, check for a design brief and token set first (`/agemon-design brief`, `/agemon-design tokens`) — durable artifacts beat per-session re-derivation. Then run [stage-intake.md](stage-intake.md) and [stage-assets.md](stage-assets.md). Use existing tokens if any token system is present. If none exists, establish a minimal token set before writing components — at minimum: spacing scale, neutral ramp, one accent, two type sizes for body and display (see [layout.md](layout.md) and [color.md](color.md)). If preferences are missing, follow [stage-intake.md](stage-intake.md).
+
+## Core Rules
+
+### The Anti-Slop Test
+
+Before shipping any UI, ask: "If someone said AI made this, would they believe it immediately?" If yes, start over.
+
+**Critical (immediately reads as AI):**
+- Identical card grids (icon + heading + text, 3-6x repeated)
+- ALL CAPS on headings, labels, tables, nav, buttons (exception: 11-13px category labels)
+- Purple/cyan gradient everything
+- Emoji as feature icons
+- Bounce/elastic easing curves
+- Glassmorphism on dark + neon accents
+
+**Major (designers notice):**
+- Colored pills on trend percentages — use plain secondary text
+- Thick colored left/top borders on cards — use elevation or bg tint
+- Uniform border-radius on everything — vary by element
+- Gradient text on hero metrics
+- Vertical bar charts for time-series — use area/line (horizontal bars OK for categorical)
+- `transition: all` — list specific properties
+- Decorative glow as primary affordance
+- Soft blurry gradient blobs/orbs
+- Generic CTAs ("Learn more", "Click here") — be specific
+- Walls of text — no landing section > 2-3 sentences
+- "OR" divider in caps between auth options — lowercase it: "or with email"
+- Full-bleed saturated brand panel beside a sign-in form — tinted neutral surface with one proof asset ([recipe-auth.md](recipe-auth.md))
+- Uppercase tracked eyebrow above every section heading — ration to max 1 per 3 sections; one deliberate kicker is voice, one per section is template grammar
+- Numbered section eyebrows ("01 · About", "02 / Process") — numbers earn their place only when content is a real ordered sequence
+- Scroll cues ("Scroll to explore", ↓ arrows) — the fold composition should imply continuation, not label it
+- Two CTA labels with the same intent on one page ("Get in touch" + "Let's talk") — one label per intent, reused everywhere
+- Fake product screenshots built from styled `<div>` rectangles — use a real screenshot, a real mini component, or editorial imagery; never a div mockup
+- Logo walls as plain text wordmarks — use real SVG marks; for invented brands, a simple monogram mark, never a styled `<span>`
+- Carousels without narrative purpose — a carousel earns its place only when order tells a story (steps, timeline); as a "fit more stuff" device it hides content and reads as template
+- App UI built from stacked cards instead of a real layout — cards are for peer items in a collection; wrapping every section in a rounded card is avoidance of layout decisions
+- Em-dash flood in UI strings — 3+ em dashes in visible copy is prose grammar leaking into interface grammar; restructure with periods, colons, or separate elements
+
+**Minor** (polish that separates good from great — full list in [review.md](review.md) Polish Pass): no `tabular-nums` on data, missing `text-wrap: balance`, straight quotes, no `&nbsp;` in brand names, testimonial star ratings, hero metric without adjacent context.
+
+### The Craft Test (What TO Do)
+
+Anti-slop says what to avoid. Craft says what to aim for.
+
+**General craft:**
+- One accent, 3-5 placements per above-the-fold viewport. Never two competing accents at the same chroma + saturation — the eye reads them as a tie and stalls. Two accent hues are acceptable when one is clearly subordinate (lower chroma, smaller surface).
+- White backgrounds with barely-there borders or whitespace. Numbers large, undecorated, `tabular-nums`.
+- Comparisons plain secondary text. One chart color at different opacities. Area fill fades ~15% → 0%.
+- Functional color only — dots for status, flags for countries. Real content, not placeholders.
+
+**Landing pages** (detail in [inspiration.md](inspiration.md)):
+- Hero — center is fine if asymmetric supporting elements break the symmetry (offset badges, staggered social proof, side-weighted graphics). Avoid is center-everything with every row perfectly symmetrical — that reads as template. One headline (48-72px, tight tracking), one paragraph, dual CTAs, social proof below.
+- Features: 2-3 asymmetric rows with real visuals (chart, timeline, funnel). NEVER uniform 3-column icon grids.
+- Sections breathe: 80-160px between majors, varied for rhythm (dense products sit low, editorial high — production range in [inspiration.md](inspiration.md)). Every section answers one question.
+- Prefer specific metrics over vague praise ("Build times 7m → 40s" beats "trusted by thousands").
+
+**Dashboards** (detail in [dashboard.md](dashboard.md)):
+- Sidebar: subtle bg tint, NOT full dark (common AI pattern).
+- Metric cards: primary gets accent tint; others neutral. Sparklines only where a trend is the question the card answers. NEVER identical colored top borders.
+- At least 3 content types per dashboard viewport (e.g., chart + table + metric). **Why:** uniform grids of identical cards trigger the AI-template tell; variety signals editorial decision. Chart type matches data story (area/horizontal bar/sparkline). Never pie or 3D.
+
+### When Rules Break
+
+Every rule above has a context where it inverts. Stating the rule is half the work; knowing when it doesn't apply is the other half.
+
+- **"Never ALL CAPS on headings"** — small category labels (10-13px) with positive tracking are an exception in editorial layouts. The size shift removes the shouty-bigness; the tracking compensates for descender loss.
+- **"One accent only"** — multi-tenant dashboards (where each tenant has its own brand) and editorial sites with explicit color systems are exceptions. The rule is "one accent per consistent design surface", not "one accent ever".
+- **"Avoid pie charts"** — for two-segment proportional comparisons (e.g., used vs. free storage on a single device), a donut with center label is acceptable. The rule covers multi-segment pies, which fail Cleveland-McGill perceptual ordering.
+- **"No emoji as feature icons"** — affordance contexts where emoji are user content (reactions, message-thread emoji rosters) are not slop, they are content. The rule covers decorative emoji standing in for designed icons.
+- **"Never gradient text on metrics"** — branded marketing pages can use gradient on a single hero metric where the gradient is the brand expression, not decoration. Inside-the-product metrics still follow the rule.
+- **"Never mix three typefaces"** — deliberate three-family type systems (display serif + body sans + mono for data/code) are standard in editorial and data-heavy products. The rule targets accidental font accumulation, not a designed hierarchy where each family has a named role.
+
+**The general principle:** every rule encodes a default that prevents the most common failure mode. When the context inverts the failure mode, the rule may invert too. The work is recognizing the inversion, not memorizing exceptions.
+
+### Convergence
+
+Actions can iterate until their stated checks pass rather than producing a single-shot output. Never fake a render; report honestly what was and was not checked. See [loops.md](loops.md).
+
+### Self-Correction
+
+When the user corrects design output — "not like that", "I don't like this", "always do X here", "never Z", or a reversal that reads as a standing preference — record it as a **learned constraint** in the brief (section 6). Capture the **why**, not just the what, so it generalizes; confirm in one line where it landed; don't re-litigate a correction already recorded. Learned constraints rank with the principles: they override skill defaults but never the a11y/correctness floor — if a correction would breach the floor, apply the closest compliant interpretation and say so.
+
+This is project-scoped and lives in the brief by design — agemon-design is a UI skill, not a general memory engine. Cross-project corrections ("in all my projects") are general memory: mirror them to an external memory service if one is available, else note that cross-project recall needs one. Full behavior → [brief.md](brief.md) (Self-Correction).
+
+### Animation Decision Ladder
+
+> **Should this animate?** → High-frequency? No. Not communicating hierarchy/state/space? Cut it. Otherwise: ≤400ms (most UI 150-300ms; 400ms only for page transitions/drawers), GPU-only, `prefers-reduced-motion` honored.
+
+Full ladder, easing, springs, stagger, interaction contract → [motion.md](motion.md) (**Decision Ladder**).
+
+### Design Rules (core)
+
+Layered shadows (ambient + direct). Semi-transparent borders + shadows for crisp edges. Hue-consistent borders/shadows/text on colored surfaces. APCA over WCAG 2. Interactions increase contrast. `color-scheme` + `theme-color` match theme. OKLCH for scales. Full detail in [layout.md](layout.md) and [color.md](color.md).
+
+## Review Format (Required)
+
+When reviewing UI code, use a markdown table. Never use "Before:"/"After:" on separate lines.
+
+| Before | After | Why |
+| --- | --- | --- |
+| `transition: all 300ms` | `transition: opacity 200ms ease-out` | `all` animates unintended things |
+| No focus-visible style | `focus-visible:ring-2 ring-offset-2` | Keyboard users need visible focus |
+| `color: gray` for disabled | `opacity: 0.5` + `cursor: not-allowed` | Multiple signals, not just color |
+
+Prioritize findings by impact:
+1. **Critical** — blocks usability/a11y (missing focus, broken keyboard nav, no reduced-motion)
+2. **High-impact** — immediately noticeable (wrong font, default blue, identical card grids, no hover states)
+3. **Quick wins** — big polish (tabular-nums, letter-spacing, curly quotes, `&nbsp;`)
+
+---
+
+## Quick Decision Frameworks
+
+### Should This Animate?
+
+| Frequency | Decision |
+|-----------|----------|
+| High (keyboard, toggles, typing) | No animation. Speed is the feature. |
+| Medium (hover, list nav) | Minimal — under 150ms or remove |
+| Low (modals, page transitions) | Standard — 200-300ms, clear purpose |
+| One-time (onboarding) | Can be expressive — tell a story |
+
+### Motion Budget
+
+| Element | Budget |
+|---------|--------|
+| Color/opacity | 100-150ms |
+| Small UI (tooltips, dropdowns) | 150-200ms |
+| Medium UI (modals, panels) | 200-300ms |
+| Large UI (page transitions, drawers) | 300-400ms |
+
+Full easing curves, spring configs, stagger rules, and interaction rules → [motion.md](motion.md).