stardust:direct
Resolve the user's freeform redesign intent into a complete target
specification: project-root PRODUCT.md and DESIGN.md (impeccable
format), a DESIGN.json sidecar with the divergence audit trail, and a
stardust/direction.md with the full reasoning trace.
direct produces the spec against which prototype and migrate
operate. It never writes prototypes or migrates pages — those are
downstream sub-commands.
Inputs
<phrase> — optional positional. The user's freeform intent
("make it better", "more Linear less Salesforce", "feel more premium
on a small screen"). If omitted, ask the user for one.
--re-direct — optional. Replace the current direction with a new
one. Triggers stale-flagging on prototyped / approved / migrated
pages per skills/stardust/reference/state-machine.md. Default
behaviour without the flag is additive: if a direction already
exists, the agent asks before replacing.
--rebrand — optional. Force rebrand mode (full divergence-seed
roll, no Mode A inheritance) regardless of whether the captured
brand surface has signal. The default mode is brand-faithful
whenever _brand-extraction.json is signal-strong (see § Setup
step 5 and Phase 2 § Mode-detection precedence); pass --rebrand
to opt out explicitly when the user's phrase is ambiguous about
whether they want a refresh or a clean-slate redesign.
--prep — optional. Run in migrate-prep mode: confirm the
type catalog, finalize the module catalog, capture color
reservations and brand-level metadata defaults, re-evaluate
direction against the wider crawl. See § Prep mode below.
Typically invoked via the prepare-migration orchestrator.
--add-variant <name> — optional. Add a new variant against
the existing direction without re-running intent reasoning or
mode detection. Writes DESIGN-<name>.{md,json} at the
project root and appends a per-variant section to
stardust/direction.md. The previous direction stays
authoritative; existing prototypes are not stale-flagged.
Used when variants are spec'd incrementally — typical
workflow: render variant A, review, then ask for B and C as
"the alternatives we discussed earlier." See § Add-variant
mode below for the per-field inheritance rules.
Setup
- Run the master skill's setup
(
skills/stardust/SKILL.md § Setup) — hard impeccable dep check,
context loader, state read.
- Verify
stardust/state.json exists and contains at least one
extracted page. If not, stop and recommend
$stardust extract <url> first.
- Read
stardust/current/_brand-extraction.json. If absent, stop —
extract did not complete brand-surface extraction; re-run extract.
3b. Cross-site brand inputs (when present). Two extract-written
signals widen the brand surface beyond the primary origin:
state.json.designSource — design-donor mode (extract ran with
--design-source <url>). The donor's derived system at
stardust/canon-source/DESIGN.{md,json} becomes the target
the Mode A pins bind to: palette and type pin to the donor
surface while content, IA priorities, and per-page evidence stay
with the primary origin. Surface in the plan: "Design-donor
mode — target system inherited from ."
_brand-extraction.json.origins[] — sibling-property evidence
captured via --brand-source. Traits captured on a sibling
origin count as captured evidence for trait amplification
(variant B/C briefs, improvements items) exactly like
primary-origin evidence; cite the origin in the evidence
citation. Under Mode A the pins still come from the primary
origin unless designSource says otherwise — sibling evidence
widens what can be amplified, not what is pinned.
- Read
stardust/direction.md if present. If a prior direction
exists and --re-direct was not passed, ask whether the user wants
to refine the existing direction or replace it.
- Validate provenance on every in-scope page (prep mode only).
When
--prep is active, call
validateProvenance(page) per
skills/stardust/reference/state-machine.md § Provenance
validation on every extracted page in state.json before
typing or module detection. Abort with the helper's error
when any page lacks live-render evidence. Surface
Provenance OK on N pages in the prep summary. Discovery-
mode direct does not validate (it operates on a 5-page
sample for which extract's own write-time refusal is
sufficient).
- Classify the captured brand signal. Read
_brand-extraction.json and stamp one of:
signal-strong — palette has ≥ 3 distinct colors (after
near-duplicate clustering and excluding pure black/white if they
are the only entries) AND at least one captured type family
is named in type.headingFamily.name or type.bodyFamily.name.
This is the common case for any extracted commercial site.
signal-thin — palette has 2 colors OR no captured type family
OR type.scaleAudit.kind === "ad-hoc" with fewer than 3
distinct heading sizes. The brand exists but cannot fully
anchor a refresh.
signal-absent — palette has 1 color or 0, or
_brand-extraction.json._provenance.notes flags the extraction
as failed / login-walled / iframe-dominated.
The classification feeds the Mode-detection precedence in Phase 2.
Surface the classification in the plan when it would change the
default mode.
Procedure
Phase 1 — Reasoning
Run the full intent-reasoning procedure from
skills/stardust/reference/intent-reasoning.md. Steps 1-6: restate
the phrase in dimensional vocabulary, identify movement, identify
gaps, ask at most two clarifying questions, map to an impeccable
command sequence, show the plan to the user.
Worked examples in
skills/stardust/reference/intent-examples.md calibrate the style.
Hard ceiling on questions: two per turn, no exceptions.
Hands-off mode (per skills/stardust/SKILL.md § Hands-off mode,
state.json.handsOff: true): ask nothing and wait for nothing.
Derive every answer the questions would have collected from the
captured evidence — density and ia-fidelity from their documented
defaults and trigger conditions, audience and register from the
captured surface — and record each as a named assumption in
direction.md § Movements (e.g. density: balanced (hands-off default — multi-audience floor fired)). The plan is still written;
execution proceeds without the confirmation gate. Question budgets
and gates below that say "ask the user" resolve the same way: derive,
stamp the assumption, proceed.
Density tuning (one-shot, only when unmoved)
When the user's phrase does not move the density axis (per
reference/intent-dimensions.md § 4), and the resolved register is
brand, ask one short follow-up — count it within the two-question
ceiling:
Density tuning — (a) airy (NYT-Opinion-tier breathing, ~96px
section padding), (b) balanced (calm but compact, ~64–72px),
(c) packed (data-dense, ~40–48px). Default for brand-register
sites with multi-audience IA is (b) balanced; pick (a) only
when the page is editorial-led with deep per-section density.
If the user answers, stamp the chosen tier in direction.md §
Movements as density: <tier>. If unanswered, default to
balanced (not airy) for brand register and stamp
density: balanced (default).
Skip this question entirely when:
- The user's phrase already moved
density (any of "make it
denser", "more breathing room", "compact", "tight", "spacious"
count as movement).
- The register is
product (default packed per § 4).
- The register is
ambiguous and resolving it earlier in the
reasoning is the higher-value question — defer density to the
next turn rather than burning a question slot.
The tier propagates to DESIGN.md's spacing.sectionPadding
deterministically per intent-dimensions.md § 4: airy = 96px,
balanced = 64px, packed = 48px. Phase 4 picks the value from this
stamp without re-asking.
IA-fidelity tuning (one-shot, only when unmoved)
When the user's phrase does not auto-pin ia-fidelity (per
reference/intent-dimensions.md § 9 — i.e. none of "verbatim",
"same IA", "keep the structure", "swap the surface",
"don't rethink the IA" and none of "reimagine", "rethink",
"deeper redesign", "what if" appear), ask one short follow-up
— count it within the two-question ceiling:
IA fidelity — (a) verbatim (same section sequence, same content
beats; variants explore surface only: color, type, density,
motion), or (b) reimagined (variants may demote / promote / drop
sections, move IA priorities, take "what if" positions on the
spine of the page).
Default (b) for the typical refresh; pick (a) when the customer
asked to keep their site structurally identical and only swap
the surface.
If the user answers, stamp the chosen tier in direction.md §
Movements as ia-fidelity: <tier>. If unanswered, default to
reimagined and stamp ia-fidelity: reimagined (default).
Skip this question entirely when:
- The user's phrase already auto-pinned the axis (any trigger phrase
in § 9 — "same IA, swap the surface" → verbatim;
"what if we rethought the home page" → reimagined).
- An existing
direction.md is being refined (the active tier holds
unless the user explicitly re-pins).
The tier propagates to DESIGN.json.extensions.iaPriorities[].mutability:
locked under verbatim, movable under reimagined. Phase 4 stamps
the field; downstream prototype reads it.
Pair this question with the density-tuning question when both are
unmoved — "two things to pin before we resolve: (1) density …, (2)
IA fidelity …" — to stay within the two-question ceiling. If
resolving register (brand vs product) is also outstanding, prioritise
register first; defer one of density / ia-fidelity to the next turn.
Wait for the user's confirmation ("go", or a correction to the
plan) before moving on.
Phase 2 — Resolve the divergence inputs
Once the plan is confirmed, resolve the divergence-toolkit inputs
from skills/stardust/reference/divergence-toolkit.md. Before
rolling the seed, run the mode-detection precedence below to decide
whether the seed needs rolling at all.
Mode-detection precedence (run first)
The default mode for direct is determined by whether an extracted
brand surface exists with usable signal — not by the user's
freeform phrase alone. Stardust's primary use case is migrating an
existing site with a design refresh; "make it modern" / "stunning new
version" / "design fatigue cure" are migration-shaped asks. Treating
those phrases as rebrand triggers (rolling a fresh divergence seed)
produces output that is recognisably a different brand from the one
that asked for the refresh — a published failure mode. The
precedence below catches the common case as the default and reserves
divergence-seed rolls for explicit rebrand requests.
The precedence is asymmetric on purpose: the safer mode (Mode A —
brand-faithful) catches ambiguous phrases, and the riskier mode
(rebrand / full divergence-seed) requires the user to name it.
Site migration / refresh — DEFAULT. When the captured brand
signal stamped in § Setup step 6 is signal-strong, Mode A is
active by default. The user's phrase moves expressive,
distinctiveness, tone, and density axes inside Mode A — but
palette and type are pinned to the captured surface, and the
image-reuse contract (below) holds. Signature preservation also
holds: a captured signature hero medium (background video /
canvas / Lottie / scroll-motion, elevated as
_brand-extraction.json#voice.heroMedium) or a site-wide motif is
reproduced, not flattened — per skills/stardust/reference/ intent-dimensions.md § 8b, and exempt from the surprise budget.
Surface in the plan:
"Brand-faithful mode active — palette and type pinned to the
captured brand surface. Pass --rebrand to override."
Rebrand — explicit opt-in. Mode A is overridden when any
of the following triggers fire:
- The user's phrase contains an explicit rebrand signal: any of
rebrand, new brand, clean slate, start over,
from scratch, replace the brand, not brand-faithful,
editorial reimagination, completely new, redo the brand.
- The
--rebrand flag is passed.
- Captured signal is
signal-absent (no usable inheritance).
Surface this case as an automatic switch with reason; the user
can correct.
In rebrand mode, run the standard divergence-seed roll per
"Default mode (no constraints)" below. Surface in the plan:
"Rebrand mode active — full divergence-seed roll. Mode A
bypassed because ."
Brand-faithful + targeted exploration. When the user requests
N variants (e.g. "3 variants", "4 directions") and Mode A is
active, the variant role contract in § Multi-variant fork
applies. Variant A is locked to strict Mode A (palette and
type pinned, IA preserved, every improvements-list item applied).
Variants B+ may amplify one captured trait (a motif, a photo
treatment, an IA priority the current site underplays) but
cannot:
- introduce a font outside the captured surface,
- introduce a color outside the captured palette,
- shift the register from PRODUCT.md.
Signal-thin fallback. When captured signal is signal-thin,
Mode A activates but warns: "Captured brand surface is thin —
{reason}. Variants will inherit what is available; some
dimensions will need to be filled by the divergence toolkit."
The user may either re-run extract with a wider crawl
(--cap 25) or proceed with reduced fidelity.
After mode-detection completes, run the existing mode definitions
below (Mode A procedure, Mode B anchor-reference precedence, Mode C
ground-family override) as applicable.
Mode A — Brand-faithful mode
Triggered automatically when the captured brand signal is
signal-strong and no rebrand-mode override fired (see
§ Mode-detection precedence above), OR when the user pinned both
type and palette (via explicit phrase: "keep typography and palette",
"preserve the existing brand", "brand-faithful redesign"; or via
constraints listing both as anchors).
In this mode, direct does not roll the type or palette
dimensions of the seed — they are already locked. Going through
the motions of font-deck and palette picks would be ceremony,
producing picked_by = "user-constraint" records that don't
reflect any real choice.
The mode procedure:
Record font_deck.name = "brand-inherited" and
font_deck.picked_by = "user-constraint". Do not invoke
reference/palette-picker.md.
Record palette.source = "inherited from _brand-extraction.json"
and palette.picked_by = "user-constraint". Apply role-renaming
per toolkit § 4 if the inherited names violate the brand-native
rule (this is still useful — role renaming is presentational,
not a divergence choice).
Still roll the seed for the non-locked dimensions
(decade, register, ground-family-as-applicable per Mode C
below). These dimensions still drive divergence — the visual
register and the era can shift even when type and palette are
pinned.
Auto-emit the brand_faithful_inversions[] block in
extensions.divergence per
reference/direction-format.md § Brand-faithful inversions.
The list is mostly mechanical (see § Brand-faithful inversions
in direction-format.md for the canonical patterns).
Surface in the user report which dimensions had teeth and
which were inert:
Divergence (brand-faithful mode):
decade ✓ rolled → 2025-now
craft ✓ rolled → Riso print
register ✓ rolled → Memoir-adjacent
ground-family inherited → stark-white (brand-native)
font deck inherited → existing site stack
palette inherited → existing 5-color set
Image-reuse contract. Captured images are reused via their
public URLs (or the local copies in
stardust/current/assets/media/ written by extract Phase 2)
at the same semantic position as on the source site. Hero
stays hero. Story-tile portrait stays story-tile portrait.
Program-card image stays program-card image. Background-motif
image stays background motif.
This is part of brand-faithful inheritance, not a separate
content rule. A variant that swaps a captured subject portrait
for a gradient placeholder, or moves the captured hero photo to
a card thumbnail, erases the brand's most load-bearing trust
signal — the named-people stories that almost every nonprofit /
service-led site has spent years building.
The only legitimate ways to deviate from semantic
position-preservation under Mode A:
- The captured image is broken (404, blocked by
referrer-policy,
CORS-walled, or recorded with localPath: null and a
downloadError).
- The brand-review surfaced the image as a tension (e.g.
T-stock-photography when added — flagging the captured
image as obviously templated stock that the brand team would
replace anyway).
- The improvements list (Phase 2.5) explicitly notes a crop or
positioning fix for that image — in which case the same
image is reused at the corrected crop or position.
Synthesised placeholders are forbidden under Mode A. When a
captured image cannot be reused, the prototype shape brief
declares the gap explicitly and the rendered prototype shows a
placeholder-with-signature element so reviewers see the gap
rather than a fabricated photo.
Mode A is the default whenever § Mode-detection precedence step 1
applies (captured signal is signal-strong and no rebrand override
fires). It also activates explicitly when the resolved direction's
constraints list contains brand-faithful AND explicit type AND
palette anchors, OR when the user's phrase contains "keep
typography" / "preserve the palette" / equivalent. The agent
surfaces "Brand-faithful mode active" in the plan it shows the
user before executing — the user can correct (e.g. "actually let
me move the palette" or "actually rebrand it") before it locks.
Mode A+ — Brand-adjacent refinement (bounded, evidence-gated)
The middle tier between Mode A's hard pins and --rebrand. It exists
because the median redesign candidate is a site whose brand is right
but whose execution of that brand is part of the problem — a
generic system body face, a palette whose only accent fails contrast
on half its surfaces. Strict Mode A reproduces those weaknesses;
rebrand throws away the brand. Mode A+ authorizes bounded
upgrades, each gated on evidence:
- Same-classification type upgrade. When the improvements list
(Phase 2.5) names the captured body or system face as a weakness
with evidence (illegibility at captured sizes, a generic system
stack where the brand deserves a voice, missing weights/axes the
layout needs), the body face may be upgraded to a
same-classification, deliverable face (humanist sans → humanist
sans; grotesque → grotesque). The display face stays pinned —
it carries the brand's recognition.
- Single-role palette recolor. When a specific captured color
fails contrast or hierarchy as evidenced (computed ratio cited,
or a
T-color-imbalance tension), that one role may be re-derived
(deepened, re-weighted) while every other role stays pinned. New
hues from outside the captured family remain forbidden.
Contract: each refinement is recorded in
DESIGN.json.extensions.divergence.brand_adjacent_refinements[] as
{ kind, captured, replacement, evidence, improvementsItem } — an
inversion-style audit entry citing the improvements-list item that
authorizes it. No evidence citation → no refinement. Mode A+ never
activates by default: it requires the qualifying improvements-list
item, and the plan surfaces each refinement explicitly ("body face
upgraded Arial → Hanken Grotesk per improvements #3; display face
pinned") so the user (or the hands-off record) sees exactly what
moved. Refinements do not run through reference research — their
justification is the captured weakness, not an external anchor.
Mode B — Anchor-reference precedence
When the user provides anchor references (Q1/Q2 answers like
"Pentagram nonprofits, This American Life, NYT Opinion longform"),
those references already imply seed dimensions. Pentagram
implies decade 2025-now editorial. This American Life implies
register Memoir-adjacent. Rolling those dimensions
deterministically and getting an accidental alignment is fragile —
the agent then has to retro-justify the alignment in
direction.md.
Agent-sourced anchors (default when the user provides none).
Mode B no longer waits for the user to name references: run the
reference-research procedure
(skills/stardust/reference/reference-research.md) to source 3–5
real-world anchors matched to the brand's category, register, and the
resolved direction movement. Researched anchors carry the same
implied-dimension weight as user-provided ones and are recorded as
picked_by: "reasoned: <anchor>" with the full citation in
extensions.divergence.references_used[]. User-provided references
always outrank researched ones on conflict. When research is
unavailable (ladder exhausted per reference-research.md § 1), Mode B
degrades to the deterministic roll for the un-implied dimensions.
Precedence rule:
- If anchor references are present, extract their implied
dimensions:
- Decade from era of the references (Pentagram → 2025-now;
vintage Penguin → 1960s).
- Craft from medium of the references (TAL → audio editorial
≠ a craft per se, but Bandcamp → web-print hybrid; Riso-print
anthology → Riso).
- Register from cultural reference set (Memoir, Tabloid,
Catalogue, etc.).
- Ground-family from typical ground of those references
(NYT Opinion → cream/parchment; Pentagram nonprofit →
stark-white or monochrome-tint).
- Mark each implied dimension as
picked_by = "anchor-reference: <ref-name>".
- Roll the seed only for un-implied dimensions.
- Record the anchor → dimension mapping in
extensions.divergence.seed.anchors[].
Mode B can compose with Mode A: anchor-references narrow the seed,
brand-faithful constraints lock type/palette, the remaining roll
is whatever the anchors didn't already imply.
Mode C — Brand-faithful ground-family override
When Mode A is active and the seed's ground_family roll
disagrees with the brand's existing ground (e.g. seed rolled
monochrome-tint but the brand's captured background is
#ffffff stark-white), the brand's ground wins. The seed roll is
not discarded — it informs the alt-section surface instead
(per divergence-toolkit.md § 4 Color roles). Record the override
in extensions.divergence.seed.ground_family.override with one
of three reasons:
brand-faithful — Mode A active and brand has a fixed ground.
print-paper — manual override for print/paper categories
(existing toolkit rule).
direction-driven — seed wins (default; no override).
The three reasons are mutually exclusive; surface the chosen one
in the user report.
Default mode (no constraints)
When neither Mode A nor Mode B applies (rebrand or thin-signal runs
with no user anchors), the procedure is research-first, roll as
fallback:
- Reference research first. Run
skills/stardust/reference/reference-research.md to source
anchors for the brand's category and the resolved direction, and
derive the dimensions they imply (picked_by: "reasoned: <basis>").
This is Mode B's machinery applied to agent-sourced anchors — see
§ Mode B above.
- Seed as fallback + tiebreaker. Roll the 4-dimension seed
(decade × craft × register × ground-family) per § 2 of the toolkit
only for dimensions research left un-implied, or entirely when
research is unavailable. The roll also remains available as a
deliberate convergence-breaker when the self-audit catches the
model reproducing its defaults despite research. Record
picked_by per dimension.
- Font deck. Pick from the 10 named decks per § 3, letting the
researched anchors inform the pick the same way a seed implication
would (e.g. an editorial-serif anchor set →
serif-luxury). When
neither research nor seed implies a deck, pick deterministically
from the hash.
- Palette. If the resolved direction moves the color-energy
axis or names the existing palette as part of the problem: derive
a full role-ramped palette (text, grounds, borders, accents,
states) from the primary researched anchor or a library candidate
— the library (
skills/direct/reference/palette-picker.md) is an
anchor bank, not a closed menu; the model designs the ramp and
validates every text-on-ground pair for WCAG AA before it lands
in tokens (deterministic where it matters — math — not where it
hurts — taste). Record the derivation basis in
extensions.divergence.palette_source. Otherwise inherit
the existing palette from
stardust/current/_brand-extraction.json, applying role-renaming
per toolkit § 4 if the inherited names violate the brand-native
rule.
Always run
- Anti-toolbox audit. Regardless of mode, run the self-audit
(toolkit § 1 Enforcement + Self-audit) on the resolved direction.
Each anti-toolbox hit needs a brand-specific justification or it
is removed.
Record every resolution in DESIGN.json.extensions.divergence per
the v2 storage shape at the bottom of divergence-toolkit.md.
Phase 2.5 — Improvements list (Mode A only)
Before any variant is rendered downstream, write
stardust/prototypes/<slug>-improvements.md listing 3–5 specific
weaknesses observed in the captured site. This is the load-bearing
artifact for variant A: without it, "make it better" has no claim
the agent can defend, and each variant ends up inventing its own
"better" — producing rebrand-shaped output even with Mode A active.
The improvements list is the brief variant A renders against. It is
not prescriptive (it does not declare visual targets); it is
descriptive of the gap between the existing site and a competent
2026 execution of the same brand. Variant A's job is to close the
gap; variants B+ honor the list as a floor (they may go further but
not contradict it).
Skip this phase when the resolved mode is rebrand — the improvements
list assumes brand-faithful inheritance, and a rebrand replaces the
site rather than fixing it.
Audit reuse. When stardust/audit/<domain-slug>/audit.json
exists for this origin (written by stardust:audit), consume its
design findings as candidate improvements instead of re-deriving from
scratch — carry the finding IDs into each item's evidence citation.
The specificity bar below still applies to every carried item.
What goes in the list
The list draws from five categories. Items should be specific enough
that a downstream prototype shape brief can cite them by number.
- Dated patterns the design world has moved past. Specific:
"centered hero with stock photo + double CTA in primary blue
is the SaaS template circa 2019" — not "the hero feels dated."
- Cluttered IA, unclear hierarchy, weak CTAs, redundant sections.
E.g. "home page has 4 different donor CTAs, each with a different
verb (DONATE / GIVE / SUPPORT / CONTRIBUTE), fragmenting the
conversion funnel."
- Contrast failures, accessibility gaps, density issues. Pull
from
brand-review.html Tensions when present (T-color-imbalance,
T-img-alt-empty, etc.). E.g. "Primary CTA #008192 on white
passes AA at 4.6:1 but the same teal on light-grey card surfaces
drops to 3.1:1 — fails AA on those instances."
- Cliché conventions the brand could move past while staying
recognisably itself. E.g. "All headings render uppercase via
CSS — the brand voice survives mixed-case headlines, and mixed-case
reads as more current without changing identity."
- Missed opportunities the existing site doesn't capitalise on.
E.g. "The captured photography of named program participants is
excellent but the home page renders all 6 portraits as 280×180
thumbnails in a slick-slider; the photographs support full-bleed
editorial treatment that would carry the trust signal far more
effectively."
Specificity bar
A weakness is specific enough when it cites:
- a measurable observation (size, ratio, contrast value, count, or
named tension ID) drawn from the per-page JSON, the brand-review,
or the brand-extraction;
- the design pattern at fault (named, e.g. "centered hero + dual CTA");
- one concrete fix the variant A brief will apply.
"The hero needs work" fails all three. "Hero photo is cropped to
280×180 in a 1440-wide viewport when the captured source supports
16:9 full-bleed at 1440×810; variant A fix: render at full-bleed and
move the headline to a left-anchored two-column overlay" passes all
three.
Format
Markdown, with a _provenance frontmatter block per the artifact-map
convention. Each item is a numbered list entry with a category tag, a
weakness statement, and a one-line fix. Example:
<!--
_provenance:
writtenBy: stardust:direct
writtenAt: 2026-04-29T11:00:00Z
readArtifacts:
- stardust/current/_brand-extraction.json
- stardust/current/brand-review.html
- stardust/current/pages/<slug>.json
stardustVersion: 0.10.x
-->
# Improvements — <slug>
1. **[dated-pattern]** Centered hero with double CTA pair (DONATE +
LEARN MORE) is the 2019 nonprofit-template silhouette.
*Fix:* Replace with a left-anchored editorial composition; one
primary CTA, one secondary text-link.
2. **[ia-clutter]** 4 distinct donor verbs across the home page
(DONATE, GIVE, SUPPORT, CONTRIBUTE) fragment the funnel.
*Fix:* Pick one canonical verb (DONATE, per the CTA frequency
table); other instances become secondary "see all ways to give"
links.
3. **[contrast]** Brand teal on light-grey card surfaces resolves to
3.1:1 — fails WCAG AA. (See `T-color-imbalance` in brand-review.)
*Fix:* Reserve teal for white-ground only; use deepened teal
(#005a68) on grey surfaces.
4. **[cliché]** All headings render uppercase via CSS, including
long-form section openers ("OFFICIAL FOUR STAR CHARITY"). The
shout reads as urgency at first heading and as fatigue by the
third.
*Fix:* Mixed-case for headings ≥3 words; preserve uppercase only
for short imperative CTAs and eyebrow labels.
5. **[missed-opportunity]** Six named-participant portraits render
as 280×180 thumbnails in a slick-slider; the captured source
supports editorial-scale treatment.
*Fix:* Replace carousel with a 3-column grid; portraits at 4:5
aspect, 1:1 minimum 480px wide.
Stopping condition
If after reading the brand-review, the per-page JSON, and the
brand-extraction the agent cannot name 3 specific weaknesses
that meet the specificity bar, stop. Variant A has no brief; the
"better" claim fails. See § Failure modes (d).
The agent should not rationalise — "the hero is dated" is not an
item, "the typography could be more modern" is not an item.
Genuine empty-list cases occur when the captured site is already at
a high execution level on observable dimensions. In that case the
honest answer is to surface the empty list and propose reduced
scope (density-and-contrast adjustments only, or pivot to a single
exploratory variant rather than three).
Phase 2.6 — Multi-variant fork (when N > 1)
When the user requests N variants (phrase contains "3 variants",
"4 directions", or equivalent), variant slots are
role-differentiated, not seed-differentiated. Each slot serves a
distinct decision the customer is making — variants exist to
de-risk a brand decision, not to fan out into N rebrand
explorations.
The previous default behavior (each variant rolls a fresh divergence
seed with anchor references picked per slot) produced what the
internal review called "three rebrands" output: each variant was
defensible standalone but none felt like the same brand. The
variant role contract below addresses this directly.
Branch on ia-fidelity first
The variant role contract is ia-fidelity-aware. Read the tier
stamped in Phase 1 (per reference/intent-dimensions.md § 9 and the
IA-fidelity tuning step above), and branch:
Under ia-fidelity: verbatim — surface-tuning forks (A1/A2/A3).
Variant slots are A1 / A2 / A3 (or A1…An for N > 3), all
surface-tuning forks of A's role. Each must differ from the others by
≥ 2 surface changes drawn from:
- type-weight choice (e.g. 400 vs 600 vs 800 display)
- type-scale ratio (e.g. 1.2 vs 1.333 vs 1.5)
- density tier (within the multi-audience floor in § 4)
- motion energy (still vs gentle vs animated)
- color-temperature move within the captured palette (warm-leaning
vs cool-leaning vs neutral-balanced)
- spacing rhythm (compact vs even vs generous within the floor)
Forbidden differentiation axes under verbatim:
- section sequence
- section presence / absence
- IA priority
- layout strategy of a major section
A1 / A2 / A3 names indicate "different tunings of the same role,"
not different roles. When the user asks for "3 variants" while
ia-fidelity is verbatim, the fork produces A1 / A2 / A3
automatically; for N=1, just A.
The improvements list (Phase 2.5) still anchors variant A's role —
A1/A2/A3 all apply every item from <slug>-improvements.md. They
differ only in surface treatment of the same applied fixes.
The convergence detector in prototype/SKILL.md Discipline 10
becomes its inverse under verbatim: structural deltas
(section-sequence / presence / IA priority / layout strategy) are
forbidden, surface-only deltas are required.
Under ia-fidelity: reimagined — A + B + C role-differentiated.
Variant slots are A + B + C (or A + B + C + D…) per the variant role
contract below. The contract is unchanged from the prior behavior:
faithful + improvements / one captured trait amplified / different
captured trait amplified.
The remainder of this Phase 2.6 (variant role contract, variant
differentiation contract, C-cliff failure mode) applies as written
under reimagined. Under verbatim, only the surface-fork rules
above apply; the variant role contract below does not.
Variant role contract
| Slot |
Role |
Brief |
| A |
Faithful + improvements — "this is what your site should be tomorrow." |
Same IA. Same section sequence. Same composition strategy. Apply every item from <slug>-improvements.md exactly — no extras, no embellishment, no creative reach. The brand team should react "yes, that's us, with the obvious fixes." This is the variant a risk-averse stakeholder green-lights. |
| B |
One captured trait amplified — "what if we leaned into X?" |
Pick one specific trait already in the captured brand surface — a motif underused in current execution, a photographic treatment the site doesn't fully exploit, an IA priority the current site underplays, a tonal register that survives in copy but not in layout. Justify in one sentence in the variant's shape brief: "This variant amplifies in service of ." |
| C+ |
Different captured trait amplified — "what if we leaned into Y?" |
Different from B by definition. Different captured trait. Different brand-personality move. Forbidden definitions: "B but more", "bolder fonts", "more empty space", "more brutalist", "more editorial". Each subsequent variant must be a defensible standalone proposition. |
Variants beyond C (D, E, …) follow the C+ contract — each amplifies
a distinct captured trait, declared in the shape brief.
Surface forks of role-differentiated variants (B1/B2/B3, C1/C2/C3…)
Under ia-fidelity: reimagined, a variant's role (A, B, C, …) may
spawn surface forks — tunings of the same role across the
same surface axes that A1/A2/A3 use under verbatim. The pattern:
B is "scroll cinema amplified" (the role).
B1, B2, B3 are surface tunings of B that all amplify scroll
cinema, but vary along type-weight, type-scale, density,
motion-energy, color-temperature, or spacing-rhythm.
This composes the verbatim-mode surface-fork machinery with the
reimagined-mode role differentiation: the role contract binds
the captured trait being amplified; the surface-fork delta
governs how that trait reads in chrome.
Surface forks of role-differentiated variants are opt-in, not
default. The default fork under reimagined is still A + B + C.
Surface forks appear in two ways:
- Explicit user request: "design 5 variant directions for B"
— the user asks for surface tunings of an existing role-
differentiated variant. Render B1 / B2 / B3 / B4 / B5, each
amplifying B's captured trait but with distinct surface tunings.
- Via
--add-variant <name> with a parent declared: e.g.,
--add-variant B3 after B exists. The parent inferred from the
slot name's letter prefix (B3 → parent B). See § Add-variant
mode → Per-field inheritance rules for the inheritance chain.
Surface forks of role-differentiated variants follow the same
≥ 2 surface-changes contract as A1/A2/A3 — the per-pair
differentiation is surface-only (type-weight / type-scale / density
/ motion-energy / color-temperature / spacing-rhythm), with the
captured trait being amplified held constant across the fork.
Structural differentiation (section sequence / presence / IA
priority / layout strategy) is forbidden between B and its surface
forks B1/B2/B3 — the role IS the captured trait, and changing
structure changes the role.
The variant-convergence detector in prototype/SKILL.md
Discipline 10 reads the variant's parent slot: when comparing
B vs B3 (parent–child surface fork), it applies the verbatim-style
inverse rule (surface deltas required, structural deltas
forbidden); when comparing B vs C (sibling role-differentiated
variants), it applies the reimagined-style rule (structural deltas
required).
The cap on motion-energy and other amplified surface axes is the
parent role's cap — a B3 that amplifies motion-energy beyond B's
ceiling must declare a cap override in its DESIGN.json
extensions with a one-sentence rationale (e.g. "B3 raises B's
motion choreography count from ≤ 3 to ≤ 5 to accommodate the loud-
register tuning of scroll cinema"). The override must cite a
captured-source basis or it refuses; cap overrides without a
captured-source rationale produce surface drift instead of trait
amplification.
Variant differentiation contract
Each pair of variants must differ by ≥ 2 substantive changes
drawn from this set:
- section sequence (which sections appear in which order),
- section presence / absence (a section in one variant, not in another),
- layout strategy of a major section (e.g. hero is split-half vs.
full-bleed-photo vs. type-led),
- IA priority (which audience leads the home — donor vs. recipient
vs. volunteer for nonprofits; product vs. story for commerce).
Variants that fail the ≥ 2 changes test are rendered as the same
variant under different chrome — "variants are barely different"
is the published failure mode and is grounds for refusing render.
See § Failure modes (b) — when only 1–2 captured traits are
distinct enough to amplify, the agent surfaces this and proposes
1 or 2 variants rather than producing 3 weak ones.
The C-cliff failure mode
When defin
…(truncated)
1---2name: direct3description: Set a redesign direction for an existing website. Analyzes the user's intent, picks a palette and visual direction, and writes the target spec (PRODUCT.md, DESIGN.md, DESIGN.json) plus a reasoning trace at stardust/direction.md. Use when the user asks to redesign a site, refresh the design, set a new design direction, define a redesign target, or invokes /stardust:direct.4license: Apache-2.05metadata:6 source: https://skillmd.com/skills/adobe/direct7---89# stardust:direct1011Resolve the user's freeform redesign intent into a complete **target12specification**: project-root `PRODUCT.md` and `DESIGN.md` (impeccable13format), a `DESIGN.json` sidecar with the divergence audit trail, and a14`stardust/direction.md` with the full reasoning trace.1516`direct` produces the spec against which `prototype` and `migrate`17operate. It never writes prototypes or migrates pages — those are18downstream sub-commands.1920## Inputs2122- `<phrase>` — optional positional. The user's freeform intent23 ("make it better", "more Linear less Salesforce", "feel more premium24 on a small screen"). If omitted, ask the user for one.25- `--re-direct` — optional. Replace the current direction with a new26 one. Triggers stale-flagging on prototyped / approved / migrated27 pages per `skills/stardust/reference/state-machine.md`. Default28 behaviour without the flag is additive: if a direction already29 exists, the agent asks before replacing.30- `--rebrand` — optional. Force rebrand mode (full divergence-seed31 roll, no Mode A inheritance) regardless of whether the captured32 brand surface has signal. The default mode is brand-faithful33 whenever `_brand-extraction.json` is `signal-strong` (see § Setup34 step 5 and Phase 2 § Mode-detection precedence); pass `--rebrand`35 to opt out explicitly when the user's phrase is ambiguous about36 whether they want a refresh or a clean-slate redesign.37- `--prep` — optional. Run in **migrate-prep mode**: confirm the38 type catalog, finalize the module catalog, capture color39 reservations and brand-level metadata defaults, re-evaluate40 direction against the wider crawl. See § Prep mode below.41 Typically invoked via the `prepare-migration` orchestrator.42- `--add-variant <name>` — optional. Add a new variant against43 the existing direction without re-running intent reasoning or44 mode detection. Writes `DESIGN-<name>.{md,json}` at the45 project root and appends a per-variant section to46 `stardust/direction.md`. The previous direction stays47 authoritative; existing prototypes are **not** stale-flagged.48 Used when variants are spec'd incrementally — typical49 workflow: render variant A, review, then ask for B and C as50 "the alternatives we discussed earlier." See § Add-variant51 mode below for the per-field inheritance rules.5253## Setup54551. Run the master skill's setup56 (`skills/stardust/SKILL.md` § Setup) — hard impeccable dep check,57 context loader, state read.582. Verify `stardust/state.json` exists and contains at least one59 `extracted` page. If not, stop and recommend60 `$stardust extract <url>` first.613. Read `stardust/current/_brand-extraction.json`. If absent, stop —62 extract did not complete brand-surface extraction; re-run extract.633b. **Cross-site brand inputs** (when present). Two extract-written64 signals widen the brand surface beyond the primary origin:65 - `state.json.designSource` — design-donor mode (extract ran with66 `--design-source <url>`). The donor's derived system at67 `stardust/canon-source/DESIGN.{md,json}` becomes the **target**68 the Mode A pins bind to: palette and type pin to the *donor*69 surface while content, IA priorities, and per-page evidence stay70 with the primary origin. Surface in the plan: *"Design-donor71 mode — target system inherited from <donor-url>."*72 - `_brand-extraction.json.origins[]` — sibling-property evidence73 captured via `--brand-source`. Traits captured on a sibling74 origin count as **captured evidence** for trait amplification75 (variant B/C briefs, improvements items) exactly like76 primary-origin evidence; cite the origin in the evidence77 citation. Under Mode A the *pins* still come from the primary78 origin unless designSource says otherwise — sibling evidence79 widens what can be amplified, not what is pinned.804. Read `stardust/direction.md` if present. If a prior direction81 exists and `--re-direct` was not passed, ask whether the user wants82 to refine the existing direction or replace it.835. **Validate provenance on every in-scope page** (prep mode only).84 When `--prep` is active, call85 `validateProvenance(page)` per86 `skills/stardust/reference/state-machine.md` § Provenance87 validation on every `extracted` page in `state.json` before88 typing or module detection. Abort with the helper's error89 when any page lacks live-render evidence. Surface90 `Provenance OK on N pages` in the prep summary. Discovery-91 mode `direct` does not validate (it operates on a 5-page92 sample for which extract's own write-time refusal is93 sufficient).946. **Classify the captured brand signal.** Read95 `_brand-extraction.json` and stamp one of:96 - `signal-strong` — palette has ≥ 3 distinct colors (after97 near-duplicate clustering and excluding pure black/white if they98 are the only entries) **AND** at least one captured type family99 is named in `type.headingFamily.name` or `type.bodyFamily.name`.100 This is the common case for any extracted commercial site.101 - `signal-thin` — palette has 2 colors OR no captured type family102 OR `type.scaleAudit.kind === "ad-hoc"` with fewer than 3103 distinct heading sizes. The brand exists but cannot fully104 anchor a refresh.105 - `signal-absent` — palette has 1 color or 0, or106 `_brand-extraction.json._provenance.notes` flags the extraction107 as failed / login-walled / iframe-dominated.108 The classification feeds the Mode-detection precedence in Phase 2.109 Surface the classification in the plan when it would change the110 default mode.111112## Procedure113114### Phase 1 — Reasoning115116Run the full intent-reasoning procedure from117`skills/stardust/reference/intent-reasoning.md`. Steps 1-6: restate118the phrase in dimensional vocabulary, identify movement, identify119gaps, ask **at most two** clarifying questions, map to an impeccable120command sequence, show the plan to the user.121122Worked examples in123`skills/stardust/reference/intent-examples.md` calibrate the style.124Hard ceiling on questions: two per turn, no exceptions.125126**Hands-off mode** (per `skills/stardust/SKILL.md` § Hands-off mode,127`state.json.handsOff: true`): ask nothing and wait for nothing.128Derive every answer the questions would have collected from the129captured evidence — density and ia-fidelity from their documented130defaults and trigger conditions, audience and register from the131captured surface — and record each as a named assumption in132`direction.md` § Movements (e.g. `density: balanced (hands-off133default — multi-audience floor fired)`). The plan is still written;134execution proceeds without the confirmation gate. Question budgets135and gates below that say "ask the user" resolve the same way: derive,136stamp the assumption, proceed.137138#### Density tuning (one-shot, only when unmoved)139140When the user's phrase does **not** move the `density` axis (per141`reference/intent-dimensions.md` § 4), and the resolved register is142`brand`, ask one short follow-up — count it within the two-question143ceiling:144145> Density tuning — (a) airy (NYT-Opinion-tier breathing, ~96px146> section padding), (b) balanced (calm but compact, ~64–72px),147> (c) packed (data-dense, ~40–48px). Default for brand-register148> sites with multi-audience IA is **(b) balanced**; pick (a) only149> when the page is editorial-led with deep per-section density.150151If the user answers, stamp the chosen tier in `direction.md` §152Movements as `density: <tier>`. If unanswered, default to153**balanced** (not airy) for brand register and stamp154`density: balanced (default)`.155156Skip this question entirely when:157- The user's phrase already moved `density` (any of "make it158 denser", "more breathing room", "compact", "tight", "spacious"159 count as movement).160- The register is `product` (default `packed` per § 4).161- The register is `ambiguous` and resolving it earlier in the162 reasoning is the higher-value question — defer density to the163 next turn rather than burning a question slot.164165The tier propagates to `DESIGN.md`'s `spacing.sectionPadding`166deterministically per `intent-dimensions.md` § 4: airy = 96px,167balanced = 64px, packed = 48px. Phase 4 picks the value from this168stamp without re-asking.169170#### IA-fidelity tuning (one-shot, only when unmoved)171172When the user's phrase does **not** auto-pin `ia-fidelity` (per173`reference/intent-dimensions.md` § 9 — i.e. none of *"verbatim"*,174*"same IA"*, *"keep the structure"*, *"swap the surface"*,175*"don't rethink the IA"* and none of *"reimagine"*, *"rethink"*,176*"deeper redesign"*, *"what if"* appear), ask one short follow-up177— count it within the two-question ceiling:178179> IA fidelity — (a) verbatim (same section sequence, same content180> beats; variants explore surface only: color, type, density,181> motion), or (b) reimagined (variants may demote / promote / drop182> sections, move IA priorities, take "what if" positions on the183> spine of the page).184> Default (b) for the typical refresh; pick (a) when the customer185> asked to keep their site structurally identical and only swap186> the surface.187188If the user answers, stamp the chosen tier in `direction.md` §189Movements as `ia-fidelity: <tier>`. If unanswered, default to190**reimagined** and stamp `ia-fidelity: reimagined (default)`.191192Skip this question entirely when:193- The user's phrase already auto-pinned the axis (any trigger phrase194 in § 9 — *"same IA, swap the surface"* → verbatim;195 *"what if we rethought the home page"* → reimagined).196- An existing `direction.md` is being refined (the active tier holds197 unless the user explicitly re-pins).198199The tier propagates to `DESIGN.json.extensions.iaPriorities[].mutability`:200`locked` under verbatim, `movable` under reimagined. Phase 4 stamps201the field; downstream `prototype` reads it.202203Pair this question with the density-tuning question when both are204unmoved — *"two things to pin before we resolve: (1) density …, (2)205IA fidelity …"* — to stay within the two-question ceiling. If206resolving register (brand vs product) is also outstanding, prioritise207register first; defer one of density / ia-fidelity to the next turn.208209Wait for the user's confirmation (`"go"`, or a correction to the210plan) before moving on.211212### Phase 2 — Resolve the divergence inputs213214Once the plan is confirmed, resolve the divergence-toolkit inputs215from `skills/stardust/reference/divergence-toolkit.md`. Before216rolling the seed, run the mode-detection precedence below to decide217whether the seed needs rolling at all.218219#### Mode-detection precedence (run first)220221The default mode for `direct` is determined by whether an extracted222brand surface exists with usable signal — **not** by the user's223freeform phrase alone. Stardust's primary use case is migrating an224existing site with a design refresh; "make it modern" / "stunning new225version" / "design fatigue cure" are migration-shaped asks. Treating226those phrases as rebrand triggers (rolling a fresh divergence seed)227produces output that is recognisably a different brand from the one228that asked for the refresh — a published failure mode. The229precedence below catches the common case as the default and reserves230divergence-seed rolls for explicit rebrand requests.231232The precedence is asymmetric on purpose: the safer mode (Mode A —233brand-faithful) catches ambiguous phrases, and the riskier mode234(rebrand / full divergence-seed) requires the user to name it.2352361. **Site migration / refresh — DEFAULT.** When the captured brand237 signal stamped in § Setup step 6 is `signal-strong`, Mode A is238 active by default. The user's phrase moves *expressive*,239 *distinctiveness*, *tone*, and *density* axes inside Mode A — but240 palette and type are pinned to the captured surface, and the241 image-reuse contract (below) holds. **Signature preservation also242 holds:** a captured signature hero medium (background video /243 canvas / Lottie / scroll-motion, elevated as244 `_brand-extraction.json#voice.heroMedium`) or a site-wide motif is245 reproduced, not flattened — per `skills/stardust/reference/246 intent-dimensions.md` § 8b, and exempt from the `surprise` budget.247 Surface in the plan:248 *"Brand-faithful mode active — palette and type pinned to the249 captured brand surface. Pass `--rebrand` to override."*2502512. **Rebrand — explicit opt-in.** Mode A is overridden when **any**252 of the following triggers fire:253 - The user's phrase contains an explicit rebrand signal: any of254 `rebrand`, `new brand`, `clean slate`, `start over`,255 `from scratch`, `replace the brand`, `not brand-faithful`,256 `editorial reimagination`, `completely new`, `redo the brand`.257 - The `--rebrand` flag is passed.258 - Captured signal is `signal-absent` (no usable inheritance).259 Surface this case as an automatic switch with reason; the user260 can correct.261262 In rebrand mode, run the standard divergence-seed roll per263 "Default mode (no constraints)" below. Surface in the plan:264 *"Rebrand mode active — full divergence-seed roll. Mode A265 bypassed because <reason>."*2662673. **Brand-faithful + targeted exploration.** When the user requests268 N variants (e.g. *"3 variants"*, *"4 directions"*) and Mode A is269 active, the variant role contract in § Multi-variant fork270 applies. Variant A is locked to **strict Mode A** (palette and271 type pinned, IA preserved, every improvements-list item applied).272 Variants B+ may amplify one **captured** trait (a motif, a photo273 treatment, an IA priority the current site underplays) but274 cannot:275 - introduce a font outside the captured surface,276 - introduce a color outside the captured palette,277 - shift the register from PRODUCT.md.2782794. **Signal-thin fallback.** When captured signal is `signal-thin`,280 Mode A activates but warns: *"Captured brand surface is thin —281 {reason}. Variants will inherit what is available; some282 dimensions will need to be filled by the divergence toolkit."*283 The user may either re-run extract with a wider crawl284 (`--cap 25`) or proceed with reduced fidelity.285286After mode-detection completes, run the existing mode definitions287below (Mode A procedure, Mode B anchor-reference precedence, Mode C288ground-family override) as applicable.289290#### Mode A — Brand-faithful mode291292Triggered automatically when the captured brand signal is293`signal-strong` and no rebrand-mode override fired (see294§ Mode-detection precedence above), OR when the user pinned **both**295type and palette (via explicit phrase: "keep typography and palette",296"preserve the existing brand", "brand-faithful redesign"; or via297constraints listing both as anchors).298299In this mode, direct does **not** roll the type or palette300dimensions of the seed — they are already locked. Going through301the motions of font-deck and palette picks would be ceremony,302producing `picked_by = "user-constraint"` records that don't303reflect any real choice.304305The mode procedure:3063071. Record `font_deck.name = "brand-inherited"` and308 `font_deck.picked_by = "user-constraint"`. Do not invoke309 `reference/palette-picker.md`.3102. Record `palette.source = "inherited from _brand-extraction.json"`311 and `palette.picked_by = "user-constraint"`. Apply role-renaming312 per toolkit § 4 if the inherited names violate the brand-native313 rule (this is still useful — role renaming is presentational,314 not a divergence choice).3153. **Still roll** the seed for the **non-locked** dimensions316 (decade, register, ground-family-as-applicable per Mode C317 below). These dimensions still drive divergence — the visual318 register and the era can shift even when type and palette are319 pinned.3204. Auto-emit the `brand_faithful_inversions[]` block in321 `extensions.divergence` per322 `reference/direction-format.md` § Brand-faithful inversions.323 The list is mostly mechanical (see § Brand-faithful inversions324 in direction-format.md for the canonical patterns).3255. Surface in the user report which dimensions had teeth and326 which were inert:327328 ```329 Divergence (brand-faithful mode):330 decade ✓ rolled → 2025-now331 craft ✓ rolled → Riso print332 register ✓ rolled → Memoir-adjacent333 ground-family inherited → stark-white (brand-native)334 font deck inherited → existing site stack335 palette inherited → existing 5-color set336 ```3373386. **Image-reuse contract.** Captured images are reused via their339 public URLs (or the local copies in340 `stardust/current/assets/media/` written by extract Phase 2)341 **at the same semantic position** as on the source site. Hero342 stays hero. Story-tile portrait stays story-tile portrait.343 Program-card image stays program-card image. Background-motif344 image stays background motif.345346 This is part of brand-faithful inheritance, not a separate347 content rule. A variant that swaps a captured subject portrait348 for a gradient placeholder, or moves the captured hero photo to349 a card thumbnail, erases the brand's most load-bearing trust350 signal — the named-people stories that almost every nonprofit /351 service-led site has spent years building.352353 The only legitimate ways to deviate from semantic354 position-preservation under Mode A:355356 - The captured image is broken (404, blocked by `referrer-policy`,357 CORS-walled, or recorded with `localPath: null` and a358 `downloadError`).359 - The brand-review surfaced the image as a tension (e.g.360 `T-stock-photography` when added — flagging the captured361 image as obviously templated stock that the brand team would362 replace anyway).363 - The improvements list (Phase 2.5) explicitly notes a crop or364 positioning fix for that image — in which case the same365 image is reused at the corrected crop or position.366367 Synthesised placeholders are forbidden under Mode A. When a368 captured image cannot be reused, the prototype shape brief369 declares the gap explicitly and the rendered prototype shows a370 placeholder-with-signature element so reviewers see the gap371 rather than a fabricated photo.372373Mode A is the default whenever § Mode-detection precedence step 1374applies (captured signal is `signal-strong` and no rebrand override375fires). It also activates explicitly when the resolved direction's376constraints list contains `brand-faithful` AND explicit type AND377palette anchors, OR when the user's phrase contains "keep378typography" / "preserve the palette" / equivalent. The agent379surfaces "Brand-faithful mode active" in the plan it shows the380user before executing — the user can correct (e.g. "actually let381me move the palette" or "actually rebrand it") before it locks.382383#### Mode A+ — Brand-adjacent refinement (bounded, evidence-gated)384385The middle tier between Mode A's hard pins and `--rebrand`. It exists386because the median redesign candidate is a site whose brand is right387but whose *execution* of that brand is part of the problem — a388generic system body face, a palette whose only accent fails contrast389on half its surfaces. Strict Mode A reproduces those weaknesses;390rebrand throws away the brand. Mode A+ authorizes **bounded391upgrades**, each gated on evidence:392393- **Same-classification type upgrade.** When the improvements list394 (Phase 2.5) names the captured *body or system* face as a weakness395 with evidence (illegibility at captured sizes, a generic system396 stack where the brand deserves a voice, missing weights/axes the397 layout needs), the body face may be upgraded to a398 same-classification, deliverable face (humanist sans → humanist399 sans; grotesque → grotesque). **The display face stays pinned** —400 it carries the brand's recognition.401- **Single-role palette recolor.** When a specific captured color402 fails contrast or hierarchy *as evidenced* (computed ratio cited,403 or a `T-color-imbalance` tension), that one role may be re-derived404 (deepened, re-weighted) while every other role stays pinned. New405 hues from outside the captured family remain forbidden.406407Contract: each refinement is recorded in408`DESIGN.json.extensions.divergence.brand_adjacent_refinements[]` as409`{ kind, captured, replacement, evidence, improvementsItem }` — an410inversion-style audit entry citing the improvements-list item that411authorizes it. No evidence citation → no refinement. Mode A+ never412activates by default: it requires the qualifying improvements-list413item, and the plan surfaces each refinement explicitly (*"body face414upgraded Arial → Hanken Grotesk per improvements #3; display face415pinned"*) so the user (or the hands-off record) sees exactly what416moved. Refinements do not run through reference research — their417justification is the captured weakness, not an external anchor.418419#### Mode B — Anchor-reference precedence420421When the user provides anchor references (Q1/Q2 answers like422"Pentagram nonprofits, This American Life, NYT Opinion longform"),423those references **already imply** seed dimensions. Pentagram424implies decade `2025-now` editorial. This American Life implies425register `Memoir`-adjacent. Rolling those dimensions426deterministically and getting an accidental alignment is fragile —427the agent then has to retro-justify the alignment in428`direction.md`.429430**Agent-sourced anchors (default when the user provides none).**431Mode B no longer waits for the user to name references: run the432reference-research procedure433(`skills/stardust/reference/reference-research.md`) to source 3–5434real-world anchors matched to the brand's category, register, and the435resolved direction movement. Researched anchors carry the same436implied-dimension weight as user-provided ones and are recorded as437`picked_by: "reasoned: <anchor>"` with the full citation in438`extensions.divergence.references_used[]`. User-provided references439always outrank researched ones on conflict. When research is440unavailable (ladder exhausted per reference-research.md § 1), Mode B441degrades to the deterministic roll for the un-implied dimensions.442443Precedence rule:4444451. If anchor references are present, extract their implied446 dimensions:447 - **Decade** from era of the references (Pentagram → 2025-now;448 vintage Penguin → 1960s).449 - **Craft** from medium of the references (TAL → audio editorial450 ≠ a craft per se, but Bandcamp → web-print hybrid; Riso-print451 anthology → Riso).452 - **Register** from cultural reference set (Memoir, Tabloid,453 Catalogue, etc.).454 - **Ground-family** from typical ground of those references455 (NYT Opinion → cream/parchment; Pentagram nonprofit →456 stark-white or monochrome-tint).4572. Mark each implied dimension as458 `picked_by = "anchor-reference: <ref-name>"`.4593. Roll the seed only for **un-implied** dimensions.4604. Record the anchor → dimension mapping in461 `extensions.divergence.seed.anchors[]`.462463Mode B can compose with Mode A: anchor-references narrow the seed,464brand-faithful constraints lock type/palette, the remaining roll465is whatever the anchors didn't already imply.466467#### Mode C — Brand-faithful ground-family override468469When Mode A is active **and** the seed's `ground_family` roll470disagrees with the brand's existing ground (e.g. seed rolled471`monochrome-tint` but the brand's captured background is472`#ffffff` stark-white), the brand's ground wins. The seed roll is473not discarded — it informs the **alt-section surface** instead474(per `divergence-toolkit.md` § 4 Color roles). Record the override475in `extensions.divergence.seed.ground_family.override` with one476of three reasons:477478- `brand-faithful` — Mode A active and brand has a fixed ground.479- `print-paper` — manual override for print/paper categories480 (existing toolkit rule).481- `direction-driven` — seed wins (default; no override).482483The three reasons are mutually exclusive; surface the chosen one484in the user report.485486#### Default mode (no constraints)487488When neither Mode A nor Mode B applies (rebrand or thin-signal runs489with no user anchors), the procedure is **research-first, roll as490fallback**:491492- **Reference research first.** Run493 `skills/stardust/reference/reference-research.md` to source494 anchors for the brand's category and the resolved direction, and495 derive the dimensions they imply (`picked_by: "reasoned: <basis>"`).496 This is Mode B's machinery applied to agent-sourced anchors — see497 § Mode B above.498- **Seed as fallback + tiebreaker.** Roll the 4-dimension seed499 (decade × craft × register × ground-family) per § 2 of the toolkit500 **only** for dimensions research left un-implied, or entirely when501 research is unavailable. The roll also remains available as a502 deliberate convergence-breaker when the self-audit catches the503 model reproducing its defaults despite research. Record504 `picked_by` per dimension.505- **Font deck.** Pick from the 10 named decks per § 3, letting the506 researched anchors inform the pick the same way a seed implication507 would (e.g. an editorial-serif anchor set → `serif-luxury`). When508 neither research nor seed implies a deck, pick deterministically509 from the hash.510- **Palette.** If the resolved direction moves the color-energy511 axis or names the existing palette as part of the problem: derive512 a full role-ramped palette (text, grounds, borders, accents,513 states) from the primary researched anchor or a library candidate514 — the library (`skills/direct/reference/palette-picker.md`) is an515 **anchor bank**, not a closed menu; the model designs the ramp and516 validates every text-on-ground pair for WCAG AA before it lands517 in tokens (deterministic where it matters — math — not where it518 hurts — taste). Record the derivation basis in519 `extensions.divergence.palette_source`. Otherwise inherit520 the existing palette from521 `stardust/current/_brand-extraction.json`, applying role-renaming522 per toolkit § 4 if the inherited names violate the brand-native523 rule.524525#### Always run526527- **Anti-toolbox audit.** Regardless of mode, run the self-audit528 (toolkit § 1 Enforcement + Self-audit) on the resolved direction.529 Each anti-toolbox hit needs a brand-specific justification or it530 is removed.531532Record every resolution in `DESIGN.json.extensions.divergence` per533the v2 storage shape at the bottom of `divergence-toolkit.md`.534535### Phase 2.5 — Improvements list (Mode A only)536537Before any variant is rendered downstream, write538`stardust/prototypes/<slug>-improvements.md` listing **3–5 specific539weaknesses** observed in the captured site. This is the load-bearing540artifact for variant A: without it, *"make it better"* has no claim541the agent can defend, and each variant ends up inventing its own542"better" — producing rebrand-shaped output even with Mode A active.543544The improvements list is the brief variant A renders against. It is545**not** prescriptive (it does not declare visual targets); it is546**descriptive of the gap** between the existing site and a competent5472026 execution of the same brand. Variant A's job is to close the548gap; variants B+ honor the list as a floor (they may go further but549not contradict it).550551Skip this phase when the resolved mode is rebrand — the improvements552list assumes brand-faithful inheritance, and a rebrand replaces the553site rather than fixing it.554555**Audit reuse.** When `stardust/audit/<domain-slug>/audit.json`556exists for this origin (written by `stardust:audit`), consume its557design findings as candidate improvements instead of re-deriving from558scratch — carry the finding IDs into each item's evidence citation.559The specificity bar below still applies to every carried item.560561#### What goes in the list562563The list draws from five categories. Items should be specific enough564that a downstream `prototype` shape brief can cite them by number.5655661. **Dated patterns the design world has moved past.** Specific:567 *"centered hero with stock photo + double CTA in primary blue568 is the SaaS template circa 2019"* — not *"the hero feels dated."*5692. **Cluttered IA, unclear hierarchy, weak CTAs, redundant sections.**570 E.g. *"home page has 4 different donor CTAs, each with a different571 verb (DONATE / GIVE / SUPPORT / CONTRIBUTE), fragmenting the572 conversion funnel."*5733. **Contrast failures, accessibility gaps, density issues.** Pull574 from `brand-review.html` Tensions when present (`T-color-imbalance`,575 `T-img-alt-empty`, etc.). E.g. *"Primary CTA `#008192` on white576 passes AA at 4.6:1 but the same teal on light-grey card surfaces577 drops to 3.1:1 — fails AA on those instances."*5784. **Cliché conventions the brand could move past while staying579 recognisably itself.** E.g. *"All headings render uppercase via580 CSS — the brand voice survives mixed-case headlines, and mixed-case581 reads as more current without changing identity."*5825. **Missed opportunities the existing site doesn't capitalise on.**583 E.g. *"The captured photography of named program participants is584 excellent but the home page renders all 6 portraits as 280×180585 thumbnails in a slick-slider; the photographs support full-bleed586 editorial treatment that would carry the trust signal far more587 effectively."*588589#### Specificity bar590591A weakness is specific enough when it cites:592- a measurable observation (size, ratio, contrast value, count, or593 named tension ID) drawn from the per-page JSON, the brand-review,594 or the brand-extraction;595- the design pattern at fault (named, e.g. "centered hero + dual CTA");596- one concrete fix the variant A brief will apply.597598*"The hero needs work"* fails all three. *"Hero photo is cropped to599280×180 in a 1440-wide viewport when the captured source supports60016:9 full-bleed at 1440×810; variant A fix: render at full-bleed and601move the headline to a left-anchored two-column overlay"* passes all602three.603604#### Format605606Markdown, with a `_provenance` frontmatter block per the artifact-map607convention. Each item is a numbered list entry with a category tag, a608weakness statement, and a one-line fix. Example:609610```markdown611<!--612_provenance:613 writtenBy: stardust:direct614 writtenAt: 2026-04-29T11:00:00Z615 readArtifacts:616 - stardust/current/_brand-extraction.json617 - stardust/current/brand-review.html618 - stardust/current/pages/<slug>.json619 stardustVersion: 0.10.x620-->621622# Improvements — <slug>6236241. **[dated-pattern]** Centered hero with double CTA pair (DONATE +625 LEARN MORE) is the 2019 nonprofit-template silhouette.626 *Fix:* Replace with a left-anchored editorial composition; one627 primary CTA, one secondary text-link.6286292. **[ia-clutter]** 4 distinct donor verbs across the home page630 (DONATE, GIVE, SUPPORT, CONTRIBUTE) fragment the funnel.631 *Fix:* Pick one canonical verb (DONATE, per the CTA frequency632 table); other instances become secondary "see all ways to give"633 links.6346353. **[contrast]** Brand teal on light-grey card surfaces resolves to636 3.1:1 — fails WCAG AA. (See `T-color-imbalance` in brand-review.)637 *Fix:* Reserve teal for white-ground only; use deepened teal638 (#005a68) on grey surfaces.6396404. **[cliché]** All headings render uppercase via CSS, including641 long-form section openers ("OFFICIAL FOUR STAR CHARITY"). The642 shout reads as urgency at first heading and as fatigue by the643 third.644 *Fix:* Mixed-case for headings ≥3 words; preserve uppercase only645 for short imperative CTAs and eyebrow labels.6466475. **[missed-opportunity]** Six named-participant portraits render648 as 280×180 thumbnails in a slick-slider; the captured source649 supports editorial-scale treatment.650 *Fix:* Replace carousel with a 3-column grid; portraits at 4:5651 aspect, 1:1 minimum 480px wide.652```653654#### Stopping condition655656If after reading the brand-review, the per-page JSON, and the657brand-extraction the agent **cannot name 3 specific weaknesses**658that meet the specificity bar, stop. Variant A has no brief; the659"better" claim fails. See § Failure modes (d).660661The agent should not rationalise — *"the hero is dated"* is not an662item, *"the typography could be more modern"* is not an item.663Genuine empty-list cases occur when the captured site is already at664a high execution level on observable dimensions. In that case the665honest answer is to surface the empty list and propose reduced666scope (density-and-contrast adjustments only, or pivot to a single667exploratory variant rather than three).668669### Phase 2.6 — Multi-variant fork (when N > 1)670671When the user requests N variants (phrase contains *"3 variants"*,672*"4 directions"*, or equivalent), variant slots are673**role-differentiated**, not seed-differentiated. Each slot serves a674distinct decision the customer is making — variants exist to675de-risk a brand decision, not to fan out into N rebrand676explorations.677678The previous default behavior (each variant rolls a fresh divergence679seed with anchor references picked per slot) produced what the680internal review called *"three rebrands"* output: each variant was681defensible standalone but none felt like the same brand. The682variant role contract below addresses this directly.683684#### Branch on `ia-fidelity` first685686The variant role contract is **`ia-fidelity`-aware**. Read the tier687stamped in Phase 1 (per `reference/intent-dimensions.md` § 9 and the688IA-fidelity tuning step above), and branch:689690**Under `ia-fidelity: verbatim` — surface-tuning forks (A1/A2/A3).**691692Variant slots are A1 / A2 / A3 (or A1…An for N > 3), all693surface-tuning forks of A's role. Each must differ from the others by694**≥ 2 surface changes** drawn from:695696- type-weight choice (e.g. 400 vs 600 vs 800 display)697- type-scale ratio (e.g. 1.2 vs 1.333 vs 1.5)698- density tier (within the multi-audience floor in § 4)699- motion energy (still vs gentle vs animated)700- color-temperature move within the captured palette (warm-leaning701 vs cool-leaning vs neutral-balanced)702- spacing rhythm (compact vs even vs generous within the floor)703704**Forbidden differentiation axes** under verbatim:705706- section sequence707- section presence / absence708- IA priority709- layout strategy of a major section710711A1 / A2 / A3 names indicate "different tunings of the same role,"712not different roles. When the user asks for *"3 variants"* while713`ia-fidelity` is verbatim, the fork produces A1 / A2 / A3714automatically; for N=1, just A.715716The improvements list (Phase 2.5) still anchors variant A's role —717A1/A2/A3 all apply every item from `<slug>-improvements.md`. They718differ only in surface treatment of the same applied fixes.719720The convergence detector in `prototype/SKILL.md` Discipline 10721becomes its inverse under verbatim: structural deltas722(section-sequence / presence / IA priority / layout strategy) are723**forbidden**, surface-only deltas are **required**.724725**Under `ia-fidelity: reimagined` — A + B + C role-differentiated.**726727Variant slots are A + B + C (or A + B + C + D…) per the variant role728contract below. The contract is unchanged from the prior behavior:729faithful + improvements / one captured trait amplified / different730captured trait amplified.731732The remainder of this Phase 2.6 (variant role contract, variant733differentiation contract, C-cliff failure mode) applies as written734under `reimagined`. Under `verbatim`, only the surface-fork rules735above apply; the variant role contract below does not.736737#### Variant role contract738739| Slot | Role | Brief |740|---|---|---|741| **A** | **Faithful + improvements** — *"this is what your site should be tomorrow."* | Same IA. Same section sequence. Same composition strategy. Apply every item from `<slug>-improvements.md` exactly — no extras, no embellishment, no creative reach. The brand team should react *"yes, that's us, with the obvious fixes."* This is the variant a risk-averse stakeholder green-lights. |742| **B** | **One captured trait amplified** — *"what if we leaned into X?"* | Pick one specific trait already in the captured brand surface — a motif underused in current execution, a photographic treatment the site doesn't fully exploit, an IA priority the current site underplays, a tonal register that survives in copy but not in layout. Justify in one sentence in the variant's shape brief: *"This variant amplifies <captured trait> in service of <brand personality move from PRODUCT.md>."* |743| **C+** | **Different captured trait amplified** — *"what if we leaned into Y?"* | Different from B by definition. Different captured trait. Different brand-personality move. Forbidden definitions: *"B but more"*, *"bolder fonts"*, *"more empty space"*, *"more brutalist"*, *"more editorial"*. Each subsequent variant must be a defensible standalone proposition. |744745Variants beyond C (D, E, …) follow the C+ contract — each amplifies746a distinct captured trait, declared in the shape brief.747748#### Surface forks of role-differentiated variants (B1/B2/B3, C1/C2/C3…)749750Under `ia-fidelity: reimagined`, a variant's role (A, B, C, …) may751spawn **surface forks** — tunings of the *same role* across the752same surface axes that A1/A2/A3 use under verbatim. The pattern:753754- `B` is "scroll cinema amplified" (the role).755- `B1`, `B2`, `B3` are surface tunings of B that all amplify scroll756 cinema, but vary along type-weight, type-scale, density,757 motion-energy, color-temperature, or spacing-rhythm.758759This composes the verbatim-mode surface-fork machinery with the760reimagined-mode role differentiation: the **role contract** binds761the captured trait being amplified; the **surface-fork delta**762governs how that trait reads in chrome.763764Surface forks of role-differentiated variants are **opt-in, not765default**. The default fork under reimagined is still A + B + C.766Surface forks appear in two ways:7677681. **Explicit user request**: *"design 5 variant directions for B"*769 — the user asks for surface tunings of an existing role-770 differentiated variant. Render B1 / B2 / B3 / B4 / B5, each771 amplifying B's captured trait but with distinct surface tunings.7722. **Via `--add-variant <name>` with a parent declared**: e.g.,773 `--add-variant B3` after B exists. The parent inferred from the774 slot name's letter prefix (`B3` → parent `B`). See § Add-variant775 mode → Per-field inheritance rules for the inheritance chain.776777Surface forks of role-differentiated variants follow the **same778≥ 2 surface-changes contract** as A1/A2/A3 — the per-pair779differentiation is surface-only (type-weight / type-scale / density780/ motion-energy / color-temperature / spacing-rhythm), with the781**captured trait being amplified held constant** across the fork.782Structural differentiation (section sequence / presence / IA783priority / layout strategy) is forbidden between B and its surface784forks B1/B2/B3 — the role IS the captured trait, and changing785structure changes the role.786787The variant-convergence detector in `prototype/SKILL.md`788Discipline 10 reads the variant's parent slot: when comparing789B vs B3 (parent–child surface fork), it applies the verbatim-style790inverse rule (surface deltas required, structural deltas791forbidden); when comparing B vs C (sibling role-differentiated792variants), it applies the reimagined-style rule (structural deltas793required).794795The cap on motion-energy and other amplified surface axes is the796parent role's cap — a B3 that amplifies motion-energy beyond B's797ceiling must declare a **cap override** in its DESIGN.json798extensions with a one-sentence rationale (e.g. *"B3 raises B's799motion choreography count from ≤ 3 to ≤ 5 to accommodate the loud-800register tuning of scroll cinema"*). The override must cite a801captured-source basis or it refuses; cap overrides without a802captured-source rationale produce surface drift instead of trait803amplification.804805#### Variant differentiation contract806807Each pair of variants must differ by **≥ 2 substantive changes**808drawn from this set:809810- section sequence (which sections appear in which order),811- section presence / absence (a section in one variant, not in another),812- layout strategy of a major section (e.g. hero is split-half vs.813 full-bleed-photo vs. type-led),814- IA priority (which audience leads the home — donor vs. recipient815 vs. volunteer for nonprofits; product vs. story for commerce).816817Variants that fail the ≥ 2 changes test are rendered as the same818variant under different chrome — *"variants are barely different"*819is the published failure mode and is grounds for refusing render.820See § Failure modes (b) — when only 1–2 captured traits are821distinct enough to amplify, the agent surfaces this and proposes8221 or 2 variants rather than producing 3 weak ones.823824#### The C-cliff failure mode825826When defining variant C+, the following definitions are827**render-refusal conditions**:828829- *"Everything from B but more"* (B+more is not a direction).830- *"120pt+ display fonts"* (size-as-personality is not a captured831 trait).832- *"96px+ section padding everywhere"* (padding-as-personality is833 not a captured trait — and conflicts with the density floor in834 `intent-dimensions.md` § 4 anyway).835- *"Extreme airy"* / *"extreme dense"* / *"extreme [axis]"* — slider836 positions pushed past the prior variant are not directions.837- Editorial-register vocabulary (*atelier*, *the studio*,838 *mise-en-place*, *the journal*) when the brand register is839 product / commerce / direct-services. See840 `divergence-toolkit.md` § 1 → *Voice-rule moves* →841 `Editorial-register vocabulary applied to non-editorial brands`.842843C+ must answer *"what if we leaned into Y?"* with a specific Y844from the captured surface, not a slider position pushed past B.845846The C-cliff name comes from the observed pattern where a8473-variant fork has A defensible, B defensible, and C reading as848*"unprofessional"* rather than *"a third proposition."* The fix is849not to soften C — it is to define C against a captured trait850instead of against B.851852### Phase 3 — Author target PRODUCT.md853854Write `PRODUCT.md` at the project root using impeccable's855`reference/teach.md` as the **format spec** (not as a runtime command856to invoke). Direct authoring is intentional: by the time `direct`857runs, every answer impeccable's interview would surface has already858been resolved through stardust's intent-reasoning + divergence859resolution above.860861Sections to populate:862863- **Register** — from the resolved direction's `register` axis.864- **Users** — from the resolved audience tuple plus tone signals from865 the extracted brand surface.866- **Product Purpose** — from the user's phrase + extracted hero copy867 + resolved tone, written as a one-line value statement followed by868 one-line scope.869- **Brand Personality** — derived from resolved expressive axis +870 tone + reference set. Weight axes the user explicitly moved over871 inherited values.872- **Anti-references** — the user's stated anti-refs **plus** any873 anti-toolbox guardrails relevant to the resolved direction874 (e.g. "modernise" triggers the Generic-2026-SaaS silhouette875 guardrail; list it explicitly so prototype and polish enforce it).876- **Design Principles** — 3-5, each mapping to a specific axis877 movement. Format: one verb-led principle, one-line elaboration.878- **Accessibility & Inclusion** — populated when the constraint set879 includes `a11y-first`, `RTL-required`, or similar. Otherwise880 inherit impeccable's defaults.881882Where a section cannot be populated with confidence from inputs,883mark it `<!-- _provenance: inferred -->` with a one-line basis884sentence. Never invent strategy.885886### Phase 4 — Author target DESIGN.md and DESIGN.json (site-level only)887888Write `DESIGN.md` at the project root using impeccable's889`reference/document.md` as the format spec — Stitch YAML frontmatter890plus the 6 canonical sections in fixed order.891892**Site-level only.** `direct` authors the design **system**, not893page-level deployments. Page-specific composition decisions live894in `stardust/prototypes/<slug>-shape.md` written by `prototype`895Phase 1 — see `skills/prototype/reference/page-shape-brief.md`.896897The boundary is **abstract role vs literal deployment**:898899| In DESIGN.md / DESIGN.json (site system) | In `<slug>-shape.md` (page deployment) |900|---|---|901| Token vocabulary (colors, typography, spacing, radii) | Per-page section list and order |902| Voice rules ("Mixed-Case-Headlines"), anti-refs | Literal copy per section (sourced from current/pages/<slug>.json) |903| Anti-toolbox audit, divergence trace | Page-specific layout decisions ("hero is 5/3 split on home") |904| Abstract component vocabulary: `button-primary`, `button-secondary`, `card`, `input`, `badge`, `link` (default treatment, density, sizing — NO page-specific dimensions or content) | Section-level component dimensions (`the211Panel` at 320×260 with dock points per viewport) |905| Named system-component **roles** (a `header` exists, a `footer` exists, a `cta-band` pattern exists) | System-component **deployment** (literal tile labels in fixed order, link targets, copy variants) |906| Default visual treatment for each abstract component | Per-page composition (statRow with literal "100 YEARS · 18,400 PEOPLE HOUSED · …") |907| Voice samples (do/don't, tone exemplars) | Per-page interaction model and key states |908909Concrete examples of items that **must not** appear in DESIGN.md /910DESIGN.json:911912- Literal tile labels for any system-component pattern.913- Section-level pixel dimensions, dock points, breakpoint-specific914 widths.915- Stat numbers, addresses, quotes, named-person references.916- "On home, the hero is X" — that's a home-page deployment.917- Per-page copy variants ("on the donate page the CTA reads Y").918919If a redesign demands a section-level dimension or a literal label920that feels site-wide ("every page has a 211 panel docked at the921bottom-right"), encode it as an **abstract role** in DESIGN.json922(e.g. `extensions.systemComponentRoles.persistent-help` with923purpose / position-class but no literal copy or dimensions) and let924each page's shape brief specify the deployment.925926Token sources:927928- **`colors`** — from the picked palette (palette-picker.md output)929 or the inherited palette with role-renaming. Role names must930 satisfy toolkit § 4 (brand-native, no `Primary` / `Secondary` /931 `Alarm` etc. as sole role names).932- **`typography`** — from the chosen font deck. Sizes scaled by the933 resolved expressive axis (drenched → ratio ≥ 1.333; committed →934 ratio 1.25; restrained → ratio 1.125-1.2). Heading vs body935 assignments inherit from the deck.936- **`rounded`** — derived from extracted brand-surface937 `borderRadius.primary` mode, unless the direction moves938 distinctiveness toward `singular` (in which case re-derive from the939 font deck's tonal cousins).940- **`spacing`** — 4pt base scale; `sectionPadding` propagated from941 the density tier stamped in Phase 1 (`reference/intent-dimensions.md`942 § 4):943 - `airy` → `sectionPadding.desktop: 96px`, `tablet: 72px`, `mobile: 48px`944 - `balanced` → `sectionPadding.desktop: 64px`, `tablet: 48px`, `mobile: 32px` ← brand-register default945 - `packed` → `sectionPadding.desktop: 48px`, `tablet: 36px`, `mobile: 24px` ← product-register default946947 The agent does **not** re-ask the density question here — the tier948 was resolved in Phase 1 (asked once when the phrase didn't move949 the axis, defaulted to balanced for brand register if unanswered).950 Pick the value deterministically from the stamp.951952 **Hard floor enforcement.** When the captured page inventory shows953 >5 sections OR >2 audience tracks (per954 `reference/intent-dimensions.md` § 4 → "Hard floor for955 brand-register multi-audience sites"), the resolved956 `sectionPadding.desktop` is bounded at ≤ 64px and ≥ 40px on every957 variant including the highest-divergence one. If Phase 1 stamped958 `airy` despite the trigger conditions firing, surface the conflict959 before writing tokens — *"density tier `airy` was selected but the960 captured inventory triggers the multi-audience hard floor; pick (a)961 override floor (`density: airy (user-pinned)` in direction.md) or962 (b) accept the floor (sectionPadding capped at 64px)."* Default to963 (b) when the user does not respond.964- **`components`** — 4-6 canonical components (`button-primary`,965 `button-secondary`, `card`, `input`, `badge`, `link`) populated966 from extracted brand-surface `componentStyle`, with values967 adjusted for direction movements.968969Write `DESIGN.json` (schemaVersion 2) with:970971- `extensions.colorMeta`, `typographyMeta`, `shadows`, `motion`,972 `breakpoints` — filled from the same sources as DESIGN.md. The973 `motion` block carries the **register selection** (when974 cinematic motion may be applied at prototype time):975976 ```json977 "motion": {978 "register": "arrival | kinetic-display | live-systems | editorial | kinetic-grid",979 "registerRationale": "<one-line citation back to PRODUCT.md Brand Personality trait that selected this register>",980 "easings": { "entrance": "...", "transition": "...", "expo": "..." },981 "durations": { "enter": <ms>, "stagger": <ms> },982 "parallax": { "translate": <vh>, "fade": <0-1>, "rangeStart": <%>, "range": <%> }983 }984 ```985986 Picked per the **register selection heuristic** in987 `skills/prototype/reference/motion-registers.md` § Selection988 heuristic, reading the resolved `PRODUCT.md` § Brand Personality:989990 | Personality traits (any match) | Register |991 |---------------------------------------------------------------------------|-------------------|992 | `civic-formal` + (`institutional` OR `place-led`) | `arrival` |993 | `signage-led` OR `wayfinding-first` OR `display-typography-signature` | `kinetic-display` |994 | `operationally-transparent` OR `data-led` OR `dashboard-register` | `live-systems` |995 | `editorial` OR `slow-paced` OR `publication-register` | `editorial` |996 | `product` OR `SaaS` OR `transactional` OR `modular-catalogue` | `kinetic-grid` |997 | (ambiguous / no clear match) | `arrival` |998999 Token defaults per register are sourced from1000 `skills/prototype/reference/motion-registers.md` § The five1001 registers; `direct` copies them verbatim into the `motion`1002 block unless the user has provided overrides during intent1003 reasoning. The `registerRationale` field records the one-line1004 justification so reviewers can audit the choice. **`direct`1005 does not apply the motion** — that happens at prototype time1006 under `--cinematic`. `direct` only **selects** the register.1007 Pages whose redesign does not need motion can leave1008 `register` absent; cinematic prototype will then either ask or1009 pick from the heuristic at render time.10101011 **Per-variant placement (when N > 1 variants).** For1012 multi-variant runs, the `motion` block goes into the1013 variant-specific `DESIGN-<id>.json` files (see § Multi-variant1014 DESIGN files below), not into the site-level `DESIGN.json`.1015 Variants that should render static omit the block entirely;1016 variants that should engage cinematic motion declare a1017 `register`. This is what lets one variant (typically C) be1018 cinematic while siblings stay static — `prototype` Phase 2.41019 reads `DESIGN-<id>.json.extensions.motion.register` per1020 variant and fires only where present.10211022 When the user's intent phrase contains explicit motion direction1023 ("make it cinematic", "feel alive", "move like signage"),1024 `direct` picks the register and notes the source in1025 `registerRationale` as `"user-phrase: <verbatim>"`.1026- `extensions.divergence` — full audit trail per the v2 storage shape1027 in `divergence-toolkit.md`. Includes the brand-faithful inversion1028 log (per `reference/direction-format.md` § Divergence inputs)1029 capturing pure-color or hex-format retentions.1030- `extensions.componentStyle` — the **abstract** v1 fields1031 (`buttons`, `cards`, `inputs`, `dualCTAPattern`). **Default**1032 treatment per component, no per-page dimensions or literal copy.1033- `extensions.systemComponentRoles` — the **abstract roles** for1034 named cross-page patterns (e.g. `persistent-help`, `cta-band`,1035 `header`, `footer`). Each role carries purpose, position class,1036 and any site-wide constraint — **not** literal copy, dimensions,1037 or per-viewport dock points (those are page-deployment, in1038 `<slug>-shape.md`).1039- `extensions.voice` — sampled DOs and DON'Ts derived from1040 `_brand-extraction.json` voice samples + the resolved tone.1041- `narrative.northStar`, `overview`, `keyCharacteristics`, `rules`,1042 `dos`, `donts` — derived from the resolved direction. Toolkit § 71043 Optional House Standards land here in `narrative.rules[]`.10441045Every component HTML/CSS snippet in `components[]` must be1046self-contained, use `ds-` class prefixes, and respect impeccable's1047hard rules (OKLCH only, no pure black/white, no glassmorphism, no1048side stripes, no gradient text, ≥ 1.25 type ratio for brand1049register).10501051#### IA-priority preservation audit (Mode A)10521053After tokens are drafted but before they land in the variant DESIGN1054files, run the IA-priority preservation audit per1055`reference/intent-dimensions.md` § 8. For each captured signal that1056fires a trigger condition (commercial conversion, search-led IA,1057donation funnel, crisis affordance, audience routing), record an1058`extensions.iaPriorities[]` entry in `DESIGN.json`:10591060```json1061[1062 {1063 "signal": "crisis-affordance",1064 "evidence": "pages/home.json#landmarks[hero] contains heading 'Looking for immediate shelter?' + phone 801-990-9999",1065 "preserveAs": "first-viewport",1066 "scope": "site-wide",1067 "mutability": "movable"1068 }1069]1070```10711072Each entry is a constraint that downstream `prototype` and `migrate`1073must honor — a variant whose home shape brief omits the crisis1074affordance from the first viewport fails the audit and is rejected.1075The audit is the structural enforcement of § 8; without it, IA-1076priority preservation is a guideline rather than a contract.10771078The `mutability` field reflects the `ia-fidelity` stamp from Phase 11079(per `reference/intent-dimensions.md` § 9): `locked` under verbatim1080(variants may not move the priority at all — A1/A2/A3 are surface1081forks), `movable` under reimagined (variants may demote / promote /1082re-shape the priority's deployment, but the § 8 floor still fires).1083The field is stamped once at Phase 4 and is the source of truth1084prototype reads.10851086#### Multi-variant DESIGN files (when N > 1)10871088When the user requested N variants (Phase 2.6 active), Phase 41089writes per-variant design files at the project root instead of a1090single pair:10911092```1093PRODUCT.md ← shared across variants (strategy doesn't change)1094DESIGN-A.md / DESIGN-A.json ← variant A (faithful + improvements)1095DESIGN-B.md / DESIGN-B.json ← variant B (one captured trait amplified)1096DESIGN-C.md / DESIGN-C.json ← variant C (different captured trait amplified)1097```10981099`PRODUCT.md` is shared because audience, register, and content1100strategy are per-brand, not per-variant. Each variant's DESIGN1101files inherit the shared `extensions.iaPriorities[]` audit from the1102above step — variants cannot opt out of IA-priority preservation1103within Mode A.11041105When the resolved mode is rebrand (`--rebrand` or rebrand-trigger1106phrase), the multi-variant fork still writes per-variant DESIGN1107files but PRODUCT.md may also vary — rebrand permits the strategy1108to shift, not just the visual treatment.11091110### Phase 5 — Write direction.md and update state11111112Write `stardust/direction.md` per1113`skills/direct/reference/direction-format.md`. The full reasoning1114trace: phrase, restatement, movements, gaps, questions and answers,1115resolved axes, divergence inputs, command sequence proposed, user1116confirmation, every assumption that defaulted in. Re-directs append1117to the file as a new section; prior direction stays as history.11181119Update `stardust/state.json`:11201121- `direction.resolvedAt` = now1122- `direction.phrase` = the user's verbatim phrase1123- `direction.directionFile` = `"stardust/direction.md"`1124- For each page in scope: `status` `extracted` → `directed`1125- On `--re-direct`, for each page already in `prototyped` /1126 `approved` / `migrated`: set `stale: true` and1127 `staleReason: "direction changed at <ts>"`. Do not change the1128 status itself; the on-disk artifact is still valid, just out of1129 step.11301131Print a one-screen summary report and recommend the next step:11321133```1134direction resolved1135==================11361137Phrase: "make it more expressive for a young audience"1138Audience: Gen Z college / first-job (resolved via Q1)1139Register: brand (inherited from current/PRODUCT.md)11401141Movements:1142 expressive axis restrained -> committed1143 distinctiveness familiar -> distinctive1144 tone serious -> playful1145 density (unchanged)1146 audience (resolved: Gen Z college / first-job)11471148Divergence:1149 seed 1970s x Riso print x zine x monochrome-tint1150 font deck zine-maximalist1151 palette "Brutalist Dawn" (picked from library)11521153Wrote:1154 PRODUCT.md, DESIGN.md, DESIGN.json1155 stardust/direction.md11561157State:1158 25 pages: extracted -> directed1159 0 stale prototypes (none exist yet)11601161Next: $stardust prototype (defaults to home page)1162```11631164## Outputs11651166| Path | Purpose |1167|---------------------------------------|----------------------------------------------------|1168| `PRODUCT.md` | Target strategy (impeccable format). Shared across variants when N > 1 under Mode A. |1169| `DESIGN.md` | Target visual system (Stitch frontmatter + 6 sections). Single-variant runs only. |1170| `DESIGN.json` | Sidecar with extensions (divergence, componentStyle, voice, iaPriorities) and narrative. Single-variant runs only. |1171| `DESIGN-{A,B,C,…}.md` | Per-variant DESIGN files when the user requested N > 1 variants (Phase 2.6 active). |1172| `DESIGN-{A,B,C,…}.json` | Per-variant DESIGN sidecars matching the .md files. |1173| `stardust/prototypes/<slug>-improvements.md` | Improvements list (Mode A only, written in Phase 2.5). The load-bearing artifact for variant A. |1174| `stardust/direction.md` | Resolved direction + full reasoning trace + per-variant resolutions when N > 1. |1175| `stardust/state.json` | Updated with direction + per-page status changes + `direction.variantMode` + `direction.variants[]` when N > 1. |11761177## Failure modes11781179- **No extracted state.** Abort and recommend `$stardust extract`.1180- **Phrase too vague even after two questions.** Persist the partial1181 reasoning to `stardust/direction.md` under a `# Pending` section,1182 ask the user to refine further, do **not** write `PRODUCT.md` /1183 `DESIGN.md` / `DESIGN.json` from incomplete reasoning.1184- **Re-direct with prior approved or migrated pages.** Always confirm1185 before stale-flagging. The flag is visible to the user and1186 reversible (clearing happens automatically on successful re-run of1187 prototype or migrate), but a re-direct invalidates work the user1188 may have signed off on.1189- **Anti-toolbox audit removes too many moves.** If the resolved1190 direction collapses to defaults after the audit strips1191 unjustifiable hits, surface this to the user and re-prompt for1192 reference anchors before writing tokens.1193- **(b) Insufficient brand signal for N variants.** When the1194 captured brand surface has fewer than 3 distinct moves to1195 amplify (e.g., monochrome palette, single type face, no1196 distinctive motifs, or `signal-thin` per § Setup step 6), refuse1197 to render N ≥ 3 variants under Mode A. Surface honestly:1198 *"the captured surface has 2 distinct traits to amplify; producing1199 3 variants would force one to invent moves not present in the1200 brand."* Propose 1 or 2 variants and let the user choose, or1201 recommend extract with a wider crawl. Better one strong variant1202 than three weak ones.1203- **(c) Hard rule conflict.** When Mode A is active *and* the1204 user's phrase requires violating a Mode A pin (e.g., the user1205 asks for *"a completely different palette"* while migration mode1206 is active and `--rebrand` was not passed), stop. Name the1207 conflict explicitly: *"You asked to keep the brand and to change1208 the palette — those are not compatible. Did you mean (a) keep the1209 current palette and only refresh execution, (b) rebrand1210 (`--rebrand`) and roll a new palette, or (c) Mode A with a1211 targeted palette move (single role recolored, rest pinned)?"*1212 Wait for explicit answer.1213- **(d) Empty improvements list.** When Phase 2.5 produces fewer1214 than 3 weaknesses meeting the specificity bar, stop before1215 rendering any variant. Variant A's brief depends on the list;1216 without it, the *"better"* claim fails. Surface honestly:1217 *"the captured site is already at a competent execution level on1218 observable dimensions — variant A would reduce to spacing and1219 contrast adjustments only."* Ask the user whether to (a) proceed1220 with reduced scope (density + contrast only), (b) extract1221 additional pages (`extract --cap 25` or higher) to surface more1222 weaknesses, or (c) pivot to rebrand mode (`--rebrand`) where the1223 brand-fidelity floor doesn't apply.12241225## Prep mode (--prep)12261227When invoked with `--prep`, direct runs an extended pass that1228finalizes the inventory data structures migrate consumes.1229Discovery-mode runs are unchanged: intent reasoning, divergence-1230toolkit resolution, target-spec authoring.12311232`--prep` adds five things on top of the standard procedure:12331234### 1. Type catalog confirmation12351236Surface the page-type catalog inferred by `extract --prep` (in1237`state.json.pages[].type`). Show counts per type and a sample of1238slugs per type:12391240```1241Page types from extract:1242 landing 1 (home)1243 article 84 (news/post-2026-04-15-housing-summit, news/post-2026-04-08-..., ...)1244 listing 6 (news, programs, events, ...)1245 program 12 (programs/shelter, programs/case-management, ...)1246 form 3 (donate, contact, volunteer)1247 static 18 (about, team, financials, ...)1248 unique 3 (404, search, faq)12491250Confirm catalog (yes / refine "<phrase>")?1251```12521253User can confirm or refine. Refinements: rename a type, split a1254type into finer-grained ones (e.g., `article-feature` vs.1255`article-press`), merge two types, mark specific pages as1256`unique`. Updates land in `state.json.pages[].type`.12571258### 2. Module catalog finalization12591260Surface the module candidates proposed by `extract --prep`1261(`DESIGN.json.extensions.modules[]` with `status: candidate`).1262For each candidate:12631264```1265hotline-211 (5 instances)1266 Slot candidates: phone, hours, headline, cta-label1267 Found in: home, get-help, donate, news, programs12681269 Confirm? (name "<id>" / promote / prune / refine slots)1270```12711272User actions per candidate:12731274- **Confirm.** Promote `status: candidate → confirmed`. Module1275 ID, slots, defaults are accepted as-is.1276- **Rename.** Change the auto-generated ID to a brand-native name.1277- **Prune.** Remove from the catalog (the candidate was a1278 spurious match; instances will render as inline content).1279- **Refine slots.** Mark slots required, set defaults, add or1280 remove slots, adjust types.12811282Confirmed modules become the catalog migrate consumes.12831284### 3. Color reservations12851286If the resolved direction reserves any color to a specific1287module/lockup (e.g., centennial-red `#DC323D` reserved to the1288`trh-100-lockup` module), capture in1289`DESIGN.json.extensions.colorReservations[]`:12901291```json1292[1293 { "color": "#DC323D", "reservedFor": ["module:trh-100-lockup"] }1294]1295```12961297Migrate validates that reserved colors appear only in their1298declared contexts; violations refuse the page.12991300### 4. Wider direction re-evaluation13011302Discovery mode resolved direction against a 5-page sample. Prep1303mode has the full inventory. Re-read the broader content surface1304and check:13051306- Does the resolved register still hold? (e.g., did discovery1307 miss a service-led section that pulls toward a different1308 register?)1309- Are there new tensions surfaced by the wider crawl that affect1310 direction?1311- Do any anti-references need updating?13121313If the re-evaluation surfaces a meaningful divergence from the1314discovery-mode direction, surface to the user. If the user wants1315to re-direct, they run `$stardust direct --re-direct` separately;1316the prep run itself is non-destructive.13171318### 5. Site-level metadata defaults13191320Capture brand-level metadata defaults in1321`DESIGN.json.extensions.metadata`:13221323- `siteName` — brand name (typically from `<title>` patterns or1324 `og:site_name`)1325- `defaultOgImage` — default OG image when a page doesn't have1326 its own1327- `themeColor` — typically already in DESIGN.md1328- `organization` — `Organization` JSON-LD entry (name, url,1329 logo, sameAs)1330- `locale` — default locale1331- `keyFacts` — optional: the short list of crawlable fact strings1332 the brand must expose in server-rendered content (price, license,1333 maker, requirement). Consumed by deploy's atomic-contract raw-HTML1334 grep (deploy SKILL.md #86); omit when the direction names none.13351336These are composed with per-page metadata at migrate time. See1337`skills/migrate/reference/metadata-and-jsonld.md` for the1338composition rules.13391340### Prep summary13411342```1343direct --prep complete1344======================13451346Type catalog: confirmed (7 types, 127 pages)1347Module catalog: confirmed (8 modules, slot vocabularies set)1348Color reservations: 1 (#DC323D reserved to trh-100-lockup)1349Brand metadata: set (siteName, defaultOgImage, themeColor, organization, locale)1350Direction: no change (wider crawl confirmed)13511352Next: $stardust prototype --prep (fill template gaps, write canon)1353```13541355Default mode is unchanged.13561357## Add-variant mode (--add-variant)13581359When the user has already approved (or rendered) variant A and1360asks for B / C / etc. as alternatives, `--re-direct` is too1361heavy: it replaces the active direction, re-runs Phase 11362reasoning, and stale-flags every approved or migrated page1363against the prior direction. The user is **not** changing1364direction — they are extending it with additional variant1365expressions of the same direction. `--add-variant <name>` is the1366incremental-extension flow.13671368The flow surfaced on the 2026-05-04 ups.com session: variant A1369shipped, the user later asked for B and C as the directional1370alternatives that had been surfaced in the initial menu but not1371committed to. Without an additive flag, the agent had to author1372B and C as page-shape briefs + proposed HTML only (skipping1373`DESIGN-B.{md,json}` / `DESIGN-C.{md,json}`), embedding their1374system-level deviations inline in per-variant CSS. Migrate then1375had no machine-readable source to re-derive B / C from.13761377### Procedure13781379When `--add-variant <name>` is passed:138013811. **Setup** runs as normal (impeccable dep check, state read,1382 brand-extraction read, brand-signal classification).1383 Validation step 5 (provenance) is **skipped** — add-variant1384 does not consume per-page extracted JSON; it consumes the1385 already-resolved direction. The brand-signal stamp stays1386 useful for the inheritance rules below.13872. **Skip Phase 1 (Reasoning).** The user's intent is *"add1388 another variant against the existing direction,"* not "resolve1389 a fresh direction." If the existing `direction.md` Active1390 section is missing, refuse — there is no direction to extend.13913. **Skip Phase 2 (Mode detection + divergence).** Mode is1392 inherited from the existing direction (typically Mode A1393 given the brand-faithful default). The seed, font deck,1394 palette, and ground family are all inherited as-is.13954. **Run Phase 2.5 (Improvements list)** **only if** the1396 existing direction is Mode A and a variant-A improvements1397 list does not yet exist for the slug being prototyped later.1398 The improvements list is shared across all Mode A variants1399 per `direct/SKILL.md` § Phase 2.5; if it already exists, the1400 add-variant pass reads it as input and does not regenerate.14015. **Run Phase 2.6 (Multi-variant fork)** only enough to1402 resolve the **new variant's** role per the variant role1403 contract (faithful + improvements / one captured trait1404 amplified / different captured trait amplified). Surface the1405 role choice to the user before proceeding. Do not re-run the1406 role contract for variants that already exist — their roles1407 are stamped in `direction.md`.14086. **Run Phase 4 against the new variant only.** Derive the1409 variant's system-level deviations (font-weight changes,1410 surface-color additions, motif amplifications, etc.) and1411 write:1412 - `DESIGN-<name>.md` — Stitch frontmatter + 6 canonical1413 sections, **inheriting** every token that doesn't change1414 for this variant.1415 - `DESIGN-<name>.json` — sidecar with extensions1416 (`divergence`, `componentStyle`, `voice`, `iaPriorities`).1417 When variant A has been written as the unsuffixed1418 `DESIGN.{md,json}` (single-variant flow), upgrade A's files1419 to the suffixed form (`DESIGN-A.{md,json}`) and **leave the1420 unsuffixed files in place as backward-compatible aliases1421 pointing at A** — `migrate` and `prototype` continue to1422 resolve the unsuffixed form to A.14237. **Append a section to `direction.md`** under the existing1424 Active section, titled `## Variant <name>`, recording: the1425 variant's role (faithful / amplified-trait), the captured1426 trait being amplified (when applicable), the system-level1427 deviations from variant A, the IA-priority audit (must1428 match A's audit — variants cannot opt out of preservation1429 under Mode A), and a one-line thesis.14308. **Skip Phase 5 update of state.json's `direction.*` block**.1431 The active direction has not changed; the direction file's1432 resolvedAt / phrase / directionFile fields stay untouched.1433 Pages already in `prototyped` / `approved` / `migrated`1434 states are **not** stale-flagged — adding a variant is1435 additive, not a re-direction. State.json gains a1436 `direction.variants[].<name>` entry (per1437 `state-machine.md`'s multi-variant additions) recording the1438 new variant's id and DESIGN files.14391440### Variant parentage and inheritance chain14411442`--add-variant <name>` infers a **parent** from the slot name:14431444- Slot name is a single letter (`A`, `B`, `C`, ...): parent is the1445 *active direction* (the resolved direction in `direction.md`).1446 The variant inherits from the active direction's resolved seed.1447- Slot name is a letter + digits (`A1`, `A2`, `B3`, `C2`...):1448 parent is the variant whose id is the letter prefix (`A1` → `A`,1449 `B3` → `B`). The variant is a **surface fork** of its parent1450 per § Surface forks of role-differentiated variants. The1451 parent must already exist; if not, refuse and recommend adding1452 the parent first (`--add-variant B` before `--add-variant B3`).14531454Inheritance chains under reimagined mode:14551456- `A → active-direction` — A inherits from the resolved direction.1457- `B → active-direction` — B inherits from the resolved direction;1458 its captured trait is declared in its shape brief.1459- `B3 → B → active-direction` — B3 inherits from B (parent surface1460 fork); B's captured trait + role propagate, B3 declares its1461 surface tuning.14621463Record the chain in `direction.md`'s per-variant section as1464`Inheritance chain: <child> → <parent> → <root>`. Stardust1465`state.json` records the parent in1466`direction.variants[].parentVariant` (per1467`stardust/reference/state-machine.md` § Variants block).14681469### Per-field inheritance rules14701471When writing `DESIGN-<name>.{md,json}`, fields fall into three1472categories:14731474| inherit-as-is | inherit-then-extend | variant-local |1475|---|---|---|1476| `colors` (palette) — Mode A pin | `componentStyle` — base treatment from A; variant adds variant-local component overrides keyed by `data-variant="<name>"` | `narrative.northStar` — per-variant thesis |1477| `typography` family / scale — Mode A pin | `extensions.divergence.brand_faithful_inversions[]` — A's list is the floor; variant may add inversions that follow from its amplified trait | `narrative.overview`, `narrative.keyCharacteristics` — written against the variant's role |1478| `rounded`, `spacing` — site-wide tokens | `extensions.iaPriorities[]` — same audit as A; cannot opt out under Mode A | `voice.examples.do/dont` — variant may amplify a captured voice register A didn't lean on |1479| `extensions.colorMeta`, `typographyMeta`, `breakpoints` | `narrative.rules[]` — A's house standards inherit; variant adds its own | `extensions.divergence.seed.anchors[]` — variant may add a captured trait as the anchor for its amplified-trait role |1480| `extensions.systemComponentRoles` (abstract roles) | | The variant-id stamp in `_provenance` |14811482Variants **cannot**:14831484- Introduce a font outside the captured surface (Mode A pin).1485- Introduce a color outside the captured palette (Mode A pin).1486- Shift the register from PRODUCT.md (per-brand strategy is1487 variant-invariant under Mode A).1488- Skip the IA-priority audit (variants are visual expressions,1489 not strategic re-shapings).14901491**Surface-fork-specific rules (when parent is a letter-prefix1492variant like B → B3):**14931494- The captured trait being amplified is **inherited from the parent1495 variant**. The surface fork cannot change which trait is amplified1496 (changing it changes the role, which is a sibling variant, not a1497 surface fork).1498- The role narrative (B's "scroll cinema amplified" thesis) is1499 inherited; the surface fork's narrative extends it with its1500 per-axis tuning ("B3 amplifies the same captured trait in a loud1501 register: weight 700 body H3s, perfect-fifth type scale, packed1502 density").1503- The parent's caps (motion-energy ≤ N, color-temperature within1504 range, etc.) inherit. Cap overrides are permitted but must be1505 declared in the surface fork's DESIGN.json `extensions.capOverrides[]`1506 with a one-sentence rationale citing a captured-source basis.1507- Structural fields (IA priority order, section sequence, layout1508 strategy of major sections) inherit verbatim from the parent —1509 changing them produces a sibling variant, not a surface fork.15101511When the user's add-variant request would violate one of the1512forbidden rules, refuse with the same § Failure modes (c) hard1513rule conflict pattern: name the conflict, propose targeted1514alternatives (rebrand mode via `--rebrand`, or a Mode A1515expression that fits within the pins).15161517### Add-variant summary15181519```1520direct --add-variant B complete1521==============================15221523Variant role: one captured trait amplified — editorial confidence1524Captured trait: caption-band typography + named-driver portraits1525Inheritance: palette, typography, rounded, spacing inherited from A1526Variant-local: narrative.northStar, voice DOs (eyebrow voice expanded),1527 componentStyle.heroOverlay (variant override)1528IA-priority audit: matches A — commercial-conversion + crisis-affordance preserved15291530Wrote:1531 DESIGN-B.md, DESIGN-B.json (alongside DESIGN-A.{md,json})1532 stardust/direction.md (appended ## Variant B section)15331534State:1535 pages unchanged (no stale flags — add-variant is additive)1536 direction.variants[]: A + B15371538Next: $stardust prototype <slug> --variant B1539```15401541### Failure modes specific to add-variant15421543- **No active direction.** Refuse — there is nothing to extend.1544 Recommend `$stardust direct` first.1545- **Variant `<name>` already exists.** Refuse — pass `--re-direct`1546 and re-resolve the variant explicitly if a refresh is wanted,1547 or pick a different name (variants are case-sensitive; B and b1548 are distinct entries but discouraged for clarity).1549- **Mode A constraint violation.** Per § Per-field inheritance1550 rules above; surface the conflict and propose targeted1551 alternatives.1552- **Existing direction is rebrand mode.** Add-variant is allowed,1553 but the inheritance rules relax — rebrand permits a different1554 PRODUCT.md per variant. Surface the relaxed contract to the1555 user before writing.15561557## References15581559- `skills/stardust/reference/intent-dimensions.md` — the 8 axes1560 (the 7 axes plus § 8 IA-priority preservation, the Mode A1561 constraint that fires on captured commercial-conversion / crisis /1562 audience-routing signals).1563- `skills/stardust/reference/intent-reasoning.md` — the procedure.1564- `skills/stardust/reference/intent-examples.md` — worked examples.1565- `skills/stardust/reference/impeccable-command-map.md` — when to1566 reach for each impeccable command (used when building the plan).1567- `skills/stardust/reference/reference-research.md` — the1568 research-first anchor procedure (refero MCP → WebSearch → seed1569 fallback) consumed by Mode B and Default mode; evidence shape and1570 budgets.1571- `skills/stardust/reference/divergence-toolkit.md` — anti-mediocrity1572 inputs and the v2 storage shape for the audit trail. Contains the1573 anti-toolbox additions for multi-variant moves1574 (`C-cliff overshoot`, `Anonymous middle variant`, `Variant1575 homogeneity`) and universal hardening (`Fabricated content`,1576 `Hero text on photographic background without contrast scrim`,1577 `Editorial-register vocabulary applied to non-editorial brands`).1578- `skills/stardust/reference/artifact-map.md` — provenance shape.1579- `reference/direction-format.md` — schema for `stardust/direction.md`.1580- `reference/palette-picker.md` — palette resolution procedure.15811582## Default-mode-flip note (2026-04-29)15831584This skill changed its default behavior in 2026-04-29 to make Mode A1585(brand-faithful) the default whenever the captured brand surface is1586`signal-strong`, rather than activating only on explicit user1587signals. (The rationale: dogfood runs showed ambiguous refresh1588phrases rolling full divergence seeds and shipping rebrand-shaped1589output to brand owners who asked for a refresh.) Behavior summary:15901591- Before: ambiguous phrases like *"make it more modern"* rolled the1592 full divergence seed and produced rebrand-shaped output.1593- After: ambiguous phrases default to Mode A; rebrand requires1594 explicit phrase signal or `--rebrand` flag.15951596The flip was driven by dogfood evidence that the typical stardust1597use case (presales refresh of an existing site for a brand owner1598with design fatigue) was getting the wrong default.