@marver-design/marver 0.2.0 → 0.2.2

package/templates/instructions/brand.md

@@ -0,0 +1,60 @@
+# Brand - extract it, or create it deliberately
+
+Every high-fidelity frame renders inside a visual world. This phase makes that world
+explicit. Never skip it silently: hi-fi work without a settled brand converges on the
+same generic AI look every model produces.
+
+## Path A - the repo has a brand: extract it
+
+If the app has real screens, tokens, or a theme, the brand already exists. Document
+it, never reinvent it:
+
+1. Read the theme CSS, tokens, tailwind config, and 2-3 representative components.
+2. Write `design/DESIGN.md` (10-20 lines): grounds and surfaces, accent
+   and its meaning, type faces and scale, radius language, shadow/border policy,
+   voice of the copy. Cite the token file as the source of truth.
+3. Frames then consume the app's real tokens. Hand-typed hex values in a frame are a
+   defect - if a value is missing, it is a token to propose, not a literal to inline.
+
+## Path B - no brand exists: create one, deliberately
+
+For a whole new surface or site, read instructions/reference/concepts.md FIRST - it
+owns the discipline of deriving distinctive directions (naming the category rut,
+candidates from the audience's world, full commitment). This section covers the
+token-level work once a direction exists.
+
+1. **Name the world first.** The product's mechanism in one sentence; the audience's
+   cultural home; three adjectives the interface should earn. Write these down before
+   touching a color.
+2. **Derive, don't default.** From the audience's actual world (its objects, notation,
+   publications, screen traditions), propose 2-3 distinct directions as one frame each -
+   same content, different world. Each direction commits fully: its own palette, type
+   pairing, radius/material language. Half-committed directions are unjudgeable.
+3. **The forbidden defaults.** These are what every unguided model produces; reaching
+   for one when the brief didn't ask means you were not deciding:
+   - warm cream ground + serif display + terracotta accent; oversized ITALIC serif
+     as the hero voice
+   - near-black + lone neon/acid accent, cyan-on-dark, purple-to-blue gradient heroes,
+     dark mode made of colored glows
+   - glassmorphism as decoration, gradient text, Inter/Geist/Space Grotesk as the
+     "safe" pick
+   - emoji as icons, `rounded-lg` on everything, everything centered
+   (the complete tell catalog: reference/slop.md)
+4. **Settle it into tokens.** The winning direction becomes CSS custom properties in
+   the theme (grounds, text tiers, accent + meaning, radius scale, spacing scale, two
+   type roles minimum). Then write DESIGN.md as in Path A. Components consume tokens;
+   nothing hand-types values.
+
+## Rules for CREATED brands (Path B)
+
+Path A documents the shipped system as it is - a mature brand with three accents or
+four faces gets described, never trimmed to fit these defaults. When CREATING:
+
+- **One accent carries the brand.** Semantic colors (success/warning/danger) are not
+  accents and never decorate.
+- **The accent has a meaning** (action, selection, live state) - write it down and
+  spend it only there.
+- **Both themes or one, decided.** Light + dark as token sets, or a deliberate
+  single-theme commitment recorded in DESIGN.md. Never an accidental single theme.
+- **Type is two faces** (display + body; mono only when the content is code, data,
+  or measurement). A third face is a decision Path B does not make alone.

package/templates/instructions/components.md

@@ -0,0 +1,52 @@
+# Components - engineering rules for promotable design
+
+Frames become the app (see AGENTS.md's promotion section). These rules make that
+promotion mechanical instead of a rewrite.
+
+## Structure
+
+- **Composition over configuration.** A component takes children and a few props;
+  it does not take a `variant` prop that swaps its entire body. When two variants
+  share less than half their markup, they are two components.
+- **Variants are props, never forks.** `<Button intent="danger">`, not
+  `DangerButton.tsx` copied from `Button.tsx`. A fork's fixes never propagate.
+- **Presentational only.** Props in, JSX out. No stores, no network, no auth, no
+  router imports inside anything that lives in `design/` (the AGENTS.md law) - and
+  keep it true after promotion: containers own data, components own pixels.
+- **Fixture shapes match PROP shapes, not API shapes.** `_fixtures.ts` exports typed
+  objects the component accepts directly, so tsc catches drift. Mapping backend
+  responses into those props is the container's job at promotion time - never bend a
+  component's props toward an endpoint.
+
+## Accessibility baseline (non-negotiable)
+
+- Interactive = a real `<button>`, `<a>`, or input - never a div with onClick.
+- Every input has a label; every icon-only button has an aria-label.
+- Focus-visible styling exists and comes from the palette.
+- Keyboard order follows reading order; Escape closes what Enter opened.
+
+## States are part of the component, not the page
+
+Every component ships knowing the states that APPLY to it: an input has error and
+disabled; a list has loading and empty; a divider has neither. Screens own the
+orchestration states (page-level loading, empty, failure - see
+reference/states.md). Pages compose component states; they never invent them per-use.
+
+## The gallery is the contract
+
+Each shared component gets `design/components/<name>/variants.tsx`: every variant ×
+every state, labeled, in one frame. The gallery is the review surface, the regression
+canary, and the documentation. A component change without a gallery update is
+incomplete work.
+
+## Maintain - pay down drift before it solidifies
+
+When the same ad-hoc pattern (a value, a markup shape, a style cluster) appears a
+third time, that is the promotion trigger: extract it into a token or shared
+component and update design/DESIGN.md in the same pass. Drift left in place becomes
+the system; three identical one-offs are a primitive announcing itself.
+
+## Naming
+
+Name by role, not appearance: `PriceCard`, not `BlueBox`. Appearance changes;
+the role is the API.

package/templates/instructions/configure.md

@@ -0,0 +1,44 @@
+# Configure - reach the idle state, once per repo
+
+The idle state is marver fully wired into THIS repo: frames render with the app's
+real theme, the app's components import cleanly, and the brand is documented. Every
+design session assumes it. Verify it on your first session in a repo, or whenever
+frames render suspiciously unstyled - then never think about it again.
+
+## The idle-state checklist
+
+1. **Theme wired**: `design/theme.css` exists and imports the app's real stylesheet.
+   Proof: the demo/existing frames render styled on the canvas, not as bare HTML.
+2. **Components importable**: the import alias in AGENTS.md's UI line actually
+   resolves (open one app component from a frame and render it).
+3. **Brand documented**: `design/DESIGN.md` exists and matches the
+   app's tokens (see brand.md Path A). Without it, every hi-fi session re-derives
+   the brand and drifts.
+4. **Manifest honest**: `design/manifest.json` lists what is really on disk.
+
+All four true → idle state. Go design.
+
+## By repo maturity
+
+- **Brand-new repo (no app)**: `design/instructions/setup.md` exists and is the
+  authority - STOP, follow it (set up the stack, re-run init). Do not design against
+  a repo that has nothing to build from.
+- **Fresh repo (app scaffolded, little product code)**: init's detection is usually
+  right. Verify the checklist, create DESIGN.md from the starter tokens (Path A -
+  even a default shadcn theme is a documentable brand), and note in it which parts
+  are placeholder so Brand can revisit deliberately.
+- **Old repo (mature app)**: detection may have picked the wrong stylesheet or missed
+  the real component library. Read the app's entry point and layout to find the TRUE
+  theme entry; fix `design/theme.css`'s import if init guessed wrong. Map the real
+  component library (where do buttons actually live?) and correct AGENTS.md's UI
+  line if needed (delete its marker line first to take ownership, or ask the human
+  to re-run `npx marver init` after fixing `components.json`). Old repos often have
+  several half-brands - document the one the app actually ships in DESIGN.md and
+  name the others as legacy.
+
+## When it breaks mid-project
+
+Frames suddenly unstyled → the theme import path moved: fix `design/theme.css`.
+New app components not resolving → the alias changed: fix the frame imports and tell
+the human AGENTS.md's UI line is stale. Never work around a broken idle state with
+hand-rolled CSS - that is how throwaway styling metastasizes.

package/templates/instructions/craft.md

@@ -0,0 +1,90 @@
+# Craft - the quality floor for high-fidelity frames
+
+Binding rules for every hi-fi frame. Read them before Build, then apply them silently -
+never announce a checklist. The brief and the settled brand (DESIGN.md) override
+anything here; your own habits never do.
+
+## When you are stuck, or the human is unhappy: the reference shelf
+
+This file is the floor. Depth lives in instructions/reference/ - pull the ONE file
+that owns the problem, when the problem appears:
+
+| Symptom / task | Read |
+|---|---|
+| hierarchy unclear, spacing monotone, "layout feels off" | reference/layout.md |
+| type roles blur, reading uncomfortable, scale arbitrary | reference/typography.md |
+| palette aimless, contrast failing, dark mode wrong | reference/color.md |
+| adding any animation, or motion feels cheap | reference/motion.md |
+| labels/errors/empty-state text | reference/copy.md |
+| human says "bland" / "too much" / "too busy" | reference/tune.md |
+| loading/empty/error coverage, stress inputs, first-run | reference/states.md |
+| dense app UI, dashboards, settings, tables | reference/operate.md |
+| a personality moment, celebration, easter egg | reference/delight.md |
+| brand-new surface or visual world (with brand.md) | reference/concepts.md |
+| a full review pass was requested | reference/critique.md |
+| output feels generic; sweeping for AI tells | reference/slop.md |
+
+These rules target content surfaces (marketing, docs, product pages). Dense Operate
+UI (dashboards, editors, admin) follows its platform's conventions where they
+conflict - a data table is allowed to be tight, and DESIGN.md's decisions always win.
+
+## Verify - checks against the RENDERED frame, never against intentions
+
+- **Contrast**: body and placeholder text ≥ 4.5:1, large text ≥ 3:1. Secondary text
+  on a colored surface takes its tint from that surface's hue - plain gray on color
+  reads broken.
+- **Spacing rhythm**: elements inside a group sit close; groups sit far apart; a
+  heading holds more air above it than below. All gaps come from the spacing scale.
+- **Type**: prose columns in the 45-75ch range (65-75 ideal for long-form); each level of hierarchy differs in BOTH size and
+  weight; letter-spacing never tighter than -0.04em; headings get `text-wrap:
+  balance`; render the real copy at every device width and fix whatever overflows.
+- **Depth**: pick borders or shadows per element, never stack both on one card. A
+  real shadow has offset and blur; an unblurred colored ring around an element is
+  ornament pretending to be elevation.
+- **States**: hover, focus-visible, disabled, loading, error, empty. A control
+  missing its states is an illustration of a control.
+- **Copy**: buttons say what they do ("Publish", not "Submit"); error text says what
+  went wrong and how to recover; everything in the product's own vocabulary.
+- **Browser-owned surfaces**: selection color, caret, focus rings, scrollbars, and
+  the numerals in data tables (`font-variant-numeric: tabular-nums`) all default to
+  browser styling that belongs to no brand. Claiming them is cheap and reads as care;
+  skipping them is the fastest giveaway of unconsidered work.
+- **Motion**: one deliberate, well-placed moment beats an effect on everything.
+  Ease-out, starting from a visible state; never the identical fade-in stamped on
+  each section; honor `prefers-reduced-motion`.
+
+## Refuse - the defaults every unguided model reaches for
+
+A brief can explicitly ask for any of these. Reaching for one unprompted means no
+decision was made - rewrite the element rather than toning it down. This is the
+short list; the COMPLETE catalog of generated-UI tells is reference/slop.md - sweep
+it on review passes.
+
+- Uniform icon+heading+paragraph card grids as the whole page structure; a card
+  inside a card (no exceptions); the oversized-number-with-tiny-label stat hero.
+- Little uppercase labels riding above every heading; numbered section markers
+  (01/02/03) when the order carries no information.
+- Gradient-filled text; blur/glass on elements that aren't overlaying anything;
+  thick colored left-border stripes on cards and alerts; chunky offset block shadows
+  in a design that isn't committed to that style throughout.
+- Monospace to signal "technical" - mono earns its place only under code, data, or
+  measurement.
+- Emoji or unicode symbols as icons - icons come drawn, from the app's icon set, in
+  one consistent stroke weight.
+- Centering everything; the same border-radius on every element; pill shapes on
+  large containers (pills belong to small controls).
+- Choosing light or dark by product category reflex - the use scene decides, or
+  DESIGN.md already did.
+
+## Frame law
+
+- Frames are made of the app's real components and tokens. Rebuilding a lookalike of
+  an existing component inside a frame is a defect.
+- Repeated and semantic values (colors, type sizes, radii, the spacing rhythm)
+  resolve to tokens; a missing one is a proposal to raise with the human, not a
+  literal quietly inlined. One-off layout geometry (a grid ratio, a max-width, an
+  SVG coordinate) may stay local - the test is "would a second use want this value".
+- Declare `meta.viewport` for the target width, then check the neighbors - the human
+  WILL sweep devices with keys 1-5.
+- Live fully inside the settled visual world. A direction executed at full commitment
+  can be judged and improved; a hedged one can only be redone.

package/templates/instructions/discover.md

@@ -0,0 +1,52 @@
+# Discover - understand before you draw
+
+Run this phase for any NEW surface, feature, or project. Skip it only when a brief
+already answers everything below. Its output is a written brief; nothing gets designed
+until the brief has a human nod.
+
+## 1. Read the repo, then interview
+
+First inspect what exists: the app's screens, components, theme, copy, and any brief
+or README - questions the repo answers are never asked. THEN ask at most five
+questions, in one message; never CSS values or aesthetic lanes. Ask what changes the
+work:
+
+1. **Who** must this serve, and in what scene (device, ambient light, attention level)?
+2. **The one job**: what should a visitor be able to decide, complete, understand, or
+   feel? (One job. If you get three, ask which one wins.)
+3. **The core flow**: entry → the moment of value → done. What are the 3-6 screens?
+4. **What exists**: real content, brand assets, an app, competitors they respect,
+   any screenshots or sites they LOVE? (A visual reference beats a paragraph of
+   description - ask for one when the direction matters.)
+5. **Out of scope**: what must NOT be touched or built?
+
+## 2. Pick the mode - it drives every later decision
+
+Name the surface's mode in the brief. The mode is the visitor's success:
+
+- **Persuade** - the visitor decides and acts (landing, pricing, campaign). The offer
+  and the action must be legible in the first viewport.
+- **Operate** - the visitor completes a task (app UI, dashboard, settings). Scanability
+  and native expectations outrank expression.
+- **Read** - the visitor understands (docs, guides). Structure for comprehension.
+- **Experience** - the visitor is inside the work (portfolio, gallery). The artifact
+  leads; the interface recedes.
+
+A tool's landing page is Persuade. A fashion house's docs are Read. The mode belongs
+to the SURFACE, not the product.
+
+## 3. Write the brief
+
+Create `design/scenes/<scene>/_brief.md`: audience + scene, the one job, mode, the
+flow as a numbered list, content sources, out-of-scope. Ten lines, not a document.
+Show it. Get the nod.
+
+## 4. Align on flow with a diagram frame
+
+When the flow has branches or more than four screens, draw it before wireframing:
+one frame (`<scene>/flow.tsx`) of labeled boxes and arrows - plain divs and SVG lines,
+grayscale, no dependency. Each box names a future frame. The human can look at one
+picture and say "step 3 is wrong" before step 3 costs anything.
+
+Then move to Wireframe. Do not brand, do not pick type, do not open the craft rules
+yet - those phases come after the flow and words are agreed.

package/templates/instructions/reference/color.md

@@ -0,0 +1,53 @@
+# Color - roles, meaning, atmosphere
+
+Color encodes hierarchy, action, and state before it decorates. Preserve confirmed
+brand commitments; a new identity is a Brand decision, not a colorize pass.
+
+## Build roles, not a bag of swatches
+
+Every palette answers to this role list; a color without a role has no reason to exist:
+
+- canvas + elevated surfaces (a SECOND neutral layer for sidebars/toolbars/panels,
+  slightly warmer or cooler than the content surface, gives product UI depth for free)
+- primary + secondary text tiers
+- action, focus, selection (usually one accent - rarity is what gives it force)
+- borders and separators
+- success / warning / error / info (semantic, stable meanings, never decorative)
+- data categories or scales when the content needs them
+
+## Strategy rules
+
+- Let the strongest color OWN a deliberate region or role; scattering tiny accents
+  reads as indecision. Name the dosage before editing: restrained or immersive is a
+  choice, not a percentage rule.
+- Never spend the primary action's color on decoration - it must stay the easiest
+  thing to find.
+- On a colored surface, secondary text derives from that surface's hue or the
+  foreground - generic gray on color always reads broken.
+- Tinted neutrals (warm or cool grays) add depth without loudness; pure gray is
+  valid only when the world calls for it.
+- Prefer OKLCH for new palettes: lightness and chroma adjust predictably. When
+  building ramps, vary lightness and REDUCE chroma near white and black.
+- Dark mode is COMPOSED, never mechanically inverted: design surface elevation and
+  contrast explicitly per theme.
+- Prefer explicit colors over stacked translucent overlays when alpha would make
+  contrast context-dependent.
+
+## Contrast (verify computed pairs, not intentions)
+
+| Content | Minimum |
+|---|---|
+| body text | 4.5:1 |
+| large text | 3:1 |
+| meaningful controls, icons, focus indicators | 3:1 |
+
+Disabled controls are exempt from contrast minimums (but should still read as
+present). Focus indicators need contrast AND a clearly visible change of appearance.
+Check interactive states, text over images, and BOTH themes.
+Anything conveyed by color alone also needs text, shape, icon, or position.
+
+## Verify
+
+Every color has a stable role; attention lands on the intended action; the palette
+holds across quiet, dense, error, and empty states; both themes are composed; the
+result is recognizably THIS product, not a generic colorful treatment.

package/templates/instructions/reference/concepts.md

@@ -0,0 +1,68 @@
+# Concepts - deriving a distinctive direction for brand-new work
+
+For a genuinely new surface or a new visual world (brand.md Path B routes here for
+whole pages/sites). The enemy is the RUT: every product category has the page it
+always ships, and an unguided pass lands in it. This discipline exists to keep
+successive attempts from converging on the category default.
+
+## 1. Ground it
+
+Name in writing: the product's unique mechanism in one sentence; the audience's real
+scene; the product's cultural home; what this first surface must prove. Then name
+the RUT explicitly - the page this category always ships and its predictable
+opposite - and keep both off the candidate list.
+
+## 2. Derive candidates from the audience's world
+
+List 5-7 concrete visual systems, artifacts, places, or rituals the audience knows
+by heart, each with one line on why it resonates and how it can carry the product's
+mechanism. The audience's world includes its SCREEN traditions, not just objects:
+the notation, publications, identity programs, data graphics, and interfaces it
+reads daily. Ask: what would this product look like as a physical object? What did
+its world look like before the web?
+
+Discipline checks:
+
+- Near-duplicates count once.
+- When more than three candidates share one material family, the derivation stopped
+  at the subject's most obvious artifact - dig until the list spans at least three
+  families.
+- A brief that paints its own picture (a name, a metaphor) gets AT MOST one
+  candidate for its literal reading; derive the rest from elsewhere.
+
+## 3. Commit and present
+
+Turn the strongest 2-3 into complete directions: each joins a reusable visual world
+to a concrete first-surface experience. Build each as ONE fully-committed frame -
+same content, different world; a hedged direction cannot be judged. Present with:
+its thesis, first viewport, signature interaction, and one honest risk each.
+
+Alongside them (not among the derived candidates - the rut exclusion in step 1
+applies to derivation, not to this), include the CATEGORY STANDARD as a quiet
+standing option, played straight: familiar and effective is a legitimate destination,
+and the human deciding that trade is the point. Present it honestly, never let it
+soften the committed directions, and when the human picks it, execute it at full
+craft without smuggled quirk.
+
+## 4. Every candidate must already be viable
+
+True claims only (prices, customers, capabilities come from supplied facts -
+illustrative material is labeled synthetic); a real palette and component family;
+workable at full-surface scale. A candidate that fails on truth is replaced before
+presenting, never rescued by enthusiasm. Refusing a bold direction because its demo
+data does not exist yet is timidity wearing honesty's clothes - author the
+illustrative material and label it.
+
+## The voice rule
+
+Loud or restrained - never neutral. Restraint is a committed direction with a point
+of view; neutrality is the absence of one, and it is what unguided generation
+produces by default. If the chosen direction cannot be described in three specific
+adjectives, it is neutral.
+
+## Modes bind the winner
+
+Persuade: the offer and action legible in the first viewport, however committed the
+form. Operate: expression never obscures task, state, or familiar affordance.
+Read: comprehension and wayfinding stay intact. Experience: the work leads, the
+interface recedes.

package/templates/instructions/reference/copy.md

@@ -0,0 +1,57 @@
+# Copy - interface language that works
+
+Read the whole interaction path, never isolated strings. For each state, decide the
+message hierarchy before writing: (1) the ONE fact the user needs now, (2) the action
+available next, (3) context that changes the decision, (4) the tone this moment
+earns. Say each idea once - a heading that explains the state makes the intro under
+it redundant.
+
+## By function
+
+**Actions.** Consequential actions get a specific verb + object ("Publish post",
+not "Submit"); labels describe what WILL HAPPEN, not the gesture. Navigation names
+its DESTINATION ("Settings", not "View Settings"). Same noun and verb for the same
+concept everywhere - interfaces never vary words for literary effect. Destructive
+actions name the object and the consequence; prefer undo over confirmation when
+recovery is safe; when confirming, the button repeats the action ("Delete board"),
+never "Yes"/"OK".
+
+**Forms.** Persistent labels - placeholders are examples, never labels. Format and
+eligibility requirements BEFORE submission, next to the field. Validation says what
+needs attention and how to fix it, without blaming. Required/optional treatment is
+consistent across the product.
+
+**Errors.** An actionable error answers: what failed; why, when known AND useful;
+how to recover or what alternative remains. No internal codes as the headline. Never
+promise a cause the system cannot know. Privacy, payment, deletion, and blocked work
+get gravity - warmth is welcome, jokes are not.
+
+**Loading / empty / success.** Loading names the real operation; never invent
+progress. Empty states are five DIFFERENT states - first use, cleared, no results,
+no permission, failed to load - each with its own explanation and next action.
+Success confirms the outcome; mention the next consequence only when it changes what
+the user should do; routine success stays brief.
+
+**Help.** Helper text answers an implicit question, never restates the control.
+Link text makes sense out of context. Icon-only controls carry accessible names.
+
+## Cadence tells (generated-copy tics to sweep)
+
+Em dashes sprinkled through body copy; manufactured-contrast aphorisms closing
+sections ("It's not X. It's Y."); dismissing things as "theater"; generic SaaS
+buzzwords ("supercharge", "seamless", "unlock"); the same label repeated in several
+slots of one card. Plain sentences in the product's own vocabulary beat all of these.
+
+## Voice and resilience
+
+Voice stays constant; tone adapts to the moment's stakes. Plain language without
+flattening terminology the audience genuinely knows. Complete translatable sentences,
+never concatenated fragments. Allow for text expansion instead of pre-abbreviating.
+Alt text conveys the image's information (empty alt for decoration).
+
+## Verify
+
+Read the flow aloud in context: comprehensible without insider knowledge; actionable
+at every error and empty state; terminology consistent; survives long names and 200%
+zoom; tone proportional to consequence. The final copy is as short as it can be
+without losing meaning or recovery.

package/templates/instructions/reference/critique.md

@@ -0,0 +1,53 @@
+# Critique - the structured review pass
+
+For a real review (the human asked "review this", or you are gating your own work
+before a milestone). Think like a design director: the deliverable is a written
+critique, not a pile of nitpicks.
+
+## Start with the specificity verdict
+
+Before anything else, answer: **could a neighboring product use this design
+unchanged?** Cover coherence, structural sameness, category-interchangeable choices,
+and missed opportunities for product character. This is the single most predictive
+question for AI-generated design - answer it before any checklist can anchor you.
+
+## Score the ten heuristics (0-4 each)
+
+| # | Heuristic | Asks |
+|---|---|---|
+| 1 | Visibility of system status | does the UI always show what is happening? |
+| 2 | Match to the real world | user's language and concepts, not the system's? |
+| 3 | User control and freedom | undo, escape hatches, no traps? |
+| 4 | Consistency and standards | same thing looks and acts the same everywhere? |
+| 5 | Error prevention | dangerous actions guarded before, not apologized after? |
+| 6 | Recognition over recall | options visible, nothing memorized between screens? |
+| 7 | Flexibility and efficiency | shortcuts for the fluent, defaults for the new? |
+| 8 | Aesthetic and minimalist | every element earns its place? |
+| 9 | Error recovery | errors named plainly with a way out? |
+| 10 | Help and documentation | help where it is needed, when it is needed? |
+
+Be honest: 4 means genuinely excellent and should be rare - an all-4 row means the
+review did not look hard enough, not that the interface is perfect.
+Mark a heuristic n/a with a one-line reason when it truly cannot apply (7 and 10
+often on marketing surfaces) and renormalize the total to the applicable maximum.
+
+## Two more lenses
+
+- **Cognitive load**: flag decision points where options compete undifferentiated
+  (no default, no grouping, no visible consequence - a labeled menu of twelve is
+  fine; four equal-weight buttons with vague labels are not), and any screen where
+  the user must remember something from a previous screen.
+- **Emotional journey**: peak-end rule - what is the peak moment and what is the
+  exit moment? Reassurance present at high-stakes points (payment, deletion, send)?
+
+## Report format
+
+1. Specificity verdict (one paragraph, first).
+2. Heuristic table with per-row key issue.
+3. **What works** - 2-3 things, specific about WHY they work.
+4. **Priority issues** - 3-5, ordered, each tagged P0 (blocks/misleads) to P3 (nit),
+   with: what, why it matters, and a concrete fix.
+5. One provocative question the team should sit with.
+
+Never bury the diagnosis: if the concept itself is wrong, the report says so at the
+top and recommends re-entering Wireframe - a P0 concept issue outranks every P2 list.

package/templates/instructions/reference/delight.md

@@ -0,0 +1,35 @@
+# Delight - personality that earns its place
+
+Delight is product character revealed at a moment that deserves it - never a layer
+of generic whimsy. One thesis per surface: state in a sentence what the user should
+feel and why that feeling belongs to THIS product. Then build the smallest system
+that delivers it.
+
+## Where delight is earned
+
+- **Effort worth acknowledging**: completion of something hard. Match the response
+  to the consequence - milestones may expand; routine saves simply feel certain.
+- **Waiting that can inform**: truthful progress with product-specific texture.
+  Never fake work or delay completion to stage a flourish.
+- **First use and empty states**: orient first, charm second. The next action must
+  be clear before personality is added.
+- **Errors and recovery**: warmth reduces stress; jokes must never trivialize loss,
+  money, privacy, or blocked work.
+- **Discovery**: reward curiosity with real utility, never hide required
+  functionality behind an easter egg.
+- **Repetition test**: will the hundredth encounter still satisfy? Charm that decays
+  into friction was mis-scoped.
+
+## The specificity bar
+
+The moment must be specific enough that a neighboring product could not use it
+unchanged. Derive the treatment from the product's own mechanism and world - a
+confetti burst is a stock part; the way THIS product acknowledges completion is a
+design decision.
+
+## Protections (absolute)
+
+Delight never: delays or blocks the primary task; overrides platform conventions or
+accessibility; plays sound without consent; becomes mandatory or unskippable; adds a
+dependency disproportionate to the moment. The interface must remain fast and
+obvious with the flourish removed.

package/templates/instructions/reference/layout.md

@@ -0,0 +1,51 @@
+# Layout - reading order, grouping, rhythm
+
+Layout turns product priority into reading order. Diagnose the structural problem
+before moving boxes.
+
+## Diagnose first (against the rendered frame)
+
+- **The squint test.** Blur your mental image of the frame: can you still identify
+  the primary element, the secondary element, and the major groups in order? If not,
+  the hierarchy fails regardless of how the details look.
+- **Grouping.** Are related items CLOSE and distinct groups SEPARATED - or are
+  containers and borders compensating for weak proximity? Proximity is the primary
+  grouping tool; boxes are the fallback.
+- **Rhythm.** Do tight and generous intervals alternate deliberately, or is one
+  spacing value repeated until everything has equal weight? Monotone spacing is the
+  most common layout defect in generated UI.
+- **Structure.** Does the topology match the content, or is it a framework default?
+  Repeated same-size cards imply the items are equivalent - are they?
+- **Density.** Information per region should match use frequency and decision
+  complexity, not a universal airiness.
+- **Extremes.** Long content, empty states, overlays, sticky elements - do they
+  break the structure?
+
+## Set a spatial thesis before editing
+
+Name in one or two sentences: the primary reading/task path; what belongs together
+and what must separate; which element leads; the intended density. Then pick the
+simplest structural model that expresses those relationships.
+
+## Apply
+
+- Group by meaning with proximity BEFORE adding containers or decoration.
+- Create rhythm through deliberate contrast: tight inside groups, generous between
+  them, more space above a heading than below it.
+- Use a documented spacing scale; a 4px base gives useful middle steps an 8-only
+  scale misses. One-off gap values are how rhythm dies.
+- Hierarchy follows product priority, not framework defaults - the most important
+  thing is the most visually weighted thing.
+- `gap` on the parent beats per-child margins for sibling rhythm.
+- Responsive behavior is STRUCTURAL: reorder, collapse, reveal based on what remains
+  important at each width - not just shrinking everything. Feature amputation is not
+  responsive design: every capability stays reachable at every supported width.
+- Depth (shadow/elevation) only where it clarifies state or hierarchy.
+- Repetition supports recognition; break it only when content or priority changes.
+  Variation for its own sake reads as noise.
+
+## Verify
+
+Squint test passes; the task path is clear at every supported width; related content
+groups without boxes; tight/generous rhythm is visible; long text and empty states
+hold; DOM order agrees with visual order.