agemon 0.1.0 → 6.0.0

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/craft-intent.md

@@ -0,0 +1,160 @@
+# Craft Intent — Read, Variance, Signature
+
+Load on every `/craft`, default Build mode, and when the user asks for a full surface without naming a command. This file is the **generative front door** — declare intent before writing code.
+
+---
+
+## 1. Craft Read (mandatory before code)
+
+Before tokens or layout, output **one line** the user can react to:
+
+> **Craft Read:** *[surface kind] for [audience], [product | marketing] language, [theme/accent hint], variance [N], signature bet: [choice].*
+
+**Infer from:** page/app kind, vibe words ("minimal", "editorial", "dense", "playful"), references the user named, existing brand tokens, audience.
+
+**Examples:**
+
+- *Craft Read: B2B ops dashboard for finance admins, product language, Graphite + teal accent, variance 4, signature bet: hero metric card with sparkline.*
+- *Craft Read: devtool launch page for technical buyers, marketing language, Porcelain + indigo, variance 7, signature bet: product screenshot cropped at fold with floating proof card.*
+- *Craft Read: designer portfolio for hiring managers, marketing language, editorial type, variance 8, signature bet: kinetic display headline with italic emphasis in same family.*
+
+If the brief is ambiguous, ask **one** clarifying question — never a questionnaire. If inferable, declare the Craft Read and proceed.
+
+**Anti-default discipline:** Generated design without a committed read clusters into three defaults — (1) warm cream background (~`#F4F1EA`) + serif display + terracotta/brass accent; (2) near-black background + one bright acid-green or vermilion accent; (3) broadsheet layout — hairline rules, zero border-radius, dense columns. Each is legitimate only *when the brief asks for it*, never as a default answer to "no brand direction" — same goes for purple mesh gradients, symmetric three-icon-card heroes, full-black sidebars, and Inter-on-everything without a reason.
+
+**Second-order check (marketing surfaces):** name the aesthetic lane before building ("editorial type", "terminal-dark devtool", "warm-craft artisan"), then ask if someone could guess it from the domain alone — "devtool → dark mode + mono" is the first reflex, "AI tool that's not-purple → editorial serif restraint" is the same reflex one tier deeper. If the lane, or any default above, is guessable from the category, rework it until it isn't — the brand's specifics should pick the lane, not the category. Self-test: "would a similar brief for a *different* brand in this category produce this same plan?" If yes for any axis, that's a reflex, not a decision — revise it and state what changed.
+
+---
+
+## 2. DESIGN_VARIANCE knob (1–10)
+
+Separate from **VISUAL_DENSITY** (how much fits) and **CRAFT_LEVEL** (how refined). Variance controls **layout risk and creative amplitude**.
+
+| Variance | Product surfaces | Marketing surfaces |
+|----------|------------------|-------------------|
+| **1–3** | Symmetric grids, safe hierarchy | Centered hero OK only with asymmetric support |
+| **4–6** | Split layouts, metric hierarchy, one layout break | Split/bento heroes, alternating feature rows |
+| **7–8** | Strong typographic moments in shell (empty state, onboarding) | Asymmetric offsets, scroll-linked logo strip, display scale drama |
+| **9–10** | Rare — one experimental shell moment only | Kinetic type, scroll choreography — **explicit brief or user asks "experimental"** |
+
+**Defaults when user doesn't specify:**
+
+| Surface | Default variance |
+|---------|------------------|
+| Dashboard, settings, auth, tables | **4** |
+| Landing (live product) | **7** |
+| Landing (waitlist / pre-launch) | **6** |
+| Portfolio, case-study, launch event | **8** |
+
+`/bolder` raises variance (+1–2, cap 10) and motion (+1, cap 10). `/quieter` lowers both. Honor `prefers-reduced-motion` always.
+
+---
+
+## 3. Signature bet (mandatory — not polish-gated)
+
+Every `/craft` ships **exactly one** memorable decision, chosen at plan time and built in Step 3 — not deferred to `/polish`.
+
+### Product surfaces (pick one)
+
+1. Custom empty-state motif (simple SVG tied to domain)
+2. Distinctive nav active indicator (left bar, pill, or dot) — system-wide
+3. Welcome / first-run panel — dismissible, value-focused
+4. Primary table row hover (subtle lift + shadow on the main table only)
+5. Command palette or keyboard hint (`⌘K`) when search/actions warrant it
+
+### Auth surfaces (pick one — load [recipe-auth.md](recipe-auth.md))
+
+1. Panel proof asset — one believable metric + sparkline **or** one attributed quote (not both)
+2. Trust footer line — compliance / data residency in tertiary text at panel foot
+3. Domain-specific welcome line — verb tied to product ("Pick up where you left off"), not generic filler
+4. Real provider marks on SSO row — equal-weight neutral outlines, no fake icons
+5. Subtle panel motif — simple SVG tied to domain on the tinted panel only
+
+### Marketing surfaces (pick one)
+
+1. Hero crop — product visual cut mid-element at fold edge
+2. Floating proof card over screenshot (metric, notification)
+3. Custom section marker (FIG label, domain icon motif)
+4. Distinctive CTA copy — specific verb, not "Get started"
+5. One scroll moment — logo strip or restrained headline entrance (variance ≥7)
+
+Name the bet in the Craft Read. Build it in the first pass.
+
+---
+
+## 4. Product surface patterns (apps, dashboards, settings)
+
+Apply on dashboard, auth, settings, onboarding, admin — load with [recipe-dashboard.md](recipe-dashboard.md).
+
+**Shell:** Tinted sidebar (not full black). Active nav = accent/10 + accent text. Page header row: title + context + primary action aligned.
+
+**Data:** One hero metric (larger, accent tint); secondaries neutral. Sparklines in KPI cards where trends matter. Table rows with context (avatar, status dot, proportion bar) — not plain grids. Ghost buttons in filter toolbars; primary CTA lives outside the toolbar.
+
+**Type & color:** `tabular-nums` on numbers. Sentence case on nav and headers. Tinted surfaces (`accent/5` on primary card). Semantic green/red only when the domain expects it.
+
+**Motion:** Optimistic UI where saves matter. Skeletons match final layout. `:active` micro-push (`scale(0.98)`). One staggered entrance per section max, `once: true`.
+
+**States:** Empty states with icon + one sentence + CTA. Errors with retry/copy path. Onboarding checklists 3–5 steps, dismissible.
+
+**Avoid in product shells:** scroll pinning, kinetic body copy, mesh backgrounds behind tables, glass on dense forms, decorative carousels.
+
+**Ecosystem briefs use the official system.** When the brief names a platform with a mandated or expected design system, install and use the official package and its tokens instead of hand-rolling a lookalike — recreating a known system's CSS by hand is both more work and instantly off. One system per project; don't mix component libraries in the same tree.
+
+Naming the platform is not enough to act on. Install what the row says:
+
+| Brief reads as… | Install | Ships as |
+|---|---|---|
+| Microsoft 365 / Fluent-flavoured | `@fluentui/react-components` | React |
+| Atlassian-suite companion | `@atlaskit/button`, `@atlaskit/textfield`, … | React, one package per component |
+| Shopify app or admin surface | `@shopify/polaris` | React |
+| Material-flavoured product | `@material/web` | Web components — any framework |
+| IBM-style B2B / enterprise analytics | `@carbon/react` | React (`@carbon/styles` for the CSS alone) |
+| Salesforce / Lightning | `@salesforce-ux/design-system` | CSS — any framework |
+| Adobe-flavoured | `@adobe/react-spectrum` | React |
+| GitHub-flavoured developer tooling | `@primer/react` | React (`@primer/primitives` for tokens alone) |
+| UK public sector | `govuk-frontend` | Plain CSS + JS |
+| US federal / state service | `@uswds/uswds` | Plain CSS + JS |
+
+Check the third column against the project before adding a dependency. Most of these ship as React and installing one into a Vue, Svelte or Angular codebase is worse than hand-rolling: take the system's tokens and CSS instead, which is the part that makes it recognisable. Atlassian has no meta-package — install the components the surface actually uses.
+
+No row matches → this rule does not apply. Proceed with the normal token flow rather than reaching for the nearest big component library.
+
+---
+
+## 5. Marketing surface patterns (landings, portfolios)
+
+Apply on landing, portfolio, waitlist — load with [recipe-landing.md](recipe-landing.md) and [inspiration.md](inspiration.md) hero archetypes.
+
+**Composition:** Pick one hero archetype (product-forward, message-forward, proof-forward, bento, editorial figure, social proof strip). **No two adjacent sections share the same layout.**
+
+**Type:** Display 48–80px H1, tight tracking, sentence case. Font pairing from theme preset or brief — body + optional display. Emphasize with italic/bold **same family**, not random serif injection.
+
+**Color:** Pick a commitment strategy first ([color.md](color.md) Commitment Axis — restrained / committed / full palette / drenched, gated by variance); default restrained: 90% neutral + one accent; rotate accent family when no brand (indigo, teal, rose, amber, forest). No default warm-beige + brass "premium" palette unless the brief names it.
+
+**Imagery:** marketing surfaces are visual products, not text-only pages — asset priority order, the div-built-screenshot ban, and the logo-wall rule live in [recipe-landing.md](recipe-landing.md) (Imagery is not optional).
+
+**Motion:** Hero stagger 50–80ms; one scroll reveal per section; multi-property hover on **one** featured block. No bounce, confetti, or idle float. Every animation must answer "what does this communicate?" in one sentence (hierarchy, sequence, feedback, state change) — "it looked cool" fails.
+
+**Portfolio:** Variable grid aspects; one hero project above fold; asymmetric about/contact — not centered template.
+
+---
+
+## 6. Rotation (when no brand direction)
+
+Rotate **one axis per build** so outputs don't converge:
+
+| Axis | Pool (pick 1) |
+|------|----------------|
+| Theme preset | Graphite, Porcelain, Signal, Carbon — [themes.md](themes.md) |
+| Accent family | indigo, teal, rose, amber, forest (OKLCH-safe) |
+| Signature bet | from §3 lists |
+
+Declare the axis in the Craft Read so the user can say "warmer accent" on iteration.
+
+**Premium/artisan briefs must rotate palette families** — the default warm-beige + brass + espresso "premium" look is a convergence tell the moment the brief doesn't name those colors. Full family list and the never-twice-in-a-row rule: [themes.md](themes.md) Premium palette families.
+
+---
+
+## Cross-refs
+
+[recipe-dashboard.md](recipe-dashboard.md) · [recipe-landing.md](recipe-landing.md) · [recipe-auth.md](recipe-auth.md) · [inspiration.md](inspiration.md) · [themes.md](themes.md) · [dashboard.md](dashboard.md) · [review.md](review.md)

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

@@ -0,0 +1,131 @@
+# Dashboard Patterns
+
+Detailed guidance for building data-heavy dashboards that feel designed, not generated.
+
+## Layout Structure
+
+A dashboard needs a sidebar + main content area. The sidebar is the navigation spine.
+
+**Sidebar navigation:**
+- Subtle background tint (e.g., `background: #f8fafc` / Tailwind: `bg-slate-50`, or `background: #030712` / Tailwind: `bg-gray-950`) — NOT full black unless Dark Premium style. A dark sidebar is a common AI pattern; prefer a subtle tint that complements the content area.
+- Muted nav text that brightens on hover/active. Active item gets accent background at low opacity (`background: oklch(var(--accent) / 0.1)` / Tailwind: `bg-accent/10`) + accent text.
+- Brand/logo at top, user profile at bottom.
+- `aria-label="Main navigation"` on `<nav>`, `aria-current="page"` on active item.
+- `overscroll-behavior: contain` on the sidebar if it scrolls independently.
+
+**Main content area:**
+- Filter/toolbar row at the top: ghost buttons for filters, active state uses accent bg at low opacity. Always include a date range selector for any time-series surface. **Why:** time-series data without an interactive range silently encodes the assumption that the default window is correct — when it isn't (and it usually isn't for power users), the dashboard becomes a screenshot. **When it breaks:** real-time monitoring surfaces with a fixed last-N-minutes window — the range is the affordance, not the picker.
+- Content grid below filters: metric cards → charts → tables/lists.
+- Minimum 3 different content types visible per viewport (e.g., metric cards + chart + table).
+
+## Metric Card Hierarchy
+
+Never show 4+ identical metric cards. Differentiate the primary metric. **Why:** a uniform grid of equal-weight cards triggers the AI-template tell — variety signals editorial decision; uniformity signals defaulted-out. It also fails the squint test: the eye can't lock on a primary at first glance. **How to differentiate:** primary card gets accent tint, slightly larger number, optional sparkline; secondaries are neutral with smaller type. See Signal-to-Noise Hierarchy section below.
+
+**Primary metric card:**
+- Accent-tinted background (`background: oklch(var(--accent) / 0.05)` / Tailwind: `bg-accent/5`) with accent-colored number, OR solid accent background with white text.
+- Slightly larger number (36px vs 28px for others).
+
+**Secondary metric cards:**
+- White background, subtle border (`1px solid oklch(92% 0.005 250)`).
+- Black number, secondary-color label.
+
+**All metric cards should include:**
+- Sparklines: 32px tall, polyline SVG, accent color with faded fill underneath.
+- Change text: "+2,149 from last month" in `var(--text-tertiary)`. **Never green arrows for positive, red for negative.** **Why:** color implies judgment that may not match user context — a 30% increase in costs is "positive" by sign and "bad" by goal; the green arrow encodes the wrong story. Render the magnitude in neutral and let the user's interpretation supply meaning. **When it breaks:** financial trading surfaces where positive/negative is universally tied to goal (gains green, losses red is the domain convention) — match the user's domain, don't fight it.
+- Label: sentence case, 12-13px, `font-weight: 500`, secondary color.
+- Value: 28-36px, `font-weight: 700`, `font-variant-numeric: tabular-nums`, `letter-spacing: -0.02em`.
+- NO colored top/left borders. NO colored change text. NO arrow icons next to percentages.
+
+## Chart Type Decision Matrix
+
+| Data story | Best chart | Why | Avoid |
+|-----------|-----------|-----|-------|
+| Trend over time | Area chart with gradient fill | Shows direction + volume | Vertical bar chart |
+| Comparing categories | Horizontal bar chart | Labels are readable, easy to scan | Vertical bar with rotated labels |
+| Comparing discrete values | Vertical bar chart | Natural for small sets (3-7 items) | Too many bars (>8) |
+| Part-of-whole | Donut/ring chart (use sparingly) | Center text shows total | Pie chart — harder to compare |
+| Inline trend in a card | Sparkline (32px polyline) | Minimal, contextual | Full chart crammed into a card |
+| Conversion/funnel | Progressive bars with stage labels | Shows drop-off clearly | Donut chart |
+| Never use | — | — | Pie charts, 3D charts of any kind |
+
+**Why never pie charts:** Cleveland-McGill perceptual hierarchy ranks angle (pie) below position (bar). Humans compare bar lengths to within a few percent; pie wedges fail at 4+ slices. **Why never 3D:** depth occludes data points and foreshortens position-based comparison. No 2D chart benefits from a third dimension. **When a two-segment donut is acceptable:** a donut with center label for binary proportions (used vs free, paid vs free) — only one comparison to make.
+
+## Chart Styling
+
+- **Single accent hue at varying opacities** for multi-series: `accent/100`, `accent/60`, `accent/30`. **Never rainbow colors.** **Why:** hue does not encode ordering — readers can't rank red vs green by magnitude. Single-hue opacity ramps preserve perceptual ordering and remain colorblind-safe. See `dataviz.md` for full palette guidance.
+- **Gradient fill underneath area lines**: line at full opacity, fill fades from ~15% at line to 0% at bottom.
+- **Label placement**: axis labels in secondary text, 11-12px. Data point labels only on hover (tooltip), not permanently displayed.
+- **Grid lines**: horizontal only, very subtle (`border-color: oklch(95% 0 0)` / Tailwind: `border-gray-100`). No vertical grid lines.
+- **No chart chrome**: skip legends when there's only one series. Put context in the card title instead.
+
+## Data Tables
+
+Tables are the workhorse of dashboards. Make them earn their space.
+
+- **Row context**: tiny avatars (24px), colored status dots (6px, not badges), flag icons, or proportion bars. Plain text tables feel like spreadsheets.
+- **Status indicators**: small colored dots (6-8px) inline with text. "Active" with a green dot, not a green badge/pill. The dot conveys status; the text provides the label. Badges add visual noise and are an AI-slop pattern.
+- **Proportion bars**: show relative values as width-proportional bars within cells. More visual than raw numbers.
+- **Row hover**: subtle background highlight (`background: #f9fafb` / Tailwind: `hover:bg-gray-50`).
+- **Headers**: sentence case, `font-weight: 500`, secondary color. **Never uppercase table headers.** **Why:** uppercase removes the lowercase letterforms that aid scan-pattern recognition; readers process uppercase ~13-20% slower than sentence case (Tinker 1969). Uppercase also reads as decorative-template, not data-functional.
+- **Alignment**: text left, numbers right, status center.
+- **Wrap every table in `overflow-x: auto`.** Horizontal, not `overflow-y` and not `overflow-hidden`. **Why:** a table is the one layout that cannot reflow — columns have minimum content widths, so at ~320px it either clips at the viewport edge or forces the whole page to scroll sideways. Vertical overflow solves a different problem and leaves this one intact.
+- **Put `position: sticky; top: 0` on `thead` past ~15 rows.** **Why:** once the header scrolls out of view every cell below it is an unlabelled string, and the user scrolls back up to remember which column is which. On an operator surface the table *is* the product, so this is not polish.
+- **Virtualize past 200 rows.** **Why:** every row is DOM the browser lays out, styles, and paints on each scroll frame — a 2,000-row table blows the 16ms budget before any of your CSS is at fault, and the fix is never "optimize the row component". Render a window (TanStack Virtual, `react-window`) or paginate. **When it breaks:** the table must be Cmd+F-searchable or printable in full — then paginate instead of virtualizing, since a virtual window hides rows from find-in-page.
+- **`scrollbar-gutter: stable` on every scroll container.** **Why:** on overlay-scrollbar platforms the track appears only on scroll, and the content reflows by its width at that moment — column edges jump the instant the user touches the wheel. Reserving the gutter costs nothing and removes the shift.
+
+## Filter & Toolbar Patterns
+
+- Ghost buttons for all filter controls — **never solid primary buttons in a toolbar.** **Why:** a toolbar holds 5-15 tertiary actions (filter, sort, group, export, refresh). Each solid primary button competes for the user's primary-action attention budget; the dashboard's actual primary action (drill-in, edit, alert config) gets buried. Hick's Law applied to visual weight.
+- Active filter state: accent background at low opacity + accent text, or subtle border change.
+- Group related filters visually. Date range selector deserves more prominence (slightly larger or separated).
+- "Reset filters" appears only when filters are active, as a text link — not a button.
+
+## Content Density
+
+Dashboards value density over breathing room (opposite of landing pages).
+
+- Metric cards: tight padding (16-20px), not the generous 32-48px of landing page cards.
+- Charts: minimize whitespace around the chart area. The data should fill the container.
+- Tables: compact row height (40-48px). Dense but scannable.
+- A dashboard should show enough data that a user can make a decision without scrolling. If the first viewport is just 4 large metric cards, you've wasted space.
+- Aim for: 3-4 metric cards + at least one chart + start of a table/list — all above the fold.
+
+---
+
+## Signal-to-Noise Hierarchy
+
+The most common AI-generated dashboard failure isn't any single bad choice — it's that every KPI, every chart, every card looks equally important. The user doesn't know where to look. Signal-to-noise hierarchy is the fix.
+
+### Tiers
+
+**Tier 1 — The hero metric.** One per dashboard. The number that answers "am I winning today?". Largest visual weight. Accent color is allowed here, and here only. Trend indicator adjacent (up/down + delta). Context micro-text below: "vs last 7 days" or "of monthly quota."
+
+**Tier 2 — Supporting metrics (2-4).** The breakdown of the hero — if the hero is revenue, supports are revenue by channel, by region, by segment. Neutral colors. Smaller type. Grouped visually with the hero (shared container, aligned baseline).
+
+**Tier 3 — Context (0-3 charts).** Trends, time series, comparisons. Chart type matches data shape (see `dataviz.md` and the Chart Type Decision Matrix above). Sparklines for micro-context inside cards. No large charts competing with the hero's visual weight.
+
+**Tier 4 — Deep-dive.** Tables, filters, raw data. Accessible but not crowding the viewport. Often collapsed by default, or lives on a separate tab / route. The user drills in when they need it.
+
+### The anti-pattern: "grid of 8 KPI cards with equal weight"
+
+Every card the same size, same color, same layout → the user's eye has nowhere to land → the user scrolls looking for meaning → the user leaves. This is the single most recognizable AI-generated dashboard shape.
+
+### The rule
+
+One hero. 2-4 supports. Context behind. Deep-dive one click away. Test by squinting at the dashboard: your eye should land on ONE thing first. If it lands everywhere, the hierarchy is broken.
+
+### Ranking decisions to document per dashboard
+
+Before building, answer these:
+
+- **What's the hero metric for this surface?** Different for exec view (revenue) vs operator view (tickets open) vs customer view (usage vs limit). See `personas.md` to ground this in concrete archetypes.
+- **What supporting metrics contextualize the hero?** The 2-4 that make the hero actionable, not the 8 you could show.
+- **What's deep-dive, not surface?** Everything the user needs once a week, not once a minute.
+- **Who's the user and what decision are they making in the next 60 seconds?** If you can't name the decision, the dashboard has no job.
+
+### Cross-references
+
+- `dataviz.md` — chart selection by data shape; Cleveland-McGill perceptual hierarchy (position-on-common-scale is most accurate — use it for the hero).
+- `heuristics.md` — Cleveland-McGill PASS/FAIL, Hick's Law for filter/nav choices.
+- `personas.md` — concrete user archetypes to ground "who's the user" in reality, not abstraction.