forgedock 1.0.16 → 1.0.18

package/docs/design/design-spec-schema.md

@@ -0,0 +1,248 @@
+# FORGE:DESIGN_SPEC — Schema
+
+> **Status:** Committed foundation — canonical schema for the UI Taste Harness (milestone #13, issue #881).
+> Output of the [design-architect phase](design-architect-rationale.md) (#886); input to generate + the
+> render-critique loop (#882); enforced by the anti-slop linter (#884); persisted to
+> [design-memory](design-memory.md) (#887) at close. Draws its vocabulary from the
+> [reference corpus](reference-corpus.md) (#880).
+> Extended: `craft` object + `surface_depth` rubric dimension (#1047); `motion.tier`, `motion.hero_technique`,
+> `motion.video_placeholder` fields + `motion` rubric dimension (#1043); `product_mock` field + `product_mock`
+> rubric dimension (#1045); `scroll_narrative` object + `scroll_narrative` rubric dimension (#1046).
+>
+> Registered as a FORGE annotation type in [`../FORGE-PROTOCOL.md`](../FORGE-PROTOCOL.md).
+
+## Purpose
+
+A structured, **machine-checkable** representation of the design language for one page — carried across pipeline
+stages as a `FORGE:DESIGN_SPEC` annotation, exactly like other FORGE annotations carry context. It exists so taste
+decisions **persist** instead of being re-rolled on every generation, and so a deterministic linter and a vision
+critic can both check the output against the *same* committed intent.
+
+Critically: the spec is **produced by the [rationale](design-architect-rationale.md)** (the reasoning), not authored
+from nowhere. Rationale → spec → page.
+
+## Schema
+
+```jsonc
+{
+  "meta": {
+    "product": "Voltage",            // anonymized brief name
+    "archetype": "technical-dense",  // one of the corpus archetypes — committed, not blended
+    "corpus_version": "2026.6",      // which grammar snapshot this was designed against
+    "rationale_ref": "<issue/comment URL of the FORGE:DESIGN_RATIONALE that produced this>"
+  },
+  "typography": {
+    "display_family": "…",           // CONSTRAINT: non-default — never Inter-at-default
+    "body_family": "…",
+    "mono_family": "…",              // optional
+    "scale_ratio": 1.25,             // modular scale; large, confident jumps
+    "base_size_px": 17,
+    "weights": [400, 500, 700],
+    "headline_tracking_em": -0.02
+  },
+  "color": {
+    "mode": "dark",                  // light | dark | auto (dark-first is common)
+    "background": "#…",
+    "foreground": "#…",
+    "accent": "#…",                  // ONE disciplined accent
+    "supporting": ["#…"],
+    "rules": ["no-default-tailwind-palette", "contrast>=4.5"]
+  },
+  "spacing":  { "base_unit_px": 8, "scale": [4,8,12,16,24,32,48,64,96] }, // all spacing on-scale
+  "radius":   { "scale": [4, 8, 16] },   // deliberate system, NOT uniform rounded-everything
+  "shadow":   { "tokens": ["0 1px 2px rgba(0,0,0,.06)", "0 8px 24px rgba(0,0,0,.12)"] }, // soft, low-spread
+  "craft": {                             // see reference-corpus.md#the-craft-vocabulary — #1047
+    "radius_system": {
+      "card_px": 16,                     // CONSTRAINT: distinct_count >= 3 across card/button/badge/input
+      "button_px": 8,
+      "badge_px": 9999,                  // 9999 = pill
+      "input_px": 6
+    },
+    "button": {
+      "depth": "shadow-lift",            // shadow-lift | gradient | flat — flat triggers N14
+      "hover": "shadow+translate",       // how hover is signaled — must not be color-only
+      "active": "press-down",            // translateY(1px) + reduced shadow
+      "focus": "custom-ring"             // custom-ring | none — none triggers N18
+    },
+    "links": {
+      "treatment": "animated-underline", // animated-underline | static-underline | color-only
+      "underline_offset_px": 3,
+      "underline_thickness_px": 1
+    },
+    "icons": {
+      "container": "tinted-square",      // tinted-circle | tinted-square | none
+      "size_context": {                  // different sizes by context — uniform triggers N16
+        "feature_px": 24,
+        "nav_px": 18,
+        "inline_px": 16
+      }
+    },
+    "micro_details": {
+      "custom_selection": true,          // ::selection — false triggers N18
+      "custom_scrollbar": true,          // thin, theme-matched scrollbar
+      "custom_focus_rings": true         // branded focus rings on all interactive elements
+    },
+    "dividers": "spacing-only"           // spacing-only | gradient-fade | hairline | color-shift
+  },
+  "motion": {
+    "tier": 1,                        // 1 = CSS-only | 2 = SVG+JS | 3 = video placeholder — from corpus hero motion vocabulary (#1043)
+    "hero_technique": "text-reveal",  // specific technique id from the corpus tier (e.g. "gradient-shift", "typewriter", "svg-path-draw", "video-scaffold")
+    "video_placeholder": false,       // true = Tier 3 scaffold included — CSS gradient poster generated, drop-in comment in HTML
+    "vocabulary": ["scroll-reveal", "micro-hover"],  // below-fold motion tokens (Tier 1F: scroll-triggered fade-in)
+    "default_ms": 200, "easing": "cubic-bezier(.2,.0,.0,1)",
+    "reduced_motion": "required"      // MUST honor prefers-reduced-motion — @media (prefers-reduced-motion: reduce) on all animated elements
+  },
+  "product_mock": {                  // see reference-corpus.md#interactive-product-mock-vocabulary — #1045
+    "type": "deploy-infra",          // issue-tracker | payment-fintech | deploy-infra | api-developer | email-messaging | none
+    "interactions": [                // select exactly 2 from the per-type list in the corpus
+      "status-building-pulse",       // CSS animation — pulsing dot while deploy is running
+      "deploy-step-progress"         // CSS animation — progress bar filling
+    ],
+    "css_only": true                 // true = CSS-only interactions (preferred) | false = lightweight vanilla JS required (e.g. typing animation, counter)
+  },
+  "scroll_narrative": {              // see reference-corpus.md#below-the-fold-narrative-vocabulary — #1046
+    "section_sequence": [            // committed section order below the fold (derived from rationale step 3 — communication hierarchy)
+      "problem-context",             // section type ids from the corpus scroll narrative vocabulary
+      "solution-showcase",
+      "social-proof",
+      "deep-features",
+      "final-cta"
+    ],
+    "section_count_min": 5,          // total sections including hero — MUST be ≥5 (triggers N25 when < 5)
+    "sticky_nav": true,              // true = nav transforms on scroll (transparent → solid); false = static nav
+    "social_proof_section": "metrics", // logos | metrics | testimonials | none — "none" skips N26 check
+    "cta_placements_min": 2          // minimum CTA count across the full page — must be ≥2 (triggers N27 when < 2)
+  },
+  "layout_grammar": {
+    // ordered sections with purpose + density — MUST NOT be the boilerplate skeleton
+    // (hero → 3 cards → testimonial → CTA). Sections derive from the rationale's communication hierarchy.
+    "sections": [
+      { "id": "hero", "purpose": "…", "density": "low" },
+      { "id": "…",    "purpose": "…", "density": "high" }
+    ],
+    "rhythm": "alternating-density",
+    "intentional_breaks": ["asymmetric hero", "full-bleed product shot"]
+  },
+  "effects_plan": {                  // see effects-appropriateness.md (#885) — reasoned via the effects doctrine, not chosen blindly
+    "per_section": [
+      { "section": "hero", "effect": "subtle-technical-visualization", "intensity": "low",
+        "justification": "product is GPU-compute; one earned hero centerpiece" }
+    ],
+    "budget": { "lcp_ms": 2000, "max_js_kb": 150 },
+    "never": ["3d-on-non-hero", "parallax-on-pricing"]
+  },
+  "negatives": [ /* anti-slop checklist pulled from corpus — linter + critic both check */ ],
+  "acceptance": {
+    "perf_budget": { "lcp_ms": 2000, "cls": 0.1, "inp_ms": 200 },
+    "a11y": { "contrast_min": 4.5, "reduced_motion": true },
+    "divergence_ref": "<design-memory check result — see #887>"
+  }
+}
+```
+
+## How each field defends against slop
+
+| Field | Defends against |
+|---|---|
+| `archetype` (committed) | mode-collapse to the mean (forces a tail direction, not the average) |
+| `typography.display_family` non-default | the Inter-default tell |
+| `color.rules: no-default-tailwind-palette` | slate/indigo "AI gradient" tell |
+| `spacing.scale` (on-scale only) | arbitrary padding / no rhythm |
+| `layout_grammar` (non-boilerplate) | the hero→3-cards→testimonial→CTA skeleton |
+| `effects_plan` (justified + budgeted) — doctrine: [effects-appropriateness](effects-appropriateness.md) (#885) | gratuitous 3D/parallax; perf blowups |
+| `acceptance.perf_budget` | "earned its milliseconds" becomes objective (via Playwright, #875) |
+| `craft.radius_system` (`distinct_count >= 3`) | one-radius-fits-all AI tell (N13) |
+| `craft.button.depth` (not `flat`) | flat Tailwind button with no depth (N14) |
+| `craft.micro_details.custom_selection` + `custom_focus_rings` | missing branded micro-details (N18) |
+| `craft.icons.size_context` (distinct sizes by context) | default uniform icon treatment (N16) |
+| `craft.links.treatment` (not `color-only`) | bare color-only or browser-default link treatment (N17) |
+| `motion.tier` + `motion.hero_technique` (committed) | static hero with no motion — the "poster" tell (N21); jQuery-era effects (N23) |
+| `motion.reduced_motion: "required"` | motion that ignores `prefers-reduced-motion` — accessibility violation |
+| `motion.video_placeholder: true` (when applicable) | video-shaped hero gap: empty space where a demo would go, or placeholder image with no scaffolding |
+| `product_mock.type` (committed, not `none`) | static product screenshot in a browser frame with no interactions — the "screenshot poster" tell (N24) |
+| `product_mock.interactions` (exactly 2 selected) | mock with too many interactions (demo feel) or zero interactions (static poster) |
+| `product_mock.css_only: false` acknowledged explicitly | lightweight JS used without acknowledgement; framework dependency creeping in |
+| `scroll_narrative.section_count_min` (≥5) | hero-only page with no narrative arc — the "above-the-fold only" tell (N25) |
+| `scroll_narrative.social_proof_section` (committed, not `none`) | missing social proof section — page makes claims without third-party validation (N26) |
+| `scroll_narrative.cta_placements_min` (≥2) | single CTA at hero only — convinced visitors at the bottom of the page have nowhere to convert (N27) |
+| `scroll_narrative.sticky_nav` (committed) | nav disappears on scroll — brand and primary CTA lost mid-narrative |
+
+## Benchmark rubric dimensions
+
+The ABC benchmark (#878) evaluates generated pages on a 1–5 rubric. The `craft` field extension (#1047) added
+two dimensions (`surface_depth`, `craft`); the `motion` field extension (#1043) adds a seventh dimension;
+the `scroll_narrative` field extension (#1046) adds a ninth dimension.
+
+| Dimension | What it measures | 1 (worst) | 5 (best) |
+|---|---|---|---|
+| `typography` | Type hierarchy, scale, non-default faces | System font, single weight, no scale | Non-default face, confident scale ratio, tight tracking |
+| `color` | Palette restraint, accent discipline, contrast | Default Tailwind palette, multiple loud accents | Near-monochrome + one disciplined accent, ≥4.5 contrast |
+| `surface_depth` | Shadows, borders, radius system, layering | Flat, no depth cues, uniform radius | Soft multi-token shadows, 3+ distinct radii, clear z-layering |
+| `craft` | Micro-detail quality — buttons, links, icons, forms, micro-details | All framework defaults, no custom states | Custom depth on buttons, animated links, tinted icon containers, branded micro-details |
+| `layout` | Grid, asymmetry, negative space, section rhythm | Centered columns, uniform padding, boilerplate skeleton | Deliberate grid breaks, asymmetry, spacing-as-divider |
+| `effects` | Effect appropriateness and restraint | Gratuitous 3D/parallax on non-visual product | Effects justified by product nature, performance-budgeted |
+| `motion` | Hero vitality — appropriate motion technique committed and executed per archetype | Static hero (poster) — N21 hit; or jQuery-era effects — N23 hit | Archetype-appropriate tier selected, `prefers-reduced-motion` honored, at most 2 simultaneous motion elements |
+| `product_mock` | Product mock interactivity — browser-chrome wrapper with live micro-interactions vs. static screenshot | No mock present, or mock with no interaction — N24 hit | Product type correctly identified, 2 interactions committed from vocabulary, CSS-only preferred, `prefers-reduced-motion` honored |
+| `scroll_narrative` | Full-page narrative completeness — below-fold section depth, social proof presence, CTA rhythm | Hero-only page, no below-fold narrative, single CTA — N25/N26/N27 hit | ≥5 sections committed and generated, social proof section present and animated, ≥2 CTAs placed at narrative milestones |
+
+The `craft` and `surface_depth` dimensions are new in `corpus_version: 2026.3` (#1047). The `motion` dimension
+is new in `corpus_version: 2026.4` (#1043). The `product_mock` dimension is new in `corpus_version: 2026.5`
+(#1045). The `scroll_narrative` dimension is new in `corpus_version: 2026.6` (#1046). Past benchmark runs scored
+under a 4-dimension rubric (no `surface_depth`, `craft`, `motion`, `product_mock`, or `scroll_narrative`).
+Comparison across versions must note the rubric version.
+
+## Section-level surgical re-generation contract
+
+<!-- Added: forge#1044 — user-feedback loop -->
+
+The `layout_grammar.sections` array is the structural hook for **targeted, section-only edits**. Each section carries
+an `id` (e.g. `"hero"`, `"features"`, `"pricing"`), a `purpose`, and a `density`. This structure enables Stage 4.5 of
+the `/design` pipeline (user-feedback loop, #1044) to re-generate a single section without touching the rest of the
+page.
+
+### Rules for surgical re-generation
+
+1. **Section IDs are the targeting key.** When `FORGE:USER_FEEDBACK` names a `section_target`, the re-generation agent
+   receives: the full current HTML + the FORGE:DESIGN_SPEC + the feedback for that section ID only. It produces a
+   replacement for that section's markup and nothing else.
+
+1.5. **`"all"` is the page-wide sentinel.** When `section_target == "all"`, the re-generation agent applies the modification as a global pass — updating CSS custom properties (color palette, typography scale) that span all sections — without replacing any individual section's markup. <!-- Added: forge#1057 -->
+
+2. **Committed archetype and signature move are locked.** User feedback can modify a section's visual execution
+   (motion, layout detail, asset placement, color treatment) but MUST NOT change the committed `meta.archetype` or the
+   signature move recorded in `FORGE:DESIGN_RATIONALE`. Those choices were the architect's and are fixed once the spec
+   is committed. If a user requests a direction change that would require a different archetype, the feedback loop
+   should note the constraint and suggest the closest achievable variation within the committed direction.
+
+3. **The spec is the source of truth for all non-targeted sections.** Sections not named in `section_target` are
+   reproduced from the committed spec unchanged — no style drift, no re-rolling of other sections' taste decisions.
+
+4. **`effects_plan.per_section` updates are allowed.** If feedback changes the hero's visual treatment (e.g., adds a
+   product video, changes the motion vocabulary), the `effects_plan.per_section` entry for that section may be updated
+   in a revised FORGE:DESIGN_SPEC annotation — this is the only part of the spec a feedback iteration may mutate.
+
+5. **Benchmark bypass.** Section-level re-generation is triggered by user presence (Stage 4.5). The ABC benchmark arm A
+   runs non-interactively and bypasses Stage 4.5 entirely — automated runs proceed directly from Stage 4 to Stage 5.
+
+### Asset integration via section targeting
+
+When `FORGE:USER_FEEDBACK` carries an asset, the re-generation agent applies it to the `section_target`:
+
+| Asset type | Section target | Integration |
+|---|---|---|
+| Video URL (mp4/webm) | `hero` | Replace or augment hero visual with `<video autoplay loop muted playsinline>` scaffold; adjust hero layout to accommodate |
+| Video embed URL (YouTube/Vimeo) | `hero` | `<iframe>` with `loading="lazy"`, aspect-ratio container, no autoplay |
+| Logo SVG | `nav` / `hero` | Replace text logo node; adjust `width`/`height` to maintain proportional sizing; verify contrast against background |
+| Brand hex colors | any | Update `color.*` CSS custom properties matching the section; run contrast check (WCAG AA ≥ 4.5:1) before emitting |
+| Product screenshot/image | `hero` / `features` | Replace placeholder with `<img>` or `background-image`; maintain existing sizing/aspect-ratio tokens |
+
+## Lifecycle
+
+1. **architect** (#886) emits this spec from the rationale.
+2. **generate** produces HTML constrained by it.
+3. **linter** ([`design-system-lint.mjs`](design-system-lint.md), #884) checks deterministic fields (palette, spacing, radius, layout skeleton, craft.radius_system, craft.button.depth, craft.micro_details).
+4. **critique loop** (#882) renders + checks `negatives`, `effects_plan` justification, and `acceptance` against the
+   rendered result; iterates until pass.
+4.5. **user-feedback loop** (#1044) prompts for hero-specific user input; applies surgical section-level re-generation
+   using section IDs as targeting keys; bypassed in automated (benchmark) runs.
+5. **close** writes the realized spec + outcome to [design-memory](design-memory.md) (#887).

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.