ForgetMeAI/design-harness

Design Harness

Run one resumable web-UI workflow. Keep the user in control of intent and keep design production separate from review.

Start and resume

Resolve <skill-dir> as the directory containing this SKILL.md; do not assume the current working directory contains the bundled scripts.

1. Run node <skill-dir>/scripts/preflight.mjs --root <project> before asking questions. Read its capability report; do not install anything. Treat a missing filesystem path as advisory: check the host's loaded skill/plugin inventory before declaring Impeccable or Jakub unavailable.
2. Run node <skill-dir>/scripts/state.mjs init --root <project>. This safely upgrades a legacy state because init is a mutating command. If state exists, run the read-only status command and resume at its nextPhase; never restart completed phases. Use explicit migrate when checking or upgrading a legacy run without reinitializing it.
3. Read only the reference needed for the current phase:
   • discovery/confirmation: references/interview.md
   • context/direction: references/context-contract.md
   • build/tool choices: references/routing.md
   • optional source selection: references/optional-tool-registry.json, only after an activation condition is confirmed
   • review/QA/handoff: references/review-and-qa.md
4. Advance state after each completed phase with node <skill-dir>/scripts/state.mjs advance <phase> --root <project>. For human-feedback, also pass --outcome used or --outcome not-used. For feedback-fixes, pass --outcome applied or --outcome not-applicable.

Use this fixed monotonic sequence:

preflight → discovery → confirmation → context → direction → build → internal-review → human-feedback → feedback-fixes → independent-review → fixes → qa → handoff → complete

Store only machine state in .design-harness/state.json; reports and screenshots belong in .design-harness/reports/. Never store full chat transcripts, tokens, cookies, credentials, or unrelated environment data.

Enforce the approval gate

Interview adaptively and summarize answers in one concise confirmation card. Include product, audience, primary goal, content, pages/surfaces, desired and undesired qualities, positive and negative references, constraints, motion, required states, stack, delegation, AI-specific states, WebGL tolerance, external-source policy, and any paid-license boundary. Ask only for missing or consequential details.

Do not write, edit, or generate UI production code before the user explicitly approves the confirmation card. Preflight, questions, read-only inspection, and an in-chat draft of the confirmation card or proposed intent content are allowed. Do not create or modify project intent .md files until approval.

If references are absent, treat descriptive words as sufficient. Derive two or three named directions with concrete tradeoffs and ask the user to choose. Generate visual boards only when visual tooling exists and the user would benefit; never make a board a prerequisite.

Create approved context

After confirmation, populate these files from user answers or proposals the user explicitly approves:

• PRODUCT.md, including an approved brand or product register
• REFERENCES.md
• DESIGN.md
• ACCEPTANCE.md
• at least one .impeccable/surfaces/<slug>.md

Copy structures from PRODUCT, references, design, acceptance, and surface templates. Mark every intent file approved only after the user approves its content. Run node <skill-dir>/scripts/validate-context.mjs --root <project> before build.

Keep DESIGN.md H2 sections exactly, once each, in this order: Overview, Colors, Typography, Elevation, Components, Do’s and Don’ts.

Treat PRODUCT.md and DESIGN.md as protected after approval. For any later change, show the proposed diff, ask for explicit approval, then apply it. Never silently rationalize drift.

Record every approved external component, recipe, effect, or feedback integration in REFERENCES.md with its exact source, selected item, pinned version or commit when available, access date, intended purpose, current license/terms result, adaptations, and required fallbacks. “Use external libraries” is not approval for a specific source.

Build through Impeccable

Make the installed Impeccable skill and its approved context the sole design and production authority for this pass. Load its skill and relevant domain references, then give it the approved intent files and surfaces. Do not let it repeat discovery or reinterpret approved intent. Let Impeccable generate or refresh .impeccable/design.json; never edit that sidecar manually, and never accept a resulting PRODUCT.md or DESIGN.md change without the protected diff-and-approval flow.

Do not load any other broad taste or design-system skill in the same production pass. Route narrow helpers only under references/routing.md. Preserve the existing component library and stack unless the approved context authorizes change. Never auto-install or auto-copy an optional registry entry; explain the exact bounded use and obtain approval first.

Run an Impeccable self-review after building and record findings; this is internal-review, not the independent review. Once the UI is stable enough to inspect, enter human-feedback: offer the approved Agentation checkpoint when useful, or record Not used with --outcome not-used and advance. Keep Agentation development-only and manual/local by default; MCP, webhooks, and autonomous resolution require separate explicit approval. In feedback-fixes, apply only adjudicated user annotations and record --outcome applied; when feedback was skipped, record Not applicable with --outcome not-applicable and advance without editing. Resolve user annotations before independent review.

Separate review, fixes, and QA

For independent-review, start a fresh read-only subagent/context with Jakub’s current better-interface skill and its six domain skills. Give it screenshots, relevant implementation files, component-library constraints, and the approved intent docs. Request a full review after build. The reviewer must report findings only and must not edit or silently redesign.

Adjudicate every finding in the root context against PRODUCT.md, DESIGN.md, the surface specs, acceptance criteria, and component library. Record accept/reject/defer plus rationale. Apply accepted fixes separately through the production authority, then request a focused quick read-only review of the changed areas.

Follow references/review-and-qa.md. Run the Impeccable detector, Playwright screenshots at mobile/tablet/desktop, axe, and Lighthouse. Cover representative routes and applicable loading, empty, error, long-copy, hover, focus, and reduced-motion states. For optional sources, also exercise their registry gates: semantic/static fallbacks, no-WebGL behavior, approved browsers, mobile CPU/GPU or bundle budgets, and production exclusion of development tools as applicable. Mark unsupported or unexercised states Not reviewed; never report them as passed.

For interfaces with meaningful document-scroll motion or for video/demo readiness, start the fresh production build on a dedicated local port and run node <skill-dir>/scripts/verify-motion.mjs --root <project> --base-url <url> --routes /,<other-routes> --config .design-harness/qa/motion.config.json after adapting the scaffolded config. The verifier tests mobile, tablet, and desktop by default, isolates every route in a fresh context, requires a successful route response, configured content root, expected observed URL/redirect chain, and measurable document scroll, and does not mock application requests or permit redirects unless explicit project config declares each exception. Retain its schema-version 4 Playwright/browser provenance and screenshot/mock hashes with the handoff. Treat first-frame/startup-probe and frame-pacing thresholds as evidence for that machine and browser only, never as a universal 60 FPS guarantee.

Use node <skill-dir>/scripts/scaffold-qa.mjs --root <project> to preview a generic QA scaffold and add --apply after the confirmation card authorizes the QA plan. Ask again only when existing files would be replaced. It never installs dependencies.

Hand off

State Ready only when approved acceptance criteria pass and no blocking finding or unexplained QA gap remains; otherwise state Not ready. List changed files, screenshots, review findings and dispositions, automated checks and results, unsupported states, remaining gaps, and every external source actually used with its pinned provenance and license result. Advance handoff, then run node <skill-dir>/scripts/state.mjs complete --root <project> only when the workflow is genuinely complete.