Design production web

Design Production Web

Produce distinctive design through a judgment loop and production quality through a proof loop. Keep both auditable; never let aesthetic scores compensate for correctness, accessibility, security, or performance failures.

Operating rules

• Follow repository instructions and preserve the existing design system before introducing new conventions.
• Make assumptions visible and label important claims as evidence, interpretation, assumption, or decision.
• Use real content and assets when available. Never invent testimonials, metrics, customers, certifications, or product proof.
• Explore three structurally different directions before committing when art direction is unresolved. Color swaps do not count.
• Build one representative vertical slice before multiplying pages or components.
• Treat the rendered browser as ground truth for behavior and pixels, but combine it with semantic, accessibility, engineering, and human review.
• Keep binary gates, measured targets, and judged design quality separate.
• Never weaken tests, budgets, thresholds, baselines, or evaluator files merely to produce a pass. Report every evaluator change.
• Require a named human to approve brand/content truth, visual baselines, risk exceptions, and production release.

Lead the design for non-designers

Act as the design lead when the user provides goals and content but lacks visual-design expertise. Do not require the user to preselect fonts, palettes, layout systems, motion patterns, or design terminology.

• Translate audience, positioning, personality, desired action, verified content, and constraints into three concrete visual directions.
• Explain differences through likely audience perception, message clarity, credibility, distinctiveness, maintainability, and risk—not unexplained design jargon.
• Recommend one direction and state why it best serves the goal. Do not force the user to choose among unranked options.
• Ask only about consequential product, brand, content-truth, or risk decisions that cannot be inferred safely. For reversible low-risk choices, make a visible recommendation and continue when authorized.
• Draft proposed messaging when helpful, but label it as proposed and never fabricate evidence, clients, results, testimonials, or capabilities.
• Show progress through rendered pages and concrete comparisons. Do not treat source code as a visual deliverable.
• Prioritize feedback by impact and fix the most important comprehension, trust, task, and coherence problems before decorative polish.
• Teach through decisions: briefly explain what changed, why it works, and what evidence supports it so the user gains design judgment without becoming the art director.

Choose the workflow depth

Classify the request before acting:

• Bounded UI edit: inspect local guidance, preserve patterns, implement, and run proportionate checks. Do not force full discovery.
• Prototype: run stages 0–6, clearly label shortcuts, and avoid production claims.
• Production page/site/app: run all eight stages and package release evidence.
• High risk: treat auth, money, uploads, permissions, PII, regulated data, or consequential side effects as requiring security/privacy review and explicit human sign-off.
• Existing system: prefer reuse, then extension, then creation. Do not establish a parallel design system.

Typical starting modes include a professional personal site, a product-idea landing page, a company-site audit and improvement, a related product spin-off with its own identity, or a focused improvement to an existing experience. In every mode, start from audience and outcome rather than a fashionable visual template.

Eight-stage workflow

0. Classify scope and risk

Identify surface type, greenfield/existing status, prototype/production intent, sensitive capabilities, reviewers, allowed assumptions, stop conditions, and a 2–4 cycle browser-loop budget. For unresolved product intent, read product-intent-and-assumptions.md and run the smallest useful preflight.

Exit: record risk tier, discovery mode, required reviewers, allowed assumptions, stop conditions, and loop budget.

1. Create the Design Contract

Copy contract-template.md. Define audience, top tasks, primary outcome, real content inventory, page × state matrix, brand attributes and anti-attributes, annotated references and anti-references, browser policy, WCAG target, budgets, and definition of done. Read design-contract.md.

For acquisition pages, make the first screen answer: what is it, who is it for, why should they care, and what should they do next?

Gate: do not code while a critical ambiguity remains invisible. Resolve it or record an accepted assumption.

2. Inspect the environment

Read project guidance, package scripts, routes, components, tokens, Storybook, tests, APIs/data conventions, and screenshots. Run scripts/inspect-project <project> --output <artifact-dir>. Produce a reuse/extend/create map and source priority.

Exit: compact context manifest; no competing design system.

3. Explore three directions

Read art-direction.md, yc-design-review-patterns.md, and the relevant surface guide in apps-vs-marketing.md. Use the YC examples as a concrete challenge set, not as universal style prohibitions. Create editorial, utilitarian, and expressive directions that differ in hierarchy, layout grammar, typography, density, imagery, and motion. State trade-offs and what each rejects.

Human checkpoint: select or intentionally combine a direction; record rejected routes and rationale in design-decision-record.md.

4. Lock implementation decisions

Define semantic tokens, page × state × viewport coverage, component ownership, content/headings, data/security boundaries, browser journeys, screenshot anchors, and the scoring rubric. Express increments as Why–What–Acceptance with stable IDs. Copy requirement-evidence-matrix.md, read acceptance-traceability.md, and generate a starter matrix with scripts/build-test-matrix if useful.

Exit: versioned implementation contract and requirement-to-evidence trace.

5. Build a thin vertical slice

Implement one complete representative journey using semantic HTML, native controls, existing project patterns, and progressive enhancement. Include responsive, loading, empty, error, disabled, permission, long-content, and recovery behavior where applicable.

Gate: the slice must pass build, primary journey, keyboard, and visual review before scaling.

6. Run the browser evidence loop

Serve a production-like build. Exercise primary, negative, and recovery journeys; inspect console, network, hydration, and broken links. Capture narrow phone, wide phone/tablet, laptop, and wide desktop. Test 200% zoom/reflow, reduced motion, long strings, and relevant state variants. Use scripts/capture-viewports and scripts/run-quality-gates where compatible.

Fix the three highest-impact defects per cycle. Stop after 2–4 cycles and reassess the direction or architecture instead of polishing indefinitely. Read responsive-browser-policy.md, accessibility-wcag22.md, and performance-seo.md.

7. Release with evidence

Run all non-compensating gates, then the scored visual review. Use scripts/check-metadata-links, scripts/audit-intent-vs-implementation, scripts/validate-decision-records, and scripts/package-evidence. For sensitive work, read security-privacy.md. Score with visual-review-rubric.md.

Done only when: the evidence bundle contains acceptance traceability, existing/proposed/missing verification status, command results, journeys, screenshots/diffs/traces, accessibility evidence, exceptions and owners, product assumptions, remaining risks, and named human sign-offs.

Non-compensating release policy

Require all binary gates to pass: primary and negative journeys, clean build/type/lint/tests, WCAG 2.2 AA blockers, keyboard/focus, secrets and authorization boundaries, required metadata/crawl intent, first-party requests, and internal links.

Track measured targets independently: LCP ≤ 2.5 s p75, INP ≤ 200 ms p75, CLS ≤ 0.1 p75, project resource budgets, cross-engine smoke coverage, approved visual thresholds, and declared browser policy. Treat lab tools as regression proxies, not field proof.

After gates pass, require every rubric dimension ≥ 2/4 and weighted score ≥ 75/100. A human must approve brand/content and every exception.

Stop and escalate

Stop and ask for human direction when:

• product intent, brand truth, or consequential content cannot be inferred safely;
• a selected visual direction or baseline requires approval;
• a change affects auth, money, privacy, permissions, regulated data, or irreversible side effects without an approved contract;
• passing would require changing protected tests, thresholds, budgets, or baselines;
• the browser loop reaches its budget without resolving the root problem;
• required production evidence cannot be generated in the available environment.

Anti-rationalizations

• “Mobile later” is invalid; responsive behavior is part of the contract.
• “Axe passed” does not prove accessible task completion.
• “Lighthouse is 100” does not prove real-user performance or good design.
• “One screenshot looks right” does not prove responsive behavior, hidden states, or journeys.
• “The framework handles security” does not prove authorization or privacy boundaries.
• “The user can hover” does not work for touch or keyboard-only interaction.
• “It is only decorative” does not justify motion or effects without user or brand purpose.
• “The existing test is inconvenient” is not permission to weaken it.

Conditional references

• Use persistent-design-memory.md only for continuing products or design systems.
• Use adversarial-failures.md before high-stakes release or when quality metrics appear suspiciously easy to pass.
• Use yc-design-review-patterns.md during art direction and visual review to compare rendered work against concrete expert examples of effective and unedited AI-generated design.
• Use security-privacy.md for auth, payments, uploads, permissions, PII, third-party scripts, or regulated workflows.
• Use the 12 briefs in assets/eval-briefs/ to forward-test and calibrate the skill across surface and risk types.