agemon 0.1.0 → 6.3.0

package/assets/skills/design/agemon-design/references/recipe-auth.md

@@ -0,0 +1,88 @@
+# Recipe: Auth (Sign in / Sign up)
+
+Outcome recipe for authentication surfaces. Small surface, zero tolerance: auth is used by 100% of users at their least patient moment, and it's where AI-generated UIs are most recognizable (full-bleed saturated brand panel, italic quote, "OR" divider). Field rules live in [forms.md](forms.md), component contracts in [components.md](components.md).
+
+**Load [craft-intent.md](craft-intent.md)** — apply product-surface patterns (§4), default **DESIGN_VARIANCE 4**, pick one **signature bet** from craft-intent §3 auth list in the Craft Read before Step 1.
+
+## Step 0 — Four inputs (defaults if unanswered)
+
+| Input | Options | Default |
+|---|---|---|
+| Brand surface | product has marketing presence worth showing / pure utility app | marketing presence |
+| Auth methods | SSO-first (Google/GitHub/SAML) / email-first / both | both, SSO on top |
+| Theme | preset from [themes.md](themes.md) or existing brand tokens | brand tokens if present, else derive from the brief |
+| Variance | DESIGN_VARIANCE 1-10 | 4 |
+| Signature bet | one from [craft-intent.md](craft-intent.md) §3 auth list | trust footer line or a domain-specific welcome line |
+
+## Step 1 — Pick the composition
+
+### Split panel (default — brand presence)
+
+```
+┌──────────────────────────┬────────────────────┐
+│ logo                     │                    │
+│                          │  Welcome back      │
+│  ONE proof asset:        │  sub, one line     │
+│  figure or detail from   │  [SSO] [SSO]       │
+│  OR attributed quote     │  ── or with email ─│
+│  (pick one, not a deck)  │  Email             │
+│                          │  Password  Forgot? │
+│                          │  [Sign in]         │
+│ trust footer (compliance)│  New here? link    │
+└──────────────────────────┴────────────────────┘
+```
+
+Panel is a **tinted neutral surface** (gray-1 of the theme), NEVER a full-saturation brand flood — a wall of pure accent is the single loudest AI tell on auth screens, and it blows the entire accent budget on decoration. Panel content: one believable proof asset with real numbers or a real attribution. Trust line at the panel's foot (compliance, data residency) — sign-in is where users think about trust.
+
+### Centered card (utility / in-product re-auth)
+
+```
+┌───────────────────────────────────────────────┐
+│                                               │
+│              logo (small, centered)           │
+│              Welcome back                     │
+│              [SSO buttons]                    │
+│              ── or with email ──              │
+│              form card, 360-400px             │
+│              footer links                     │
+│                                               │
+└───────────────────────────────────────────────┘
+```
+
+No panel, no story — speed is the design. Card 360-400px, generous vertical rhythm, page background gray-1 with the card on white (or theme surfaces in dark).
+
+## Step 2 — Form contract (non-negotiable)
+
+- Form column **360-400px**. Wider reads as a document; narrower cramps the SSO row.
+- **SSO buttons above email** when SSO is the dominant path — order by actual usage, not aesthetics. Equal visual weight between SSO providers (neutral outline buttons, real provider marks).
+- Divider is lowercase, quiet: "or with email" — not "OR" shouting in caps.
+- Labels above fields ([forms.md](forms.md)); "Forgot password?" inline with the password label, right-aligned — not buried under the button.
+- **No required asterisks** — every field on an auth form is required; single-purpose familiar forms skip marking entirely ([forms.md](forms.md)).
+- Password: show/hide toggle with `aria-label`. On sign-UP: live strength hint, validate-as-you-type with debounce; never a wall of "must contain" rules before the user types.
+- Submit: full-width primary, verb label ("Sign in", "Create account") — the page's ONE accent-filled element. Stays enabled; validates on press ([forms.md](forms.md)).
+- Error state: message below the offending field + border, focus moved to it. Auth errors stay honest but unspecific where security demands ("Email or password doesn't match") — and actionable where it doesn't (rate-limit: say when to retry).
+- Cross-link the sibling flow ("New here? Start a free trial") — one line, after the submit.
+
+## Step 3 — Sign-up deltas
+
+- Ask the minimum: email + password (+ name only if the product needs it day one). Every extra field measurably increases drop-off — enrich the profile later, in-product.
+- State what happens next under the CTA ("We'll send a verification link").
+- Legal line (terms/privacy) in tertiary text under the CTA — present, quiet, real links.
+- Multi-step signup (workspace, invites): apply the multi-step contract from [forms.md](forms.md) — cost upfront, easy→hard, progress.
+
+## Acceptance bar
+
+- [ ] Craft Read declared; variance 4 unless brief says otherwise; signature bet built in first pass
+- [ ] Squint test: eye lands on the submit button; accent appears ONLY on submit + links
+- [ ] No saturated full-bleed brand panel; panel (if any) is tinted neutral with one proof asset
+- [ ] Form column 360-400px, labels above, no asterisks, divider lowercase
+- [ ] "Forgot password?" findable without scanning; sibling flow cross-linked
+- [ ] Submit enabled + validates on press; errors below fields, focus managed
+- [ ] Keyboard: tab order top-to-bottom, Enter submits, focus visible on every control
+- [ ] Trust signals present (compliance line or equivalent) and honest
+- [ ] Works at 320px wide: panel drops, form survives alone
+- [ ] Product patterns from craft-intent §4: tinted panel surface, one accent-filled element, honest error copy
+
+## Cross-refs
+
+[craft-intent.md](craft-intent.md) Craft Read, variance, auth signature bets · [forms.md](forms.md) field layout, validation, marking · [components.md](components.md) buttons, links · [themes.md](themes.md) surface tokens · [state-design.md](state-design.md) loading/error states for the submit roundtrip

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

@@ -0,0 +1,130 @@
+# Recipe: SaaS Dashboard
+
+An outcome recipe is a build contract, not a rule list: follow it top to bottom and the result is shippable without a design retouch pass. Rules live in [dashboard.md](dashboard.md), [dataviz.md](dataviz.md), and [tokens.md](tokens.md) — this file decides **composition**: which layout, which defaults, in what order, and what "done" means.
+
+**Who this serves:** the zero-questions path produces a strong default for users who don't design. Every default below is overridable — users who do design treat the compositions as skeletons and go from there.
+
+**Load [craft-intent.md](craft-intent.md)** — apply product-surface patterns (§4), default **DESIGN_VARIANCE 4**, pick one **signature bet** from craft-intent §3 (product list) in the Craft Read before Step 1.
+
+## Step 0 — Three inputs (defaults if unanswered)
+
+Ask once, in one compact prompt. If the user declines or says "you decide", apply the defaults — never block.
+
+| Input | Options | Default |
+|---|---|---|
+| Primary user + 60-second decision | exec ("are we winning?") / operator ("what needs action now?") / analyst ("why did X change?") | operator |
+| Theme | one of the four presets in [themes.md](themes.md), or project's existing tokens | existing tokens if present, else derive from the brief |
+| Density | VISUAL_DENSITY knob 1-10 | 7 |
+| Variance | DESIGN_VARIANCE knob 1-10 | 4 |
+| Signature bet | one from [craft-intent.md](craft-intent.md) §3 product list | nav active indicator or a motif drawn from the domain |
+
+The first answer selects the composition. The persona is not cosmetic — it decides what the hero metric is and what gets buried ([dashboard.md](dashboard.md) "Ranking decisions").
+
+## Step 1 — Pick the composition
+
+Three named compositions. Don't invent a fourth unless the user's brief demands it — these cover the decision shapes that recur in production SaaS.
+
+### Overview (exec)
+
+```
+┌──────┬──────────────────────────────────────┐
+│      │ topbar: title · date range · avatar  │
+│ nav  ├───────────────┬──────┬──────┬────────┤
+│      │ HERO metric   │ sup1 │ sup2 │ sup3   │
+│      ├───────────────┴──────┴──────┴────────┤
+│      │ trend area chart (2/3)  │ breakdown  │
+│      │                         │ h-bars 1/3 │
+│      ├─────────────────────────┴────────────┤
+│      │ table (top movers, 5-8 rows)   ▼fold │
+└──────┴──────────────────────────────────────┘
+```
+
+One hero answering "are we winning", 3 supports decomposing it, one trend, one breakdown. Table is below the fold on purpose — execs drill rarely. Charts large, tables small.
+
+### Command (operator) — default
+
+```
+┌──────┬──────────────────────────────────────┐
+│      │ topbar: title · global filter · ⌘K   │
+│ nav  ├──────┬──────┬──────┬─────────────────┤
+│      │ hero │ sup1 │ sup2 │  status strip   │
+│      ├──────┴──────┴──────┴─────────────────┤
+│      │ filter row: ghost buttons · reset    │
+│      ├──────────────────────────────────────┤
+│      │ WORK QUEUE table — dominant, 60%+    │
+│      │ of viewport height            ▼fold  │
+└──────┴──────────────────────────────────────┘
+```
+
+The table IS the product: the operator acts on rows. Metric strip is compact (single row, small cards). Row actions visible on hover, keyboard navigable (j/k or arrows), status as 6px dots. Charts only as sparklines inside cards — a big trend chart steals space from the queue.
+
+### Analytics (analyst)
+
+```
+┌──────┬──────────────────────────────────────┐
+│      │ topbar: title · saved views · export │
+│ nav  ├──────────────┬───────────────────────┤
+│      │ filter rail  │ primary chart canvas  │
+│      │ (dimensions, │ (area or h-bars,      │
+│      │  segments,   │  direct-labeled)      │
+│      │  compare)    ├───────────────────────┤
+│      │              │ segmented table  ▼fold│
+└──────┴──────────────┴───────────────────────┘
+```
+
+Filters are first-class (left rail, not a toolbar row) because the analyst's job is slicing. Chart canvas re-renders on every filter change — show a 150ms opacity transition, never a spinner for operations under 400ms. Direct-label series, drop the legend ([dataviz.md](dataviz.md)).
+
+## Step 2 — Shell spec (exact values)
+
+- **Sidebar:** 240px (range 220-260). Subtle bg tint per [dashboard.md](dashboard.md) — never full dark outside Dark Premium. Collapses to 56px icon rail below 1024px, off-canvas below 768px.
+- **Topbar:** 56px (range 48-64), same surface as content (no border-bottom heavier than 1px hairline).
+- **Content:** padding 24px (density ≤4: 32px; ≥8: 16px), max-width none — dashboards use the viewport. 12-col grid, gap 16px (24px at density ≤4).
+- **Card padding:** 16-20px. **Table rows:** 40-48px. Both from [dashboard.md](dashboard.md) Content Density.
+- **Above the fold at 1440×900:** hero + supports + one more content type minimum. Three content types visible — non-negotiable.
+
+## Step 3 — Component inventory
+
+Build exactly these, to spec — each links to its contract:
+
+1. Nav item (active = accent bg at 10% + accent text; `aria-current="page"`) — [dashboard.md](dashboard.md)
+2. Metric card, two variants: primary (accent-tinted, 36px number) / secondary (neutral, 28px). Sparkline 32px. Change text plain tertiary — [dashboard.md](dashboard.md)
+3. Area chart with gradient fill 15%→0, horizontal-only gridlines — [dashboard.md](dashboard.md) Chart Styling
+4. Data table: status dots, right-aligned `tabular-nums` numbers, sentence-case headers, row hover — [dashboard.md](dashboard.md) Data Tables
+5. Filter bar: ghost buttons, conditional "Reset" text link — [dashboard.md](dashboard.md)
+6. Empty / loading / error states for EVERY data region — [state-design.md](state-design.md). Skeletons mirror final layout geometry, never generic gray boxes of arbitrary size.
+
+**Libraries** (tools, not design authority — match the project's stack first): charts via Recharts/visx (React) or ECharts/Chart.js (otherwise); sparklines as inline SVG polylines, no library. Tables: headless (TanStack Table) + own markup; never a themed datagrid that fights the token system. Icons per SKILL.md rule 4.
+
+## Step 4 — Build order
+
+Token spine first, states before polish. Skipping ahead is how slop happens.
+
+1. Tokens: apply theme preset or map existing tokens ([themes.md](themes.md), [tokens.md](tokens.md))
+2. Shell: sidebar + topbar + grid, responsive collapse wired
+3. Hero tier + supports (the squint test must already pass here)
+4. Primary chart or work-queue table (per composition)
+5. Remaining tiers
+6. States: loading / empty / error / partial for every data region
+7. Keyboard pass: focus-visible everywhere, table navigable, ⌘K if Command composition
+8. Finish: run [finish-bar.md](finish-bar.md) passes 1-4 + 7 minimum (full bar at CRAFT_LEVEL ≥ 8)
+
+## Acceptance bar — "would a designer retouch this?"
+
+Ship only when every box checks. One unchecked = not done, no exceptions:
+
+- [ ] Squint test: eye lands on exactly ONE thing first (the hero)
+- [ ] One accent color, ≤5 placements in the viewport; everything else neutral
+- [ ] ≥3 content types above the fold; NO equal-weight card grid anywhere
+- [ ] Every number `tabular-nums`; every comparison plain secondary text (no pills, no arrows)
+- [ ] Empty, loading, and error states exist and match layout geometry
+- [ ] Date range or equivalent time control present on time-series surfaces
+- [ ] Keyboard: tab order logical, focus visible, table rows reachable
+- [ ] Sidebar tinted (not black), headers sentence case, no uppercase anywhere except 11-13px tracked labels
+- [ ] Charts: correct type per data story, single-hue opacity ramp, no legend for single series
+- [ ] Signature bet from Craft Read is built and visible (not deferred to polish)
+- [ ] Product patterns from craft-intent §4: tinted sidebar, metric hierarchy, row context or sparkline on hero metric
+- [ ] `prefers-reduced-motion` honored; all transitions ≤400ms
+
+## Cross-refs
+
+[dashboard.md](dashboard.md) component contracts · [dataviz.md](dataviz.md) chart science · [themes.md](themes.md) token presets · [state-design.md](state-design.md) state lattice · [finish-bar.md](finish-bar.md) finishing passes · [personas.md](personas.md) grounding the persona choice

package/assets/skills/design/agemon-design/references/recipe-landing.md

@@ -0,0 +1,120 @@
+# Recipe: Landing Page
+
+Outcome recipe for marketing landing pages — composition, section grammar, and the bar that makes the result publishable without a design retouch. Component rules live in [components.md](components.md), copy rules in [copy.md](copy.md), pattern evidence in [inspiration.md](inspiration.md). This file decides what to build and in what order.
+
+**Who this serves:** zero-questions path → strong default. Designers treat the compositions as skeletons.
+
+**Portfolios / case studies:** use this recipe with **DESIGN_VARIANCE 8** (craft-intent default) — variable grid aspects, one hero project above fold, asymmetric about/contact. Marketing patterns (§5) apply; default composition is often message-forward or proof-forward with editorial type.
+
+**Load [craft-intent.md](craft-intent.md)** and [inspiration.md](inspiration.md) hero archetypes — apply marketing patterns (§5), default **DESIGN_VARIANCE 7** (6 for waitlist-only), pick **signature bet** from craft-intent §3 marketing list in the Craft Read.
+
+## Step 0 — Three inputs (defaults if unanswered)
+
+| Input | Options | Default |
+|---|---|---|
+| What exists to show | live product (screenshots possible) / pre-launch (no product yet) / sales-led service | live product |
+| Theme | a preset from [themes.md](themes.md) or existing brand tokens | brand tokens if present, else derive from the brief |
+| One conversion action | trial signup / demo request / waitlist / purchase | trial signup |
+| Variance | DESIGN_VARIANCE 1-10 | 7 (6 if pre-launch / waitlist only) |
+| Signature bet | one from [craft-intent.md](craft-intent.md) §3 marketing list | derived from the brief: the product's own artifact, cropped or enlarged, or the one thing only this subject has |
+
+The first answer selects the composition. One page, ONE conversion action — every section either advances it or gets cut.
+
+## Step 1 — Decide what the fold argues, then pick its geometry
+
+Two decisions, in this order, and they are not the same decision. **What the fold argues** is yours to choose from the brief. **How it is laid out** is picked by exclusion, not taste.
+
+### 1a — What it argues
+
+| Strategy | Lead with | Fold carries |
+|---|---|---|
+| **Product-forward** — live product to show | the product doing its job | badge (what's new, or none) · H1 2-3 lines · sub ≤2 sentences · primary + ghost CTA · one micro-trust line · a real product shot, cropped at the fold **and** an edge · at most one floating mini-card over it (live metric, notification) for depth |
+| **Message-forward** — pre-launch, waitlist, no product to show | the claim, in language | H1 as the largest thing on the page · sub one sentence · email input with the join CTA attached to it · proof placed off-centre on purpose (avatars + count one side, badge the other) · an abstract motif rather than a screenshot |
+| **Proof-forward** — sales-led, B2B service | evidence before argument | compact H1 + sub + demo CTA · an outcome strip of exactly 3 specific metrics in large numerals · a case block: quote + attributed face + numbers · capability rows alternating beneath |
+
+No strategy is a default. A brief with a live product picks product-forward; a brief without one cannot.
+
+### 1b — What it looks like
+
+Pick a class the project's brief has not used yet (see `## Fold classes used` in the brief), and put `split` last. Do not pick by taste: asking a model for a composition returns its default every time, which is how eight builds in a row produced the same hero.
+
+The six classes are geometric and orthogonal to 1a — `type-only`, `full-bleed-overlay`, `split`, `stacked`, `product-dominant`, `band`. Most strategies can be built as most classes. The exclusions are the ones where the geometry cannot carry the argument:
+
+- **product-forward** cannot be `type-only` — no visual means no product
+- **message-forward** cannot be `product-dominant` — nothing to dominate with
+- **proof-forward** cannot be `full-bleed-overlay` — one dominating image cannot hold three metrics and a case block
+
+Any other unused class is legitimate. If the class you pick fights the brief for a reason not listed above, say which reason in the Craft Read and pick again — do not silently substitute the shape you had in mind.
+
+### 1c — Verify what you actually built
+
+If you can run a browser, render the page and compare the fold you see with the class you committed to. If you cannot, say the check was not verified.
+
+If they differ, the geometry drifted while you were writing. Fix the build to match the class, or record in the brief that the class changed and why. A declared class the code does not honour is worse than no declaration: it reads as compliance to anyone auditing the transcript.
+
+Record the class in the brief's spent list ([brief.md](brief.md)) so the next landing in this project picks something else.
+
+### Hero discipline (all compositions)
+
+The hero is a single moment, not a feature list. Hard limits:
+
+- **Max 4 text elements:** one eyebrow/badge (or none), headline (≤2 lines desktop), subtext (≤20 words, ≤4 lines), CTAs (1 primary + ≤1 secondary). If the value prop needs more than 20 words of subtext, the value prop is unclear — fix the copy, not the limit.
+- **Plan font scale and asset together.** Headline >6 words with a large hero shot → start at 48-60px, not 72-80px. A 4-line hero headline is always a font-size error.
+- **Nothing else rides the hero:** trust micro-strips, pricing teasers, feature bullets, avatar rows, and the logo wall all live in dedicated sections **below** the fold line. One micro-trust line under the CTAs is the ceiling.
+- **The headline starts 18-30% down the fold, not at the top.** This used to read "top padding cap ~96px", and that cap was wrong: on a 900px viewport it puts the headline at 11%, which is where a dense app starts its content, not a landing. Measured on four surfaces whose design is the reason people copy them, the first headline pixel lands at **19%, 20%, 24% and 64%** of the fold. 18-30% is the working band; above 30% is a deliberate, centred composition and needs the rest of the fold to be nearly empty to earn it. On 900px that is **160-270px of clear space** above the eyebrow — an amount that feels wrong while you are writing the CSS and correct the moment you look at the render.
+- **Ink density in the fold: 15-35 text nodes.** The same four measured 16, 34, 34 and 88 — and the 88 is a page whose fold is 68% one product screenshot, so its text is concentrated inside that image. A fold with 50 separate text nodes is a dashboard. Count them: if the fold has more than ~35, something in it belongs to the section below.
+- **The hero asset is 30-70% of the fold, or it is absent.** Measured: 68%, 32%, 31%, and one page with no hero image at all. What does not work is the middle: a 4:1 letterbox band or a small framed card reads as a placeholder for a real asset. Either give the product most of the fold and crop it at the edge, or commit to type alone.
+- **No decorative cues:** no "Scroll to explore", no ↓ arrows, no version badges (BETA, v0.6) unless the brief is literally a launch announcement, no mono-caps decoration strips at the hero foot.
+
+Order, each answering ONE question; spacing 80-160px between majors, varied:
+
+1. **Proof strip** — "do people like me use this?" Logos at low contrast + one specific stat ("teams cut X from 6h to 20min" beats "trusted by thousands").
+2. **Feature rows × 2-3** — "what does it do for me?" Asymmetric alternating rows with REAL visuals (chart, flow, screenshot detail). NEVER a uniform 3-column icon grid — that's the #1 template tell.
+3. **How it works / depth section** — "is it credible?" 3 steps max, or one technical diagram. Cut it if the product is self-evident.
+4. **Pricing teaser or full pricing** — "can I afford it?" See pricing block below.
+5. **Final CTA** — "ok, how do I start?" Restate the primary action + the micro-trust line. One section, not a wall.
+6. **Footer** — boring on purpose. Sitemap, legal, socials. Footers that try to be clever bury the links people need. No fake version stamps (`v1.4.2`, `Build 0048`) — those are devtool fixtures, not marketing content.
+
+**Layout-family budget.** A layout family (3-column cards, split text+image, full-width quote, bento, marquee) appears **at most once per page**; a page with 8 sections needs ≥4 distinct families. Max 2 consecutive image+text splits — the third consecutive zigzag is a fail; break it with a full-width section, a vertical stack, or a bento. "Selected work" must not look like "What we do".
+
+**Eyebrow budget.** Max 1 uppercase tracked micro-label per 3 sections (hero counts as one). Mechanical check: count `uppercase` + wide-tracking labels above headings; if count > ceil(sections / 3), delete eyebrows until it passes — the headline alone is enough.
+
+**Imagery is not optional.** Marketing pages are visual products; a text-only page is incomplete work, not minimalism. Priority order: (1) real product shots / brand assets, (2) image-generation tool if available in the environment, (3) clearly-labeled placeholder slots plus a list for the user of what's needed — never div-built fake screenshots or hand-drawn decorative SVG scenes. Logo walls use real SVG marks (both themes); invented brands get a simple monogram mark, never styled text wordmarks. Logos only — no industry labels printed under each logo.
+
+**Pricing block rules** (when present): highlight the recommended plan (border/badge/size) without making siblings look irrelevant; sticky column headers on long comparison tables; tooltips on hover for feature jargon; discounts shown as % under $100 and absolute amounts above (perceived size); charm pricing where the brand tolerates it; scarcity only if genuinely true — faked urgency reads instantly and burns trust.
+
+## Step 3 — Craft constraints (the ones landings break most)
+
+- **CTA hierarchy is three levels that must not tie:** nav CTA ≠ hero primary ≠ section CTAs. Hero primary is the most prominent interactive element on the page ([components.md](components.md)).
+- **Headline carries a dual benefit** where honest — immediate + long-term ("Answers today, confidence at month-end"). Front-load the key noun. No jargon: a stranger gets the value in one read.
+- **One signature detail** — drawn underline on the key word, a custom marker, a motif from the brand mark. Exactly one.
+- **Specific beats vague, everywhere:** metrics with units, named customers, real UI. Every "world-class/powerful/seamless" is a slot where evidence should be.
+- **Gradients**: if used, adjacent hues only, plus subtle grain/noise to kill the flat plastic look. Never the purple-cyan template wash.
+- **Copy budget:** no section over 2-3 sentences; CTAs are verb + outcome ("Start free trial", not "Get started" twice in different colors).
+
+## Step 4 — Build order
+
+1. Tokens (preset or brand) → 2. Nav + hero (squint test must pass with hero alone; then check the two numbers: headline top at 18-30% of the fold, and 4-6 distinct font sizes on the page with a 2.5x+ jump to display — see [typography.md](typography.md)) → 3. Proof strip → 4. Feature rows → 5. Pricing → 6. Final CTA + footer → 7. Responsive pass ([responsive.md](responsive.md) — hero stacks text-first on mobile, shot below, still cropped) → 8. Motion: entrances subtle, one scroll reveal per section max ([motion.md](motion.md)) → 9. Finish: [finish-bar.md](finish-bar.md) passes 1-4 + 8.
+
+## Acceptance bar — publishable without retouching?
+
+- [ ] Squint test on the hero: H1 → primary CTA, in that order; nothing competes
+- [ ] One conversion action; every section advances it
+- [ ] Product/visual cropped at fold or edge (scroll tease); no visual floating in dead air
+- [ ] CTA hierarchy: 3 distinct levels, no ties
+- [ ] At least one specific, attributed proof point; zero unattributed superlatives
+- [ ] No uniform icon-card grid anywhere
+- [ ] Section spacing 80-160px, varied; every section answers one question
+- [ ] One signature detail, exactly one
+- [ ] Mobile: hero readable without zoom, CTAs thumb-reachable, no horizontal scroll
+- [ ] Craft Read declared; variance and signature bet match the built page
+- [ ] No two adjacent sections share the same layout structure; no layout family repeats; ≤2 consecutive image+text splits
+- [ ] Hero discipline: ≤4 text elements, subtext ≤20 words, headline ≤2 lines, logo wall below the hero
+- [ ] Eyebrow count ≤ ceil(sections / 3); no numbered section eyebrows; no scroll cues
+- [ ] One CTA label per intent across the page (nav, hero, footer reuse the same words); every CTA fits one line at desktop and passes AA contrast on its own background
+- [ ] Real imagery where the composition calls for it; no div-built fake screenshots; logo wall is real SVG marks
+- [ ] `prefers-reduced-motion` honored; entrances ≤400ms; no scroll-jacking
+
+## Cross-refs
+
+[inspiration.md](inspiration.md) observed patterns · [components.md](components.md) buttons, links, nav · [copy.md](copy.md) voice, CTAs, numbers · [themes.md](themes.md) presets · [recipe-dashboard.md](recipe-dashboard.md) when the hero shot needs a product UI worth showing

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

@@ -0,0 +1,168 @@
+# Responsive & Adaptive Design
+
+Adaptation is not just scaling — it's rethinking for each context.
+
+---
+
+## Breakpoint Strategy: Content-Driven (Preferred)
+
+Add breakpoints where the content breaks, not at conventional device widths. Container queries are the preferred mechanism — components respond to their container, not to the viewport.
+
+```css
+.card-container { container-type: inline-size; }
+
+@container (min-width: 400px) {
+  .card { grid-template-columns: 1fr 2fr; }
+}
+```
+
+Use fluid sizing to eliminate most breakpoints entirely:
+
+```css
+/* Fluid font: 16px at 320px → 20px at 1200px */
+font-size: clamp(1rem, 0.5rem + 1.5vw, 1.25rem);
+
+/* Fluid spacing */
+padding: clamp(1rem, 2vw, 3rem);
+```
+
+For full container query patterns — style queries, named containers, when to prefer container over media queries — see [modern-css.md](modern-css.md).
+
+---
+
+## Breakpoint Strategy: Device Reference (Fallback)
+
+When the project's existing system uses device breakpoints, match it. The conventional ranges:
+
+- Mobile: < 768px
+- Tablet: 768–1023px
+- Desktop: 1024px+
+
+Use these only when integrating with an existing system. New code should prefer container queries (see above).
+
+### Verify Coverage
+
+- Mobile, tablet, laptop, ultra-wide
+- Portrait AND landscape
+- Different browsers (Safari, Chrome, Firefox)
+- iOS Low Power Mode, macOS Safari
+
+---
+
+## Mobile Adaptation (Desktop → Mobile)
+
+### Layout
+- Single column (not multi-column)
+- Vertical stacking
+- Full-width components
+- Bottom navigation (not top/side)
+
+### Interaction
+- Touch targets **44x44px minimum**
+- Swipe gestures only for reversible, spatially-implied actions — dismiss a sheet, page a carousel, reveal a row action. **Why:** a swipe leaves no visible affordance, so anything discovered only by swiping is undiscoverable to a first-time user, and anything destructive behind it is irreversible-by-accident. Every swipe needs a visible equivalent: a button, a menu item, or a drag handle.
+- Bottom sheets instead of dropdowns
+- **Thumbs-first design** — primary and navigational actions inside the bottom-center thumb zone; destructive or cancel actions deliberately OUTSIDE easy reach. **Why:** the thumb zone optimizes for the action you want repeated; placing "Delete" there optimizes for accidents.
+- More spacing between interactive elements
+
+### Content
+- **Progressive disclosure** — don't show everything at once
+- Secondary content in tabs/accordions
+- Shorter, more concise text
+- Minimum **16px font size** (prevents iOS zoom)
+
+### Navigation
+- Hamburger or bottom nav
+- Reduce complexity
+- Sticky headers for context
+- Back button in flows
+
+---
+
+## Tablet Adaptation
+
+- Two-column layouts (not single or three)
+- Master-detail views (list + detail)
+- Adaptive per orientation (portrait vs landscape)
+- Support both touch and pointer
+- Touch targets 44px but allow denser layouts than phone
+
+---
+
+## Desktop Adaptation (Mobile → Desktop)
+
+### Layout
+- Multi-column (use horizontal space)
+- Side navigation: always visible on desktop (1024px+). On tablet (768–1023px): collapse to icon rail or persistent narrow sidebar. On mobile: collapse to a drawer or bottom-nav pattern. **Why:** primary navigation must remain discoverable; visible-by-default at desktop trades screen real estate for discoverability, while mobile trades discoverability for content room — both are correct in their context.
+- Multiple information panels
+- Max-width constraints (don't stretch to 4K)
+
+### Interaction
+- Hover states for additional info
+- Keyboard shortcuts
+- Right-click context menus
+- Drag and drop, multi-select with Shift/Cmd
+
+### Content
+- Show more info upfront (less progressive disclosure)
+- Data tables with many columns
+- Richer visualizations
+
+---
+
+## Responsive Grid (No Breakpoints)
+
+```css
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: var(--space-lg);
+}
+```
+
+---
+
+## Responsive Images
+
+```html
+<picture>
+  <source media="(min-width: 768px)" srcset="large.webp">
+  <img src="small.webp" alt="..." width="600" height="400" loading="lazy">
+</picture>
+```
+
+---
+
+## Viewport Units
+
+Use `dvh` instead of `100vh` or Tailwind's `h-screen` for any surface meant to fill the viewport. Mobile browsers change the visible viewport height as the URL bar shows and hides — `100vh` measures the *largest* possible viewport and locks to it, so a full-height hero or modal ends up taller than what's actually visible and the bottom gets clipped behind the browser chrome. `dvh` (dynamic viewport height) tracks the real, current viewport instead.
+
+---
+
+## Safe Areas
+
+Any fixed or sticky element must respect `env(safe-area-inset-*)` on notched devices — a bottom nav bar or sticky CTA that ignores the inset sits under the home indicator or gets clipped by it.
+
+```css
+.fixed-bottom {
+  padding-bottom: env(safe-area-inset-bottom);
+}
+```
+
+---
+
+## Print Adaptation
+
+- Remove navigation, footer, interactive elements
+- Page breaks at logical points
+- Expand shortened content (show full URLs)
+- Black and white or limited color
+- Add page numbers, headers, print date
+
+---
+
+## Never
+
+- Don't hide core functionality on mobile — feature parity is the floor; if a feature is too complex for mobile, redesign the feature, don't hide it.
+- Don't assume touch only on mobile — tablets and 2-in-1 laptops blur the line; design pointer-agnostic.
+- Don't forget landscape orientation — mobile in landscape and tablet in portrait often have similar dimensions and need similar treatment.
+- Don't ship horizontal scroll at any breakpoint without an explicit scroll affordance — accidental horizontal scroll is the most common AI-template responsive failure.