agemon 0.1.0 → 6.0.0

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

@@ -0,0 +1,188 @@
+# State Design — Design the Unhappy Path First
+
+Every interactive surface has more states than "it works." The happy path is the easy one. Idle, loading, empty, error, partial, conflict, and offline are where real UX lives — and where AI-generated UIs fall apart.
+
+Design every state before writing any JSX. Stub the ones the knob level doesn't require — don't skip them.
+
+---
+
+## The State Lattice
+
+Every component-that-touches-data has this set. For each, design the visual AND the copy before coding.
+
+This table is the evaluation source for the `state-coverage` loop preset (see `../SKILL.md` → loops.md).
+
+| State | What to design | Common mistake |
+|-------|---------------|----------------|
+| **Idle** | Default resting state. Primary action obvious. | Treating "empty form" as idle — it's actually Empty. |
+| **Loading** | Skeleton matching final layout. Appears after 200ms. | Centered spinner on a blank screen (no layout match, no cue). |
+| **Empty** | Explain why empty + CTA to fix it. | "No data" with no illustration, no explanation, no next step. |
+| **Error** | Specific cause + one-click recovery + support ID. | "Something went wrong" with no detail and no retry. |
+| **Partial** | Some data loaded, some failing. Show what succeeded. | Hide everything because one field failed — user sees blank. |
+| **Success** | Positive feedback, brief, visual + textual. | Toast that vanishes in 1s; user misses it. |
+| **Conflict** | Two actors edited. Show both, let user resolve. | Last write wins silently; prior user's work is gone. |
+| **Offline** | Connection lost. Queue writes. Communicate. | Pretend everything is fine; fail on next sync. |
+
+---
+
+## Design the Unhappy Path First
+
+Designing loading / empty / error states first produces a better happy path. When you start from "the list is empty and we need to onboard the user," the happy-path card has a job it has to fit into, not the other way around. When you start from "this API returns an error," your loading skeleton and retry copy are baked in, not bolted on.
+
+Teams that design happy-first ship demos that crumble on real data. Teams that design unhappy-first ship products.
+
+---
+
+## Loading States
+
+**Skeleton rules:**
+- Match the final layout — same grid, same rough box sizes. Skeletons that don't match cause cumulative layout shift (CLS) when real content arrives.
+- Show after **200ms**, not immediately. A flash of skeleton for fast responses looks broken.
+- Set an upper bound of **5s**. Past that, escalate to a progress indicator or a timeout message with a retry.
+- Use a subtle pulse or shimmer — not a spinner on top of a skeleton. One signal is enough.
+- Preserve stable layout for known elements (avatar, title) while skeletonizing variable ones (body, list).
+
+**Button loading:**
+- Keep the label; don't swap to just a spinner. Users lose context.
+- Disable but don't hide — users click it trying to cancel.
+- Spinner goes *inside* the button, not next to it.
+
+**Navigation loading:**
+- Optimistic route change — paint the new layout immediately; stream data into it.
+- A progress bar at the top of the viewport is better than a blank screen.
+
+---
+
+## Empty States
+
+Empty states are the most skipped state and the most valuable. A first-time user sees an empty state before any happy path.
+
+**Required:**
+- Explain **why** it's empty — "You haven't created any projects yet" beats "No data"
+- Offer **a next action** — a CTA to populate the state. Every empty state is a call to onboard.
+- Visual or illustration — even a subtle icon. Prevents the "this page is broken" read.
+- Secondary info if useful — "Projects help you organize your work. Learn more."
+
+**Empty state types:**
+- **First-run empty** (user just signed up) — onboarding. Heavy CTA.
+- **Filtered empty** (user applied filters that match nothing) — "No results — try removing filters" with a clear-filters button.
+- **Cleared empty** (user archived / deleted everything) — celebratory or contextual; may not need a CTA.
+
+---
+
+## Error States
+
+Specific beats generic. Actionable beats dead-end. Recoverable beats fatal.
+
+**Field-level errors:**
+- Inline, at the field. Not a toast, not a global banner.
+- Describe the problem AND the fix — "Password must include a number" beats "Invalid password."
+- Red is a signal, not the whole message. Pair color with icon and text.
+- `aria-invalid` + `aria-describedby` so screen readers announce.
+
+**Form-level errors:**
+- Scroll to the first invalid field, focus it.
+- Summary at the top is fine in addition to inline, not instead of.
+
+**Server errors:**
+- Specific cause if you know it ("File too large — max 10MB").
+- Copy-paste support ID — `Error ID: xyz-123` — so the user can send it to support.
+- One-click retry where possible.
+- Never blame the user for network failures.
+
+**Network errors:**
+- Distinguish offline from 500 from 403. Different causes, different fixes.
+- Keep the in-flight state — don't throw away the form the user just filled.
+
+---
+
+## Conflict, Partial, and Offline States
+
+These are the forgotten states. Designing them separates products from demos.
+
+### Conflict
+
+Two users edited the same resource at the same time. Someone's about to lose work if you don't handle this.
+
+- Detect via version / etag / updated_at.
+- Present both versions. Let the user pick or merge.
+- Never silently overwrite. The "last write wins" pattern looks like a bug to the losing user.
+- For high-frequency collaborative surfaces, consider CRDT or operational transform rather than explicit conflict UI.
+
+### Partial
+
+Some data loaded, some failed. Common with multi-source dashboards or parallel fetches.
+
+- Show what succeeded.
+- Mark what failed with a per-tile error state, not a page-level one.
+- Let the user retry the failing piece without reloading the rest.
+- Example: dashboard with 6 metrics, one metric API is down — render 5 metrics + one inline error tile with retry.
+
+### Offline
+
+Connection is gone. Anticipate this on mobile, field apps, travel, and flaky wifi.
+
+- Detect with `navigator.onLine` + a heartbeat (more reliable).
+- Communicate at the app shell: "You're offline — changes will sync when reconnected."
+- Queue writes locally (IndexedDB, localStorage). Optimistic UI locally.
+- Reconcile on reconnect: apply queued writes, handle conflicts, surface any rejections.
+- Disable actions that *require* connectivity (payments) — explain why.
+
+---
+
+## State Machine Reference
+
+Don't ship a state library for this. But think in state machines. Pseudocode:
+
+```
+states:
+  idle          -> on FETCH -> loading
+  loading       -> on SUCCESS(data=empty)   -> empty
+                 -> on SUCCESS(data)         -> success
+                 -> on SUCCESS(data=partial) -> partial
+                 -> on ERROR(network)        -> offline
+                 -> on ERROR(server)         -> error
+                 -> on TIMEOUT               -> error
+  empty         -> on CREATE  -> loading
+  error         -> on RETRY   -> loading
+  partial       -> on RETRY   -> loading (retains successful data)
+  offline       -> on ONLINE  -> loading (retries + drains queue)
+  success       -> on EDIT    -> loading (optimistic)
+                 -> on CONFLICT -> conflict
+  conflict      -> on RESOLVE -> loading
+```
+
+The mental model is the value. Use `useReducer`, XState, Zustand slices, or plain discriminated unions — whatever the project uses. Just don't model states as disconnected booleans (`isLoading && !error && !data`) — that's how impossible states appear.
+
+---
+
+## Checklist
+
+Before any interactive surface ships, every item on this list is designed (not necessarily implemented — design can be "stubbed as an empty component"):
+
+- [ ] Idle state has a clear primary action
+- [ ] Loading state matches final layout; appears after 200ms
+- [ ] Empty state has explanation + CTA + visual
+- [ ] Error state is specific, actionable, and recoverable
+- [ ] Partial state handled if data has multiple sources
+- [ ] Success state provides visual feedback (not color-only)
+- [ ] Conflict state exists if the resource is collaborative
+- [ ] Offline state exists if the user-journey is likely on mobile / flaky networks
+
+**Knob gating (used by `/ui-craft:unhappy`):**
+
+| CRAFT_LEVEL | Required states |
+|-------------|----------------|
+| ≤ 4 | idle, loading, error |
+| 5-7 | idle, loading, empty, error, success |
+| 8+ | all of the above plus partial, conflict, offline |
+
+Missing a required state is a finding. Fix before declaring the happy path "done."
+
+---
+
+## Cross-Refs
+
+- `heuristics.md` — visibility of system status (Nielsen #1) is the principle behind the loading/partial states; use it to argue severity.
+- `forms.md` — validation timing and error-state placement for form surfaces.
+- `recipe-dashboard.md` — states are a build step (step 6), not polish; skeletons mirror final layout geometry.

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

@@ -0,0 +1,229 @@
+# Theme Presets
+
+Four named, production-ready token stacks. Each is a complete primitive layer for the 3-layer contract in [tokens.md](tokens.md) — map these into your semantic tokens, don't reference them raw from components. Pick one when the project has no token system; if the project has tokens, those win ([SKILL.md](../SKILL.md) Discovery).
+
+These are not "styles to sprinkle". A preset is all-or-nothing: mixing Porcelain's radii with Carbon's shadows produces incoherence that reads as generated.
+
+**Contrast rule for all presets:** before shipping, verify text pairs with APCA — Lc ≥ 75 for body text, Lc ≥ 60 for large text (≥24px), Lc ≥ 45 for non-text UI. The pairs below are chosen to clear these; re-verify after any tweak.
+
+**Default usage:** light mode unless the user asks for dark. Every preset defines both; both must be intentional ([color.md](color.md) dark-mode rules).
+
+**Motion tokens:** each preset's `--motion-*` values intentionally override the canonical scale in [motion.md](motion.md) — pace is part of the aesthetic (Signal is fast, Porcelain unhurried). When a preset is active, its values win; the motion.md scale is the default when building without a preset. All values stay within the ≤400ms ceiling.
+
+---
+
+## Graphite — minimal clean (default)
+
+Cool neutrals, one deep accent, hairline borders, tight type. The safe choice for SaaS tools, admin surfaces, and the Command/Overview dashboard compositions. Disappears behind the data — which is the point.
+
+```css
+:root {
+  /* neutrals — cool, hue 255 */
+  --gray-0:   oklch(99% 0.002 255);   /* page */
+  --gray-1:   oklch(97% 0.003 255);   /* raised surface, sidebar tint */
+  --gray-2:   oklch(93% 0.004 255);   /* hairlines, dividers */
+  --gray-3:   oklch(86% 0.005 255);   /* disabled fills */
+  --gray-6:   oklch(55% 0.012 255);   /* secondary text */
+  --gray-7:   oklch(42% 0.014 255);   /* tertiary headings */
+  --gray-9:   oklch(18% 0.012 255);   /* primary text */
+
+  /* accent — deep indigo */
+  --accent:        oklch(46% 0.17 275);
+  --accent-hover:  oklch(41% 0.17 275);
+  --accent-tint:   oklch(46% 0.17 275 / 0.08);
+  --on-accent:     oklch(99% 0.002 255);
+
+  /* semantic */
+  --success: oklch(52% 0.13 155);
+  --warning: oklch(62% 0.14 75);
+  --danger:  oklch(52% 0.18 25);
+
+  /* type — one grotesque sans for everything */
+  --font-body: var(--font-sans);       /* Inter-class; system-ui acceptable */
+  --text-body: 14px / 1.5;
+  --text-display: 28px;                 /* metrics; 36px for hero */
+  --tracking-display: -0.02em;
+
+  /* shape + depth */
+  --radius-input: 0.375rem;  --radius-card: 0.625rem;  --radius-modal: 0.875rem;
+  --shadow-card: 0 0 0 1px oklch(0% 0 0 / 0.04), 0 1px 2px oklch(0% 0 0 / 0.05);
+  --shadow-overlay: 0 0 0 1px oklch(0% 0 0 / 0.05), 0 8px 24px oklch(0% 0 0 / 0.12);
+
+  /* motion */
+  --motion-fast: 120ms;  --motion-base: 200ms;  --motion-slow: 320ms;
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+}
+```
+
+**Dark mapping:** page `oklch(15% 0.012 255)`, raised `oklch(19% 0.012 255)`, hairline `oklch(26% 0.012 255)`, text `oklch(93% 0.004 255)`, accent lifts to `oklch(62% 0.15 275)`, shadows replaced by surface lightness steps.
+
+---
+
+## Porcelain — soft modern
+
+Warm neutrals, terracotta accent, generous radius, soft layered shadows. For products that want approachable over technical: consumer SaaS, onboarding-heavy tools, health/finance for humans. Pairs with VISUAL_DENSITY ≤ 5.
+
+```css
+:root {
+  --gray-0:   oklch(98.5% 0.004 80);
+  --gray-1:   oklch(96.5% 0.006 80);
+  --gray-2:   oklch(92% 0.008 80);
+  --gray-3:   oklch(85% 0.009 80);
+  --gray-6:   oklch(54% 0.015 70);
+  --gray-9:   oklch(22% 0.015 60);
+
+  --accent:        oklch(60% 0.13 40);
+  --accent-hover:  oklch(55% 0.13 40);
+  --accent-tint:   oklch(60% 0.13 40 / 0.09);
+  --on-accent:     oklch(98.5% 0.004 80);
+
+  --success: oklch(56% 0.12 150);
+  --warning: oklch(66% 0.13 80);
+  --danger:  oklch(54% 0.17 28);
+
+  /* type — humanist sans body, optional rounded display */
+  --text-body: 15px / 1.55;
+  --text-display: 30px;
+  --tracking-display: -0.015em;
+
+  --radius-input: 0.625rem;  --radius-card: 0.875rem;  --radius-modal: 1.25rem;
+  --shadow-card: 0 1px 2px oklch(30% 0.02 60 / 0.06), 0 4px 12px oklch(30% 0.02 60 / 0.06);
+  --shadow-overlay: 0 2px 4px oklch(30% 0.02 60 / 0.08), 0 16px 40px oklch(30% 0.02 60 / 0.14);
+
+  --motion-fast: 140ms;  --motion-base: 220ms;  --motion-slow: 360ms;
+  --ease-out: cubic-bezier(0.22, 1, 0.36, 1);
+}
+```
+
+**Dark mapping:** keep the warm hue — page `oklch(17% 0.012 70)`, raised `oklch(21% 0.012 70)`; accent lifts to `oklch(70% 0.12 45)`. Warm dark is this preset's signature; switching to cool dark breaks it.
+
+---
+
+## Carbon — dark premium
+
+Dark-first. Deep cool neutrals, elevation by surface tint (not shadow), one restrained luminous accent. For developer tools, monitoring, pro audio/video — products used for hours in the dark. Light mode exists but dark is primary.
+
+```css
+:root {  /* dark IS the root */
+  --surface-0: oklch(14% 0.012 260);   /* page */
+  --surface-1: oklch(17.5% 0.012 260); /* card */
+  --surface-2: oklch(21% 0.012 260);   /* raised: popover, hover */
+  --surface-3: oklch(25% 0.012 260);   /* highest: modal */
+  --line:      oklch(28% 0.012 260);   /* hairlines */
+  --text-1:    oklch(93% 0.005 260);
+  --text-2:    oklch(70% 0.01 260);
+  --text-3:    oklch(52% 0.012 260);
+
+  --accent:        oklch(78% 0.12 170);  /* luminous mint — reads as light, not paint */
+  --accent-hover:  oklch(84% 0.12 170);
+  --accent-tint:   oklch(78% 0.12 170 / 0.10);
+  --on-accent:     oklch(8% 0.008 260);  /* near-true black — the 14% surface tone fails Lc 60 here */
+
+  --success: oklch(74% 0.12 155);
+  --warning: oklch(78% 0.13 85);
+  --danger:  oklch(68% 0.16 25);
+
+  --text-body: 14px / 1.5;
+  --text-display: 28px;
+  --tracking-display: -0.02em;
+  /* numbers and code in mono; tabular-nums everywhere */
+
+  --radius-input: 0.375rem;  --radius-card: 0.625rem;  --radius-modal: 0.875rem;
+  /* NO drop shadows — elevation = surface step + 1px line. Glow only on the
+     single primary CTA, subtle: 0 0 16px var(--accent-tint) */
+
+  --motion-fast: 120ms;  --motion-base: 180ms;  --motion-slow: 300ms;
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+}
+```
+
+**Light mapping (secondary):** invert the surface ladder onto Graphite's neutrals; accent darkens to `oklch(50% 0.13 170)`. Don't ship light-Carbon as default — if light is the primary need, pick Graphite.
+
+---
+
+## Signal — sharp geometric
+
+High-contrast, near-mono neutrals, semantic color doing real work, minimal radius, zero decorative depth. For dense data products — the Analytics composition, trading-adjacent surfaces, ops consoles at VISUAL_DENSITY ≥ 8.
+
+```css
+:root {
+  --gray-0:   oklch(100% 0 0);
+  --gray-1:   oklch(97% 0 0);
+  --gray-2:   oklch(91% 0 0);
+  --gray-6:   oklch(50% 0 0);
+  --gray-9:   oklch(12% 0 0);
+
+  --accent:        oklch(40% 0.16 264);   /* one decisive blue-violet — used ONLY for selection + primary action */
+  --accent-hover:  oklch(34% 0.16 264);
+  --accent-tint:   oklch(40% 0.16 264 / 0.08);
+  --on-accent:     oklch(100% 0 0);
+
+  /* semantic carries the information load — held to dots, deltas-on-demand, alerts */
+  --success: oklch(50% 0.15 150);
+  --warning: oklch(60% 0.15 70);
+  --danger:  oklch(50% 0.20 25);
+
+  /* type — body sans, ALL numerals mono */
+  --text-body: 13px / 1.45;
+  --font-data: var(--font-mono);
+  --text-display: 26px;
+  --tracking-display: -0.01em;
+
+  --radius-input: 0.125rem;  --radius-card: 0.375rem;  --radius-modal: 0.625rem;
+  --shadow-card: none;                      /* 1px hairline only */
+  --shadow-overlay: 0 0 0 1px oklch(0% 0 0 / 0.08), 0 6px 20px oklch(0% 0 0 / 0.10);
+
+  --motion-fast: 100ms;  --motion-base: 160ms;  --motion-slow: 240ms;  /* speed IS the aesthetic */
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+}
+```
+
+**Dark mapping:** pure-neutral dark — page `oklch(13% 0 0)`, card `oklch(16.5% 0 0)`, hairline `oklch(25% 0 0)`; accent lifts to `oklch(70% 0.13 264)`; semantic hues lift ~20% lightness. The mono-numeral rule does not relax in dark.
+
+---
+
+## Choosing
+
+| Signal in the brief | Preset |
+|---|---|
+| "clean", "professional", internal tool, no strong brand | **Graphite** |
+| "friendly", "approachable", consumer-facing, onboarding matters | **Porcelain** |
+| "developer tool", "pro", users live in it at night | **Carbon** |
+| "dense", "fast", data is the product, power users | **Signal** |
+
+Brand color exists? Replace `--accent` with the brand hue at the preset's lightness/chroma discipline — the preset survives an accent swap; it does not survive a radius or shadow swap.
+
+---
+
+## Accent rotation (no brand yet)
+
+When the brief has no brand color, **rotate one accent family per build** so outputs don't all land on indigo. Declare the choice in the Craft Read ([craft-intent.md](craft-intent.md) §6). Swap only `--accent`, `--accent-hover`, `--accent-tint`, and `--on-accent` on the chosen preset — keep neutrals, radii, and shadows intact.
+
+| Family | Light `--accent` (OKLCH) | Best on preset | Avoid pairing with |
+|---|---|---|---|
+| **Indigo** | `oklch(46% 0.17 275)` | Graphite, Signal | — (default; rotate away often) |
+| **Teal** | `oklch(48% 0.12 195)` | Graphite, Carbon | Porcelain terracotta clash |
+| **Rose** | `oklch(52% 0.14 15)` | Porcelain, Graphite | Signal high-contrast grids |
+| **Amber** | `oklch(58% 0.14 75)` | Porcelain, Graphite | Carbon mint accent |
+| **Forest** | `oklch(46% 0.11 155)` | Porcelain, Graphite | Signal blue-violet default |
+
+**Hover / tint discipline:** `--accent-hover` ≈ 5% darker on the same hue; `--accent-tint` ≈ 8–10% alpha of accent; `--on-accent` must clear APCA Lc ≥ 60 against the filled button.
+
+**Dark mode:** lift accent lightness ~15–20% on dark surfaces (see each preset's dark mapping). Re-verify contrast after swap.
+
+**Marketing vs product:** landings and portfolios may rotate accent **and** theme preset; dashboards and auth rotate accent only unless the user asks for a full re-skin.
+
+## Premium palette families (artisan / luxury / wellness briefs)
+
+"Premium" briefs converge on one palette — warm cream background, brass/clay accent, espresso text — until every generated artisan site is interchangeable. Unless the brief names those colors, rotate through distinct families (one per build, never the same family twice in a row):
+
+| Family | Recipe | Reads as |
+|---|---|---|
+| **Cold luxury** | silver-grey neutrals + chrome + smoke dark | precision, engineering premium |
+| **Forest** | deep green + bone + amber accent | outdoor heritage, built-to-last |
+| **Black & tan** | true off-black + warm tan, hard contrast, no beige | leather-goods, deliberate |
+| **Cobalt + cream** | one saturated blue against a single neutral | confident, modern craft |
+| **Terracotta + slate** | warm rust against cool grey | earthy without the beige wash |
+| **Mono + pop** | off-white + off-black + one bright accent | gallery, editorial-modern |
+
+Warmth can come from typography, imagery, and copy — it doesn't have to live in the background color. Verify AA contrast after picking; dark-mode mapping per the preset rules above.