Frontend Design Pipeline
This is the project front door. It routes UI work to the smallest relevant workflow, persists decisions as change-local artifacts, and prevents implementation claims that lack evidence. It does not replace specialist design skills; it coordinates them.
Start Here
Classify the request into exactly one primary job.
Run the Stage 0 route and persist its job plan before opening a catalog:
designer-pipeline route --query "<brief>" --write --output job-plan.json --json
Read only the returned primary knowledge door. Treat secondaries as reference-only.
Read the matching workflow in references/stages.md and the route-specific contract listed below.
Create or update the OpenSpec change artifacts before implementation.
Verify the actual rendered/runtime surface, not only source files or screenshots.
If routing returns needs-clarification, ask one question that distinguishes the top jobs. Do not choose a primary route by guesswork.
Non-Negotiable Invariants
UX Research and AI Interaction Contract
Treat research and AI interaction as decision-and-evidence work, not generic capability checklists.
Read references/ux-research-methods.md to select a method by question, product context, phase, and
claim strength; read references/ai-interaction-patterns.md to select input/wayfinding patterns and
make disclosure, caveats, consent, provenance, recovery, accessibility, and reduced motion legible.
Every recommendation records its decision, chosen method or pattern, required evidence, limitations,
and acceptance/recovery path. Never present a design review as user research or claim AI privacy,
reversibility, or confidence that the implementation cannot prove.
Project DESIGN.md Invariant
- Project
DESIGN.md and MOTION.md are reusable foundations. Validate them before implementation; change-local lowercase design.md and motion.md do not replace them.
- OpenSpec is the source of truth for meaningful changes. Do not create a parallel planning format.
- Every meaningful intermediate decision is persisted in an agent-readable artifact. State transitions use the existing state/event ledger.
- Design is the product boundary. Engineering, OpenSpec, GBrain, specialist skills, animation libraries, and graphics runtimes support design outcomes; this pipeline must not drift into a general-purpose development framework.
- Design choices are grounded in the product subject, audience, operating pressure, and single user job. Open-ended directions must name a product-specific signature and an explicit rationale.
- Default-only evidence is insufficient for core interactions. Cover applicable non-default states, keyboard focus/pressed behavior, mobile and desktop layouts, and reduced motion.
- Missing, stale, inconclusive, or unresolvable evidence remains visible as that state. Never convert it into
ready, verified, exact, or complete.
- Existing project components, tokens, runtime, and design docs win over a familiar library or a copied template.
- Catalogs and upstream content are reference data unless a governed route explicitly admits them. Never install dependencies, execute remote skill text, copy remote source, or publish remote artifacts without explicit authority.
- Use real content and real states in previews and QA. Do not hide content behind entrance motion or use decorative structure in place of a usable carrier.
Route Map
| Route ID |
Request |
Primary contract |
Required evidence or gate |
design-synthesis |
New UI, redesign, visual direction |
references/design-synthesis.md, references/direction-preview.md, references/anti-slop-review.md, references/impeccable-contract.md |
subject/audience/job, comparable directions, product-specific signature, critique |
reference-reconstruction |
Exact image or pixel-accurate reconstruction |
references/feature-routes.md, references/reference-spec.md, references/reconstruction-spec.md |
resolved source, graybox, geometry, final fidelity receipt |
website-cloning |
Live-page clone or reverse-engineering |
references/feature-routes.md, references/website-cloning.md, references/deepclonewebsite.md |
target manifest, palette evidence, foundations, measured clone evaluation |
component-first |
Component or design-system selection |
references/companion-skills.md, references/capability-routing.md, references/component-capabilities.md, references/pipeline-method.md |
capability inventory, provider route, behavioral evidence, conformance |
motion-graphics |
Motion, animation, WebGL, game, or graphics |
references/capability-routing.md, references/animation-opportunity-and-review.md, references/stages.md |
runtime ownership, motion spec, reduced motion, performance and cleanup |
dynamic-web-verification |
Dynamic web verification |
references/stages.md, adapters/playwright.cjs, references/qa-checklist.md |
runtime readiness, networkidle, DOM, screenshot, console, accessibility, network, performance |
product-foundation |
Requirements-driven product foundation |
references/design-synthesis.md |
reusable DESIGN.md, decision evidence, validation |
feedback-loop |
Pipeline bug, missing capability, or reusable gap |
references/feedback-loop.md, references/lifecycle.md |
redacted local feedback, regression test, explicit publication authority |
When several routes appear, route once, preserve one primary job, and use the others only as bounded supporting evidence. Read the narrowest returned skill or reference instead of loading every catalog.
Stage Map
Detailed stage instructions live in references/stages.md.
- validate it with
scripts/check-motion-foundation.cjs;
- if it is missing, synthesize it from product requirements and
references/motion-foundation.md;
- if it is incomplete or contains executable procedural definitions, repair or resynthesize it;
- select stable IDs from
references/motion-primitives.json;
- never substitute change-level lowercase
motion.md, a runtime-specific animation snippet, or a
copied showcase implementation.
Project MOTION.md defines reusable motion language. Change-level motion.md references its hash
and specializes selected primitives into scenes, layers, tracks, timelines, runtime bindings, and
evidence. Stage 5 implementation requires both foundation checkers to report ready.
Design-System Knowledge and Adoption
Treat component systems as candidate knowledge providers, not automatic project dependencies.
The bundled Astryx snapshot is an attributed, inert reference surface that agents may search before
inventing components. It does not override project DESIGN.md, MOTION.md, existing components,
tokens, or runtime choices.
Use the public CLI for the complete lifecycle:
design-system options lists the governed styling choices, UI libraries, current shadcn preset
dimensions, external tool sources, and indexed skill count.design-system resolve-stack resolves framework, styling, UI library, complete shadcn preset,
and tool/skill routes into a hash-bound frontend-stack-decision.json.design-system profiles lists governed providers and compatibility constraints.design-system decompose converts a product brief into a durable capability inventory; a direct
zero-result does not prove exhaustion when capability searches find candidates.design-system route selects project, platform, package, or attributed reference routes for the
decomposed component capabilities.design-system search searches the bundled Astryx catalog by text, kind, category, or status.design-system normalize converts a supplied snapshot into the strict namespaced catalog.design-system acquire runs an explicit contained local provider or the bundled Astryx adapter
against an existing contained Astryx CLI. It never installs or downloads that CLI.design-system project-tokens emits DTCG-compatible tokens plus an explicit loss report.design-system decide records reference, adopt, substitute, or custom; runtime use
requires compatible React/React DOM/StyleX constraints and admitted adapter intake.
DesignMD Directory is an ingestible local knowledge source for five resource kinds: skills,
templates, design examples, guides, and tools. The GitHub example set from dimabraven/design-md
is bundled offline. Directory sync remains a live snapshot:
designer-pipeline designmd search --query "keyboard-first dark productivity" --json and
designer-pipeline designmd inspect --id design-md:example:linear --json read the bundled
examples. designer-pipeline designmd verify --json checks that snapshot.designer-pipeline designmd sync --output-root .design-pipeline/designmd --json crawls the
DesignMD hubs and writes designmd-catalog.json plus local content snapshots.designer-pipeline designmd search --catalog .design-pipeline/designmd/designmd-catalog.json --kind skill --query "accessibility" --json searches the live directory snapshot.designer-pipeline designmd inspect --catalog .design-pipeline/designmd/designmd-catalog.json --id designmd:skill:a11y-audit --json reads one directory entry and its provenance.designer-pipeline designmd verify --catalog .design-pipeline/designmd/designmd-catalog.json --json checks the directory snapshot hashes.
Fetched and bundled DesignMD content is reference-only. Never execute remote page content, wrap
designmd-cli install, or copy a Stripe/Linear/Vercel example in as the product DESIGN.md.
Resolve reusable component behavior before selecting a library:
component decompose converts a multilingual brief into framework-neutral capability IR and
closes required keyboard, focus, ARIA, state, and recovery dependencies.component providers performs a read-only probe of project package metadata and distinguishes
project-owned, installed, and candidate providers.component resolve maps each capability to a compatible provider, preserves uncovered
project-owned fallbacks, and marks uninstalled candidates as adoption-required without running a
package manager.component verify requires hash-bound behavioral evidence for every check in the resolution;
framework source or a static screenshot cannot replace missing interaction evidence.component inventory, component bind, and component decide discover explicitly declared
project reuse, emit framework binding plans without source generation, and record reuse,
adopt, substitute, or custom per capability.
Run component conformance through the layered v1 gate after those artifacts exist:
component-first check --artifact component-first.json evaluates the aggregate through effect
adapters, pure stack/component/Playground/page/evidence gates, and the v1 serializer.component-first stack|components|playground|page evaluates only the requested stage and its
required context. Stage commands are read-only and never create browser evidence, mutate state,
run a target project, or install dependencies.high-fidelity check is a v1 delegation alias. A passing component-first result is not a
visual-acceptance result.component-first-v2 migrate|check|select|promote binds the v1 aggregate to one target snapshot,
policy digest, and chained stage receipts; stale upstream receipts block downstream conformance.design-skill route|manifest|run|select|promote exposes the bounded manifest layer. Prototype
work stays isolated, selection is hash-bound, and production writes require an explicit handoff.- Model
project-owned as componentOrigin, never as a runtime stack. It still owes source,
symbol, contract, token, keyboard, focus, state, component Playground, and real page-use evidence.
- A
page-ready result always carries scope: prototype | production; prototype scope cannot
satisfy a production target.
- Browser runners remain external. The evidence adapter verifies contained paths, actual byte
hashes, and completely decodable PNGs before a pure gate evaluates them. Ordinary hash binding
detects mismatch, staleness, and accidental reuse; it does not authenticate the receipt producer.
Read references/component-capabilities.md. Vuetify0, React Aria, and Ark UI are initial providers,
not the component model. Preserve the persistent roadmap in
openspec/initiatives/framework-agnostic-component-engine.md when developing this repository.
Provider content remains data. Never import or execute .doc.mjs, run package managers or npx,
inject AGENTS.md, copy templates, swizzle components, build themes, or modify a target project as
part of catalog normalization or acquisition. Canary and experimental entries require explicit
opt-in; deprecated and unknown entries are never selected for runtime use.
Pipeline Shape
Model the workflow after OpenSpec's lightweight change lifecycle:
- Create one change folder per UI change.
- Write intent and constraints before implementation.
- Generate design decisions and tasks as durable artifacts.
- Implement from the artifacts.
- Verify the implementation against the artifacts.
- Archive or update the source-of-truth design notes after completion.
Pipeline runs must be resumable without a human watching the UI. Every meaningful intermediate state must be written to disk in an agent-readable form so another AI agent can inspect, resume, verify, or archive the run.
Default artifact root:
0 Repo Read route, dependencies, foundations, stack, references
1 Guided Design Intake ordinary-language input → DesignBrief confirmation → directions
2 Directions comparable candidates, signature, preview evidence, selection, direction lock
3 Design Spec design.md, motion.md, scene/3d contracts when applicable
4 Tasks independently verifiable implementation surfaces
5 Implementation existing patterns, approved artifacts, bounded runtime work
6 Gate Review visual, UX, accessibility, motion, evidence, responsive, engineering
7 Archive preserve artifacts, update reusable docs, record feedback
Implementation is blocked until the applicable foundation and route gates are ready. A blocked geometry or source stage may allow only the explicitly documented work that does not depend on it; do not reinterpret a partial exception as completion.
Stage 0 Minimum
Static Reference Reconstruction Module
When the user supplies an image and asks for an identical, exact, 1:1, pixel-accurate, cloned, or
faithfully reproduced result:
A missing source downgrades the verification claim, never the requested fidelity. Requested fidelity
changes only through explicit user approval recorded in the non-destructive downgrade field. An
unavailable file, a schedule, and implementation convenience are not approval.
- Resolve the reference source to a file path before writing any artifact. When the reference is
not a resolvable path, ask the user for one and state what the path unlocks: rectification,
camera calibration, landmark error, and the fidelity receipt.
- When the user cannot or will not supply a path, record
source.availability: pending with
pendingReason and requestedFrom in reference-evidence.json, then continue. Do not block the
remaining work, and never write a fabricated path, dimension, or hash. When the raster later
lands, run designer-pipeline reference resolve --path "<file>" --json instead of hand-editing
measurements.
- Read
references/reference-spec.md and references/reconstruction-spec.md completely.
- Record the image as
role: primary-target, with both requested and effective fidelity set to
exact-reconstruction in reference-evidence.json v2. A reference is inspiration only when the
user says it is inspiration.
- Do not generate alternative design directions. The reference already determines the direction.
- Record the per-region structure table in
reference.md and the matching composition block in
reference-evidence.json before any layout is authored.
- Separate image, canonical/object, world, and camera spaces. Rectify the source into a canonical
front view, author the front elevation there, then solve and lock the output camera. A pending
source blocks rectification and the camera solve; the rest of the module still runs.
- Run
designer-pipeline reference check. blocked with reason source-pending is a recorded
state with contractValid: true, not a contract failure. Exact and adaptive reconstruction
remain blocked until the geometry stage of reconstruction.json passes. Read the exit code as
returned: 0 success, 1 invalid or error, 2 blocked, 3 a measured fidelity mismatch. 3
is a real outcome that reaches the caller and prints fidelity-limited; it is not success.
- Render the layout-only graybox and run
designer-pipeline reconstruction check --stage graybox. This gate precedes change design.md
and precedes materials, glow, bloom, depth of field, scanlines, and cinematic grading. It is the
only gate on that optical treatment.
- Write change
design.md against the graybox capture and cite that capture in it.
- Before detail geometry, type treatment, or any measured fidelity claim, run
designer-pipeline reconstruction check --stage geometry. It independently recomputes
distributed landmark error. Against a pending source it reports blocked with reason
source-pending, never fidelity-limited. This stage does not gate optical treatment; when it
is blocked and the graybox stage is ready, continue.
- After final rendering, an independent EvidencePort must produce reference, implementation, and
diff images plus a hash-bound fidelity receipt. Run
designer-pipeline reconstruction check --stage final.
- Missing evidence is
blocked; complete measured evidence outside thresholds is
fidelity-limited. Neither state may be described as exact, identical, pixel-perfect, or done.
- Record the verification claim in
qa.md from the whole --stage final result - its top-level
status and its stages map together: verified only when the top-level status is ready and
every reported stage is ready, fidelity-limited when the top-level status is
fidelity-limited and no stage is blocked, and unverified for everything else, including a
single blocked stage and a pending or unresolvable source. Requested fidelity does not move with
it. Only that complete output is evidence for the claim. reconstruction check defaults to
--stage geometry, and no stage-scoped result - the default run, an explicit --stage geometry
or --stage graybox run, or a bare stages.graybox reading lifted out of any result - may be
cited as evidence for verified.
- Report the unlock action whenever the source is still pending: supplying the source file path
and running
designer-pipeline reference resolve --path "<file>" --json stamps resolvedAt
and unlocks rectification, camera calibration, landmark error, and the fidelity receipt.
Website Cloning Module
When the user asks to clone, reproduce, rebuild, reverse-engineer, or use one or more live pages as implementation references:
- Read
references/website-cloning.md and references/website-clone-component-spec.md completely.
For authenticated, multi-page, whole-site, template-discovery, or reverse-analysis work, also
read references/deepclonewebsite.md and use its direct/structure/full capture boundary.
- Initialize the run with
scripts/init-website-clone.cjs; pass direct clone targets with --url and supporting inspiration/comparison pages with --reference-url. When one target is the user-designated structure or motion template, pass it as the primary --url/--authority-url, enumerate every allowed difference, protect the required invariants, and select actual-browser when live-tab interaction is part of acceptance.
- Treat
references/website-cloning-manifest.schema.json as the machine-readable Browser/Builder/Evidence port and fidelity contract.
- Complete
targets/<target-id>/research/palette-evidence.json from both DOM/computed-style
evidence and screenshot/raster-media evidence, then reflect the same roles and values in
design-tokens.md.
- Run
scripts/check-website-clone-foundations.cjs --change-root <change-root> --json before
synthesizing the implementation design or starting BuilderPort work. Project DESIGN.md,
project MOTION.md, and every target palette must be ready; adaptive mode does not bypass
this gate.
- Keep the URL-first user experience, but record each adapter, its available capabilities, and a successful capability probe before claiming exact fidelity.
- After EvidencePort writes its measured report, run
scripts/evaluate-website-clone.cjs; this is the only path that may move the manifest to complete. The evaluator must also verify implementation-authority identity, protected invariants, allowed differences, replay provenance, and the declared interaction environment; adaptive fidelity does not bypass these checks.
- If a required port or measurement is missing, keep
blocked; if complete measurements miss a threshold, use fidelity-limited. Never fill missing measurements by visual guesswork.
The website-cloning module is a design-pipeline superset capability. It adds live evidence capture and convergence gates while preserving all existing accessibility, motion, responsive, engineering, and headless-state requirements.
Requirements-Driven DESIGN.md Synthesis
When the target project has no reusable DESIGN.md, or the existing file cannot express the
requested product direction:
- Read
references/design-synthesis.md completely.
- Initialize with
scripts/init-design-synthesis.cjs, using --problem as the primary input.
- Register live pages with
--reference-url and existing DESIGN.md examples with --template.
Both are attributed evidence; templates are always inspiration-only.
- Run
/grill-with-docs <problem> when material product decisions remain unresolved, persist its
ADR/glossary/decision evidence, then record grill-completed.
- Run the deterministic scope assessment. Only when the score exceeds the selected budget, say
“哦，天哪，这比我预期的要大得多。” and request
/wayfinder 为此制作一张地图.
- Wayfinder must use a configured issue-tracker host. Never invent a local issue map when that host
is unavailable.
- Synthesize 2-3 product-specific directions from requirements, repository constraints, and cited
evidence. Select one and write the reusable project
DESIGN.md.
- Validate it through
scripts/advance-design-synthesis.cjs, then immediately continue into the
normal implementation and QA stages unless another material decision is pending.
Keep the artifacts distinct:
- lowercase change
design.md defines how the active change will be implemented;
- project
DESIGN.md defines reusable product identity for future coding agents.
The bundled scripts manage deterministic state and validation. The host design agent performs the
creative synthesis; do not disguise a copied template or token dump as generated product design.
Companion Skills
Reference file: references/companion-skills.md.
Capability routing reference: references/capability-routing.md.
Machine-readable companion registry: references/companion-capabilities.json.
Requirements-driven synthesis reference: references/design-synthesis.md.
Feedback and contribution reference: references/feedback-loop.md.
Upstream capability sync reference: references/upstream-capability-sync.md.
Development compatibility reference: references/development-compatibility.md.
Self-check reference: references/self-check.md.
QA checklist reference: references/qa-checklist.md.
Direct plain-language contract: references/plain-language.md.
CJK typography contract: references/cjk-typography.md.
Visual direction preview contract: references/direction-preview.md.
Governed Playground contract: references/playground.md.
Evidence-gated layered adaptation contract: references/adaptation.md.
Machine-readable adaptation contract: references/adaptation-contract.schema.json.
Framework-agnostic component contract: references/component-capabilities.md.
Project motion foundation reference: references/motion-foundation.md.
Machine-readable motion foundation schema: references/motion-foundation.schema.json.
Motion primitive registry: references/motion-primitives.json.
Motion spec reference: references/motion-spec.md.
Animation opportunity and review reference: references/animation-opportunity-and-review.md.
Reference evidence and spatial-routing spec: references/reference-spec.md.
Change visual/screen-space design spec: references/design-spec.md.
Change 3D world spec: references/3d-spec.md.
Graphics runtime routing reference: references/graphics-runtime-routing.md.
Machine-readable graphics runtime catalog: references/graphics-runtime-catalog.json.
XY Python charting reference: references/xy-charting.md.
Change scene/runtime spec reference: references/scene-runtime-spec.md.
Phaser v4 game runtime reference: references/phaser-v4.md.
Game UI and narrative profile reference: references/game-ui-and-narrative.md.
Curation policy reference: references/curation-policy.md.
Contextual anti-slop review reference: references/anti-slop-review.md.
Machine-readable anti-slop rubric: references/anti-slop-rubric.json.
Impeccable design contract: references/impeccable-contract.md.
Impeccable product-design capability map: references/impeccable-product-design.json and
references/impeccable-product-design.md.
If these design skills are installed, use them as lenses in this order:
impeccable: command vocabulary, surface modes, refinement semantics, bounded verification, and design-detector workflow.frontend-design: visual direction, composition, strong first impression, avoiding generic AI aesthetics.design-taste-frontend: anti-template discipline, typography taste, language and visual restraint.ui-ux-pro-max: UX heuristics, design-system selection, color and type pairing, stable repeatability.web-design-guidelines: production UI rules, layout, semantics, accessibility, responsive behavior.emil-design-eng: motion, transitions, input feedback, perceived quality, interaction details.
For dynamic UI, interaction motion, and animation-specific work, apply these motion skills:
design-motion-principles: primary create/audit workflow for purposeful UI motion.emil-design-eng: design-engineering judgment for animation and interaction polish.animation-vocabulary: translate vague motion intent into precise timing, easing, choreography, and behavior language.review-animations: strict post-implementation animation review.references/animation-opportunity-and-review.md: project-owned gate for screening opportunities before implementation, naming vocabulary/curves, and recording review evidence.apple-design: Apple HIG-inspired interface principles and fluid system UI motion for web (WWDC-informed).vercel-react-view-transitions: React and Next.js view-transition implementation patterns.
Choose companions by capability, not by the presence of a familiar skill name. Classify the brief
with designer-pipeline route first. Read references/capability-routing.md and
references/job-registry.json when the change crosses evidence capture, design systems, assets,
motion runtimes, editable design handoff, or hosted delivery. For 2D, 3D, data visualization,
geospatial, GPU, game, or narrative surfaces, also read references/graphics-runtime-routing.md
and select a capability family before selecting an adapter.
For product UI, flows, design-system work, user-visible UI changes, or interface reviews, always
apply the bundled interface discipline in references/interface-discipline.md. It is present in
the package and does not require a global skill installation. Start with its better-interface
router, use full coverage unless a narrow repair qualifies for quick coverage, and use its
change-scoped review protocol for changed UI.
Catalog CLIs are escape hatches. Open them only when designer-pipeline route selects that catalog
as the primary knowledge door, or when a listed secondary is needed as reference. Do not search
MengTo, Prism, Astryx, shadcnio, DesignMD, iart, and holosticker as peer Stage 0 searches.
For visual direction, web technique, motion, WebGL, reference analysis, asset, or game work, when
the job dispatcher selects MengTo as primary, search the bundled library before inventing a
workflow:
designer-pipeline mengto search --query "<capability or brief>" --json
Read the narrowest returned SKILL.md and only the linked supporting files needed for the task.
Apply its workflow, numeric guidance, pitfalls, and verification gates through the target project's
DESIGN.md, MOTION.md, OpenSpec artifacts, existing stack, accessibility rules, and budgets.
Never treat a bundled demo, runtime asset, dependency choice, account workflow, or publishing recipe
as automatic project authority. The activation and adaptation rules live in
references/mengto-skills.md; explicit-only entries still require the user's matching request and
normal side-effect authority.
For web motion, WebGL motion, kinetic type, or motion-graphics/video craft, when the job
dispatcher selects iart as primary, route before implementing. A domain brief is enough; do not
wait for a skill id:
designer-pipeline iart route --query "<motion or video brief>" --json
designer-pipeline iart search --query "<narrow playbook>" --json
Read references/iart-motion-skills.md. Record the selected playbook, alternatives, and runtime,
then load only that SKILL.md. Keep project MOTION.md authoritative. HTML video, reels,
captions, overlays, and explainers use HyperFrames unless the brief names Remotion, Manim, or
After Effects. A route result is a selection, not install or execution authority.
For product-design intake, Design DNA, token governance, design-corpus learning, or handoff work,
when the job dispatcher selects Prism as primary, route through the bundled Prism System layer
before loading a broad recipe set:
designer-pipeline prism route --query "<design request>" --json
designer-pipeline prism search --query "<narrow capability>" --json
Read references/prism-system.md, load only the returned local skill sequence, and execute it
inside the native brief, directions, implementation, and QA stages. Reuse the pipeline's existing
design tokens, catalogs, adapters, evidence, DESIGN.md, and MOTION.md; never create a parallel
Prism runtime or treat upstream autonomy metadata as side-effect authority.
For an explicit holographic sticker, holofoil, die-cut, pointer-tilt, peel, or matching export
request, when the job dispatcher selects holosticker as primary, inspect the bundled
implementation before creating another shader or geometry path:
designer-pipeline holosticker inspect --capability "<capability>" --json
Read references/holosticker.md, adapt only the returned source files, and route them through the
project-pinned threejs adapter with scene.json, 3d.md, motion.md, and browser evidence. Do not
add the full Studio UI or optional dependencies for an unselected capability.
When web-design/build-threejs-scroll-worlds is selected, or Kage is supplied as a reference, also
read references/kage-scroll-world.md. It adds the current Kage repository's license boundary and
post-snapshot responsive lessons without importing its unlicensed code or artwork.
For animation implementation, choose library skills by job:
- Use
gsap-core, gsap-timeline, gsap-scrolltrigger, gsap-react, gsap-plugins, gsap-utils, gsap-performance, and gsap-frameworks for advanced choreography, scroll-driven animation, timeline control, React integration, SVG/plugin-heavy work, or when GSAP is already in the project.
- Use
animejs v4.5 for modular timelines, layout transitions, accessible text splitting, SVG, draggable interactions, scroll observers, WAAPI, deterministic stagger, or adapter-driven targets such as Three.js.
- Use the built-in
reflex-xy route for Python-native charts, notebooks, static chart export, Reflex applications, or large datasets that need screen-bounded rendering. Read references/xy-charting.md; pin the alpha version in the target project and keep a semantic data-table path.
- Use the official
pixijs router and the matching PixiJS v8 sub-skills only for justified interactive 2D render surfaces such as sprite fields, particles, filters, shaders, canvas editors, or high-object-count scenes. Read references/pixijs-rendering.md before selecting it.
- Use the built-in Phaser v4 route for a complete 2D game runtime with scenes, game-loop ownership, input, audio, physics, cameras, scaling, and game-state transitions. Read
references/phaser-v4.md; do not depend on an unverified community skill pack.
- Use Three.js or React Three Fiber for focused 3D scene rendering; use Babylon.js or PlayCanvas when a fuller 3D engine is justified. Existing project runtimes still win when they meet the capability and budget.
- For explicit holographic sticker work, use
references/holosticker.md as the pinned Three.js implementation route and select only the required material, die-cut, tilt, peel, or export slice.
- Use
references/game-ui-and-narrative.md for HUDs, game menus, dialogue systems, visual novels, and Galgame surfaces. Keep dialogue, choice, backlog, save/load, skip, autoplay, and accessibility state independent of animation timing.
- If no animation or rendering library is already present, prefer semantic DOM plus CSS transitions/keyframes for simple state changes; choose Anime.js, GSAP, PixiJS, Phaser, or a 3D runtime only when the required capability justifies it.
- Do not add overlapping runtimes unless
design.md, motion.md, and when required scene.md or
3d.md assign distinct responsibilities. One adapter owns each render loop, clock, property,
lifecycle, and cleanup path.
- Treat an installed but stale
animejs companion as a warning. Use official v4.5 documentation for missing markers and record the fallback in qa.md.
- Treat a partial or stale PixiJS suite as a warning. Use the canonical PixiJS v8 documentation index for missing APIs and record the fallback in
qa.md.
For React and Next.js work, also apply the installed Vercel / Next.js engineering skills listed in references/companion-skills.md:
vercel-react-best-practicesvercel-composition-patternsvercel-react-view-transitionsnext-cache-components-adoptionnext-cache-components-optimizernext-dev-loop
If a companion skill is missing, continue with the same gate manually and note the missing skill in qa.md. Do not block the user unless the requested output depends on a missing asset, credential, or external service.
Stage 0: Repo Read
Before writing design artifacts or code:
- Persist the route job plan and bind
jobPlanSha256/jobPlanPath to later toolchain and execution requests.
- Run
node <design-pipeline>/scripts/check-deps.cjs from the target project root.
- Identify framework, styling system, component library, routing, design tokens, test surface, and existing UI patterns.
- Resolve visual sources to file paths before writing source-bound evidence. If unavailable, record
source.availability: pending, its reason, and the unlock action; never invent paths, dimensions, or hashes.
- Check project
DESIGN.md and MOTION.md; route missing or incompatible foundations through synthesis.
- Resolve the frontend/tool/graphics plan with the governed CLI before invoking an external runtime. Probe first; do not install from a route result.
- Use the design-system CLI to decompose capabilities and record adoption as
reference, adopt, substitute, or custom.
- Run
designer-pipeline component lock from the approved direction selection, then run designer-pipeline component fit for each capability set. The resulting matrix must preserve direction-lock, catalog, project-inventory, and evidence hashes.
- Initialize or update
state.json, events.jsonl, and handoff.md through the existing state tools.
Use references/stages.md for the full Stage 0 checklist and the required toolchain/execution commands.
Direction and Copy Rules
- Treat the hero or first viewport as the product thesis, not a generic template slot.
- Choose palette, typography, layout, and motion from the subject and audience. A named style alone is not a rationale.
- Spend boldness in one justified signature element; remove decoration that does not improve understanding or action.
- Use structural markers, labels, and numbering only when they encode true information.
- Write from the user's side of the screen. Controls name real actions, errors name the fix, empty states direct the next action, and the same action keeps the same name through the flow.
- Read
references/plain-language.md for user-facing copy and references/cjk-typography.md for CJK or mixed-script surfaces.
Browser and Evidence Rules
The browser runner is an evidence port, not a source of authority. For dynamic web apps:
- Start or verify the target runtime and wait for readiness.
- Wait for
networkidle before inspecting dynamic DOM.
- Discover selectors from the rendered surface.
- Exercise the required interaction and state transitions.
- Capture the applicable DOM, screenshot, console, accessibility, network, and performance artifacts.
- Bind artifacts to hashes and record missing or degraded capabilities explicitly.
adapters/playwright.cjs is the project-owned implementation. A static screenshot cannot replace behavioral evidence.
Public CLI Surfaces
Use the public CLI rather than reaching into implementation modules:
designer-pipeline route --query "<brief>" --write --output job-plan.json --json
designer-pipeline toolchain resolve --artifact toolchain-request.json --write --output toolchain-plan.json --json
designer-pipeline design-system decompose --query "<brief>" --write --output capability-inventory.json --json
designer-pipeline direction check --stage preview --change-root <change-root> --json
designer-pipeline component lock --artifact direction-lock-request.json --write --output direction-lock.json --json
designer-pipeline component fit --artifact component-fit-request.json --write --output component-fit-matrix.json --json
designer-pipeline component validate-fit --artifact component-fit-matrix.json --json
designer-pipeline reference check --change-root <change-root> --json
designer-pipeline reconstruction check --stage final --change-root <change-root> --json
designer-pipeline playground check --stage integration --change-root <change-root> --json
designer-pipeline scene check --change-root <change-root> --json
For the first-wave guided multi-surface flow, use these commands:
designer-pipeline surface validate --artifact surface.json --json
designer-pipeline intake start --artifact input.json --json
designer-pipeline intake answer --artifact brief.json --answer answer.json --json
designer-pipeline intake confirm --artifact brief.json --json
designer-pipeline template inventory --catalog catalog.json --json
designer-pipeline template search --catalog catalog.json --surface surface.json --request request.json --json
designer-pipeline template select --selection selection.json --json
designer-pipeline template adapt --receipt receipt.json --context context.json --json
designer-pipeline template review --plan plan.json --rev
…(truncated)
1---2name: design-pipeline3description: OpenSpec-style design development pipeline for visual direction, UX research, website cloning and reverse-engineering, interaction polish, frontend implementation, and evidence-backed QA. Use for product UI, marketing pages, dashboards, live-page references, pixel-accurate rebuilds, design reviews, and frontend work that must avoid generic AI-looking output.4---56# Frontend Design Pipeline78This is the project front door. It routes UI work to the smallest relevant workflow, persists decisions as change-local artifacts, and prevents implementation claims that lack evidence. It does not replace specialist design skills; it coordinates them.910## Start Here11121. Classify the request into exactly one primary job.132. Run the Stage 0 route and persist its job plan before opening a catalog:1415 ```bash16 designer-pipeline route --query "<brief>" --write --output job-plan.json --json17 ```18193. Read only the returned primary knowledge door. Treat secondaries as reference-only.204. Read the matching workflow in `references/stages.md` and the route-specific contract listed below.215. Create or update the OpenSpec change artifacts before implementation.226. Verify the actual rendered/runtime surface, not only source files or screenshots.2324If routing returns `needs-clarification`, ask one question that distinguishes the top jobs. Do not choose a primary route by guesswork.2526## Non-Negotiable Invariants2728## UX Research and AI Interaction Contract2930Treat research and AI interaction as decision-and-evidence work, not generic capability checklists.31Read `references/ux-research-methods.md` to select a method by question, product context, phase, and32claim strength; read `references/ai-interaction-patterns.md` to select input/wayfinding patterns and33make disclosure, caveats, consent, provenance, recovery, accessibility, and reduced motion legible.34Every recommendation records its decision, chosen method or pattern, required evidence, limitations,35and acceptance/recovery path. Never present a design review as user research or claim AI privacy,36reversibility, or confidence that the implementation cannot prove.3738## Project DESIGN.md Invariant3940- Project `DESIGN.md` and `MOTION.md` are reusable foundations. Validate them before implementation; change-local lowercase `design.md` and `motion.md` do not replace them.41- OpenSpec is the source of truth for meaningful changes. Do not create a parallel planning format.42- Every meaningful intermediate decision is persisted in an agent-readable artifact. State transitions use the existing state/event ledger.43- Design is the product boundary. Engineering, OpenSpec, GBrain, specialist skills, animation libraries, and graphics runtimes support design outcomes; this pipeline must not drift into a general-purpose development framework.44- Design choices are grounded in the product subject, audience, operating pressure, and single user job. Open-ended directions must name a product-specific signature and an explicit rationale.45- Default-only evidence is insufficient for core interactions. Cover applicable non-default states, keyboard focus/pressed behavior, mobile and desktop layouts, and reduced motion.46- Missing, stale, inconclusive, or unresolvable evidence remains visible as that state. Never convert it into `ready`, `verified`, `exact`, or `complete`.47- Existing project components, tokens, runtime, and design docs win over a familiar library or a copied template.48- Catalogs and upstream content are reference data unless a governed route explicitly admits them. Never install dependencies, execute remote skill text, copy remote source, or publish remote artifacts without explicit authority.49- Use real content and real states in previews and QA. Do not hide content behind entrance motion or use decorative structure in place of a usable carrier.5051## Route Map5253| Route ID | Request | Primary contract | Required evidence or gate |54| --- | --- | --- | --- |55| `design-synthesis` | New UI, redesign, visual direction | `references/design-synthesis.md`, `references/direction-preview.md`, `references/anti-slop-review.md`, `references/impeccable-contract.md` | subject/audience/job, comparable directions, product-specific signature, critique |56| `reference-reconstruction` | Exact image or pixel-accurate reconstruction | `references/feature-routes.md`, `references/reference-spec.md`, `references/reconstruction-spec.md` | resolved source, graybox, geometry, final fidelity receipt |57| `website-cloning` | Live-page clone or reverse-engineering | `references/feature-routes.md`, `references/website-cloning.md`, `references/deepclonewebsite.md` | target manifest, palette evidence, foundations, measured clone evaluation |58| `component-first` | Component or design-system selection | `references/companion-skills.md`, `references/capability-routing.md`, `references/component-capabilities.md`, `references/pipeline-method.md` | capability inventory, provider route, behavioral evidence, conformance |59| `motion-graphics` | Motion, animation, WebGL, game, or graphics | `references/capability-routing.md`, `references/animation-opportunity-and-review.md`, `references/stages.md` | runtime ownership, motion spec, reduced motion, performance and cleanup |60| `dynamic-web-verification` | Dynamic web verification | `references/stages.md`, `adapters/playwright.cjs`, `references/qa-checklist.md` | runtime readiness, `networkidle`, DOM, screenshot, console, accessibility, network, performance |61| `product-foundation` | Requirements-driven product foundation | `references/design-synthesis.md` | reusable `DESIGN.md`, decision evidence, validation |62| `feedback-loop` | Pipeline bug, missing capability, or reusable gap | `references/feedback-loop.md`, `references/lifecycle.md` | redacted local feedback, regression test, explicit publication authority |6364When several routes appear, route once, preserve one primary job, and use the others only as bounded supporting evidence. Read the narrowest returned skill or reference instead of loading every catalog.6566## Stage Map6768Detailed stage instructions live in `references/stages.md`.6970- validate it with `scripts/check-motion-foundation.cjs`;71- if it is missing, synthesize it from product requirements and72 `references/motion-foundation.md`;73- if it is incomplete or contains executable procedural definitions, repair or resynthesize it;74- select stable IDs from `references/motion-primitives.json`;75- never substitute change-level lowercase `motion.md`, a runtime-specific animation snippet, or a76 copied showcase implementation.7778Project `MOTION.md` defines reusable motion language. Change-level `motion.md` references its hash79and specializes selected primitives into scenes, layers, tracks, timelines, runtime bindings, and80evidence. Stage 5 implementation requires both foundation checkers to report `ready`.8182## Design-System Knowledge and Adoption8384Treat component systems as candidate knowledge providers, not automatic project dependencies.85The bundled Astryx snapshot is an attributed, inert reference surface that agents may search before86inventing components. It does not override project `DESIGN.md`, `MOTION.md`, existing components,87tokens, or runtime choices.8889Use the public CLI for the complete lifecycle:9091- `design-system options` lists the governed styling choices, UI libraries, current shadcn preset92 dimensions, external tool sources, and indexed skill count.93- `design-system resolve-stack` resolves framework, styling, UI library, complete shadcn preset,94 and tool/skill routes into a hash-bound `frontend-stack-decision.json`.95- `design-system profiles` lists governed providers and compatibility constraints.96- `design-system decompose` converts a product brief into a durable capability inventory; a direct97 zero-result does not prove exhaustion when capability searches find candidates.98- `design-system route` selects project, platform, package, or attributed reference routes for the99 decomposed component capabilities.100- `design-system search` searches the bundled Astryx catalog by text, kind, category, or status.101- `design-system normalize` converts a supplied snapshot into the strict namespaced catalog.102- `design-system acquire` runs an explicit contained local provider or the bundled Astryx adapter103 against an existing contained Astryx CLI. It never installs or downloads that CLI.104- `design-system project-tokens` emits DTCG-compatible tokens plus an explicit loss report.105- `design-system decide` records `reference`, `adopt`, `substitute`, or `custom`; runtime use106 requires compatible React/React DOM/StyleX constraints and admitted adapter intake.107108DesignMD Directory is an ingestible local knowledge source for five resource kinds: skills,109templates, design examples, guides, and tools. The GitHub example set from `dimabraven/design-md`110is bundled offline. Directory sync remains a live snapshot:111112- `designer-pipeline designmd search --query "keyboard-first dark productivity" --json` and113 `designer-pipeline designmd inspect --id design-md:example:linear --json` read the bundled114 examples. `designer-pipeline designmd verify --json` checks that snapshot.115- `designer-pipeline designmd sync --output-root .design-pipeline/designmd --json` crawls the116 DesignMD hubs and writes `designmd-catalog.json` plus local content snapshots.117- `designer-pipeline designmd search --catalog .design-pipeline/designmd/designmd-catalog.json118 --kind skill --query "accessibility" --json` searches the live directory snapshot.119- `designer-pipeline designmd inspect --catalog .design-pipeline/designmd/designmd-catalog.json120 --id designmd:skill:a11y-audit --json` reads one directory entry and its provenance.121- `designer-pipeline designmd verify --catalog .design-pipeline/designmd/designmd-catalog.json122 --json` checks the directory snapshot hashes.123124Fetched and bundled DesignMD content is reference-only. Never execute remote page content, wrap125`designmd-cli install`, or copy a Stripe/Linear/Vercel example in as the product `DESIGN.md`.126127Resolve reusable component behavior before selecting a library:128129- `component decompose` converts a multilingual brief into framework-neutral capability IR and130 closes required keyboard, focus, ARIA, state, and recovery dependencies.131- `component providers` performs a read-only probe of project package metadata and distinguishes132 project-owned, installed, and candidate providers.133- `component resolve` maps each capability to a compatible provider, preserves uncovered134 project-owned fallbacks, and marks uninstalled candidates as adoption-required without running a135 package manager.136- `component verify` requires hash-bound behavioral evidence for every check in the resolution;137 framework source or a static screenshot cannot replace missing interaction evidence.138- `component inventory`, `component bind`, and `component decide` discover explicitly declared139 project reuse, emit framework binding plans without source generation, and record `reuse`,140 `adopt`, `substitute`, or `custom` per capability.141142Run component conformance through the layered v1 gate after those artifacts exist:143144- `component-first check --artifact component-first.json` evaluates the aggregate through effect145 adapters, pure stack/component/Playground/page/evidence gates, and the v1 serializer.146- `component-first stack|components|playground|page` evaluates only the requested stage and its147 required context. Stage commands are read-only and never create browser evidence, mutate state,148 run a target project, or install dependencies.149- `high-fidelity check` is a v1 delegation alias. A passing component-first result is not a150 visual-acceptance result.151- `component-first-v2 migrate|check|select|promote` binds the v1 aggregate to one target snapshot,152 policy digest, and chained stage receipts; stale upstream receipts block downstream conformance.153- `design-skill route|manifest|run|select|promote` exposes the bounded manifest layer. Prototype154 work stays isolated, selection is hash-bound, and production writes require an explicit handoff.155- Model `project-owned` as `componentOrigin`, never as a runtime stack. It still owes source,156 symbol, contract, token, keyboard, focus, state, component Playground, and real page-use evidence.157- A `page-ready` result always carries `scope: prototype | production`; prototype scope cannot158 satisfy a production target.159- Browser runners remain external. The evidence adapter verifies contained paths, actual byte160 hashes, and completely decodable PNGs before a pure gate evaluates them. Ordinary hash binding161 detects mismatch, staleness, and accidental reuse; it does not authenticate the receipt producer.162163Read `references/component-capabilities.md`. Vuetify0, React Aria, and Ark UI are initial providers,164not the component model. Preserve the persistent roadmap in165`openspec/initiatives/framework-agnostic-component-engine.md` when developing this repository.166167Provider content remains data. Never import or execute `.doc.mjs`, run package managers or `npx`,168inject `AGENTS.md`, copy templates, swizzle components, build themes, or modify a target project as169part of catalog normalization or acquisition. Canary and experimental entries require explicit170opt-in; deprecated and unknown entries are never selected for runtime use.171172## Pipeline Shape173174Model the workflow after OpenSpec's lightweight change lifecycle:1751761. Create one change folder per UI change.1772. Write intent and constraints before implementation.1783. Generate design decisions and tasks as durable artifacts.1794. Implement from the artifacts.1805. Verify the implementation against the artifacts.1816. Archive or update the source-of-truth design notes after completion.182183Pipeline runs must be resumable without a human watching the UI. Every meaningful intermediate state must be written to disk in an agent-readable form so another AI agent can inspect, resume, verify, or archive the run.184185Default artifact root:186187```text1880 Repo Read route, dependencies, foundations, stack, references1891 Guided Design Intake ordinary-language input → DesignBrief confirmation → directions1902 Directions comparable candidates, signature, preview evidence, selection, direction lock1913 Design Spec design.md, motion.md, scene/3d contracts when applicable1924 Tasks independently verifiable implementation surfaces1935 Implementation existing patterns, approved artifacts, bounded runtime work1946 Gate Review visual, UX, accessibility, motion, evidence, responsive, engineering1957 Archive preserve artifacts, update reusable docs, record feedback196```197198Implementation is blocked until the applicable foundation and route gates are ready. A blocked geometry or source stage may allow only the explicitly documented work that does not depend on it; do not reinterpret a partial exception as completion.199200## Stage 0 Minimum201## Static Reference Reconstruction Module202203When the user supplies an image and asks for an identical, exact, 1:1, pixel-accurate, cloned, or204faithfully reproduced result:205206A missing source downgrades the verification claim, never the requested fidelity. Requested fidelity207changes only through explicit user approval recorded in the non-destructive downgrade field. An208unavailable file, a schedule, and implementation convenience are not approval.2092101. Resolve the reference source to a file path before writing any artifact. When the reference is211 not a resolvable path, ask the user for one and state what the path unlocks: rectification,212 camera calibration, landmark error, and the fidelity receipt.2132. When the user cannot or will not supply a path, record `source.availability: pending` with214 `pendingReason` and `requestedFrom` in `reference-evidence.json`, then continue. Do not block the215 remaining work, and never write a fabricated path, dimension, or hash. When the raster later216 lands, run `designer-pipeline reference resolve --path "<file>" --json` instead of hand-editing217 measurements.2183. Read `references/reference-spec.md` and `references/reconstruction-spec.md` completely.2194. Record the image as `role: primary-target`, with both requested and effective fidelity set to220 `exact-reconstruction` in `reference-evidence.json` v2. A reference is inspiration only when the221 user says it is inspiration.2225. Do not generate alternative design directions. The reference already determines the direction.2236. Record the per-region structure table in `reference.md` and the matching `composition` block in224 `reference-evidence.json` before any layout is authored.2257. Separate image, canonical/object, world, and camera spaces. Rectify the source into a canonical226 front view, author the front elevation there, then solve and lock the output camera. A pending227 source blocks rectification and the camera solve; the rest of the module still runs.2288. Run `designer-pipeline reference check`. `blocked` with reason `source-pending` is a recorded229 state with `contractValid: true`, not a contract failure. Exact and adaptive reconstruction230 remain blocked until the geometry stage of `reconstruction.json` passes. Read the exit code as231 returned: `0` success, `1` invalid or error, `2` blocked, `3` a measured fidelity mismatch. `3`232 is a real outcome that reaches the caller and prints `fidelity-limited`; it is not success.2339. Render the layout-only graybox and run234 `designer-pipeline reconstruction check --stage graybox`. This gate precedes change `design.md`235 and precedes materials, glow, bloom, depth of field, scanlines, and cinematic grading. It is the236 only gate on that optical treatment.23710. Write change `design.md` against the graybox capture and cite that capture in it.23811. Before detail geometry, type treatment, or any measured fidelity claim, run239 `designer-pipeline reconstruction check --stage geometry`. It independently recomputes240 distributed landmark error. Against a pending source it reports `blocked` with reason241 `source-pending`, never `fidelity-limited`. This stage does not gate optical treatment; when it242 is blocked and the graybox stage is `ready`, continue.24312. After final rendering, an independent EvidencePort must produce reference, implementation, and244 diff images plus a hash-bound fidelity receipt. Run245 `designer-pipeline reconstruction check --stage final`.24613. Missing evidence is `blocked`; complete measured evidence outside thresholds is247 `fidelity-limited`. Neither state may be described as exact, identical, pixel-perfect, or done.24814. Record the verification claim in `qa.md` from the whole `--stage final` result - its top-level249 status and its `stages` map together: `verified` only when the top-level status is `ready` and250 every reported stage is `ready`, `fidelity-limited` when the top-level status is251 `fidelity-limited` and no stage is `blocked`, and `unverified` for everything else, including a252 single blocked stage and a pending or unresolvable source. Requested fidelity does not move with253 it. Only that complete output is evidence for the claim. `reconstruction check` defaults to254 `--stage geometry`, and no stage-scoped result - the default run, an explicit `--stage geometry`255 or `--stage graybox` run, or a bare `stages.graybox` reading lifted out of any result - may be256 cited as evidence for `verified`.25715. Report the unlock action whenever the source is still pending: supplying the source file path258 and running `designer-pipeline reference resolve --path "<file>" --json` stamps `resolvedAt`259 and unlocks rectification, camera calibration, landmark error, and the fidelity receipt.260261## Website Cloning Module262263When the user asks to clone, reproduce, rebuild, reverse-engineer, or use one or more live pages as implementation references:2642651. Read `references/website-cloning.md` and `references/website-clone-component-spec.md` completely.266 For authenticated, multi-page, whole-site, template-discovery, or reverse-analysis work, also267 read `references/deepclonewebsite.md` and use its direct/structure/full capture boundary.2682. Initialize the run with `scripts/init-website-clone.cjs`; pass direct clone targets with `--url` and supporting inspiration/comparison pages with `--reference-url`. When one target is the user-designated structure or motion template, pass it as the primary `--url`/`--authority-url`, enumerate every allowed difference, protect the required invariants, and select `actual-browser` when live-tab interaction is part of acceptance.2693. Treat `references/website-cloning-manifest.schema.json` as the machine-readable Browser/Builder/Evidence port and fidelity contract.2704. Complete `targets/<target-id>/research/palette-evidence.json` from both DOM/computed-style271 evidence and screenshot/raster-media evidence, then reflect the same roles and values in272 `design-tokens.md`.2735. Run `scripts/check-website-clone-foundations.cjs --change-root <change-root> --json` before274 synthesizing the implementation design or starting BuilderPort work. Project `DESIGN.md`,275 project `MOTION.md`, and every target palette must be `ready`; adaptive mode does not bypass276 this gate.2776. Keep the URL-first user experience, but record each adapter, its available capabilities, and a successful capability probe before claiming exact fidelity.2787. After EvidencePort writes its measured report, run `scripts/evaluate-website-clone.cjs`; this is the only path that may move the manifest to `complete`. The evaluator must also verify implementation-authority identity, protected invariants, allowed differences, replay provenance, and the declared interaction environment; adaptive fidelity does not bypass these checks.2798. If a required port or measurement is missing, keep `blocked`; if complete measurements miss a threshold, use `fidelity-limited`. Never fill missing measurements by visual guesswork.280281The website-cloning module is a design-pipeline superset capability. It adds live evidence capture and convergence gates while preserving all existing accessibility, motion, responsive, engineering, and headless-state requirements.282283## Requirements-Driven DESIGN.md Synthesis284285When the target project has no reusable `DESIGN.md`, or the existing file cannot express the286requested product direction:2872881. Read `references/design-synthesis.md` completely.2892. Initialize with `scripts/init-design-synthesis.cjs`, using `--problem` as the primary input.2903. Register live pages with `--reference-url` and existing DESIGN.md examples with `--template`.291 Both are attributed evidence; templates are always inspiration-only.2924. Run `/grill-with-docs <problem>` when material product decisions remain unresolved, persist its293 ADR/glossary/decision evidence, then record `grill-completed`.2945. Run the deterministic scope assessment. Only when the score exceeds the selected budget, say295 “哦，天哪，这比我预期的要大得多。” and request `/wayfinder 为此制作一张地图`.2966. Wayfinder must use a configured issue-tracker host. Never invent a local issue map when that host297 is unavailable.2987. Synthesize 2-3 product-specific directions from requirements, repository constraints, and cited299 evidence. Select one and write the reusable project `DESIGN.md`.3008. Validate it through `scripts/advance-design-synthesis.cjs`, then immediately continue into the301 normal implementation and QA stages unless another material decision is pending.302303Keep the artifacts distinct:304305- lowercase change `design.md` defines how the active change will be implemented;306- project `DESIGN.md` defines reusable product identity for future coding agents.307308The bundled scripts manage deterministic state and validation. The host design agent performs the309creative synthesis; do not disguise a copied template or token dump as generated product design.310311## Companion Skills312313Reference file: `references/companion-skills.md`.314Capability routing reference: `references/capability-routing.md`.315Machine-readable companion registry: `references/companion-capabilities.json`.316Requirements-driven synthesis reference: `references/design-synthesis.md`.317Feedback and contribution reference: `references/feedback-loop.md`.318Upstream capability sync reference: `references/upstream-capability-sync.md`.319Development compatibility reference: `references/development-compatibility.md`.320Self-check reference: `references/self-check.md`.321QA checklist reference: `references/qa-checklist.md`.322Direct plain-language contract: `references/plain-language.md`.323CJK typography contract: `references/cjk-typography.md`.324Visual direction preview contract: `references/direction-preview.md`.325Governed Playground contract: `references/playground.md`.326Evidence-gated layered adaptation contract: `references/adaptation.md`.327Machine-readable adaptation contract: `references/adaptation-contract.schema.json`.328Framework-agnostic component contract: `references/component-capabilities.md`.329Project motion foundation reference: `references/motion-foundation.md`.330Machine-readable motion foundation schema: `references/motion-foundation.schema.json`.331Motion primitive registry: `references/motion-primitives.json`.332Motion spec reference: `references/motion-spec.md`.333Animation opportunity and review reference: `references/animation-opportunity-and-review.md`.334Reference evidence and spatial-routing spec: `references/reference-spec.md`.335Change visual/screen-space design spec: `references/design-spec.md`.336Change 3D world spec: `references/3d-spec.md`.337Graphics runtime routing reference: `references/graphics-runtime-routing.md`.338Machine-readable graphics runtime catalog: `references/graphics-runtime-catalog.json`.339XY Python charting reference: `references/xy-charting.md`.340Change scene/runtime spec reference: `references/scene-runtime-spec.md`.341Phaser v4 game runtime reference: `references/phaser-v4.md`.342Game UI and narrative profile reference: `references/game-ui-and-narrative.md`.343Curation policy reference: `references/curation-policy.md`.344Contextual anti-slop review reference: `references/anti-slop-review.md`.345Machine-readable anti-slop rubric: `references/anti-slop-rubric.json`.346Impeccable design contract: `references/impeccable-contract.md`.347Impeccable product-design capability map: `references/impeccable-product-design.json` and348`references/impeccable-product-design.md`.349350If these design skills are installed, use them as lenses in this order:3513521. `impeccable`: command vocabulary, surface modes, refinement semantics, bounded verification, and design-detector workflow.3532. `frontend-design`: visual direction, composition, strong first impression, avoiding generic AI aesthetics.3543. `design-taste-frontend`: anti-template discipline, typography taste, language and visual restraint.3554. `ui-ux-pro-max`: UX heuristics, design-system selection, color and type pairing, stable repeatability.3565. `web-design-guidelines`: production UI rules, layout, semantics, accessibility, responsive behavior.3576. `emil-design-eng`: motion, transitions, input feedback, perceived quality, interaction details.358359For dynamic UI, interaction motion, and animation-specific work, apply these motion skills:360361- `design-motion-principles`: primary create/audit workflow for purposeful UI motion.362- `emil-design-eng`: design-engineering judgment for animation and interaction polish.363- `animation-vocabulary`: translate vague motion intent into precise timing, easing, choreography, and behavior language.364- `review-animations`: strict post-implementation animation review.365- `references/animation-opportunity-and-review.md`: project-owned gate for screening opportunities before implementation, naming vocabulary/curves, and recording review evidence.366- `apple-design`: Apple HIG-inspired interface principles and fluid system UI motion for web (WWDC-informed).367- `vercel-react-view-transitions`: React and Next.js view-transition implementation patterns.368369Choose companions by capability, not by the presence of a familiar skill name. Classify the brief370with `designer-pipeline route` first. Read `references/capability-routing.md` and371`references/job-registry.json` when the change crosses evidence capture, design systems, assets,372motion runtimes, editable design handoff, or hosted delivery. For 2D, 3D, data visualization,373geospatial, GPU, game, or narrative surfaces, also read `references/graphics-runtime-routing.md`374and select a capability family before selecting an adapter.375376For product UI, flows, design-system work, user-visible UI changes, or interface reviews, always377apply the bundled interface discipline in `references/interface-discipline.md`. It is present in378the package and does not require a global skill installation. Start with its `better-interface`379router, use full coverage unless a narrow repair qualifies for quick coverage, and use its380change-scoped review protocol for changed UI.381382Catalog CLIs are escape hatches. Open them only when `designer-pipeline route` selects that catalog383as the primary knowledge door, or when a listed secondary is needed as reference. Do not search384MengTo, Prism, Astryx, shadcnio, DesignMD, iart, and holosticker as peer Stage 0 searches.385386For visual direction, web technique, motion, WebGL, reference analysis, asset, or game work, when387the job dispatcher selects MengTo as primary, search the bundled library before inventing a388workflow:389390```bash391designer-pipeline mengto search --query "<capability or brief>" --json392```393394Read the narrowest returned `SKILL.md` and only the linked supporting files needed for the task.395Apply its workflow, numeric guidance, pitfalls, and verification gates through the target project's396`DESIGN.md`, `MOTION.md`, OpenSpec artifacts, existing stack, accessibility rules, and budgets.397Never treat a bundled demo, runtime asset, dependency choice, account workflow, or publishing recipe398as automatic project authority. The activation and adaptation rules live in399`references/mengto-skills.md`; explicit-only entries still require the user's matching request and400normal side-effect authority.401402For web motion, WebGL motion, kinetic type, or motion-graphics/video craft, when the job403dispatcher selects iart as primary, route before implementing. A domain brief is enough; do not404wait for a skill id:405406```bash407designer-pipeline iart route --query "<motion or video brief>" --json408designer-pipeline iart search --query "<narrow playbook>" --json409```410411Read `references/iart-motion-skills.md`. Record the selected playbook, alternatives, and runtime,412then load only that `SKILL.md`. Keep project `MOTION.md` authoritative. HTML video, reels,413captions, overlays, and explainers use HyperFrames unless the brief names Remotion, Manim, or414After Effects. A route result is a selection, not install or execution authority.415416For product-design intake, Design DNA, token governance, design-corpus learning, or handoff work,417when the job dispatcher selects Prism as primary, route through the bundled Prism System layer418before loading a broad recipe set:419420```bash421designer-pipeline prism route --query "<design request>" --json422designer-pipeline prism search --query "<narrow capability>" --json423```424425Read `references/prism-system.md`, load only the returned local skill sequence, and execute it426inside the native brief, directions, implementation, and QA stages. Reuse the pipeline's existing427design tokens, catalogs, adapters, evidence, `DESIGN.md`, and `MOTION.md`; never create a parallel428Prism runtime or treat upstream autonomy metadata as side-effect authority.429430For an explicit holographic sticker, holofoil, die-cut, pointer-tilt, peel, or matching export431request, when the job dispatcher selects holosticker as primary, inspect the bundled432implementation before creating another shader or geometry path:433434```bash435designer-pipeline holosticker inspect --capability "<capability>" --json436```437438Read `references/holosticker.md`, adapt only the returned source files, and route them through the439project-pinned `threejs` adapter with `scene.json`, `3d.md`, `motion.md`, and browser evidence. Do not440add the full Studio UI or optional dependencies for an unselected capability.441442When `web-design/build-threejs-scroll-worlds` is selected, or Kage is supplied as a reference, also443read `references/kage-scroll-world.md`. It adds the current Kage repository's license boundary and444post-snapshot responsive lessons without importing its unlicensed code or artwork.445446For animation implementation, choose library skills by job:447448- Use `gsap-core`, `gsap-timeline`, `gsap-scrolltrigger`, `gsap-react`, `gsap-plugins`, `gsap-utils`, `gsap-performance`, and `gsap-frameworks` for advanced choreography, scroll-driven animation, timeline control, React integration, SVG/plugin-heavy work, or when GSAP is already in the project.449- Use `animejs` v4.5 for modular timelines, layout transitions, accessible text splitting, SVG, draggable interactions, scroll observers, WAAPI, deterministic stagger, or adapter-driven targets such as Three.js.450- Use the built-in `reflex-xy` route for Python-native charts, notebooks, static chart export, Reflex applications, or large datasets that need screen-bounded rendering. Read `references/xy-charting.md`; pin the alpha version in the target project and keep a semantic data-table path.451- Use the official `pixijs` router and the matching PixiJS v8 sub-skills only for justified interactive 2D render surfaces such as sprite fields, particles, filters, shaders, canvas editors, or high-object-count scenes. Read `references/pixijs-rendering.md` before selecting it.452- Use the built-in Phaser v4 route for a complete 2D game runtime with scenes, game-loop ownership, input, audio, physics, cameras, scaling, and game-state transitions. Read `references/phaser-v4.md`; do not depend on an unverified community skill pack.453- Use Three.js or React Three Fiber for focused 3D scene rendering; use Babylon.js or PlayCanvas when a fuller 3D engine is justified. Existing project runtimes still win when they meet the capability and budget.454- For explicit holographic sticker work, use `references/holosticker.md` as the pinned Three.js implementation route and select only the required material, die-cut, tilt, peel, or export slice.455- Use `references/game-ui-and-narrative.md` for HUDs, game menus, dialogue systems, visual novels, and Galgame surfaces. Keep dialogue, choice, backlog, save/load, skip, autoplay, and accessibility state independent of animation timing.456- If no animation or rendering library is already present, prefer semantic DOM plus CSS transitions/keyframes for simple state changes; choose Anime.js, GSAP, PixiJS, Phaser, or a 3D runtime only when the required capability justifies it.457- Do not add overlapping runtimes unless `design.md`, `motion.md`, and when required `scene.md` or458 `3d.md` assign distinct responsibilities. One adapter owns each render loop, clock, property,459 lifecycle, and cleanup path.460- Treat an installed but stale `animejs` companion as a warning. Use official v4.5 documentation for missing markers and record the fallback in `qa.md`.461- Treat a partial or stale PixiJS suite as a warning. Use the canonical PixiJS v8 documentation index for missing APIs and record the fallback in `qa.md`.462463For React and Next.js work, also apply the installed Vercel / Next.js engineering skills listed in `references/companion-skills.md`:464465- `vercel-react-best-practices`466- `vercel-composition-patterns`467- `vercel-react-view-transitions`468- `next-cache-components-adoption`469- `next-cache-components-optimizer`470- `next-dev-loop`471472If a companion skill is missing, continue with the same gate manually and note the missing skill in `qa.md`. Do not block the user unless the requested output depends on a missing asset, credential, or external service.473474## Stage 0: Repo Read475476Before writing design artifacts or code:477478- Persist the route job plan and bind `jobPlanSha256`/`jobPlanPath` to later toolchain and execution requests.479- Run `node <design-pipeline>/scripts/check-deps.cjs` from the target project root.480- Identify framework, styling system, component library, routing, design tokens, test surface, and existing UI patterns.481- Resolve visual sources to file paths before writing source-bound evidence. If unavailable, record `source.availability: pending`, its reason, and the unlock action; never invent paths, dimensions, or hashes.482- Check project `DESIGN.md` and `MOTION.md`; route missing or incompatible foundations through synthesis.483- Resolve the frontend/tool/graphics plan with the governed CLI before invoking an external runtime. Probe first; do not install from a route result.484- Use the design-system CLI to decompose capabilities and record adoption as `reference`, `adopt`, `substitute`, or `custom`.485- Run `designer-pipeline component lock` from the approved direction selection, then run `designer-pipeline component fit` for each capability set. The resulting matrix must preserve direction-lock, catalog, project-inventory, and evidence hashes.486- Initialize or update `state.json`, `events.jsonl`, and `handoff.md` through the existing state tools.487488Use `references/stages.md` for the full Stage 0 checklist and the required toolchain/execution commands.489490## Direction and Copy Rules491492- Treat the hero or first viewport as the product thesis, not a generic template slot.493- Choose palette, typography, layout, and motion from the subject and audience. A named style alone is not a rationale.494- Spend boldness in one justified signature element; remove decoration that does not improve understanding or action.495- Use structural markers, labels, and numbering only when they encode true information.496- Write from the user's side of the screen. Controls name real actions, errors name the fix, empty states direct the next action, and the same action keeps the same name through the flow.497- Read `references/plain-language.md` for user-facing copy and `references/cjk-typography.md` for CJK or mixed-script surfaces.498499## Browser and Evidence Rules500501The browser runner is an evidence port, not a source of authority. For dynamic web apps:5025031. Start or verify the target runtime and wait for readiness.5042. Wait for `networkidle` before inspecting dynamic DOM.5053. Discover selectors from the rendered surface.5064. Exercise the required interaction and state transitions.5075. Capture the applicable DOM, screenshot, console, accessibility, network, and performance artifacts.5086. Bind artifacts to hashes and record missing or degraded capabilities explicitly.509510`adapters/playwright.cjs` is the project-owned implementation. A static screenshot cannot replace behavioral evidence.511512## Public CLI Surfaces513514Use the public CLI rather than reaching into implementation modules:515516```bash517designer-pipeline route --query "<brief>" --write --output job-plan.json --json518designer-pipeline toolchain resolve --artifact toolchain-request.json --write --output toolchain-plan.json --json519designer-pipeline design-system decompose --query "<brief>" --write --output capability-inventory.json --json520designer-pipeline direction check --stage preview --change-root <change-root> --json521designer-pipeline component lock --artifact direction-lock-request.json --write --output direction-lock.json --json522designer-pipeline component fit --artifact component-fit-request.json --write --output component-fit-matrix.json --json523designer-pipeline component validate-fit --artifact component-fit-matrix.json --json524designer-pipeline reference check --change-root <change-root> --json525designer-pipeline reconstruction check --stage final --change-root <change-root> --json526designer-pipeline playground check --stage integration --change-root <change-root> --json527designer-pipeline scene check --change-root <change-root> --json528```529530For the first-wave guided multi-surface flow, use these commands:531532```bash533designer-pipeline surface validate --artifact surface.json --json534designer-pipeline intake start --artifact input.json --json535designer-pipeline intake answer --artifact brief.json --answer answer.json --json536designer-pipeline intake confirm --artifact brief.json --json537designer-pipeline template inventory --catalog catalog.json --json538designer-pipeline template search --catalog catalog.json --surface surface.json --request request.json --json539designer-pipeline template select --selection selection.json --json540designer-pipeline template adapt --receipt receipt.json --context context.json --json541designer-pipeline template review --plan plan.json --rev542543…(truncated)
2233admin