design-pipeline

name	design-pipeline
description	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.

Frontend Design Pipeline

Use this skill when the user wants UI/frontend work to be driven by a repeatable design pipeline, especially when they mention OpenSpec, design skills, frontend polish, visual taste, design review, product UI, marketing pages, dashboards, or "make it not AI-looking".

This skill does not replace individual design skills. It orchestrates them into a durable workflow with repo artifacts, implementation gates, and verification evidence.

Design is the product boundary. Engineering, OpenSpec, GBrain, Matt Pocock, Vercel, animation libraries, and graphics runtimes are support systems for producing, implementing, and validating better design outcomes. Do not let this pipeline drift into a general-purpose development framework.

Impeccable Design Contract

The pipeline permanently adopts the reviewed Impeccable contract in references/impeccable-contract.md. Apply it even when the optional upstream impeccable skill is not installed: resolve the visitor mode, respect the brief, distinguish refinement from redesign, challenge template defaults, complete real UI states, and verify the rendered path in bounded desktop/mobile passes. The upstream Neo Kinpaku visual theme is not a default; only its design judgment and workflow vocabulary are internalized.

The complete upstream product-design surface is mapped in references/impeccable-product-design.json and summarized in references/impeccable-product-design.md. All 23 core commands are available as pipeline intents: shape, init, document, extract, visualize, critique, audit, polish, bolder, quieter, distill, harden, onboard, animate, colorize, typeset, layout, delight, overdrive, clarify, adapt, optimize, and live. They route into product truth, surface shaping, design authority, experience quality, and implementation evidence. hooks, doctor, routing, pin, and native-platform references are supporting enforcement and maintenance capabilities, not visual themes. Do not claim coverage from the command name alone: use the mapped artifact and evidence fields as the acceptance contract.

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

Every target project must have one reusable project DESIGN.md before implementation begins. This is a system invariant, not an optional input:

• if it exists, validate it with scripts/check-design-foundation.cjs;
• if it is missing, route through requirements-driven synthesis;
• if it is incomplete, repair or resynthesize it;
• never substitute change-level lowercase design.md, a template copy, or a token dump.

Planning may begin in order to produce the foundation. Stage 5 implementation may not begin until the foundation checker reports ready.

Project MOTION.md Invariant

Every target project must also have one reusable project MOTION.md before implementation begins. This remains true for static products: posture: static is an explicit motion decision.

• 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:

1. Create one change folder per UI change.
2. Write intent and constraints before implementation.
3. Generate design decisions and tasks as durable artifacts.
4. Implement from the artifacts.
5. Verify the implementation against the artifacts.
6. 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:

design/changes/<change-id>/
  brief.md
  direction-preview.json # required/waived applicability, hash-bound candidates, and decision
  direction-previews/    # index.html plus one comparable screenshot per candidate
  playground.json        # required/waived interactive exploration, selection, and integration receipt
  playground/            # self-contained HTML and hash-bound natural-language selection prompt
  reference.md    # observed reference evidence and 2D / 2.5D / 3D / hybrid route
  reference-evidence.json # normative reference role, fidelity, geometry/camera/interaction/output
  reconstruction.json     # exact/adaptive static-reference calibration and comparison contract
  graybox.png             # layout-only capture with materials and optical treatment suppressed
  rectified-reference.png # canonical front view derived from the supplied frame
  front-elevation.svg     # object-space construction source
  camera-calibration.json # locked camera/lens/viewport parameters
  landmark-overlay.png    # source/render projection overlay
  fidelity-receipt.json   # EvidencePort metrics bound to render hashes
  directions.md
  design.md       # visual language and screen-space UI
  motion.md
  scene.json      # normative contract for persistent spatial or engine-owned runtime state
  scene.md        # readable projection for persistent non-3D runtime state
  3d.md           # readable spatial projection for 3D capability families
  tasks.md
  qa.md
  state.json
  events.jsonl
  handoff.md

Use an existing project convention instead if the repo already has openspec/, spec/changes/, docs/design/, .omx/, or another active planning directory.

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.

1. 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.
2. 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.
3. Read references/reference-spec.md and references/reconstruction-spec.md completely.
4. 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.
5. Do not generate alternative design directions. The reference already determines the direction.
6. Record the per-region structure table in reference.md and the matching composition block in reference-evidence.json before any layout is authored.
7. 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.
8. 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.
9. 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.

Website Cloning Module

When the user asks to clone, reproduce, rebuild, reverse-engineer, or use one or more live pages as implementation references:

1. 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.
2. 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.
3. Treat references/website-cloning-manifest.schema.json as the machine-readable Browser/Builder/Evidence port and fidelity contract.
4. 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.
5. 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.
6. Keep the URL-first user experience, but record each adapter, its available capabilities, and a successful capability probe before claiming exact fidelity.
7. 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.
8. 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:

1. Read references/design-synthesis.md completely.
2. Initialize with scripts/init-design-synthesis.cjs, using --problem as the primary input.
3. Register live pages with --reference-url and existing DESIGN.md examples with --template. Both are attributed evidence; templates are always inspiration-only.
4. Run /grill-with-docs <problem> when material product decisions remain unresolved, persist its ADR/glossary/decision evidence, then record grill-completed.
5. Run the deterministic scope assessment. Only when the score exceeds the selected budget, say “哦，天哪，这比我预期的要大得多。” and request /wayfinder 为此制作一张地图.
6. Wayfinder must use a configured issue-tracker host. Never invent a local issue map when that host is unavailable.
7. Synthesize 2-3 product-specific directions from requirements, repository constraints, and cited evidence. Select one and write the reusable project DESIGN.md.
8. 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: . Machine-readable anti-slop rubric: . Impeccable design contract: . Impeccable product-design capability map: and .

If these design skills are installed, use them as lenses in this order:

1. impeccable: command vocabulary, surface modes, refinement semantics, bounded verification, and design-detector workflow.
2. frontend-design: visual direction, composition, strong first impression, avoiding generic AI aesthetics.
3. design-taste-frontend: anti-template discipline, typography taste, language and visual restraint.
4. ui-ux-pro-max: UX heuristics, design-system selection, color and type pairing, stable repeatability.
5. web-design-guidelines: production UI rules, layout, semantics, accessibility, responsive behavior.
6. 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.

For React and Next.js work, also apply the installed Vercel / Next.js engineering skills listed in references/companion-skills.md:

• vercel-react-best-practices
• vercel-composition-patterns
• vercel-react-view-transitions
• next-cache-components-adoption
• next-cache-components-optimizer
• next-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:

• Classify the brief into exactly one primary job, then persist the plan before opening a catalog:

designer-pipeline route --query "<brief>" --write --output job-plan.json --json

Open only the returned primary knowledge door. Kernel steps in next always run. Secondaries stay reference-only and do not become a second primary. Do not search every catalog. Add a new capability by registering a job in references/job-registry.json, not by adding another mandatory Stage 0 search. Status needs-clarification asks one question that distinguishes the top jobs; it does not pick a primary or write a plan. Put jobPlanSha256 and jobPlanPath on the toolchain request, and the same jobPlanSha256 on the execution request. Job id and toolchain primaryRouteId are different identifiers. Plan presence does not make an inert or reference-only catalog executable-ready.

• For HTML video, reels, motion graphics, captions, overlays, slideshows, explainers, voiceovers, or Remotion ports, route through references/hyperframes.md before choosing a runtime. HyperFrames uses HTML as the source of truth and a deterministic, paused, seekable timeline; ordinary UI motion remains on the normal motion route. Load only the matched workflow/domain skill when the upstream HyperFrames skill tree is available.

• For read-only pull-request orientation, review-thread inspection, or CI failure drilldown, use node <design-pipeline>/scripts/github.cjs pr-snapshot|pr-threads|ci-failures. The commands collapse repeated gh calls into bounded reports, preserve valid gh failure statuses, keep review resolution state through GraphQL, and write full CI logs to the OS temp directory. They require gh on PATH and an authenticated session; they never create or mutate GitHub artifacts. Use raw gh for workflows these commands do not cover, and never pipe gh into head.

• Run node <design-pipeline>/scripts/check-deps.cjs from the target repo root, or manually perform the same checks from references/self-check.md if Node is unavailable.

• Read references/companion-capabilities.json as the source of truth for install groups, suite requirements, capability markers, and upstream sources. Do not add another hard-coded companion list.

• Read capability-profile warnings separately from install status. installed means discoverable; WARN means the companion surface does not advertise the current capability baseline.

• Treat missing optional/enhancement companion skills as a fallback path, not a blocker. Record missing capabilities in qa.md.

• When a warning represents a reusable pipeline or companion gap, run self-check with --record-feedback or call scripts/record-feedback.cjs immediately. This writes a local, redacted, deduplicated draft; it does not publish remotely.

• When version-sensitive upstream freshness matters, read references/upstream-capability-sync.md. The host retrieves source evidence; the bundled audit compares it without executing remote content. Missing evidence is UNKNOWN, never current.

• Never append a retrieved taste prompt to global agent instructions. Curate reviewed observations into , preserve source hashes, and keep the remote text inert.

Stage 1: Brief

Create or update brief.md with:

• Goal: what UI outcome the user wants.
• Audience: who uses it and under what pressure.
• Visitor mode: Persuade, Operate, Read, or Experience, with the mode-specific success condition.
• Surface: pages, components, states, and screen sizes.
• Constraints: tech stack, assets, data, accessibility, performance, deadlines.
• Non-goals: what should not change.
• Real content ranges: minimum, typical, maximum, long, missing, localized, and permission-limited cases where relevant.
• Acceptance checks: observable behavior and visual qualities.
• Playground applicability: whether an interactive representation would express or tune the product problem better than prose, with a supported required reason or waiver.

Keep this short. It is an execution contract, not a product essay.

Form sanity backstop

Before choosing a visual direction, declare the deliverable form from the user's or controller's language, then state the reader action in plain terms. Apply the single-canvas counterfactual: if the proposed carrier were all the reader received, could it perform that action without the author explaining it? If the brief implies a sequence, set, or state flow, do not compress it to one canvas for production convenience. Record unresolved form uncertainty in the brief and take the least-assumptive path; a model-written concept cannot approve its own form.

When the brief, handoff, or interface copy asks a person to decide or act, read references/plain-language.md. Put the exact consequence or available action first, then preserve scope, limits, exclusions, uncertainty, unchanged state, and recovery actions in the second pass.

Stage 2: Design Directions

Read references/direction-preview.md and write direction-preview.json before selecting a direction. For an open whole-surface request, produce three candidates by default in one comparable direction-previews/index.html; two candidates require a real product/reference constraint, and four are for an explicit broader exploration. Use the same real content fixture, state coverage, and viewport, then capture and hash one screenshot per candidate.

Run designer-pipeline direction check --stage preview --change-root <change-root> --json while the decision is pending. Only after it reports ready may the user or an autonomous run select a candidate. Record the selected ID and product/visitor-fit rationale, then run direction check --stage selection. A narrow change, established surface, non-visual change, exact primary target, or user-specified single direction records an explicit supported waiver. Missing evidence is not a waiver.

Create directions.md from the selected, verified preview before implementation. Present the committed direction and at most two honest alternates. When a waiver inherits an established or user-selected direction, record that inheritance instead of inventing alternatives.

When references are present, directions must preserve the route and fidelity invariants recorded in reference.md. A 3d or hybrid route cannot be downgraded to flat card composition for implementation convenience.

For a primary-target exact reconstruction, do not produce alternative directions. Record that directions.md is intentionally bypassed because the supplied reference is the selected direction, then proceed through rectification, camera calibration, and the graybox capture.

Each direction must include:

• Visual thesis: layout, density, rhythm, typography, color posture.
• Interaction thesis: motion, feedback, empty/loading/error states.
• Fit: why it suits this product and audience.
• Risk: where it may fail or feel wrong.

Choose the carrier and visual language from the subject, audience task, and viewing context, not from a style label alone. Every major visual technique must name its subject or reference cause and its intended viewer effect. Anti-template work has two sides: reject generic AI grammar and reject under-designed output; a title over an untreated asset with faint decorative furniture is not a finished direction.

When anti-template risk matters, use references/anti-slop-review.md to compare cohesion, product-grounded signature, specificity, and template-pattern density. Named colors, fonts, punctuation, shapes, effects, or common layout families are not automatic rejection criteria.

Default decision rule:

• Product dashboards and operational tools: choose the quietest direction that maximizes scanability and repeated use.
• Marketing pages and portfolios: choose the direction with the strongest first-viewport signal and least generic composition.
• Components and app flows: choose the direction with the clearest states, accessibility, and interaction feedback.

Read references/playground.md when the user requests a Playground or an interactive representation would express the problem better than prose. A Playground may tune an accepted visual system, visualize code architecture or concepts, explore data, critique a document or diff, or tune game balance when that work directly supports product design, frontend implementation, scene/runtime design, or QA. Generate the self-contained HTML and run designer-pipeline playground check --stage build. Read the matching blueprint under references/playground-templates/ before generating the HTML. When no built-in route fits, create a hash-bound change Blueprint using the open protocol and record its governed integration target. Persist the accepted full state and natural-language prompt, exercise every control and preset in a browser, persist the hash-bound verification report, and run playground check --stage selection. Do not use a design Playground to replace honest direction comparison. A supported waiver remains explicit and machine-readable.

Stage 3: Design Spec

Create lowercase change design.md using references/design-spec.md. It is the selected source of truth for visual language and screen-space UI.

Order this stage by reference role. For primary-target, capture and pass the graybox first, then write design.md against it and cite that capture; a spec written from a reading alone propagates the misreading into the implementation. For constraint and inspiration, keep the existing order and reconcile design.md against the first render afterwards. Reconciliation is required for every change that has a reference; the role decides when it happens, never whether it happens, and there is no role for which it is optional, inspiration included. Every change with a reference records a Spec Reconciliation section; an empty table is a valid result, an absent section is not.

design.md records:

• Layout grid and responsive behavior.
• Color tokens and contrast posture. For website references, these must cite the ready palette-evidence.json, preserve DOM and raster-media sources separately, and record coverage, luminance, saturation, and temperature relationships rather than listing accents alone.
• Type scale and font constraints.
• When shipped copy contains CJK text, the system/project font stack, CJK body size and line height, punctuation/mixed-script convention, and decorative subset evidence required by references/cjk-typography.md.
• User-facing copy follows references/plain-language.md: titles name the smallest accurate scope, the first useful sentence exposes the consequence or action, and controls name only real actions.
• Component inventory and states.
• Motion rules and reduced-motion fallback.
• Accessibility requirements: semantic structure, focus order, keyboard behavior, labels, announcements, contrast.
• Interface-discipline decisions: selected review scope; layout, type, color, writing, surface, and accessibility constraints affected by the change; and downstream consumers of changed shared components or tokens.
• Asset strategy: real assets, generated bitmap images, icons, or no-assets justification.
• Anti-template decisions when the contextual anti-slop review is active: deliberately avoided patterns, retained common patterns, product-specific rationale, and non-applicable rules.
• Spec reconciliation when the change has a reference: the cited graybox capture, the reconciliation timestamp, and every value the implementation changed with an observed cause.
• Design Playground integration when applicable: the accepted instruction plus playground-kind, playground-artifact-sha256, playground-state-sha256, and playground-prompt-sha256 bindings. Non-design modes use the purpose-aware target in references/playground.md: motion.md, handoff.md, brief.md, qa.md, or scene.md. Run designer-pipeline playground check --stage integration after writing the target; a later selection invalidates it and requires reintegration.

Do not define camera projection, world coordinates, geometry, lighting, world-space UI, or spatial navigation in design.md. Those belong in 3d.md for 3D families.

When requirements-driven synthesis is active, also write the project DESIGN.md according to references/design-synthesis.md. Link it from change design.md; do not duplicate the entire file.

Use concrete values when implementation will need them. Avoid vague style words without implementation consequences.

Create motion.md when the change includes animation, transitions, gesture feedback, loading motion, scroll-linked motion, route transitions, hover/focus motion, or micro-interactions. Use references/motion-spec.md.

Change motion.md must record the validated project MOTION.md hash, selected primitive IDs, authored or observed provenance, runtime capability status, and any degradation. It may not silently invent a parallel motion vocabulary.

motion.md is required for:

• GSAP or Anime.js usage.
• PixiJS, Canvas, WebGL, or WebGPU render surfaces.
• React view transitions.
• Scroll-triggered animation.
• Multi-step choreography.
• Motion that affects navigation, focus, loading, data updates, or user confidence.

Simple CSS hover/focus transitions can stay in design.md, but still need reduced-motion behavior and QA notes.

Create normative scene.json plus its family-specific readable projection using references/scene-runtime-spec.md when the change has persistent spatial state or an engine-owned lifecycle: Canvas/WebGL/WebGPU scenes, cameras, coordinate transforms, asset manifests, render or game loops, physics, world input, procedural state, save/load state, or runtime-specific degradation. The pair binds design and motion semantics to a selected adapter; it does not replace design.md or motion.md.

Fixed-camera cinematic 3D, Three.js, React Three Fiber, Babylon.js, PlayCanvas, CesiumJS, and equivalent 3D families require scene.json plus 3d.md from references/3d-spec.md. Phaser, PixiJS, persistent 2D editors, WebGPU/WGSL effects without a 3D family, and stateful narrative runtimes use scene.json plus scene.md. A narrative UI without a scene renderer may remain DOM-first, but still requires the pair when it owns dialogue state, save/load, backlog, autoplay, or another persistent game-state lifecycle.

Every change with a reference-evidence.json implements and verifies the actual-runtime graybox gate before materials, glow, bloom, depth of field, scanlines, or cinematic grading. The gate is unconditional: it applies to 2d and 2.5d as well as 3d and hybrid, to every fidelity mode, and to runs whose source is pending. 3d and hybrid routes record the graybox contract in 3d.md and reconstruction.json; 2d and 2.5d routes without a reconstruction.json record it in reference-evidence.json. Camera navigation is required only when the approved interaction model is inspectable or navigable.

Stage 4: Tasks

Create tasks.md with a checkbox list grouped by implementation surface:

• Tokens/theme
• Layout
• Components
• States
• Playground build, selection, and purpose-aware integration when required
• Motion opportunity screen and static-alternative decision
• Motion vocabulary, curve, runtime, and spec
• Motion review and evidence capture
• Scene/runtime spec when required
• Accessibility
• Responsive QA
• Browser/manual QA
• Interface discipline review for changed UI: scope, selected domains, consumer expansion, and finding status classification.

Tasks must be small enough to verify independently. Update checkboxes as implementation proceeds.

Stage 5: Implementation

Implement directly from design.md and tasks.md.

Rules:

• When playground.json records required applicability, run designer-pipeline playground check --stage integration --change-root <change-root> --json and stop unless it reports ready. Implementation consumes the bound purpose-aware artifact, never unbound browser state or an earlier copied prompt.

• Re-run design-system resolve-stack, design-system decompose, design-system route, and design-system decide against the final brief and installed project stack. Stop if the stack or design-system decision is not ready, or if its registry hash/selected routes differ from the artifacts approved at Stage 0 without a recorded design change.

• For website-cloning changes, run scripts/check-website-clone-foundations.cjs --change-root <change-root> --json first and stop unless it reports ready.

• Re-run scripts/check-design-foundation.cjs and stop unless it reports ready.

• Re-run scripts/check-motion-foundation.cjs and stop unless it reports ready.

• When references influence the change, run designer-pipeline reference check and stop unless it reports ready, with exactly one exception: a standalone source-pending. Standalone means the top-level reason is source-pending and every entry in the stages map reports ready. Only then continue - through the graybox gate, with the measured gates kept blocked. A run blocked for source-pending and anything else - a blocked stages.graybox, a blocked stages.reconciliation, any other reason - is still a stop. The aggregate reports one top-level reason, so source-pending on that line is not by itself evidence that the stages are clear; read the stages map before continuing. This command now carries three stages - stages.graybox, stages.reconciliation, and the aggregate's own contract checks - and reports blocked when any of them is not ready, so a change that passed it before the fold can block on a section that was never written.

Stage 6: Gate Review

Before claiming completion, write qa.md using references/qa-checklist.md with the result of these gates:

• Visual gate: composition is non-generic, brand/product signal is clear, palette is not one-note, typography fits the surface.
• Impeccable gate: the selected visitor mode is explicit, refinement has not become a hidden redesign, anti-default exceptions are justified, and critique/audit/polish claims are supported by separate evidence.
• UX gate: primary workflow is obvious, states are complete, destructive actions are guarded, recovery paths exist.
• Playground gate: when interactive exploration is required, the self-contained build, selected typed state, natural-language prompt, and purpose-aware target bindings all pass playground check --stage integration; browser/manual QA exercises every control and preset and confirms that representation, prompt, and copied text stay synchronized. Otherwise a supported waiver is recorded.
• Plain-language gate: user-facing copy puts the exact consequence or available action first, then passes the fact-scope review in references/plain-language.md; a shorter rewrite cannot widen a partial failure, remove a limit, strengthen uncertainty, or invent an action.
• Engineering gate: existing patterns are respected, no unnecessary dependency or abstraction was added.
• Accessibility gate: keyboard navigation, focus behavior, labels, reduced motion, and contrast are checked.
• Interface-discipline gate: the bundled full or quick protocol was applied to the actual UI; changed UI has an interface-review scope, consumer expansion, removed-signal inspection where applicable, and Introduced / Regression / Pre-existing status for every finding in qa.md.
• Motion gate: interaction feedback is intentional, not decorative, and has reduced-motion fallback.
• Animation opportunity/review gate: non-trivial motion passed the frequency, purpose, function, and budget screen before implementation; its vocabulary/curve/runtime decision and actual-surface review evidence are recorded, including interruption, performance, accessibility, and cleanup.
• Motion foundation gate: project MOTION.md is ready, its hash is recorded, and selected primitive IDs exist in the bundled registry.
• Motion spec gate: motion.md exists for any non-trivial motion and includes trigger, purpose, timing, easing, choreography, interruption behavior, implementation library, performance budget, and reduced-motion fallback.
• Reference-routing gate: when references influence the change, reference.md records evidence and normative reference-evidence.json separates reference role, requested/effective fidelity, geometry, camera, interaction, and output; selects , , , or ; names the required artifact set; records source availability; and records approval. Every route names in , and v2 documents carry a block. A document declaring while carrying or a block is current work wearing a stale version label: it is validated as v2 and owes and , failing with until both are recorded. A v1 document that carries neither stays exempt.

If a gate cannot be run, record why and use the next-best check.

Stage 7: Archive

After completion:

• Keep active artifacts with the code if the repo has no archive convention.
• If the repo has OpenSpec-style archiving, move completed change notes to the matching archive folder.
• Update persistent design docs only when the change creates reusable tokens, components, or interaction rules.
• Link accepted feedback observations to the completed change. Mark them resolved or superseded only after verification evidence exists.

Feedback and Maintainer Loop

Use references/feedback-loop.md whenever a run exposes a pipeline bug, stale companion, missing capability, quality gap, documentation gap, or reusable feature request.

The local loop is:

1. Observe during self-check, implementation, or QA.
2. Normalize, redact, and deduplicate with scripts/record-feedback.cjs.
3. Generate an Issue draft by default; generate a PR draft only when changed files and validation evidence exist.
4. Review the draft, target remote, privacy boundary, and evidence.
5. Publish only after explicit user authority through an installed GitHub or ship workflow.
6. Preserve the regression test and update companion-capabilities.json when the durable learning changes compatibility routing.

When modifying design-pipeline itself, use this same pipeline and OpenSpec lifecycle. The pipeline is allowed to improve itself, but it must not silently mutate third-party skills or use ambient credentials to create remote artifacts.

Layered Adaptation Loop

Use references/adaptation.md only after the user's requested artifact or implementation is delivered. Capture minimal evidence rather than transcripts. Treat a single acceptance or silence as weak evidence; it cannot produce durable guidance. Keep every candidate in shadow mode until a different evaluator runs both replay and held-out comparisons and designer-pipeline adaptation evaluate returns a passing hash-bound receipt.

Methodology Kernel and packaged skill/ resources are release-governed and cannot be adaptation targets. Task Session Policy expires. Only an external versioned Project Adaptation Skill or User Collaboration Skill may be promoted, and promotion requires explicit user approval. Durable rules select from the finite collaboration dimensions in the contract; they are never free-form behavior instructions. Bind each candidate to the exact external-skill path, incumbent content hash, metric direction, manifest, and construction fixtures before evaluation. Promotion and rollback use their process-owned, recoverable prepare/commit journal; raw actor and review labels are stored only as purpose-separated hashes. Resolve mutually exclusive values by collaboration dimension in the order defaults, user, project, current task while carrying constraints and quality gates as immutable inputs. Rejection leaves the incumbent unchanged. Roll back before forgetting a promoted candidate, then remove its usable content and retain only the non-sensitive tombstone required to prevent reinstatement.

Output Contract

Final responses should report:

• Change id and artifact folder.
• Project DESIGN.md path, input mode, scope score/budget, and Wayfinder map URL when synthesis ran.
• Implemented surfaces.
• Playground applicability, selected state/integration status, and accepted prompt path when used.
• Adaptation applicability, scope, shadow/evaluated/promoted disposition, evidence receipt, and rollback or forgetting status when the layered loop was used.
• Verification evidence.
• Reference source availability. When it is pending, name the action that unlocks the measured gates: supply the source file path, which enables rectification, camera calibration, landmark