agemon 0.1.0 → 6.0.0

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

@@ -0,0 +1,122 @@
+# 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 **Graphite** |
+| 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 | hero crop or floating proof card |
+
+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 draw 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 drawn, not chosen.
+
+Until 2026-08-13 this section shipped three ASCII diagrams, one per strategy, and the first was labelled *default*. Its geometry was text one side and a visual the other — which is the `split` composition class, the one `fold_candidates` deliberately draws last because *"it is the fold every generator reaches for unprompted."* Measured across seven landing builds, every fold that got built was one of the three geometries those diagrams prescribed, and none was the class the draw had offered. A drawn class cannot introduce variety while this file ships the answer with a picture, so the pictures are gone and the content grammar stayed.
+
+### 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
+
+Call **`fold_candidates`** and commit to one of the classes it returns. 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 draw is seeded per project, so two projects start somewhere different and one project stays reproducible.
+
+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
+
+Anything else the draw offers is legitimate. If it draws a class that fights the brief for a reason not listed above, say which reason in the Craft Read and draw again — do not silently substitute the shape you had in mind.
+
+### 1c — Verify what you actually built
+
+Render it and call **`check_fold` with `expected_class`** set to the class you committed to. Without that argument it reports what the fold *is* and cannot tell you whether it is what you intended — and it will say so rather than imply agreement.
+
+If it reports drift, the geometry moved 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 draws 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.

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

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