npm - dreative - Versions diffs - 0.5.0 → 0.5.2 - Mend

dreative 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (48) hide show

package/README.md +49 -27
package/dist/cli/audit.js +206 -0
package/dist/cli/audit.test.js +79 -0
package/dist/cli/docsCheck.js +163 -0
package/dist/cli/docsCheck.test.js +8 -0
package/dist/cli/index.js +81 -8
package/dist/server/preview.js +73 -73
package/dist/server/store.js +11 -0
package/dist/shared/artifacts.js +162 -0
package/dist/shared/design.js +42 -22
package/dist/shared/ruleSystem.js +130 -0
package/dist/shared/ruleSystem.test.js +187 -0
package/dist/shared/skillSystem.js +173 -0
package/dist/shared/skillSystem.test.js +110 -0
package/dist/ui/assets/{index--vztc_MR.js → index-CKwmbx2j.js} +13 -13
package/dist/ui/index.html +12 -12
package/package.json +5 -3
package/skill/dreative/DESIGN.md +290 -95
package/skill/dreative/PLAN.md +462 -71
package/skill/dreative/SKILL.md +230 -126
package/skill/dreative/frameworks/nextjs.md +13 -0
package/skill/dreative/frameworks/react-vite.md +12 -0
package/skill/dreative/frameworks/styling.md +14 -0
package/skill/dreative/frameworks/sveltekit.md +10 -0
package/skill/dreative/frameworks/vue-nuxt.md +12 -0
package/skill/dreative/recipes/3d-recipes.md +44 -0
package/skill/dreative/recipes/cinematic-recipes.md +19 -0
package/skill/dreative/recipes/immersive-recipes.md +18 -0
package/skill/dreative/recipes/media-recipes.md +60 -0
package/skill/dreative/recipes/motion-recipes.md +44 -0
package/skill/dreative/references/ARTIFACTS.md +180 -0
package/skill/dreative/references/REFLEX_FONTS.json +44 -0
package/skill/dreative/references/RULES.json +186 -0
package/skill/dreative/references/SKILL_CONTRACT.md +30 -0
package/skill/dreative/references/TIERS.md +42 -0
package/skill/dreative/schemas/plan.schema.json +241 -0
package/skill/dreative/schemas/verify.schema.json +61 -0
package/skill/dreative/skills/3d.md +94 -157
package/skill/dreative/skills/cinematic.md +56 -232
package/skill/dreative/skills/experimental.md +111 -0
package/skill/dreative/skills/immersive.md +61 -223
package/skill/dreative/skills/interaction.md +9 -1
package/skill/dreative/skills/media.md +135 -216
package/skill/dreative/skills/mobile.md +128 -117
package/skill/dreative/skills/motion.md +89 -229
package/skill/dreative/skills/refined.md +116 -102
package/skill/dreative/skills/ux.md +155 -144
package/dist/server/ai.js +0 -177

package/dist/ui/index.html CHANGED Viewed

@@ -1,13 +1,13 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Dreative</title>
-    <script type="module" crossorigin src="/assets/index--vztc_MR.js"></script>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Dreative</title>
+    <script type="module" crossorigin src="/assets/index-CKwmbx2j.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-y0gVjC7u.css">
-  </head>
-  <body>
-    <div id="root"></div>
-  </body>
-</html>
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "dreative",
-  "version": "0.5.0",
-  "description": "Layout-first visual editor skill for coding CLIs: extract your app's UI into editable wireframes, tweak with drag-drop + ref images, then the agent applies the diff back to your code.",
+  "version": "0.5.2",
+  "description": "Frontend design skill for coding CLIs with typed planning, specialist treatments, verification, and an optional visual editor.",
   "type": "module",
   "bin": {
     "dreative": "dist/cli/index.js"
@@ -14,7 +14,9 @@
     "build": "npm run build:server && npm run build:ui",
     "prepublishOnly": "npm run build",
     "build:server": "tsc -p tsconfig.json",
-    "build:ui": "vite build",
+    "build:ui": "vite build",
+    "test": "npm run build:server && node --test dist/shared/*.test.js dist/cli/*.test.js",
+    "docs-check": "npm run build:server && node dist/cli/index.js docs-check",
     "dev": "concurrently \"tsx watch src/cli/index.ts --no-open\" \"vite\"",
     "start": "node dist/cli/index.js"
   },

package/skill/dreative/DESIGN.md CHANGED Viewed

@@ -2,8 +2,8 @@
 You MUST read this file before servicing any `propose-skeletons`, `propose-variants`,
 `design-page`, or `edit-element` request, and run §12 before every respond. It exists
-because LLM-designed UIs converge on one templated look. Every rule corrects a known
-model default; none is a suggestion. Requests may carry a `plan` (Dreative's
+because LLM-designed UIs converge on one templated look. Every rule corrects a known
+model default, but its category determines how it governs. Requests may carry a `plan` (Dreative's
 pre-computed decision: dials, per-section layout families, budgets, lints) — execute
 the plan, apply this doctrine to everything the plan doesn't specify. When
 `plan.skills` names specialist skills (`motion`, `3d`, `interaction`, `immersive`,
@@ -11,6 +11,17 @@ the plan, apply this doctrine to everything the plan doesn't specify. When
 `skills/<name>.md` files extend this doctrine for that request — read them first;
 where they go deeper than a section here, they win.
+Rules use the three categories in `references/RULES.json`. **Hard gates** cover
+objective failures—preservation, functionality, mobile/reduced motion, content
+visibility, spatial integrity, organic-subject honesty, fallbacks, assets, and
+real verification—and cannot be waived. **Evidence-backed defaults** are proven
+remedies for repeated dogfood failures; follow them or declare a planning-time
+alternative with measurable criteria and runtime evidence. **Creative
+provocations** force divergent exploration but do not become shipment checklists.
+When attention is scarce, hard gates outrank defaults, and defaults outrank
+stylistic preference—but a page that only clears gates and shows no point of
+view is still a failure of this file.
 ## 1. Register: the first decision
 Every page is one of two registers. Misclassifying it is the biggest single error.
@@ -48,21 +59,145 @@ Then run three tests on your intended output; restart if any fails:
 3. **Competitor sentence**: describe what you're about to build as a competitor would
    describe theirs. If the sentence fits the modal page in the category, restart.
-### The working process: commit before code
-Never design by accretion. Two passes:
-1. **Commit** — before any code, write a compact spec: 4-6 named colors (hex/OKLCH),
+### The working process: explore, commit, review — before code
+Never design by accretion, and never commit to the first concept. Three passes:
+1. **Explore** — sketch THREE genuinely divergent concepts, one line each:
+   palette strategy + type voice + signature element + hero thesis. Different
+   families of idea, not three shades of one (if two concepts share a palette
+   strategy or signature type, they are one concept — replace one). The slop
+   tests below are filters: they reject bad ideas but never generate better
+   ones; this pass is where a better idea gets a chance to exist. Pick one,
+   and record the two rejects with a one-line reason in the plan file
+   (PLAN.md §4).
+   **The entropy draw (before sketching, at expressive/award ambition).** Your
+   "random" pick is your reflex — the same fonts, the same hero move, run
+   after run. So the variance comes from OUTSIDE your head: roll a real random
+   number (`node -e "console.log(1+require('crypto').randomInt(20))"`, or
+   `$RANDOM % 20 + 1`, or read digits off `date +%N`) and record the literal
+   command AND its output in plan.md. The roll picks one **provocation** from
+   the table below; at least ONE of the three explore concepts must take it
+   literally. If that concept wins, the provocation becomes a candidate;
+   experimental delivery selects only the strongest two or three peaks instead
+   of forcing every candidate to ship. Roll a second number (1–6) to pick a **forced-rotation
+   axis** — 1 palette strategy · 2 type voice · 3 hero concept · 4 nav/page
+   architecture · 5 signature driver · 6 set-piece family — and that axis must
+   differ from anything in your ledger's last 3 entries AND from the most
+   obvious genre default. One re-roll is allowed per table if the result is
+   genuinely incompatible with the brief or usability — record both rolls and
+   the reason. A plan file with no recorded roll at expressive+ is incomplete.
+   **Provocation table (roll 1–20):**
+   1. The hero image is not a rectangle.
+   2. One image behaves like a physical object — mass, drag, inertia, release.
+   3. Type and imagery share one depth space; one passes through the other.
+   4. The page has a light source, and media visibly responds to it.
+   5. Scroll does something besides move the page down in one section.
+   6. The cursor is an instrument from the subject's world and acts on media.
+   7. One section is traversed by dragging, not scrolling.
+   8. An image disassembles into what it is physically made of.
+   9. Media leaks outside its frame and touches the UI around it.
+   10. Something never stops moving, slowly, for the whole visit.
+   11. The visitor's behavior (speed, hesitation, return) changes an element.
+   12. Two media assets visibly react to each other.
+   13. A transition destroys something that reassembles as something else.
+   14. The palette of a chapter is sampled live from the media on screen.
+   15. One interaction hands the visitor control they didn't expect to have.
+   16. Something pulses to an invisible rhythm, like sound with the audio cut.
+   17. The signature element recurs at three scales/roles across the page.
+   18. An ordinary control (button, input, nav) is built from the scene itself.
+   19. One moment of true depth: layers visibly separate and re-stack.
+   20. The final section answers the hero — a visual callback with a twist.
+2. **Commit** — write the winner as a compact spec: 4-6 named colors (hex/OKLCH),
    2+ type roles with actual font names, a one-sentence layout description per
-   section, and ONE **signature element** — the single memorable move (an
-   interaction, a typographic device, a composition) that carries the page's
-   distinctiveness. Spend your boldness there; keep everything around it disciplined
-   and quiet. Ground choices in the subject's world: its materials, instruments,
-   artifacts, and vernacular ("a coffee brand's world: burlap, roast curves,
-   thermometers, cupping notes") — not in web-design tropes.
-2. **Review** — test the spec against the slop tests below. If any part could apply
+   section, the **compositional spine** (§5), the page's ACTUAL hero headline
+   plus 2-3 section headlines written in the brand's voice (copy precedes
+   layout — type and composition are designed around real words, never
+   lorem-shaped assumptions; §8 governs the writing), and ONE **signature
+   element** with a mini-spec of its own: what it is, what drives it
+   (scroll / cursor / time / data), and why it could only belong to THIS brand
+   (subject-world grounding) — plus a novelty check: seen on a template, or in
+   your own ledger (below)? Invent again. Spend your boldness there; keep
+   everything around it disciplined and quiet. Ground choices in the subject's
+   world: its materials, instruments, artifacts, and vernacular ("a coffee
+   brand's world: burlap, roast curves, thermometers, cupping notes") — not in
+   web-design tropes.
+3. **Review** — test the spec against the slop tests below. If any part could apply
    to any similar project, revise that part. Only then build.
+**The choice ledger (anti-self-similarity across projects).** Slop tests can't
+see your own history — repeating yourself project after project is a
+monoculture of one. A global ledger at `~/.dreative/ledger.md` records one
+line per completed build: date · project · display/body fonts · palette
+strategy + hue · signature-element type · hero concept. During the commit
+pass, read it if it exists: anything in the new spec that repeats an axis
+from the last 3 entries is now YOUR reflex — rework that axis. After
+verification, append this build's line (create the file if missing). The
+ledger is also a taste memory: when the user gives a verdict on a shipped
+build ("the hero feels generic", "too much motion"), append it to that
+build's entry as a one-line `lesson:` — and the commit pass reads lessons
+alongside choices, so the same critique never has to be given twice.
+**No-media builds: structure IS the media.** When a build ships zero
+imagery (no image-gen tool, product register, or the user chose
+placeholders), the ambition tier does NOT tier down — it transfers whole
+onto layout, type, and motion, and this is where no-media builds die: the
+executor, with no assets to arrange, collapses to the one layout it knows
+(a vertical list of rounded cards in a centered column) and ships slop that
+its own plan didn't describe. Hard rules for any expressive+ no-media build:
+1. **The compositional spine must survive to the screenshot.** Whatever
+   bespoke structure the plan named (a strip rack, a ledger, a switchboard,
+   a timetable) must be RECOGNIZABLE as that thing in the shipped page — its
+   physical vocabulary built for real: the holder edge, the notch, the rail,
+   the perforation, the column rules. If a stranger shown the screenshot and
+   the blueprint's layout-family words couldn't match them, the build
+   restyled a card list and called it the spine — that is a depth-honesty
+   failure (§11), not a detail.
+2. **≥ 2 bespoke drawn/procedural artifacts.** With no photography, the page
+   earns visual richness from things MADE for it: a live canvas (meter,
+   field, trace), custom SVG structure (rules, notches, connectors, dials —
+   drawn, not icon-font), procedural texture/grain, a data-driven ornament.
+   A no-media page whose only visuals are borders and border-radius has no
+   media plan at all.
+3. **Type does structural work.** Multi-scale composition (oversized
+   numerals/designators against small mono metadata), real hierarchy per §6
+   — not one font-size row layout repeated N times.
+4. **Motion budget spends on the structure**, not on entrance fades: the
+   spine's own physicality (things racked, tossed, slid, stamped) is the
+   choreography. Motion.md's inventory applies at full dial.
+5. **A live rendered layer is required at award tier.** No imagery does not
+   mean no rendering: the page ships at least one WebGL/canvas system doing
+   real graphic work — a particle field, procedural texture/flowfield,
+   shader-lit surface, a data-driven instrument that never stops — plus
+   dimensional motion somewhere real (CSS 3D card physicality, depth-layered
+   parallax, a lit WebGL surface). A no-media award page with zero rendered
+   pixels is a text document with transitions. Vocabulary to draw from
+   (subject-grounded, not decorative): oscilloscope/waveform traces driven by
+   real events · topographic contour lines drifting · dot-matrix/LED field
+   that spells live state · plexus line-network connecting related items ·
+   isometric grid that lights under the cursor · scan sweep across data
+   rows · ASCII/character rain in the brand's glyphs · particle flow along
+   the layout's own rails · generative engraving borders · a physical sim
+   (springs, gravity) on the UI's actual objects.
+6. **Layout creativity means spatial composition, not relocated chrome.**
+   Moving the nav to the bottom, a novel tab bar, an unusual dock — that is
+   furniture rearrangement, and if it's the build's ONLY inventive move the
+   build failed. The invention must live in how the CONTENT is composed:
+   asymmetric multi-scale grids, overlapping planes, diagonal/rotated flow,
+   sections that share edges and interlock — while staying rigorously
+   modern and clean (generous space, disciplined alignment, few colors).
+   "Clean" and "insane motion" are the same build: calm composition,
+   spectacular behavior.
+The slop tests above apply to the RENDERED page: "dark theme + rounded
+cards + one accent color" fails the competitor sentence for every no-media
+product tool at once — and shipped exactly that once (user verdict on
+record: "pure ai slop… I would not want something like that again"). Treat
+these rules as a shipped-failure postmortem, not theory.
 **Hero thesis:** open with the most characteristic thing in the subject's world —
 a headline, an image, a live demo, an interactive moment. Whatever form fits.
@@ -87,20 +222,27 @@ a headline, an image, a live demo, an interactive moment. Whatever form fits.
 ## 3. Typography
-**Font selection procedure (brand register, never skip):**
-1. Write three physical-object brand-voice words ("warm, mechanical, opinionated" —
-   never "modern" or "elegant").
-2. List the three fonts you'd reach for by reflex. Reject any on the ban list below.
-3. Pick for the brand as a physical object (museum caption, 1970s terminal manual,
-   concert poster, mid-century receipt). Reject the first thing that "looks designy".
-4. If the final pick matches the original reflex, start over.
-**Reflex-reject fonts (training-data defaults, banned as defaults):** Fraunces,
-Newsreader, Lora, Crimson (all), Playfair Display, Cormorant (all), Syne, IBM Plex
-(all), Space Mono, Space Grotesk, Inter, DM Sans/Serif, Outfit, Plus Jakarta Sans,
-Instrument Sans/Serif. Inter/system stacks ARE legitimate in the product register
-and for trust briefs. When an existing app already uses one, identity-preservation
-wins — keep it.
+**Font selection procedure (brand register, never skip):**
+1. Write three physical-object brand-voice words ("warm, mechanical, opinionated" —
+   never "modern" or "elegant").
+2. Read the last three display fonts from the design ledger and generate at least
+   three candidates for this brand, including continuity candidates when an
+   existing identity or design system matters.
+3. Mark candidates found in `references/REFLEX_FONTS.json`. A reflex font is not
+   bad or prohibited; it is a frequently unexamined choice that needs a specific
+   reason if it wins.
+4. Pick for the brand as a physical object (museum caption, 1970s terminal manual,
+   concert poster, mid-century receipt), supplied reference, product metrics,
+   language coverage, variable-font capability, or performance constraint.
+5. Record candidates and the winner in `plan.fontDecision`. If the winner is a
+   reflex font, record the concrete justification and at least one registry
+   category in `reasonKinds`. If it repeats one of the last three display fonts,
+   add a stronger repeat justification.
+Valid reflex-font reason: "Inter is already embedded throughout this authenticated
+product, preserves its density metrics and translated layout, and changing it
+would damage brand continuity." Invalid reason: "Inter looks clean and modern."
+The goal is to stop reflex selection, not to declare common fonts inherently bad.
 **Serif discipline:** "creative/premium brief = serif" is the most-tested AI tell.
 Default is sans display. Serif only when the brief is genuinely editorial/luxury/
@@ -175,6 +317,16 @@ When redesigning an extracted app, its `theme` colors are the brand — preserve
 ## 5. Layout
+**Compositional spine (brand register, whenever variance > 4 or ambition is
+expressive+).** Color and type get selection procedures; composition deserves
+one too — the rules below only bound a layout, they don't give it a point of
+view. Before applying them, derive ONE structural idea from a physical
+artifact in the subject's world and let it organize the page: a vinyl label's
+concentric rings → a radial hero; a boarding pass's rule structure → the
+page grid; a contact sheet → the gallery; a cupping form → the comparison
+table. Name artifact → idea in the commit spec (§2). The memorable award
+sites win on composition, not decoration; this is where that happens.
 **Hard rules (failing any = broken work):**
 - Hero fits the initial viewport: headline ≤ 2 lines, subtext ≤ 20 words, CTA visible
   without scroll, top padding ≤ pt-24. 4-line headline is a font-size error. Max 4
@@ -260,65 +412,53 @@ library (Phosphor/Radix/Tabler/HugeIcons; Lucide only on request), one strokeWid
 globally. Logo walls: real SVG marks (`https://cdn.simpleicons.org/<slug>`) or
 generated monograms — logos only, no category captions, below the hero.
-### Generated media (probe your environment, then use it)
-Before designing, check what media generation your environment actually offers —
-image-gen tools, video-gen tools, or a CLI that can produce them — and treat any
-capability found as a first-class design material, not a nice-to-have:
-- **Images**: generate hero photography, product/context shots, and textures at
-  the section's exact aspect ratio, prompted for the brand's physical subject
-  and the page's light temperature so they grade into the palette. Generate the
-  grain tile and any masks/mattes too instead of hand-rolling SVG.
-- **Video**: a generated 5–10s seamless loop is one of the biggest single UI
-  upgrades available — use it as: a hero background (muted, `autoplay loop
-  playsinline`, poster frame, `prefers-reduced-motion` swaps to the poster);
-  the budget "living surface" (a pre-rendered fluid/particle/atmosphere loop
-  instead of a GPGPU sim — cinematic.md's budget recipe); hover-preview loops
-  on work cards; or an image-sequence for scroll-scrubbed narratives (export
-  frames, scrub per motion.md).
-- **Integrate with motion, don't just embed** — a raw `<video>`/`<img>` dropped
-  in a section is not the treatment. Generated media enters the page THROUGH the
-  motion system; pick 1–2 treatments per page from this vocabulary (or invent in
-  its spirit), matched to the register:
-  - **Pixel/dither reveal**: video or image materializes from coarse blocks —
-    a shader that lerps sample resolution from ~24px mosaic to full res (or a
-    stepped `image-rendering: pixelated` downscale swap for the budget path),
-    driven by scroll progress or hover. Reads as digital-craft; dark-tech and
-    editorial registers.
-  - **Floating media**: images hover in depth with slow damped drift (±6-10px,
-    4-8s loops, each at a different phase), subtle parallax by depth layer, and
-    a soft contact shadow — the immersive "paper sheets in space" look without
-    WebGL. Cap at 3-5 floaters per view.
-  - **Mask-shaped video**: the loop plays inside display type (`background-clip:
-    text` / SVG mask on a 10vw+ headline), an arch/circle clip-path, or the
-    brand mark — the video becomes typography/identity rather than a rectangle.
-  - **Scroll-scrubbed sequence**: generated frames scrubbed by scroll for
-    assemble/morph/rotate narratives (motion.md's canvas product story).
-  - **Velocity-touched media**: scroll/drag velocity stretches, RGB-splits, or
-    ripples the media plane for a beat, settling with damped decay
-    (cinematic.md §2) — needs the WebGL media-plane sync.
-  - **Hover-woken loops**: stills that crossfade into their video loop on
-    hover/focus (240ms), pause + rewind-to-poster on leave; works as generated
-    "living thumbnails" on work/product cards.
-  - **Curtain/split reveal**: media enters behind a 2-4 panel wipe or an
-    expanding inset clip (`clip-path: inset(40% 30%) → inset(0)`), timed with
-    the section's line-mask type reveal so image and headline arrive as one
-    choreographed beat.
-  Whatever the treatment, honor the floors: reduced-motion gets the poster
-  frame, hover treatments have focus equivalents, and the effect is justified
-  in one sentence like any other motion (§6).
-- Discipline: same rationing as everything else — one video loop per view,
-  compress hard (H.264/AV1, ≤ 2–4MB per loop, no audio track), lazy-load below
-  the fold, and never let generated media replace REAL product screenshots or
-  the client's actual photography when those exist.
-- If no generation capability exists, say so and fall back down the §7 priority
-  list — never fake a video with a div animation.
-- `skills/media.md` is this section's deep dive: the production pipeline
-  (prompting for the page's light, compression targets, frame sequences), the
-  full DOM-tier and WebGL media-plane treatment vocabulary, and the
-  entrance/idle/response reasoning frame. Read it whenever generated media or
-  motion-integrated imagery ships.
+### Generated media (probe your environment, then use it)
+Before designing, check what media generation your environment actually offers —
+image-gen tools, video-gen tools, or a CLI that can produce them — and treat any
+capability found as a first-class design material, not a nice-to-have. Generate
+for the section's exact ratio, physical subject, and light temperature. Preserve
+real product screenshots and supplied photography when they are authoritative.
+Do not choose a media treatment from a catalog here. First record three original
+brand-native concepts in `conceptExploration`; then read `skills/media.md` for
+principles. Open `recipes/media-recipes.md` only afterward for feasibility,
+implementation, performance, or fallback guidance, and log that access in
+`recipeAccess`. A raw `<video>` or `<img>` is not a treatment: the chosen media
+system must develop the concept and retain poster/static, focus/touch, reduced-
+motion, low-power, and loading fallbacks. If generation is unavailable, use the
+§7 source priority instead of simulating media with decorative divs.
+### Surface & light — material identity for every layer
+Flat untreated hex fills are the loudest AI tell after Inter-everywhere: real
+designed surfaces are MADE of something and sit under a light. At expressive+
+ambition every major surface (page background, hero, cards/panels, media
+frames) carries at least one deliberate material cue, and the page declares
+ONE light direction that everything obeys:
+- **Grain/noise** — a 1-3% opacity tileable PNG/WebP noise overlay (one shared
+  asset; never `feTurbulence`) kills gradient banding and digital
+  flatness; vary its intensity by section as part of the pacing curve.
+- **Light consistency** — pick the light's direction once; every shadow,
+  edge-highlight, gradient hotspot, and 3D/scene light agrees with it. Tint
+  shadows toward the background hue (never pure black); give elevated
+  elements a subtle top edge-light (1px inset highlight) on dark themes.
+- **Gradients are graded, not defaulted** — two neighbouring hues from the
+  palette with a noise/dither pass, or a radial hotspot placed where the
+  light is; never the template diagonal of two loud complementaries.
+- **Depth is layered, not dropped** — combine a tinted ambient shadow + a
+  tighter contact shadow instead of one big blur; `backdrop-filter` glass
+  only where content actually passes beneath it.
+- **Type can be a surface too** — one display moment per page may carry
+  material (image/video masked into headline glyphs via `background-clip`,
+  a light sweep, foil/emboss shading) when the register supports it; body
+  text never does.
+Clean registers (refined/product/brutalist) obey the same physics with
+quieter amplitudes — grain nearly invisible, shadows tighter, no masked
+type — the discipline is identical, only the volume changes. "Clean" is a
+designed material choice, never the absence of one.
 ## 8. Content and copy
@@ -375,6 +515,23 @@ product-register page and any redesign touching navigation, forms, or state.
   elements (animate the card's border/background/shadow instead).
 - Headline text that overflows its container at any breakpoint — test the actual
   copy; the viewport is part of the design.
+- **The generic SaaS-template hero, banned by name.** Dark navy/purple
+  background with a soft color-blob (pink→orange or purple→blue) behind bold
+  sans headline ("We Make Brands Shine" register), an orange/pink gradient
+  pill CTA next to a ghost-outline secondary button, and a plain top nav —
+  this exact composition is what every ungrounded LLM defaults to and reads
+  as a template regardless of copy. If the in-progress design converges on
+  this (gradient-blob backdrop + gradient-pill CTA + generic bold claim
+  headline), stop and change at least the background treatment, the CTA
+  material, and the headline's specific claim before continuing.
+- **Zero leaked tool/placeholder artifacts in shipped output, ever, no
+  exceptions.** Things like `[Image #1]`, `[Image: source: ...]`, `<image
+  placeholder>`, alt-text strings, markdown image syntax, or any other
+  tool/generation-pipeline token must never render as visible text/alt/aria
+  content on the page — this is the single most obvious "an LLM built this"
+  tell there is. Before shipping, grep the built output for `\[Image`,
+  `placeholder`, and any literal file paths from the generation pipeline; a
+  hit is a shipped bug, not a minor cosmetic issue.
 ## 11. Redesign and preservation (extracted apps)
@@ -510,7 +667,10 @@ rules for whatever the user said to keep (routes, legal copy, form semantics).
 Mentally verify; fix failures, then respond. If a box cannot be honestly ticked,
 the output is not done.
-0. Commit pass done: named palette, named fonts, one signature element, subject-
+0. Explore + commit passes done: three divergent concepts sketched (rejects
+   recorded in the plan file), named palette, named fonts, real headlines
+   written, compositional spine named (when §5 requires it), signature element
+   with mini-spec + novelty check, choice ledger consulted (§2), subject-
    grounded. The quality floor (responsive to mobile, visible keyboard focus,
    reduced motion) is built silently — never announced in copy or comments.
 1. Register named (brand/product); design read stated; brief and plan obeyed.
@@ -518,8 +678,9 @@ the output is not done.
 3. Zero em/en-dashes visible. Zero banned tells from §10.
 4. One accent + one tinted-neutral family + one theme + one radius system + one
    icon family, locked page-wide; matches sibling pages of this project.
-5. Fonts: not on the reflex-reject list (or justified by existing brand); scale
-   ratio committed; body ≥16px at 45-75ch; caps tracked; data tabular.
+5. Fonts: three candidates considered; registry matches marked; any reflex winner
+   has a specific registered reason; scale ratio committed; body ≥16px at
+   45-75ch; caps tracked; data tabular.
 6. Every CTA/form/placeholder passes WCAG AA; no CTA wraps; no duplicate CTA intent.
 7. Hero: ≤2-line headline, ≤20-word subtext, ≤4 elements, real visual, CTA above
    fold; centered only if variance ≤ 4 or manifesto brief.
@@ -609,10 +770,11 @@ desktop), at most 1 scroll-driven sequence per page, marquees pause when
 off-screen. Battery is a design constraint: continuous rAF loops must idle
 when nothing animates.
-## 14. Typography sourcing (kill the Inter-everywhere default)
-The reflex-reject list (§3) says what NOT to reach for; this is where to reach
-instead. All fonts below are free (Google Fonts or Fontshare/ITF). The
+## 14. Typography sourcing (escape the first reflex)
+Use this section only after the brand-register exercise in §3 has produced
+several candidates; it is a sourcing aid, not a rejection or approved-font list.
+All fonts below are free (Google Fonts or Fontshare/ITF). The
 commercial fonts real award sites use — verified: unseen.co sets **Saol
 Display Light/Italic + Neue Montreal**; unseen's Blossom lab sets **SangBleu
 Serif + PP Neue Montreal**; capsul-in-pro sets **Messina Sans** — are the
@@ -644,7 +806,12 @@ Per aesthetic register (display / body):
   not font novelty.
 Rules: still run §3's selection procedure — this list feeds step 3, it does
-not replace the brand-voice reasoning. Self-host via Fontshare/google-webfonts
+not replace the brand-voice reasoning. **The named fonts are worked examples
+of the procedure, not a menu**: a closed replacement list just becomes the new
+monoculture one tier deeper. Any font here that appears in your choice
+ledger's last 3 entries (§2) is now YOUR reflex — reject it in step 2 like the
+banned list and run the procedure again; the same rotation duty applies to
+§4's alternative palettes. Self-host via Fontshare/google-webfonts
 downloads (`font-display: swap`, preload the display weight only). Never ship
 more than 2 families / ~5 weight files. If the brief names a commercial font
 the project already licenses, use the real thing.
@@ -663,6 +830,34 @@ put it in flow. Decoration layers (glows, grain, orbs, canvas backgrounds) are
 `absolute inset-0 -z-10 pointer-events-none` — below content, never intercepting
 clicks, never between the user and a control.
+**Persistent/traveling scene objects get a TRAVEL MAP.** Any element that
+survives across sections — a fixed canvas object, a scroll-morphing prop, a
+signature that "recurs" down the page — must have a scripted state PER
+SECTION written in the plan blueprint: position, scale, opacity at each
+chapter, chosen so it NEVER rests over a headline, body text, or control at
+any scroll position (including mid-transition — occlusion while traveling
+between keyframes counts). `pointer-events: none` solves clicks, not
+reading: a decorative object visually covering words is a hard fail even
+when clicks pass through. When a section's layout leaves no safe berth, the
+object exits (fades/scales out) and re-enters at the next chapter — an
+object with no scripted berth for a section defaults to HIDDEN there, not
+to floating wherever the scroll math happens to park it.
+**Dominant abstract objects must survive the "what is it?" test.** A large
+abstract signature (orb, core, monolith) earns its prominence only if a
+stranger reads it as either a nameable thing or deliberate scene
+architecture (a horizon, an instrument, a frame). If the honest answer is
+"a dark ball with rings," reduce it: shrink it to an accent, anchor it into
+the composition (consistent berth, edges lit by the page's light, cropped
+by a frame ON PURPOSE), or replace it with imagery. Ambiguity at accent
+scale is intrigue; ambiguity at hero scale is confusion. The test is judged
+from the SCREENSHOT, not from the plan's prose: naming the object "eclipse",
+"thermal horizon", or "roast core" in the plan does not make a translucent
+sphere read as one — if the verify screenshot shows a ball floating over a
+photo, it fails regardless of what the plan swore it wasn't. At hero scale
+the answer must be a nameable thing (see 3d.md §2: generic abstract forms are
+supporting-only and can never be the promoted signature object).
 **Interactive elements never overlap other interactive elements.** Not at any
 breakpoint, not mid-animation, not after a toast appears. Two clickable things
 occupying the same pixels is an automatic fail — one of them is unreachable.