page-foundry 2.9.1 → 3.2.0

package/skills/page-foundry/references/conversion-rules.md

@@ -42,11 +42,11 @@ Score each factor 1 to 5:
 - **F, friction (weight 2, subtracted from I).** Form length, page length mismatched to decision weight, confusing navigation, slow load.
 - **A, anxiety (weight 2, negative).** Unanswered risk at the moment of action: price surprise, data concerns, "what happens after I click", missing refund terms. Risk reversal and proof near the CTA reduce A.
 
-Record the per-factor scores and the computed C in the gate report. There is no absolute pass threshold; the value is in the diagnosis. Flag direction differs by factor: M, V, and I flag at 1 or 2 (low is bad); F and A flag at 4 or 5 (high is bad). Any flagged factor must be addressed or explicitly accepted by the user before ship.
+Record the per-factor scores and the computed C in the gate report. The composite C has no absolute pass threshold; the value is in the diagnosis. But the per-factor scores do have floors, because some flags are too severe to accept: a severe flag in the independent score (M, V, or I at 1, or F or A at 5) is a Gate 1 FAIL and blocks ship until the page is fixed. Flag direction differs by factor: M, V, and I flag at 1 or 2 (low is bad); F and A flag at 4 or 5 (high is bad). A lesser flag (M/V/I at 2, F/A at 4) may be addressed or explicitly accepted, but acceptance is the user's call in chat, never the builder's own; the fresh-context re-score exists precisely so the page is not graded by the person who wrote it.
 
 ## Pricing psychology
 
-For archetypes with a pricing block (saas-homepage, course-sales, membership-community, and campaign-landing offers), apply these levers, honestly:
+For archetypes with a pricing block (saas-homepage, course-sales, membership-community, campaign-landing offers, docs-dev-tool-landing, paid event-webinar tickets, ecommerce-product at the buy box, and pricing-page, where the whole page is the block), apply the levers that fit the block's shape, honestly (a single-product buy box has no tiers to guide, but anchoring, framing, and price endings still apply):
 
 - **Anchor before the ask.** Show the higher tier or the cost-of-the-problem first, so the target price reads as reasonable against it.
 - **Three tiers, guide the choice.** Good-better-best with the recommended tier visually marked reduces choice paralysis; a genuinely weaker decoy tier steers toward the target. The tiers must be real.

package/skills/page-foundry/references/design-direction.md

@@ -1,10 +1,10 @@
 # Design Direction
 
-The design phase has one job: make a page that could only belong to this property. Mechanics of the design process live in the frontend-design skill when installed (token plan, critique against the generic default, one signature element, restraint everywhere else); this file adds the marketing-page-specific and property-specific layer on top. Trend references are directional and dated 2026-07; re-check the design landscape if this file is more than a year old.
+The design phase has one job: make a page that could only belong to this property. Mechanics of the design process live in the frontend-design skill when installed (token plan, critique against the generic default, one signature element, restraint everywhere else); this file adds the marketing-page-specific and property-specific layer on top, plus the craft rules absorbed from impeccable's reference set so the craft floor holds whether or not that companion is installed. Trend references are directional and dated 2026-07; re-check them against what is currently shipping if this file is more than a year old.
 
 ## One property, one theme
 
-Each property (each product, each brand under the holding company) gets exactly one token set: 4 to 6 named palette colors, a display/body type pairing, spacing scale, radius and border conventions, and the signature element. Persist it as `theme.css` with custom properties; use theme-factory when installed to generate or apply a cohesive palette and type pairing, but `theme.css` is the durable per-property token store (theme-factory is a theming toolkit for artifacts, not a persistence layer). Every subsequent page for that property reuses the tokens unchanged. Distinctiveness between properties, consistency within one.
+Each property (each product, each brand under the holding company) gets exactly one token set: 4 to 6 named palette colors, a display/body type pairing, spacing scale, a layout grid (container max-widths, column count, gutters per breakpoint), radius and border conventions, and the signature element. Persist it as `theme.css` with custom properties; that file is the durable per-property token store. Every subsequent page for that property reuses the tokens unchanged. Distinctiveness between properties, consistency within one.
 
 ## Choosing a direction
 
@@ -30,19 +30,64 @@ Reject these defaults regardless of direction (this extends the frontend-design
 - Emoji as section markers.
 - AI-generated hero imagery that depicts nothing real about the product. Real screenshots, real terminal output, real diagrams, real photography only.
 - Any staged reconstruction of the product in use: a hand-built terminal, a mocked screenshot, or a console showing output that was not actually produced, or that shows an action the user never takes (an internal script the pipeline runs, not the user). This is a fabrication even when it looks real and the underlying command exists; it fails the integrity gate. Show a real artifact of real use (the actual page it built, a real screenshot of a real property, the output the user actually receives), or describe the thing in words. Real data in a clearly-labeled card (a real gate report) is fine; a reenactment is not.
+- When the request is "bolder" or "more impact": cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics, and scroll-fade-rise reveals on every section are the saturated AI defaults for impact, and they are the opposite of bold. Reject them first, then raise impact by making the committed design language more decisive: amplify hierarchy contrast, proportion, and density inside the existing tokens rather than adding effects. (impeccable: `bolder.md`)
+
+## Craft rules
+
+Absorbed from impeccable's craft references (pinned pbakaus/impeccable; constants spot-checked against the reference files at version 3.9.1, clone `8967edc`, on 2026-07-18) so a run without that companion designs to the same floor; each rule names its source file. The deeper machinery, the deterministic detector, scored critique, and in-browser variants, stays invocation-only per the integration notes in SKILL.md.
+
+One tension is settled up front: impeccable's craft doctrine leans toward task-completion minimalism, few options, short paths, every element earning its pixel. Conversion pages repeat CTAs and run long by design; the compiled contract and the conversion rules set structure and length, and MECLABS scoring arbitrates them. The rules here govern execution quality inside that structure, never the structure itself; Nielsen-style usability readings (impeccable `critique`) are advisory on conversion pages.
+
+### Space and composition
+
+- Every spacing value comes from a 4pt base scale (4, 8, 12, 16, 24, 32, 48, 64, 96px), and rhythm comes from contrast: 8 to 12px between related siblings, 48 to 96px between sections. Monotone equal spacing is itself a defect; it encodes no hierarchy. (impeccable: `layout.md`)
+- One focal point per section. Pick the one thing the visitor should remember there and make everything else support it; if every element is louder, the composition is flatter, not bolder. (impeccable: `bolder.md`)
+- The squint test: with the page blurred, the primary element, the secondary, and the groupings must still be identifiable within 2 seconds. Apply it to the hero first, then section by section on the built page. (impeccable: `layout.md`)
+
+### Type
+
+- Five sizes cover the whole page, spaced on one committed ratio (1.25, 1.333, or 1.5); sibling sizes such as 14/15/16px read as muddy hierarchy, and the cure is fewer sizes with more contrast between them. Fluid `clamp()` belongs to headings and display text only, body stays fixed at 16px or larger, the clamp maximum stays at or under 2.5 times its minimum, and the measure holds 45 to 75ch at every viewport. (impeccable: `typeset.md`)
+
+### Color
+
+- Commit to a color strategy per property before styling anything: Restrained, Committed, Full palette, or Drenched. Dosage reads the 60-30-10 rule as visual weight, not pixel count, and accents work because they are rare; the chosen strategy, not habit, decides how far past a restrained dosage the page goes. (impeccable: `colorize.md`)
+- Brand-tinted neutrals: pure gray reads dead next to a colored brand, and the stock warm-cream tint (`oklch(97% 0.01 60)` and its neighbors) has become an AI tell in its own right. Neutrals carry 0.005 to 0.015 OKLCH chroma hued toward this property's brand color, and color scales are generated in OKLCH, holding hue steady while lightness varies and chroma eases near white and black. (impeccable: `colorize.md`)
+- Three micro-bans, absolute: no gray text on colored backgrounds (use a darker shade of the background color, or transparency); no colored `border-left` or `border-right` accent stripe wider than 1px (a hairline full border, a 4 to 8% background tint, or a leading glyph does the same job); no bounce or elastic easing anywhere. (impeccable: `colorize.md`, `polish.md`)
+
+### Motion
+
+- Durations by job: 100 to 150ms for feedback, 200 to 300ms for state changes, 300 to 500ms for layout changes, 500 to 800ms for entrances only, with exits at roughly 75% of the matching enter; sibling stagger is legitimate for real lists, capped near 500ms total (10 items at 50ms each). At most one earned scroll-triggered moment per page, chosen because it serves the message; fade-and-rise on every scrolled section is a tell, not a choreography. (impeccable: `animate.md`)
+
+### Brief discipline
+
+Two commitments that cost one short paragraph in the Phase 4 design direction and pay for themselves in every shape confirmation that follows, then again at the comp stage, whose critique judges the rendered comp against exactly these two artifacts.
+
+- A scene sentence plus named anchors. The scene sentence is one sentence of physical context for the page: who is reading it, where, under what ambient light, in what mood. **It is written from the ICP and entry state in the brief and `voc.md`, not invented: the reader it names is a specific segment (the solo founder at 2am after a failed launch, not "a user"), and the mood is the entry state that segment arrives in.** Name the segment it was drawn from in the sentence or the note beside it, so the derivation is checkable at Gate 5; a scene sentence that could describe any page for any buyer is not yet written. It forces the dark-versus-light call; if it does not, it needs more detail. Alongside it, 2 or 3 named anchor references: specific products, brands, objects, never adjectives like "modern" or "clean". (impeccable: `shape.md`)
+- Identity lock for existing properties: before restyling anything the property already ships, write one factual sentence of its current identity, actual hex values, actual font names, layout topology, copy tone, no aesthetic adjectives. Every candidate must read as the same brand next to the live page; departure is legitimate only when the brief asks for it. The persistent `theme.css` is this sentence in token form, so iterations start from it. (impeccable: `live.md`)
+
+## The grid and the breakpoints
+
+The spacing scale governs vertical rhythm; horizontal structure needs its own commitment, and a page built without one reads placed rather than arranged. Two artifacts close that gap. Both belong to the token plan, and Gate 5 verifies the built page against both.
+
+- **A layout grid spec.** Container max-widths, column count, and gutter width, stated per breakpoint, with gutters drawn from the 4pt scale. Every candidate token plan carries one; plans may legitimately differ on grid, since the density axis often forces it, but a plan that states palette and type while leaving the grid to the build is incomplete. The winning grid persists in `theme.css` as custom properties beside the palette (`--container-max`, `--grid-cols`, `--gutter`), so every later page on the property composes on the same grid, and it is the substance of the `## Layout` section when `DESIGN.md` is persisted.
+- **Per-breakpoint recomposition notes for the hero and the densest section.** Breakpoints are content-driven, set where the design breaks; these notes are where each named breakpoint gets designed rather than merely survived. For the hero and for the page's densest section (the spec's job order plus the confirmed shapes identify it), write one note per named breakpoint stating how the composition re-forms there: what re-stacks and in what order, which elements drop or collapse, how the hero visual crops, where the primary CTA lands. The notes are written after the shape confirmations, because density follows shape, and they land in the winning token plan file in `tokens/`.
+
+"Fully usable at 390px" is a floor. A recomposition note is a design decision, and the render gate checks that the decision was executed at the breakpoint it names, screenshotting that width when it falls between the standard pair. In handoff mode the external tool owns the grid within the manifest geometry (`references/handoff.md` grants it), so the spec and notes above apply to what this skill builds itself.
 
 ## Marketing-page specifics
 
 When web-design-guidelines is installed it is authoritative on the accessibility, typography, imagery, and interaction mechanics below; the items here are the marketing-page emphasis. When it is absent, these condensed mechanics apply.
 
 - The hero visual shows the product doing its job: actual UI, actual output, actual artifact. If the product is a service or community, show the real artifact of the work (a redacted report page, a session board, a member thread) rather than a metaphor.
+- Image-led pages get real or sourced imagery, never decorative CSS panels, emoji, or fabricated metrics standing in where an image belongs. Verify every image URL before referencing it, since a guessed photo id ships as a broken image; fewer images held with confidence beat many guessed. (impeccable: `craft.md`)
 - Design the 390px view first. Hero type must wrap gracefully (use `text-wrap: balance` on the headline to kill widows); the CTA must sit above the fold on a phone; respect `env(safe-area-inset-*)` so nothing hides under a notch, and set `touch-action: manipulation` on tap targets.
-- Every interactive element has a visible focus state (`:focus-visible` with a real ring, never `outline: none` without a replacement) and a hover state; interactive states increase contrast and never rely on color alone.
-- Images carry explicit `width`/`height` to hold layout (CLS), lazy-load below the fold, and set `fetchpriority="high"` on the hero image (LCP). This ties straight to the performance budget below.
+- Every interactive element has a visible focus state and a hover state: `:focus-visible` with a real ring, 2 to 3px, offset outside the element, at 3:1 contrast against what surrounds it, and never `outline: none` without a replacement. Nothing on the page is hover-only, since keyboard and touch users never see hover; tap targets reach 44px, with padding or a pseudo-element when the visual must stay smaller; interactive states increase contrast and never rely on color alone. (impeccable: `interaction-design.md`)
+- Images carry explicit `width`/`height` or `aspect-ratio` to hold layout (CLS), lazy-load below the fold and never above it, and set `fetchpriority="high"` on the hero image (LCP, under 2.5s). Web fonts load with `font-display: swap` and a metric-matched fallback (`size-adjust`/`ascent-override`), preloading only the critical weight. Breakpoints are content-driven, set where the design breaks rather than at device widths, and adaptation reads the `pointer` and `hover` media queries instead of inferring input from screen size. This ties straight to the performance budget below. (impeccable: `optimize.md`, `typeset.md`, `adapt.md`)
+- Copy blocks survive real content: test the headline and CTA labels at their long and short extremes, set `min-width: 0` on flex and grid children that hold text, never give a text container a fixed width, and keep 30 to 40% expansion headroom so a longer product name or a translation does not shear the layout. (impeccable: `harden.md`)
 - Respect `prefers-reduced-motion` with a static fallback. Animate only `transform` and `opacity`, never `transition: all`; keep animations interruptible and set an explicit `transform-origin`.
 - Contrast meets WCAG 2.2 AA (4.5:1 body, 3:1 large text and UI components) inside the chosen palette from the start, not patched after. Set `color-scheme` and a `theme-color` meta when the property has a dark identity.
 - Performance is a design constraint: the direction must be achievable in roughly under 200KB of CSS+JS and under 1MB total transfer for the page. If the vision needs more, change the vision.
 
 ---
 
-_Provenance: reconciled 2026-07-07 against frontend-design (Anthropic), web-design-guidelines (vercel-labs, live ruleset), and theme-factory (Anthropic). web-design-guidelines is authoritative on the a11y/typography/imagery/interaction mechanics when installed; the condensed mechanics here are the fallback. Re-reconcile when those companions change._
+_Provenance: reconciled 2026-07-07 against frontend-design (Anthropic), web-design-guidelines (vercel-labs, live ruleset), and theme-factory (Anthropic). Craft rules absorbed 2026-07-18 from impeccable (pbakaus/impeccable) at version 3.9.1, clone `8967edc`; every stamped constant was spot-checked against its named reference file at that version before copying. web-design-guidelines is authoritative on the a11y/typography/imagery/interaction mechanics when installed; the condensed mechanics here are the fallback. Re-reconcile when those companions change._

package/skills/page-foundry/references/handoff.md

@@ -1,41 +1,63 @@
-# Handoff Mode: Claude Design Package
+# Handoff Mode: The Design Package
 
-Handoff mode produces everything a design tool needs to build a 10/10 page, with the thinking, copy, and constraints already done. The primary target is Claude Design (Anthropic Labs); the package also works for any designer or design tool.
+Handoff mode produces everything a design tool needs to build a page that passes this skill's gates, with the thinking, copy, and constraints already done. The primary target is Claude Design (Anthropic Labs); the package also works for any designer or design tool.
 
-What matters about Claude Design for this package: it accepts plain text prompts, screenshots and image assets, DOCX/PPTX/XLSX documents, codebases, and web captures; it can build a persistent design system from brand sources (palette, type scale, components, layout patterns); it outputs deployable HTML/CSS/JS and can hand off to Claude Code; and it does NOT retain brand context across separate conversations, so the package must be fully self-contained and re-pasteable every session.
+The package's balance is deliberate, and it leans the opposite way from a normal creative brief. Where the tool excels (layout, art direction, motion, visual invention) the package grants explicit license instead of prescribing. Where the tool cannot know better, it over-specifies: the voice rules for text the tool will generate, the fabrication ban, asset geometry, the acceptance criteria, and the shape of what comes back. A tool handed a signature element as a mandate produces a worse page than one handed the same element as an anchor with license to beat it; a tool handed no voice rules writes microcopy that fails the post-build scan every time.
+
+What matters about Claude Design for this package: it accepts plain text prompts, screenshots and image assets, DOCX/PPTX/XLSX documents, codebases, and web captures; it can build a persistent design system from brand sources (palette, type scale, components, layout patterns); it outputs deployable HTML/CSS/JS and can hand off to Claude Code; and it does NOT retain brand context across separate conversations, so the package must be fully self-contained and re-pasteable every session, and every revision round re-sends it in full (the revision format in `06-return-spec.md` assumes exactly this).
 
 ## Package contents
 
-Write to `handoff/<product>/`:
+Write to `handoff/<product>/`. Each file is produced from a named run artifact; the package is a projection of the run directory, never new thinking.
 
 ```
 handoff/<product>/
-├── 00-master-prompt.md      The paste-ready prompt; references the other files
-├── 01-copy.md               Final copy, verbatim, in page order
-├── 02-page-spec.md          The Phase 2 spec (sections, claims, proof, CTAs)
-├── 03-design-direction.md   Tokens, direction, anti-slop list, asset manifest
-├── 04-acceptance-criteria.md Gates rewritten as testable acceptance criteria
-└── assets/                  Logos, screenshots, theme.css, reference captures
+├── 00-master-prompt.md       The paste-ready prompt: orientation, the five non-negotiables,
+│                             the creative license grant, the questions list
+├── 01-copy.md                Final voice-gated copy, verbatim, with image-slot geometry
+│                             (from copy/copy-approved.md)
+├── 02-page-spec.md           The compiled conversion contract and section spec
+│                             (from page-spec.md)
+├── 03-design-direction.md    Locked tokens, or propose-then-lock; signature element as
+│                             anchor; anti-slop list (from tokens/, theme.css, DESIGN.md)
+├── 04-acceptance-criteria.md Filled from the fixed template below; IDs map to gate IDs
+├── 05-voice-rules.md         Excerpt of references/voice.md; governs tool-generated text
+├── 06-return-spec.md         What comes back, and the revision-request format
+├── DESIGN.md                 The design system projected into the published design.md
+│                             format; generated from the files above, never hand-edited
+└── assets/                   theme.css, manifest.md (geometry), llms.txt, schema.jsonld,
+                              logos, screenshots, captures. Real artifacts only.
 ```
 
+Files `00` through `06` ship in every package, and so does the generated `DESIGN.md` (under propose-then-lock it carries no token values, and that absence is deliberate; the projection section below says why). A file with nothing run-specific to say for this product still ships and says why (a greenfield property's `03` opens with the propose-then-lock instruction instead of tokens); a missing file reads as an oversight, and the tool fills oversights with defaults.
+
 ### 00-master-prompt.md
 
 The single document pasted into Claude Design (attach the rest as files). Structure:
 
-1. One paragraph: product, audience, archetype, the page's single job.
-2. Instruction block, verbatim rules for the design tool:
-   - "The copy in 01-copy.md is final. Use it verbatim. Do not paraphrase, shorten, expand, or 'improve' any sentence. If a layout needs shorter text, flag it; do not rewrite."
-   - "Follow the section order in 02-page-spec.md exactly. Do not add, merge, or reorder sections."
-   - "Use the tokens in 03-design-direction.md (and attached theme.css if present) as the design system. Do not introduce new palette colors or typefaces."
-   - "Build to the acceptance criteria in 04-acceptance-criteria.md. Treat them as the definition of done."
-3. The signature element description and any motion notes from Phase 4.
-4. What to ask about instead of guessing (unresolved [TK] items, image slots without assets).
+1. One paragraph: product, audience, archetype, and the page's single job, taken from the compiled contract's goal block.
+2. The five non-negotiables, verbatim from below.
+3. The creative license grant, verbatim from below.
+4. The signature element candidate and any motion notes from Phase 4.
+5. Questions, not guesses: unresolved `[TK]` items, image or proof slots without assets, and anything else the tool would otherwise decide silently.
+
+**The five non-negotiables** (carry into `00` verbatim):
+
+1. **The copy is final.** The copy in `01-copy.md` is voice-gated and verbatim. Do not paraphrase, shorten, expand, or improve any sentence. If a layout needs shorter text, flag it in the return log; do not rewrite it. Any text you generate that is not in `01-copy.md` (navigation labels, form microcopy, error and empty states, button labels, alt text, aria-labels, footer lines) follows `05-voice-rules.md` and is scanned on return.
+2. **The section order is the conversion contract.** Build the content in the order `02-page-spec.md` gives, keeping each section's claim, proof element, and CTA treatment together as specified. Visual sectioning is yours: folding two adjacent sections into one band, or splitting one across a scroll sequence, is legitimate when the reading order and each claim-to-proof pairing survive. Adding content sections, dropping them, or reordering them is not.
+3. **The CTA policy binds.** Exactly one primary CTA action on the page; every repeat identical in wording and destination; every CTA instance with its proof element within one viewport, as the spec places them.
+4. **No fabricated proof, ever.** "Zero fabricated testimonials, logos, counts, or statistics" (this skill's integrity gate, verbatim). Concretely: do not add a logo strip, star rating, avatar row, testimonial, user count, or statistic that is not in the package. Proof lives in `01-copy.md` and `assets/` only. A proof slot the package leaves empty stays empty and goes in the return log as a question.
+5. **The acceptance criteria are the definition of done.** Meet every criterion in `04-acceptance-criteria.md`, by ID. The return log answers each ID: met, not met with a reason, or N/A as marked.
+
+**The creative license grant** (carry into `00` verbatim):
+
+You own layout, grid, visual rhythm, art direction, and imagery treatment within the geometry `assets/manifest.md` fixes; motion design within `prefers-reduced-motion` and the performance criteria; and the signature element: `03-design-direction.md` names a candidate as an anchor, and you may propose alternatives that serve the same claim more strongly, with a sentence on why. Where `03-design-direction.md` says propose-then-lock, the token system itself is in scope: propose 2 or 3, apply your recommendation consistently, and return it machine-readable.
 
-The verbatim-copy rule exists because the voice gate ran BEFORE handoff; any downstream paraphrase silently un-passes it. This is the most commonly violated instruction, so it goes first and is repeated next to the copy itself.
+The verbatim-copy rule exists because the voice gate ran BEFORE handoff; any downstream paraphrase silently un-passes it. It is the most commonly violated instruction, so it leads the non-negotiables and is repeated next to the copy itself.
 
 ### 01-copy.md
 
-Final copy in page order, one block per spec section, each labeled with the spec section number and the element roles:
+Source: `copy/copy-approved.md`, shipped as the package's copy file (the same content; Gate 2's verbatim diff runs against it when the build returns). Final copy in page order, one block per spec section, each labeled with the spec section number and the element roles:
 
 ```
 ## Section 3: Quickstart  [spec §3]
@@ -44,39 +66,191 @@ Body: ...
 CTA button: Copy install command
 ```
 
-Header note, repeated from the master prompt: "This copy is final and voice-gated. Verbatim use only." Image slots are marked `[IMAGE: description, asset filename or TK]`.
+Header note, repeated from the master prompt: "This copy is final and voice-gated. Verbatim use only." The file also carries the `<title>` and meta description as labeled entries; they are copy, they passed the voice gate, and criterion G6.5 checks them in the build.
+
+Every image slot carries its geometry, so the tool designs around the real shapes instead of discovering them at the render gate:
+
+```
+[IMAGE: {description} · displays at {W}x{H}px on desktop · aspect {W:H} · asset: {filename in assets/, or TK}]
+```
 
 ### 02-page-spec.md
 
-The Phase 2 output as-is: numbered sections with purpose, claim carried, proof element, CTA treatment, plus nav policy and archetype name. Include the mobile ordering note: the spec order is the single-column order.
+The operative Phase 2 output: the filled conversion contract (goal, buyer entry states, jobs, proof requirements, CTA policy, ordering constraints, axis settings), the numbered section spec in the computed order with purpose, claim, proof element, and CTA treatment per section, the answer block, the measurement plan, nav policy, and the archetype name. Include the mobile ordering note: the spec order is the single-column order. The candidate skeletons and their pre-reads stay in the run directory; they are decision history, not build input.
 
 ### 03-design-direction.md
 
-- Token set: named palette hex values, type pairing and scale, spacing, radius/border conventions. Attach `theme.css` in assets/ when it exists; for an existing brand, attach real captures or screenshots of current properties so Claude Design can extract the system itself (it is good at this; give it sources rather than descriptions when possible).
-- The chosen direction in two or three sentences, plus the signature element.
-- The anti-slop list from design-direction.md, included verbatim; design tools regress to defaults without it.
-- Asset manifest: every file in assets/ with its intended slot.
+Opens by naming which regime the run is in, so the tool knows what is fixed:
+
+- **Locked** (existing brand, or a persisted theme from a prior run): the token set as named values with `theme.css` attached, the property's `DESIGN.md` content carried when it exists, and captures or screenshots of live properties in `assets/` so the tool extracts the system from sources rather than descriptions (it is good at this; give it sources when they exist). Do not introduce new palette colors or typefaces.
+- **Propose-then-lock** (new property, no committed theme): the brief's aesthetic constraints, the OKLCH seed when Phase 4 produced one, and the instruction to propose 2 or 3 token systems differing on a real axis (temperature, type contrast, density). The owner locks one on return, and the locked system persists as `theme.css` for every later page on the property.
+
+Then: the chosen direction in two or three sentences; the signature element candidate, framed as an anchor the license grant lets the tool beat; and the anti-slop list from `references/design-direction.md`, included verbatim, because design tools regress to defaults without it. Asset-to-slot mapping lives in `assets/manifest.md`, not here.
 
 ### 04-acceptance-criteria.md
 
-Rewrite the build-dependent gates (ship-gates.md gates 3, 4, 5 plus the build requirements from Phase 5) as numbered, testable criteria. Examples: "Renders fully usable at 390px width with the CTA above the fold"; "One h1; heading levels do not skip"; "Total transfer under 1MB"; "JSON-LD from the included template embedded in head"; "prefers-reduced-motion respected". Include the llms.txt and schema templates pre-filled with the product's real values so the builder embeds rather than writes them.
+Filled from the fixed template below, never written fresh. Copy the template whole, fill the `{slots}` with the run's real values, mark inapplicable criteria N/A with the reason on the line, and append run-specific criteria (a motion asset, a form flow) under the owning gate with the next free number. Nothing is reworded, renumbered, or deleted; a criterion ID means the same thing in every package, so a post-build gate failure traces mechanically to the exact line the builder was given. The prefix is the map: criterion `G4.2` belongs to ship gate 4.
+
+### 05-voice-rules.md
+
+An excerpt of `references/voice.md` as configured at run time, so an owner's voice overlay carries through automatically: the Register section, the Punctuation rules, and the banned list, plus one paragraph naming what the excerpt governs: every string the tool generates that `01-copy.md` does not contain. Nav labels, form fields and their error and empty states, button labels, alt text, aria-labels, footer lines, cookie or consent text. The excerpt exists so tool-generated microcopy passes the post-build scan the first time instead of failing it predictably.
+
+### 06-return-spec.md
+
+What the tool hands back:
+
+1. **The built page**: deployable HTML/CSS/JS with assets, as files or a repo, plus the deployed URL when one exists. A tool that can only return a design file rather than code must say so up front, because the post-build gates run on rendered markup and a design file cannot pass them.
+2. **The return log**: every criterion ID answered (met, not met with a reason, or N/A as marked); the list of every text string the build introduced that is not in `01-copy.md`, which is the first target of the voice re-scan; and the flags and questions the non-negotiables call for.
+3. **Exercised license**: any signature-element alternative or proposed token system, each with its sentence of reasoning; under propose-then-lock, the applied tokens as CSS custom properties.
+
+When a post-build gate fails, the revision request uses this fixed shape, and the full package is re-attached every round because the primary target retains nothing between sessions:
+
+```
+## Revision request {n}: {product}
+
+Package: re-attached in full.
+Unchanged: the five non-negotiables in 00-master-prompt.md.
+
+- {criterion ID}: observed {what the check saw}; required {what must be true}.
+- {criterion ID}: ...
+
+Out of scope for this revision: everything not listed above.
+```
+
+Ownership across rounds: revisions go to the tool, and the tool's project stays the source of truth for the markup. When the owner chooses to patch the returned files directly instead, the patched files become the build of record and later rounds run on them; a hand-patch that touches copy re-enters Phase 3 step 5 like any other post-pass edit.
+
+### assets/
+
+- `theme.css`: the locked tokens as custom properties, contrast-verified (locked regime only).
+- `manifest.md`: one row per file: filename, the spec section it serves, display dimensions, aspect ratio, intended treatment (crop, frame, full-bleed), and its alt text, written under the voice rules; criterion G3.6 checks the build against this column.
+- `llms.txt` and `schema.jsonld`: pre-filled with the product's real values from the templates in `references/ship-gates.md`, shipped as files so the build embeds them instead of retyping them; criteria G6.1 and G6.2 check byte-identity.
+- Logos, product screenshots, captures of live properties. Real artifacts only; no placeholder or generated stand-in enters the package.
+
+### DESIGN.md: the generated projection
+
+The package root carries a `DESIGN.md`: the package's design-system layer projected into the published design.md format (the open spec behind Google Stitch, shipped on npm as `@google/design.md`). It exists for consumers the file layout cannot reach otherwise: tools that read the format natively, and agents that discover a root `DESIGN.md` by the format's own convention. The canonical files stay the source of truth. The projection is generated from them, never edited by hand, and regenerated whenever `00` through `05`, `theme.css`, or the property's design system changes; an edit that seems to belong in the projection belongs in a source file, so make it there and regenerate.
+
+Two files share this name, and they are different things. The property's `DESIGN.md` at the product repo root is the durable design system Phase 4 step 6 persists; it outlives any single page and is an input to this package (its content rides in `03`). The package's `DESIGN.md` is run-scoped output, derived from the package files. They never merge and neither overwrites the other.
+
+**Generation rules.** The projection is a deterministic compilation: the same package produces the same file, every line traces to a named package source, and nothing in it is new thinking. Target the published spec: eight body sections in their fixed order (omitting an empty one is legal, reordering is not), `version: alpha` pinned in the frontmatter so a future spec bump surfaces as a diff. The eight-versus-six profile question is settled in Phase 4 step 6; the projection follows the same ruling.
+
+| design.md part | Compiled from |
+|---|---|
+| Frontmatter (`colors`, `typography`, `rounded`, `spacing`, `components`) | Locked regime: the token values from `theme.css` and `03`, keeping the property's own token names so every value traces back; the accent role also lands under the name `primary`, the one name the linter checks for, and the CTA button enters `components` with its background and text colors. Propose-then-lock: `name` and `version` only. Token values are exactly what the license grant hands the tool, and a projection that invents them decides what `00` said the tool would decide. |
+| `## Overview` | The orientation paragraph from `00` plus the chosen-direction sentences from `03`. |
+| `## Colors` | The palette roles from `03` as prose (what each color is for; values stay in the frontmatter). Propose-then-lock: the OKLCH seed when Phase 4 produced one, and the brief's aesthetic constraints as the region to propose within. |
+| `## Typography` | The type pairing and scale from `03`. |
+| `## Layout` | The spacing rhythm and density setting from `02` and `03`. Never the section order: page structure is `02`'s contract, and design.md is a style contract with no concept of a page. |
+| `## Elevation & Depth` | `03`'s treatment, stated explicitly even when the answer is flat; borders and tonal layers are a chosen strategy, not an omission. |
+| `## Shapes` | The radius and border language from the tokens. |
+| `## Components` | Button, input, and card treatments from `theme.css` and `03`, inside the spec's eight component properties. |
+| `## Do's and Don'ts` | The anti-slop list carried in `03`, verbatim; the CTA policy's styling consequence (one action styled as primary); and the design-facing line of the fabrication ban: no logo strips, star ratings, avatar rows, or count badges that are not in the package. |
+
+The projection carries no copy, no section order, no conversion contract, no acceptance criteria, and no voice enforcement, which is why it never travels alone as a build brief: a consumer holding only this file styles well and builds blind. The per-tool table below draws the consequence.
+
+**Lint.** After every regeneration, when `npx` can reach it, run `npx @google/design.md lint <package>/DESIGN.md`. A `broken-ref` finding is the linter's one error and blocks delivery; warnings go into the gate report, each with a disposition. Two are expected and accepted by design: `missing-primary` under propose-then-lock (the frontmatter deliberately carries no palette) and `orphaned-tokens` when tokens exist for the tool's use rather than for cross-reference. When the linter cannot run, the package still ships and the gate report says the projection went out unlinted; delivery is not hostage to npm being reachable, but an unrecorded skip is a suppressed check.
+
+## The acceptance criteria template (fixed)
+
+```markdown
+# Acceptance criteria: {product}
+
+Copied from the fixed template in page-foundry's references/handoff.md. IDs are stable and
+the prefix names the owning ship gate (G3 accessibility, G4 performance, G5 render review, G6 AI
+discovery, G7 measurement). {slots} are filled per run. Inapplicable criteria are marked
+N/A with the reason on the line; nothing is reworded, renumbered, or deleted. Run-specific
+criteria append under their gate with the next free number. The return log answers every ID.
+
+## G3 · Accessibility (WCAG 2.2 AA)
+- G3.1 One h1; heading levels do not skip.
+- G3.2 Landmarks present (nav, main, footer); links and buttons are real a/button elements;
+  icon-only controls carry an aria-label.
+- G3.3 Text contrast at least 4.5:1 (3:1 for large text and UI components), CTA buttons included.
+- G3.4 Visible keyboard focus on every interactive element; logical tab order; focus never
+  obscured.
+- G3.5 Touch targets at least 24x24px; 44px or larger for primary actions.
+- G3.6 Every informative image carries the alt text assets/manifest.md specifies and explicit
+  width/height attributes; decorative images have empty alt.
+- G3.7 No content conveyed by color alone; prefers-reduced-motion respected; motion animates
+  only transform and opacity.
+- G3.8 Form inputs have programmatic labels and correct type/inputmode/autocomplete; async
+  status changes use aria-live. {N/A when the page has no form}
+- G3.9 No step forces a memory or transcription test without an easier alternative.
+  {N/A when the page has no auth}
+- G3.10 Every interactive element has a hover state as well as a focus state; nothing is
+  hover-only, and no state change signals by color alone.
+
+## G4 · Performance
+- G4.1 Total transfer under {budget, default 1MB}; CSS plus JS under {budget, default 200KB}.
+- G4.2 Images sized to the display dimensions in assets/manifest.md, WebP or AVIF, lazy-loaded
+  below the fold.
+- G4.3 Fonts: system stack, or at most two self-hosted files, preloaded, font-display: swap
+  with a metric-matched fallback so the swap shifts no layout.
+- G4.4 No render-blocking third-party scripts; analytics loads deferred.
+- G4.5 LCP under about 2 seconds on a mid-range phone; the LCP element is the hero image or
+  text block, not a script-injected element.
+
+## G5 · Render review
+- G5.1 Fully usable at 390px width with the primary CTA above the fold; composed, not
+  stretched, at 1440px.
+- G5.2 {locked regime: only the palette, type, and radii in 03-design-direction.md and
+  theme.css appear on the page} {propose-then-lock regime: the proposed token system is
+  applied consistently and returned as CSS custom properties}
+- G5.3 Nothing on the anti-slop list in 03-design-direction.md appears on the page.
+- G5.4 Blurred, the primary element, the secondary element, and the groupings still read
+  within 2 seconds (the squint test), the hero first.
+
+## G6 · AI discovery and meta
+- G6.1 llms.txt from assets/ placed at the site root, byte-identical.
+- G6.2 The JSON-LD in assets/schema.jsonld embedded in <head>, byte-identical.
+- G6.3 The answer block from spec section {n} survives as one self-contained block of real
+  text near the top of the page.
+- G6.4 robots.txt does not disallow GPTBot, ChatGPT-User, PerplexityBot, ClaudeBot,
+  anthropic-ai, Google-Extended, or Bingbot. {N/A when the tool does not control deployment}
+- G6.5 <title> and meta description exactly as 01-copy.md gives them.
+- G6.6 Open Graph and Twitter card meta complete; the OG image is {filename}, 1200x630.
+- G6.7 Canonical URL set to {url}; favicon present.
+- G6.8 /pricing.md from assets/ placed at the site root. {public-pricing archetypes only;
+  N/A otherwise}
+
+## G7 · Measurement
+- G7.1 The conversion event wired exactly as the measurement plan in 02-page-spec.md defines
+  it: {event, destination}.
+- G7.2 Outbound campaign links carry the UTM convention the measurement plan states.
+  {N/A when the plan names no campaign links}
+- G7.3 The analytics snippet ({name}) included, deferred. {N/A when the plan declined
+  analytics}
+```
+
+## Per-tool packaging
+
+One package, three delivery shapes. Which shape a tool gets follows from what it can receive, and the middle row is priced honestly.
+
+| Tool class | What ships | How it enters, and what the seam costs |
+|---|---|---|
+| Attachment-capable: Claude Design, a human designer, any tool that takes files | The full package | Paste `00-master-prompt.md`, attach everything else. Nothing is lost; the gate split below applies as written. |
+| Single-prompt or design.md-aware: Stitch, one-box generators | `DESIGN.md`, plus the page ask distilled from `00` where the tool takes a prompt at all | Import or paste the projection as the style contract. This seam cannot carry the verbatim copy, the criteria, or the return spec, so what comes back is a styled draft, never a build of record: reaching a shippable page means re-entering Phase 5 with the draft as design input and running every gate in full. Say so to the user before choosing this seam, not after the draft arrives. |
+| Repo-based: Claude Code, Codex, any agent working in a checkout | The package directory | Point the agent at `00-master-prompt.md` as the entry file; `DESIGN.md` at the package root is found by the format's own convention. The return spec applies as written. |
 
 ## Gate split in handoff mode
 
 Run BEFORE delivering the package (these gate the package itself):
 
-- Gate 1, conversion audit: runs against the spec and copy (5-second test, CTA policy, headline budget, proof adjacency, MECLABS scored on the planned page).
-- Gate 2, voice: `voice_scan.py` at zero FAILs on 01-copy.md and 00-master-prompt.md.
-- Gate 6, integrity: no fabricated proof anywhere in the package; [TK] items listed in the master prompt's questions section.
+- Gate 0, orchestration: `run_audit.py` over the run artifact directory, and the preflight cross-check, exactly as in build mode. A handoff package assembled without the marketing pipeline is the same failure as a build without it; the tool receiving the package inherits whatever the run actually did, so the provenance is checked before the package ships, not left to the downstream tool to trust. The pre-build artifacts (brief, `voc.md`, `message-architecture.md`, `persuasion-map.md`, `page-spec.md`, copy snapshot, `conversion-audit.md`) must all be present and pass; the build-side artifacts (comp, `pages/`) are N/A here because the external tool produces them, and their acceptance is the returned-build gates below.
+- Gate 1, conversion audit: runs against the spec and copy (5-second test, CTA policy, headline budget, proof adjacency). The MECLABS score of record comes from a fresh agent given the package's verbatim copy and the brief, per Gate 1's mechanics in `references/ship-gates.md`.
+- Gate 2, voice: `voice_scan.py` at zero FAILs across the package's prose files (`00` through `06`, and the generated `DESIGN.md` with them); the pattern pass and the humanizer already ran in Phase 3 and the copy-fit pass on the copy itself.
+- The projection check: `DESIGN.md` regenerated from the current package files, then linted per the projection section (`broken-ref` blocks; warnings dispositioned in the gate report; an unlinted projection recorded as unlinted).
+- Gate 8, integrity: no fabricated proof anywhere in the package; `[TK]` items listed in the master prompt's questions section.
 
-Run AFTER the built asset comes back (request the HTML or a deployed URL):
+Run AFTER the built asset comes back:
 
+- Gates 3 through 7 in full, walked against the criteria file by ID; the criteria are the same checks pre-translated for the builder, and the gates in `references/ship-gates.md` remain the arbiter.
 - Gate 1 re-check on the rendered page (did the build preserve CTA policy and proof adjacency?).
-- Gate 2 re-scan on the built HTML (catches paraphrase drift; this catches real violations often, run it every time).
-- Gates 3, 4, 5 in full.
+- Gate 2 re-scan on the built HTML: the verbatim diff of rendered text against `01-copy.md`, then the scan of every string the return log lists as introduced. This catches real violations often; run it every time.
+- Gate 8 re-check: nothing the build added fabricates proof.
 
 A handoff is not done at package delivery; it is done when the returned asset passes the post-build gates.
 
 ---
 
-_Provenance: page-foundry-native (no direct companion source). The Claude Design capability description reflects Anthropic Labs as of 2026-07; re-verify it if the tool's inputs or outputs change. Gate references stay in sync with ship-gates.md and design-direction.md._
+_Provenance: page-foundry-native (no direct companion source). The Claude Design capability description reflects Anthropic Labs as of 2026-07; re-verify it if the tool's inputs or outputs change. The `DESIGN.md` projection targets the published design.md spec (`google-labs-code/design.md`, `version: alpha`, linter `@google/design.md` 0.3.0, both verified 2026-07); if the spec leaves alpha, revisit the pinned version and the section list. Gate IDs, the criteria template, and the embedded-file checks stay in sync with `references/ship-gates.md`; the `05` excerpt with `references/voice.md`; the anti-slop list with `references/design-direction.md`; the profile ruling with Phase 4 step 6 in `SKILL.md`._