forgedock 1.0.17 → 1.0.19

package/docs/design/design-system-lint.md

@@ -0,0 +1,150 @@
+# Design-System Linter — `scripts/design-system-lint.mjs`
+
+> **Status:** Committed — the deterministic anti-slop gate for the UI Taste Harness (milestone #13, issue #884).
+> Consumes the [`FORGE:DESIGN_SPEC` schema](design-spec-schema.md) (#881); enforces the machine-checkable
+> negatives from the [reference corpus](reference-corpus.md) (#880); invoked by the
+> render → critique loop (#882) and/or quality-gate.
+> Extended: `checkFoundationUsage` check for per-archetype CSS foundation class usage (#1048).
+
+## Purpose
+
+The positive, deterministic floor of the harness. It **hard-fails** generated landing-page output that
+violates the committed design system, rather than hoping prose prevents regression to generic AI defaults.
+
+> Don't let the LLM "reason its way" back to generic defaults — **constrain it out of them deterministically**.
+> Prose is a suggestion; a failing lint is a constraint. This raises the floor and never lets it regress,
+> regardless of model variance. (Same philosophy as the #639 fix.)
+
+The linter and the vision critic (#882) check the rendered output against the **same** committed intent
+(the `FORGE:DESIGN_SPEC`). The linter owns the **deterministic** negatives; the critic owns the perceptual ones.
+
+## Scope — what the linter owns
+
+The [corpus](reference-corpus.md) tags each negative with its check surface. The linter implements exactly the
+deterministic ones; the rest are left to the vision critic.
+
+| Negative | Check | Default severity | Surface |
+|---|---|---|---|
+| **N1** | Purple/blue gradient hero on a white/near-white background | BLOCKING when spec opts in | `checkHeroGradient` |
+| **N2** | Inter / system-default typeface at default weights as the display/body face | BLOCKING (typography is core taste) | `checkTypography` |
+| **N4** | Exactly three identical feature cards (structural pattern only) | WARNING — icon judgement is the critic's | `checkRepeatedCards` |
+| **N5** | A single radius applied to everything, or off-scale radii | BLOCKING when a multi-token `radius.scale` exists | `checkRadius` |
+| **N6** | Default Tailwind palette (slate/gray/zinc/neutral/indigo/violet) used as the brand color | BLOCKING when `no-default-tailwind-palette` is set | `checkPalette` |
+| **N7** | The boilerplate skeleton: hero → 3-cards → testimonial → CTA, in that order | BLOCKING when `layout_grammar.sections` exists | `checkSectionSkeleton` |
+| **N24** | Static product mock: `product_mock.type` is committed (not `"none"`) but the rendered hero has a `.product-window` or `.mock-*` element with no `animation`, `transition`, or JS `addEventListener` present <!-- Added: forge#1045 --> | BLOCKING when `product_mock.type` is set and not `"none"` | `checkProductMock` |
+| **N25** | Truncated narrative: `scroll_narrative` is committed in spec but the rendered page has ≤1 below-fold section (`<section>` or `<div role="region">` elements outside the first/hero section) <!-- Added: forge#1046 — spec only; .mjs implementation follows --> | BLOCKING when `scroll_narrative.section_count_min` is set | `checkScrollNarrative` |
+| **N26** | Missing social proof: `scroll_narrative.social_proof_section` is committed (not `"none"`) but no element with class `section-social-proof`, `social-proof`, or `[data-section="social-proof"]` is present <!-- Added: forge#1046 — spec only; .mjs implementation follows --> | BLOCKING when `scroll_narrative.social_proof_section` is set and not `"none"` | `checkSocialProof` |
+| **N27** | Single CTA: `scroll_narrative.cta_placements_min` is ≥ 2 but the rendered page has fewer than 2 elements matching `.btn-primary`, `.cta-button`, `[data-cta]`, or `<a>` with class containing `cta` <!-- Added: forge#1046 — spec only; .mjs implementation follows --> | BLOCKING when `scroll_narrative.cta_placements_min` ≥ 2 | `checkCTACount` |
+| — | Foundation class usage: a foundation CSS file was injected (Stage 3, #1048) but none of `.btn`, `.card`, `.badge`, `.input` appear in the generated HTML — generator replaced foundation classes with Tailwind equivalents <!-- Added: forge#1048 --> | WARNING when `meta.archetype` maps to a known foundation file | `checkFoundationUsage` |
+| — | Off-scale spacing (padding/margin/gap not on `spacing.scale`) | WARNING | `checkSpacing` |
+| — | Contrast: `color.foreground` vs `color.background` below `acceptance.a11y.contrast_min` | BLOCKING when a contrast floor is declared | `checkContrast` |
+
+**Opt-in trigger for N24**: `product_mock.type` present in spec and not `"none"`. When `product_mock.type: "none"`,
+N24 is skipped entirely — the architect deliberately opted out of a mock, and no check is needed.
+
+**Opt-in trigger for N25**: `scroll_narrative.section_count_min` present in spec. The check counts `<section>`
+(and `<div role="region">`) elements in the rendered HTML; when the count is below `section_count_min`, the check
+blocks. When `scroll_narrative` is absent from the spec, N25 is skipped.
+
+**Opt-in trigger for N26**: `scroll_narrative.social_proof_section` present in spec and not `"none"`. Checks for
+social proof element presence using class-name patterns (`section-social-proof`, `social-proof`) and
+`[data-section="social-proof"]` attribute. When `social_proof_section: "none"`, the architect deliberately opted
+out and N26 is skipped.
+
+**Opt-in trigger for N27**: `scroll_narrative.cta_placements_min` ≥ 2. Counts CTA elements using class-name
+patterns (`.btn-primary`, `.cta-button`, `[data-cta]`, and `<a>` elements with class containing `cta`). When
+`cta_placements_min` is absent or < 2, N27 is skipped.
+
+**Out of scope** (vision-critic-owned, #882): N3 (everything centered), N8 (stock illustration / generic 3D),
+N9 (glassmorphism overuse), N10 (no visual hierarchy), N11 (abstract copy / no product shown),
+N12 (decorative effects that serve nothing), N24 perceptual quality (whether the 2 interactions feel right — the critic
+judges that; the linter only checks that interaction signals are present at all), N25/N26/N27 narrative quality
+(whether the section content is compelling — the critic judges that; the linter only checks structural presence).
+These require perceptual judgement and are not deterministically checkable.
+N12 / effect justification specifically is governed by the [effects-appropriateness doctrine](effects-appropriateness.md) (#885)
+and judged by the vision critic (#882) against the per-section `justification`; the perf gate (#875) owns the hard `budget`. The linter stays out.
+
+## Spec-driven gating
+
+Which checks **block** (vs. merely warn) is driven by the spec, not hardcoded — so the same linter serves any
+archetype. A check escalates to `BLOCKING` when the spec opts in via:
+
+- `color.rules` — e.g. `"no-default-tailwind-palette"` (gates N6/N1), `"contrast>=4.5"` (gates contrast).
+- `negatives[]` — e.g. `"N6"`, `"N7"` (raw IDs, `{ "id": "N6" }` objects, or descriptive strings are all accepted).
+- Presence of the relevant token field — a multi-entry `radius.scale` opts N5 in; `layout_grammar.sections` opts N7 in;
+  a committed non-default `typography.display_family` opts N2 in; `acceptance.a11y.contrast_min` opts contrast in;
+  `product_mock.type` set to any value other than `"none"` opts N24 in;
+  `scroll_narrative.section_count_min` present opts N25 in;
+  `scroll_narrative.social_proof_section` set to any value other than `"none"` opts N26 in;
+  `scroll_narrative.cta_placements_min` ≥ 2 opts N27 in;
+  `meta.archetype` matching a known foundation archetype opts `checkFoundationUsage` in (WARNING only — see #1048). <!-- Added: forge#1048 -->
+
+`--strict` forces **every** deterministic check to block regardless of spec opt-in.
+
+## Usage
+
+```bash
+node scripts/design-system-lint.mjs --spec <spec.json> --html <page.html> [options]
+```
+
+| Option | Meaning |
+|---|---|
+| `--spec <path>` | The `FORGE:DESIGN_SPEC` JSON (required) |
+| `--html <path>` | The generated HTML to lint (required, unless `--selftest`) |
+| `--css <path>` | Optional separate CSS file (inline `<style>` and `style="…"` are always read) |
+| `--baseline` | Report findings but always exit `0` (survey existing slop, never fail the build) |
+| `--strict` | Every deterministic check blocks, even without spec opt-in |
+| `--json` | Emit findings as JSON on stdout (for the #882 critique loop to consume) |
+| `--selftest` | Run internal self-checks (contrast math, palette table) and exit |
+| `--help` | Show usage |
+
+### Output
+
+Plain mode prints one finding per line with the established severity prefixes, then a summary:
+
+```
+BLOCKING: [N6] Committed color accent=#4f46e5 is a default Tailwind palette value — not a brand color.
+WARNING:  [SPACING] Off-scale spacing value(s): 17px — not on spacing.scale [4, 8, 12, 16, 24, 32, 48, 64, 96].
+OK:       [N1] No purple/blue-gradient-on-white hero detected.
+
+=== Summary ===
+Checks run: 13
+Blocking: 11
+Warnings: 1
+```
+
+`--json` emits `{ blocking, warnings, baseline, findings: [{ severity, negative, message }] }`.
+
+### Exit codes
+
+Matches the scripts-layer convention (`scripts/verify-env-vars.sh`):
+
+| Code | Meaning |
+|---|---|
+| `0` | Pass — no blocking findings |
+| `1` | Blocking findings present |
+| `2` | Warnings only (or bad invocation) |
+
+`--baseline` always exits `0`.
+
+## Integration
+
+- **Render → critique loop (#882):** call the linter with `--json` on the generated HTML before the vision pass.
+  Blocking findings short-circuit the iteration (the page is regenerated against the spec) without spending a
+  vision-critique turn. The linter is deterministic and dependency-free, so it is cheap to run every iteration.
+- **quality-gate:** invoke as a sibling scripts-layer check (like `scripts/verify-*.sh`) and key off the exit code.
+  Use `--baseline` for a non-failing survey, or default mode to hard-gate.
+
+## Design notes
+
+- **Zero runtime dependencies** — Node built-ins only (`node:fs`), matching `scripts/gen-logo.mjs`. HTML/CSS is
+  scanned with tolerant regex (attribute order, quote style, and whitespace are accommodated); no jsdom/cheerio.
+- **Injection-safe** — inputs are read as data and never interpolated into a shell; there is no `eval`/`exec`
+  (avoids the class of review-findings #73 / #335).
+- **Deterministic** — no network, no randomness, stable finding order. The contrast check uses the standard WCAG
+  relative-luminance formula (self-tested: `#000`/`#fff` = 21:1).
+- **Parser limitations** — being regex-based, the linter reads inline `<style>` blocks and `style="…"` attributes
+  plus Tailwind utility classes; it does not resolve an external Tailwind build's computed colors. Ambiguous cases
+  (e.g. a committed font that cannot be confirmed in the output) are reported as `WARNING`, not `BLOCKING`, to avoid
+  false hard-fails. For computed/rendered-pixel checks (e.g. N8–N12), defer to the vision critic with a real render
+  (Playwright, #875).

package/docs/design/divergent-generation.md

@@ -0,0 +1,106 @@
+# Divergent generation + archetype sampling + taste-judge selection
+
+> **Status**: committed foundation doc for the UI Taste Harness (#883).
+> The variance lever: how the harness produces *different* good pages instead of mode-collapsing to one.
+> Consumes: [reference-corpus](reference-corpus.md) archetypes (#880), the [design-architect rationale](design-architect-rationale.md) (#886).
+> Produces: a `FORGE:DESIGN_CANDIDATES` set whose winner hands off into [`FORGE:DESIGN_SPEC`](design-spec-schema.md) (#881).
+> Judge is independent from the render → vision-critique loop (#882) and the [ABC benchmark judge](abc-benchmark.md) (#878) — anti-Goodhart.
+> Part of #877.
+
+## Purpose
+
+Two failure modes bracket AI UI generation. **Mode collapse**: "make it beautiful" yields the same gradient-hero
+template every time — zero variance. **Incoherent blending**: averaging archetypes ("a bit editorial, a bit
+brutalist") yields mush — variance without taste. This doc defines the lever that sits between them: **commit to one
+archetype, then diverge *within* it across N distinct directions, and let an independent taste-judge pick the winner.**
+
+Variance between runs comes from *which archetype + which direction* is chosen — never from blending. Coherence within
+a run comes from committing and not drifting.
+
+## Step 1 — Archetype sampling (commit, never blend)
+
+From the design-blind brief + the architect rationale (#886), select **exactly one** archetype from the five committed
+in [reference-corpus](reference-corpus.md) (#880). The ids are fixed tokens — they must match exactly, because the
+selected id is written into `meta.archetype` in the [spec](design-spec-schema.md):
+
+| `archetype` id | When it fits |
+|---|---|
+| `editorial-typographic` | considered, magazine, type-led products; content-forward |
+| `technical-dense` | dashboards, compute, infra; capable, data-forward |
+| `minimal-luxury` | premium, lots of air; restraint as the message |
+| `bold-brutalist` | opinionated, high-contrast; a stance |
+| `warm-photographic` | human, approachable; image/people-led |
+
+**Selection rule** (from the corpus): pick the one appropriate to *product nature* + *audience* inferred from the
+brief, then **commit**. No blending, no averaging, no "60% A / 40% B". The variance lever is the *choice between*
+archetypes across runs and the divergent directions below — not a blend within a run.
+
+## Step 2 — Divergent generation (N distinct directions)
+
+Within the committed archetype, generate **N distinct directions** (default N=3). Each direction is a genuinely
+different interpretation of the *same* archetype + rationale — different layout grammar, different signature move,
+different typographic instantiation — not N near-duplicates with a hue shift. Divergence is structural, not cosmetic.
+
+Each direction carries:
+- a one-line concept (the interpretation),
+- its **signature move** (from the rationale's diary — the non-obvious idea that makes it *this* page),
+- the salient token/grammar choices that distinguish it from its siblings.
+
+Sampling within one archetype keeps every direction coherent; requiring *structural* difference keeps them genuinely
+divergent. If two directions collapse to the same signature move, one is rejected and re-rolled — duplicate directions
+defeat the lever.
+
+## Step 3 — Taste-judge score + select
+
+An **independent taste-judge** scores the N directions and selects one winner. The judge:
+- scores each direction on a small taste rubric (hierarchy/intent, signature-move strength, archetype fit, restraint),
+- rejects any that trip the corpus negatives or duplicate a sibling,
+- selects the highest-scoring surviving direction; ties break toward the stronger signature move.
+
+### Judge independence (anti-Goodhart) — non-negotiable
+
+This taste-judge is **distinct** from both:
+- the **render → vision-critique loop** (#882), which judges a *rendered* page against its committed spec, and
+- the **ABC benchmark judge** (#878), which scores arms blind against arm C for evaluation.
+
+Reusing either as the selection judge would let the harness optimize directly against its own evaluator — the textbook
+Goodhart failure. The selection judge scores *candidate directions* (pre-render intent); the critic scores *rendered
+output*; the benchmark scores *finished arms*. Three separate judges, three separate jobs.
+
+## Step 4 — Hand-off to DESIGN_SPEC
+
+The winning direction is what gets fully specified: it hands off into [`FORGE:DESIGN_SPEC`](design-spec-schema.md)
+(#881) — `meta.archetype` = the committed id, `layout_grammar`/`signature` = the winning direction. The losing
+directions are retained in the `FORGE:DESIGN_CANDIDATES` annotation (below) so the choice is auditable and so
+[design-memory](design-memory.md) (#887) can later diverge from past winners.
+
+## The `FORGE:DESIGN_CANDIDATES` annotation
+
+Registered in [FORGE-PROTOCOL](../FORGE-PROTOCOL.md). Posted at the divergent-generation step, between the rationale
+and the spec. It records the committed archetype, the N directions, and the judge's selection + scores — so the
+variance decision is a first-class, machine-queryable artifact, not a hidden roll.
+
+```markdown
+<!-- FORGE:DESIGN_CANDIDATES -->
+## Design Candidates — {product}
+
+**Archetype (committed):** {one of the 5 corpus ids}
+**Directions:**
+1. {concept} — signature: {move} — {distinguishing grammar/tokens}
+2. {concept} — signature: {move} — {…}
+3. {concept} — signature: {move} — {…}
+**Judge scores:** 1) {score} 2) {score} 3) {score}
+**Selected:** #{n} — because {reason}
+
+→ Winner produces DESIGN_SPEC: {link}
+```
+
+## Acceptance (worked expectation)
+
+On the seed set, the same brief produces a *committed archetype* and visibly different *directions*:
+- **Voltage** (`technical-dense`): directions differ on whether the signature move is a scaling-compute visualization,
+  a code-first hero, or a benchmark-grid — same archetype, three structures.
+- **Plume** (`minimal-luxury` / `editorial-typographic`): directions differ on keyboard-motif vs cycle-timeline vs
+  pure-type hierarchy — all restrained, all coherent.
+
+Variance shows up as *which archetype + which direction wins*, across runs — never as a blend within a run.

package/docs/design/effects-appropriateness.md

@@ -0,0 +1,133 @@
+# Effects-appropriateness layer
+
+> **Status**: committed foundation doc for the UI Taste Harness (#885).
+> Consumes: [reference-corpus](reference-corpus.md) effect-usage patterns (#880),
+> [design-spec-schema](design-spec-schema.md) `effects_plan` slot (#881).
+> Enforced by: the perf gate (#875, hard/objective) and the vision critique loop (#882, perceptual — N12).
+> Stays out of: the deterministic [linter](design-system-lint.md) (#884) — effect justification is not deterministically checkable.
+> Authored to be consumed by: the [design-architect rationale](design-architect-rationale.md) (#886) and [design-memory](design-memory.md) (#887) phases.
+> Part of #877.
+
+## Purpose
+
+The schema (#881) gives every page an `effects_plan` — a slot for *which* heavy techniques run *where*, at *what*
+intensity, with a *budget* and a *never* list. The slot is a placeholder. This doc is the **reasoning doctrine that
+fills it**: how the harness decides, **from the design-blind brief alone**, when a heavy effect earns its cost and
+when restraint is the more confident choice.
+
+The thesis: AI UI mode-collapses toward gratuitous motion because "make it impressive" has no cost model. The fix is
+to treat every effect as a spend that must be *justified against the content it serves and the budget it consumes* —
+and to make the default **restraint**, with effects added only on evidence, never by reflex.
+
+## The core asymmetry
+
+Not all effects reward the same posture. This is the single most important rule in this doc:
+
+> **Compositional contrast rewards *more* intention. 3D/WebGL, parallax, and multi-layer depth reward *restraint*.**
+
+Flattening this into "less is always more" loses the doctrine. Low contrast is itself a slop tell (flat, equal-weight,
+nothing directs the eye — see N12's sibling failures). Deliberate contrast is almost always correct. The *decorative*
+effects (depth, motion, 3D) are the ones that must earn their place against a hard cost.
+
+## Effect taxonomy + appropriateness/cost
+
+Derived from the corpus effect-usage table (#880); this layer formalizes the `Earns its place when…` / `Slop when…`
+columns into authoring rules with an explicit cost axis.
+
+| Effect | Posture | Earns its place when… | Slop when… | Primary cost |
+|---|---|---|---|---|
+| **Compositional contrast** | *more* intention | almost always — direct the eye, establish hierarchy | flat, equal-weight, everything the same size/color | ~none (CSS) |
+| **Multi-layer depth** (glass / grain / gradient) | restraint | one hero backdrop; foreground/background separation that aids reading | over-glass, muddy contrast, applied everywhere | contrast/a11y risk; minor paint |
+| **Parallax / scroll-driven** | restraint | a single progressive-capability reveal where depth *is* the message | on every section; jank/CLS; fights readability | INP/CLS; JS |
+| **3D / WebGL** | strong restraint | the product is spatial/visual; exactly one premium hero centerpiece with a fallback | bolted onto non-visual B2B; wrecks LCP; no reduced-motion/no-WebGL fallback | LCP + JS-kb (largest) |
+
+## The 6 decision inputs
+
+The architect/rationale phase (#886) infers all six from the brief alone, then writes them into `effects_plan`:
+
+1. **Product nature** — is the product itself *spatial/visual* (renders, maps, 3D, creative tooling), *technical/data*
+   (compute, dashboards, infra), or *text/workflow* (trackers, docs, email)? Spatial → a heavy hero may be earned;
+   text/workflow → near-zero decorative.
+2. **Archetype** — the committed archetype carries an **effects posture** prior (#880): `bold-brutalist` →
+   "sharp, near-zero decorative"; `technical-dense` → "code/data motion welcome"; `minimal-luxury` →
+   "restrained micro-motion"; `editorial-typographic` → "minimal, type-led"; `warm-photographic` → "image-driven, soft motion".
+3. **Section job** — what is *this* section for? A hero may carry one centerpiece; a pricing table or feature grid
+   carries none. Effect intensity is assigned **per section**, not per page.
+4. **Audience expectation** — engineers who "read the code sample closely" reward technical credibility and are
+   *repelled* by gratuitous motion; a consumer/creative audience tolerates more spectacle.
+5. **Measurable perf budget** (#875) — LCP / CLS / INP / JS-kb ceilings. This is the **hard gate**: an effect that
+   blows the budget is rejected regardless of how good it looks.
+6. **Accessibility** — `prefers-reduced-motion` must be honored; depth must not destroy contrast; every WebGL/3D
+   centerpiece needs a static fallback. A11y failures are not negotiable against aesthetics.
+
+## Mapping decision inputs → `effects_plan`
+
+The fields mirror [design-spec-schema](design-spec-schema.md) exactly:
+
+`effects_plan { per_section[{ section, effect, intensity, justification }], budget{ lcp_ms, max_js_kb }, never[] }`
+
+- **`per_section[].effect` / `.intensity`** — from inputs 1–4. Default `intensity: none`. Raise it only when product
+  nature + archetype + section job *agree* that the effect serves the content. Each step up in intensity needs a
+  stronger justification.
+- **`per_section[].justification`** — one sentence stating *what content the effect serves*. "Looks premium" is not a
+  justification; "the spatial product *is* the demo, shown once in the hero" is. The critic (#882) reads this field
+  and judges whether the rendered effect actually delivered on it (N12).
+- **`budget{ lcp_ms, max_js_kb }`** — from input 5. The hard ceiling. The perf gate (#875) measures the rendered arm
+  against it; over-budget = fail, no aesthetic override.
+- **`never[]`** — from inputs 2 + 6. Per-archetype prohibitions (e.g. `bold-brutalist` → `never: [parallax, glass]`)
+  and universal a11y rules (`never: [motion-without-reduced-motion-fallback]`).
+
+## Enforcement split
+
+Three mechanisms, deliberately non-overlapping — no single check owns the whole problem:
+
+| Mechanism | Owns | Nature |
+|---|---|---|
+| **Perf gate** (#875) | `budget` — did the effect stay within LCP/CLS/INP/JS-kb? | **Hard, objective.** Earned its *ms*. Blocking. |
+| **Vision critic** (#882) | N12 — did each effect *serve the content* it claimed to? | **Perceptual.** Earned its *place*. Finding. |
+| **Deterministic linter** (#884) | nothing here | Effects are explicitly **out of scope** — not deterministically checkable. |
+
+The perf gate answers "could the user afford it?"; the critic answers "was it worth it?". An effect must pass **both**:
+within budget *and* serving the content. Within budget but gratuitous → critic N12 finding. Justified but over budget →
+perf-gate fail. The linter stays out because perceptual judgement can't be reduced to a regex without false hard-fails
+(consistent with `design-system-lint.md`'s N8–N12 out-of-scope list).
+
+## Worked inferences (seed set)
+
+Demonstrating that the doctrine produces **visibly different effect intensity from the briefs alone** — the acceptance
+criterion. Each is derived purely from the design-blind brief; no visual direction is given.
+
+### Voltage — serverless compute / GPUs for ML engineers
+- **Product nature**: technical/data (compute), with a *credible* spatial story (containers scaling zero→thousands).
+- **Audience**: engineers who read the code sample closely → reward technical credibility, repelled by spectacle.
+- **Inference**: `technical-dense` archetype; **one restrained** technical hero visualization (subtle scaling/compute
+  motion that *is* the product story), `intensity: subtle`. Code sample is the real hero. No parallax, no glass.
+- `effects_plan`: hero → `effect: technical-motion, intensity: subtle, justification: "the zero→N scaling IS the product, shown once"`;
+  all other sections → `none`. `never: [parallax, decorative-3d]`. Tight JS budget (audience will notice bloat).
+
+### Plume — fast, keyboard-driven issue tracker for software teams
+- **Product nature**: text/workflow. Speed and focus are the message.
+- **Audience**: craft-focused technical teams who find heavy tools heavy → motion that slows them is *anti-product*.
+- **Inference**: `minimal-luxury` / `editorial-typographic`; **near-zero motion**. The product's own speed is the
+  argument; any decorative effect contradicts it. Contrast and typography do all the work.
+- `effects_plan`: every section → `intensity: none`; `never: [parallax, 3d, glass]`. Restraint *is* the design.
+
+### Slipstream — git-connected deploy platform / global edge
+- **Product nature**: technical/infra; "confidence and restraint" stated explicitly in the brief.
+- **Audience**: frontend/full-stack devs; serious, opinionated platform.
+- **Inference**: restrained, typographic-technical. At most **one** subtle scroll reveal for the push→production flow
+  (depth *is* part of that narrative), `intensity: subtle`; everything else `none`. Restraint as the move.
+- `effects_plan`: hero/flow → `effect: scroll-reveal, intensity: subtle, justification: "push→prod is a sequence; one reveal shows it"`;
+  rest → `none`. `never: [decorative-3d, glass]`.
+
+**Differential**: Voltage gets one subtle *technical* hero motion; Plume gets *zero*; Slipstream gets one subtle
+*scroll reveal* — three visibly different intensities, inferred from product nature + audience alone. None reaches for
+3D/WebGL, because none is a spatial/visual product. That restraint is the doctrine working.
+
+## Authoring checklist (for the rationale phase, #886)
+
+- [ ] Default every section to `intensity: none`; raise only on agreement of inputs 1–4.
+- [ ] Every non-`none` entry carries a content-serving `justification` (not "looks premium").
+- [ ] `budget` set from #875 ceilings; `never[]` set from archetype posture + a11y.
+- [ ] Reduced-motion + WebGL/3D fallback covered in `never[]` or per-section notes.
+- [ ] Contrast treated as *expected*, not optional; low contrast flagged as a tell.

package/docs/design/fixtures/briefs/README.md

@@ -0,0 +1,47 @@
+# Seed Briefs — Fixtures
+
+> Reproducible fixtures for the [ABC benchmark](../../abc-benchmark.md) (#878, milestone #13).
+> Each brief is **design-blind** (describes only what the product *does*) and uses an **anonymized**
+> product name. These are the fixed inputs re-run as the harness evolves.
+
+## What a brief is
+
+A brief is the single input shared by all three arms (A = ForgeDock `/design`, B = raw one-shot model,
+C = the real reference). It is derived from a real reference page by **stripping every visual cue** —
+no colors, no typefaces, no layout, no "make it like X" — and keeping only a factual description of what
+the product does, who it is for, and what the page must communicate.
+
+## Anonymization is load-bearing — do not leak the real brand
+
+Each brief maps to a real reference page (arm C), but the brief **must never name the real product or brand**.
+
+A real brand name lets the generation model recall that brand's actual page from training. That measures
+**brand recall, not taste**, and it unfairly inflates arm B (the raw model would reproduce a page it has
+memorized). Treat any real-brand reference inside a brief file as a fixture bug.
+
+The mapping below is kept in this README — **separate from the brief files** — so the generator, which is only
+ever handed a single `*.md` brief, never sees which real page it is being compared against.
+
+## Brief → reference (C) mapping
+
+| Anonymized brief | Real reference (arm C) | Archetype it exemplifies | Category |
+|------------------|------------------------|--------------------------|----------|
+| **Cadence**   | resend.com  | Clean / warm-minimal       | Email API / developer tooling |
+| **Tender**    | stripe.com  | Polished / enterprise-dev  | Payments API |
+| **Slipstream**| vercel.com  | Stark monochrome / brutalist-minimal | Deploy platform |
+| **Voltage**   | modal.com   | Technical / playful        | Serverless compute |
+| **Plume**     | linear.app  | Refined minimal / dark technical-luxury | Issue tracking |
+
+The references and archetypes are drawn from the [reference corpus](../../reference-corpus.md) (#880). The
+mapping is an internal record for scoring and the C-as-calibration check — it is **not** part of the brief
+input handed to any arm.
+
+## Adding a brief
+
+1. Pick a corpus reference (#880) not already represented, or one that adds a distinct archetype.
+2. Strip it to a design-blind, factual product description. Remove every visual cue.
+3. Choose an **anonymized** product name (no resemblance to the real brand).
+4. Save as `fixtures/briefs/<name>.md` following the structure of the existing briefs.
+5. Add the `<name> → real reference` row to the mapping table above.
+6. Keep n high enough: the benchmark runs 3–5 generations per arm across 3–5 products — adding a sixth brief
+   is fine, but never run fewer than three.

package/docs/design/fixtures/briefs/cadence.md

@@ -0,0 +1,39 @@
+# Brief — Cadence
+
+> Design-blind seed brief. Describes only what the product does. No visual direction.
+> Anonymized name — do not infer or reproduce any real brand.
+
+## Product
+
+**Cadence** is an email-sending API for developers and product teams. It lets engineers send
+transactional and marketing email from their applications with a few lines of code, and gives
+non-engineers a way to write, manage, and schedule those emails without touching the codebase.
+
+## Who it's for
+
+Developers integrating email into a product, plus the marketing and product people on the same team
+who own the content of those emails.
+
+## What it does
+
+- A simple REST API and SDKs to send email from application code.
+- Deliverability tooling: domain authentication, suppression handling, and bounce/complaint tracking.
+- A way to author emails as reusable templates, including from React-style components.
+- Analytics on opens, clicks, deliveries, and bounces.
+- A test/preview mode so teams can see an email before it ships.
+
+## What the landing page must communicate
+
+- That sending email from code is genuinely simple here (show, don't claim).
+- That deliverability is handled — the hard, invisible part of email is taken care of.
+- That both engineers and content owners have a place in the workflow.
+- Credibility: this is production infrastructure, not a toy.
+
+## Primary call to action
+
+Get started / sign up with an API key.
+
+## Constraints
+
+- Honest, concrete copy about what the product does — no vague promises.
+- The page should read as current, well-resourced SaaS for a technical audience.

package/docs/design/fixtures/briefs/plume.md

@@ -0,0 +1,39 @@
+# Brief — Plume
+
+> Design-blind seed brief. Describes only what the product does. No visual direction.
+> Anonymized name — do not infer or reproduce any real brand.
+
+## Product
+
+**Plume** is an issue tracking and project management tool for software teams. It is built to be fast and
+keyboard-driven, and it organizes work into issues, cycles, and projects so a team can plan, prioritize,
+and ship without ceremony.
+
+## Who it's for
+
+Software engineering teams and the product and design people who plan alongside them — small, fast-moving
+teams that find traditional project tools heavy.
+
+## What it does
+
+- Issues with statuses, priorities, labels, and assignees, navigable almost entirely by keyboard.
+- Cycles (time-boxed sprints) and longer-running projects to organize work.
+- Roadmap and progress views so leads can see where things stand.
+- Tight integrations with code hosting so issues track real development.
+- A fast, responsive interface that stays out of the way.
+
+## What the landing page must communicate
+
+- Speed and focus: the tool is fast and respects the user's attention.
+- It is opinionated and designed for teams who care about craft.
+- Planning and shipping live in one place, without bureaucracy.
+- A premium, considered product for discerning technical teams.
+
+## Primary call to action
+
+Get started / sign up.
+
+## Constraints
+
+- Crisp, confident copy; minimal and precise.
+- Reads as a refined, premium, well-funded product for technical teams.

package/docs/design/fixtures/briefs/slipstream.md

@@ -0,0 +1,39 @@
+# Brief — Slipstream
+
+> Design-blind seed brief. Describes only what the product does. No visual direction.
+> Anonymized name — do not infer or reproduce any real brand.
+
+## Product
+
+**Slipstream** is a platform for building and deploying web applications. Developers connect a git
+repository and every push is built and deployed automatically to a global edge network, with preview
+environments for each change and zero server management.
+
+## Who it's for
+
+Frontend and full-stack developers and the teams shipping web apps who want to deploy without operating
+infrastructure.
+
+## What it does
+
+- Git-connected deploys: push to a branch, get a live URL.
+- Preview deployments for every pull request, so changes can be reviewed running, not just as a diff.
+- A global edge network and CDN so apps are fast everywhere by default.
+- Serverless and edge functions for backend logic without managing servers.
+- Collaboration features so a whole team can see and comment on deploys.
+
+## What the landing page must communicate
+
+- Speed and immediacy: from push to production is effortless and fast.
+- Zero infrastructure burden — no servers, no ops.
+- It is the obvious home for modern frontend frameworks.
+- Confidence and restraint: this is a serious, opinionated platform.
+
+## Primary call to action
+
+Deploy now / start for free.
+
+## Constraints
+
+- Concrete and direct copy; let the capability speak.
+- Reads as a stark, confident, well-funded developer platform.

package/docs/design/fixtures/briefs/tender.md

@@ -0,0 +1,39 @@
+# Brief — Tender
+
+> Design-blind seed brief. Describes only what the product does. No visual direction.
+> Anonymized name — do not infer or reproduce any real brand.
+
+## Product
+
+**Tender** is a payments platform and API for internet businesses. It lets companies accept payments,
+send payouts, and run subscription billing through a single integration, and handles the regulatory and
+financial plumbing — fraud screening, currency conversion, compliance — on their behalf.
+
+## Who it's for
+
+Engineers building checkout, billing, or marketplace flows, plus finance and operations teams at the
+companies that run on top of those flows.
+
+## What it does
+
+- A unified API to accept cards and local payment methods across many countries and currencies.
+- Subscription and usage-based billing with proration and invoicing.
+- Payouts and money movement for marketplaces and platforms.
+- Fraud detection and risk scoring built in.
+- A dashboard for finance teams to see revenue, disputes, and payouts.
+
+## What the landing page must communicate
+
+- Breadth and reliability: this handles serious money at scale, globally.
+- Developer-first: integration is clean and well-documented.
+- Trust and compliance are handled — the regulated, scary parts are someone else's problem now.
+- It serves both the engineers who integrate and the finance teams who reconcile.
+
+## Primary call to action
+
+Start integrating / view the docs.
+
+## Constraints
+
+- Enterprise-credible but not stuffy; concrete about capabilities.
+- Reads as a high-stakes, well-funded developer platform.

package/docs/design/fixtures/briefs/voltage.md

@@ -0,0 +1,39 @@
+# Brief — Voltage
+
+> Design-blind seed brief. Describes only what the product does. No visual direction.
+> Anonymized name — do not infer or reproduce any real brand.
+
+## Product
+
+**Voltage** is a serverless platform for running compute-heavy and AI workloads. Developers write
+ordinary Python, attach the resources they need — including GPUs — and Voltage runs it in the cloud on
+demand, scaling from zero to thousands of containers and back without provisioning anything.
+
+## Who it's for
+
+Machine-learning engineers, data scientists, and backend developers who need heavy or bursty compute
+(model inference, batch jobs, training) but do not want to manage clusters.
+
+## What it does
+
+- Run Python functions in the cloud by adding a decorator — no Dockerfiles or YAML required.
+- On-demand GPUs and large CPU/memory, billed only while running.
+- Scale to thousands of parallel containers and back to zero automatically.
+- Schedule jobs, serve inference endpoints, and run long batch pipelines.
+- Fast cold starts and a local-feeling developer loop.
+
+## What the landing page must communicate
+
+- Power made simple: serious compute, but the developer experience feels like writing local code.
+- Pay-for-what-you-use economics — idle costs nothing.
+- It is built for the AI/ML era specifically.
+- Technical credibility: the audience is engineers who will read the code sample closely.
+
+## Primary call to action
+
+Run your first function / get started.
+
+## Constraints
+
+- Technical, code-forward copy; show a real usage example in spirit.
+- Reads as a capable, modern, well-funded compute platform.