site-designer

Site Designer

Generate design systems. Audit visual quality. Extract tokens from existing sites. Produce implementation-ready DESIGN.md + design-tokens.json.

This skill operates as a workflow orchestrator. Domain knowledge lives in reference files and databases, not here. This file defines the workflow, routing, and constraints.

---

Phase 0: Manifest-First Lookup (project-workspace-contract@2)

Before any other workspace-touching read, read MANIFEST.md at the project root — NOT workspace/MANIFEST.yaml (under v2, workspace/ is opaque AI scratch and is never the routing surface). This is the manifest-first invariant (manifest-first-pattern v1.1.0; project-workspace-contract@2, child at ${CLAUDE_SKILL_DIR}/references/project-workspace-contract-v2.md).

1. Read MANIFEST.md. Parse the YAML frontmatter for project metadata (type:, brand:, output_language:, canonicals:) and parse the entries: YAML block for the routing index. Accepts legacy client: as brand: during the R66 migration window.
2. Locate prior design output. If a design/ entry already exists, this is a refresh/audit/extract over existing work — read it at the indexed path: and pre-populate. If none exists, this is a first design run.
3. Honor output_language: from the manifest frontmatter over inferred conversation language (see Language Handling below).
4. Resolve the write location for DESIGN.md + design-tokens.json from the contract: the design/ Kind-3 zone (see "Output Format" below). Do not write to project-root-flat or under workspace/.

If no MANIFEST.md exists at the project root, STOP. Ask the orchestrator/human to run the project-local bootstrap routine or choose an existing v2 project with MANIFEST.md. Do not search for flat root files, do not write project-root-flat artifacts, and do not use workspace/MANIFEST.yaml.

site-designer is a producer under project-workspace-contract@2: it owns the design/ zone (kind: spec). After producing, it writes/refreshes the design/ entry in MANIFEST.md (see "Output Format").

---

Phase 1: Establish Requirement Anchor

Before beginning any design work, establish the requirement anchor by asking:

1. What is this product/practice/business? Who operates it, and what do they offer?
2. Who is the target audience? (Not projected. Actual.) Who visits this site today? Demographics, expectations, sophistication level.
3. What is the actual traffic? How many visitors per month? (Not projected. Actual.) A site with 200 visitors/month does not need a design system built for 200K.
4. What are the brand constraints? Existing colors, fonts, logo, tone already decided? Or is this a blank slate?
5. Which use case? (A: create new design, B: replicate/extract existing design, C: reshape existing design)
6. What must "done" look like? Pixel-identical to a reference? A fresh direction? Specific mood or feeling?
7. What is the target stack? (Astro/Svelte/Tailwind default, but confirm.)

Record the answers. Every subsequent design decision, token value, and recommendation must trace back to these answers. If a recommendation cannot be justified by the requirement anchor, it does not belong in the output.

If the user cannot answer questions 1-4, that is itself diagnostic -- they need domain exploration and competitive analysis before design.

"Not Projected. Actual." Constraint

When asking about traffic, audience size, number of pages, or any quantitative scope question, always append the constraint: "(Not projected. Actual.)"

Accept only current, measured values. If the user provides projections, aspirational targets, or industry benchmarks instead of actual numbers, flag this explicitly: "I need the actual current number, not a projection. If you don't have it, that is useful information -- it means we need to instrument measurement before proceeding."

Never use projected numbers as the basis for design complexity decisions. Projected numbers justify monitoring; actual numbers justify building.

---

Operating Modes

This skill has three operating modes. Determine the mode from the user's command or intent before loading reference files.

Mode A: Create (/design)

Purpose: Design a new visual identity from scratch. Full 6-step workflow.

Load these references:

• references/hierarchy.md -- 6 visual hierarchy strategies
• references/layout-spacing.md -- Spacing systems, whitespace rules, responsive density
• references/typography.md -- Type scale, font selection criteria, line-height, alignment
• references/color.md -- HSL model, grey shades, saturation falloff, hue rotation, WCAG contrast
• references/depth-and-polish.md -- Light source, elevation system, two-part shadows, accent borders
• references/spec-website-design-invariants.md -- specification.website design-side invariants (137 topics / 10 categories as of 2026-06-12)
• references/modern-css-primitives.md -- modern platform primitives to specify in DESIGN.md when relevant
• references/ai-tells.md -- Comprehensive banned-patterns list for anti-generic output
• references/creative-arsenal.md -- 40+ advanced UI concepts as alternatives to generic defaults
• references/quality-gates.md -- Swap, Squint, Signature, Token tests

Load these databases:

• databases/products.csv -- 40 product types with recommended patterns, styles, color moods, typography moods
• databases/styles.csv -- 25 UI styles with keywords, best-for, performance/accessibility ratings
• databases/colors.csv -- 30 color palettes with primary/secondary/accent/background/text hex values
• databases/typography.csv -- 25 font pairings with heading/body pair, mood, best-for, Google Fonts URL
• databases/landing-pages.csv -- 15 landing page patterns with sections and CTA strategies
• databases/ui-reasoning.csv -- 5 condition-action rules mapping product type to design implications

Workflow:

1. Requirement anchor -- Establish per Phase 1 above (after the Phase 0 manifest-first lookup)
2. Intent-first questioning -- "Who is this human? What must they accomplish? What should this feel like?" Plus product domain exploration:
   • 5+ domain concepts from the product's physical world (e.g., dental: clinical precision, porcelain, enamel, water, light)
   • 5+ colors from the product's physical world (not from a generic palette)
   • One signature element that will make this design non-generic
   • 3 defaults to explicitly reject (what this design will NOT be)
   • Do NOT proceed until all four exploration outputs exist
3. Design system generation -- Draw from databases for industry-matched style, palette, font pairing, and landing page pattern. Apply Refactoring UI concrete scales (spacing: 4-128px, type: 12-72px, HSL color with saturation curves). Structure tokens in 3-tier taxonomy (global > alias > component). Embed spec-aligned invariants from references/spec-website-design-invariants.md: contrast, visible focus, touch target, reduced motion, line length/line height, color-scheme, native interaction semantics, privacy-aware measurement, and locale/i18n metadata. Use references/hierarchy.md, references/layout-spacing.md, references/typography.md, references/color.md, references/depth-and-polish.md, and references/modern-css-primitives.md
4. Anti-slop validation -- Check output against references/ai-tells.md. See Anti-Slop Validation section below. If ANY banned pattern is present, replace before proceeding
5. Tactical refinement -- Apply Refactoring UI rules. See Tactical Refinement section below
6. Quality review -- Run all diagnostic lenses as interpreted advisory checks. See Quality Review section below

Output: DESIGN.md (9-section) + design-tokens.json, conforming to design-system-contract@1.

Checklist: Follow checklists/design-checklist.md step-by-step.

Mode B: Audit (/design-audit)

Purpose: Review an existing design against anti-slop rules, tactical refinement rules, and quality-review lenses. Steps 4-6 of the Create workflow.

Load these references:

• references/ai-tells.md -- Banned patterns
• references/creative-arsenal.md -- Non-generic alternatives
• references/quality-gates.md -- Advisory diagnostic lenses
• references/hierarchy.md -- Hierarchy strategies
• references/typography.md -- Type scale and font selection
• references/color.md -- HSL palette and contrast
• references/spec-website-design-invariants.md -- Do not propagate source-site accessibility, motion, privacy, or i18n failures

Workflow:

1. Requirement anchor -- Establish per Phase 1 above (after the Phase 0 manifest-first lookup; scoped to audit: what is the existing design? what prompted the audit?)
2. Anti-slop validation -- Check existing design against references/ai-tells.md
3. Tactical refinement -- Evaluate spacing, hierarchy, color, typography against Refactoring UI rules
4. Quality review -- Run all diagnostic lenses as interpreted advisory checks
5. Produce findings -- Evidence-attached findings ordered by severity (V3 first)

Output: Structured audit report with evidence-attached findings, severity ratings, and prioritized recommendations.

Checklist: Follow checklists/audit-checklist.md step-by-step.

Mode C: Extract (/tokenize)

Purpose: Extract design tokens from existing code, CSS, or a live site into DESIGN.md format.

Load these references:

• references/quality-gates.md -- Review extracted tokens with advisory diagnostic lenses
• references/spec-website-design-invariants.md -- Source-site failures to flag instead of preserving
• references/modern-css-primitives.md -- Platform primitives that may affect extracted responsive, motion, and performance tokens

Workflow:

1. Requirement anchor -- Establish per Phase 1 above (after the Phase 0 manifest-first lookup; scoped to extraction: what is the source? what fidelity level is needed?)
2. Source analysis -- Read the source site's CSS, computed styles, or code. Extract every color, font, spacing value, shadow, border-radius
3. Token structuring -- Organize extracted values into 3-tier taxonomy (global > alias > component). Remove duplicates. Identify the spacing scale, type scale, color palette, focus-ring treatment, tap-target minimum, motion duration scale, reduced-motion fallback, supported color schemes, contrast matrix, and layout/performance primitive notes
4. Validation -- Run quality-review lenses on extracted tokens. Identify gaps (missing semantic colors, incomplete spacing scale, etc.)
5. Produce output -- DESIGN.md (9-section) + design-tokens.json from extracted values

Output: DESIGN.md + design-tokens.json reflecting the source site's actual design, conforming to design-system-contract@1.

Checklist: Follow checklists/tokenize-checklist.md step-by-step.

---

Commands

Command	Checklist	Mode	Description
/design	checklists/design-checklist.md	Create	Full 6-step workflow: anchor, explore, generate, validate, refine, review
/design-audit	checklists/audit-checklist.md	Audit	Review existing design: anti-slop + tactical rules + quality-review lenses
/fix-hierarchy	checklists/fix-hierarchy-checklist.md	Audit	Targeted: apply visual hierarchy tactics to existing design
/fix-typography	checklists/fix-typography-checklist.md	Audit	Targeted: apply type scale, line-height, font selection fixes
/fix-colors	checklists/fix-colors-checklist.md	Audit	Targeted: apply HSL palette, contrast, hue rotation fixes
/fix-layout	checklists/fix-layout-checklist.md	Audit	Targeted: apply spacing system, grid, density fixes
/tokenize	checklists/tokenize-checklist.md	Extract	Extract design tokens from existing code/site into DESIGN.md

---

Anti-Slop Validation

Every design output must be checked against these banned patterns before proceeding. If any are present, replace them with a non-generic alternative from references/creative-arsenal.md.

Banned Fonts

Inter, Roboto, Arial, Space Grotesk. These are the four fonts that signal "AI-generated default." If the database recommends one of these, override with a distinctive alternative from databases/typography.csv.

Banned Aesthetics

• AI purple/pink gradients (the #8B5CF6 to #EC4899 corridor)
• Neon glows or glow effects on text or buttons
• Pure #000000 for text or backgrounds (use near-black with a hue tint instead)
• Glassmorphism blur effects used as the primary design technique
• Generic dark mode with purple accents

Banned Content

• Lorem Ipsum or any placeholder text in output
• "Elevate", "Seamless", "Leverage", "Cutting-edge", "Revolutionary" in any design system description
• "Acme Corp", "John Doe", "Jane Smith" as placeholder names
• Stock photo descriptions as design requirements

Banned Layouts

• Centered hero section when content variance is high (different page types need different heroes)
• Generic 3-column card grid as the default content layout
• Identical card heights enforced by CSS when content length varies naturally
• Full-bleed gradient backgrounds on every section

If any banned pattern is detected, treat it as an advisory finding with evidence. Replace the offending element with a specific, defensible alternative before presenting the design, or explicitly document why the apparent pattern is intentional and appropriate for this project.

---

Tactical Refinement

Apply these concrete rules from Refactoring UI during step 5. Use references/hierarchy.md, references/layout-spacing.md, references/typography.md, references/color.md, references/depth-and-polish.md as the detailed reference.

Hierarchy

• Grayscale-first: Solve layout and spacing in grayscale before adding color. If the hierarchy is unclear in grayscale, color will not fix it.
• Weight and color, not size: Establish hierarchy through font weight and text color rather than increasing font size. De-emphasize competing elements rather than making the target louder.
• Two or three font sizes maximum per section. If you need more, the content structure is wrong, not the type scale.

Color

• HSL model: Define all colors in HSL. Rotate hue for natural shading: cool (blue-shifted) for dark shades, warm (yellow/orange-shifted) for light tints.
• Saturation curves: Lightest tints have lowest saturation. Darkest shades have lower saturation than mid-tones. Peak saturation is in the mid-range.
• Grey is not grey: Every grey should have a slight hue tint matching the brand palette. Pure neutral grey looks dead.

Shadows

• Two-part shadow system: Ambient shadow (large, soft, low opacity) + occlusion shadow (small, tight, slightly darker). Never use a single box-shadow for elevation.
• Cool-tinted shadows: Shadows should be slightly blue-tinted, not pure black/grey, for a natural light appearance.

Spacing

• Spacing scale from base unit: All spacing derives from a base unit (4px or 8px). No arbitrary pixel values.
• Generous whitespace: When in doubt, add more space. Cramped layouts feel cheap; generous layouts feel premium.

Buttons

• Semantic button hierarchy: Primary (filled, high contrast) > Secondary (outlined or ghost) > Tertiary (text-only link style). Every page should have at most one primary button per viewport.

---

Quality Review

Run all diagnostic lenses (see below) plus the priority checklist before presenting the design system. These are interpreted advisory review instruments: they surface evidence and tradeoffs for AI/human judgment, but they do not autonomously decide status, delivery, or acceptance.

Priority Checklist (in order)

1. Accessibility -- WCAG AA contrast on all text? Touch targets >= 44x44px? Focus states visible?
2. Touch -- Primary actions reachable with one thumb on mobile?
3. Performance -- Are font files under 100KB total? Are color values CSS-native (no runtime computation)? Are off-screen heavy sections candidates for content-visibility + contain-intrinsic-size, containment, or native lazy loading without harming anchors, find-in-page, or LCP?
4. Style -- Does the design pass the Swap, Squint, and Signature tests?
5. Layout -- Does the spacing scale hold at all breakpoints?
6. Typography -- Does the type scale produce readable body text at mobile sizes? Are body line length and line-height specified for prose and dense UI contexts?
7. Animation -- Are transitions under 300ms for interactive feedback? Does every decorative, scroll-linked, View Transition, or parallax effect have a prefers-reduced-motion fallback?
8. Forms -- Are input states (default, focus, error, disabled) all defined?
9. Navigation -- Is the nav pattern appropriate for the page count?
10. Charts/Data -- (Only if relevant) Are data visualization colors distinguishable?
11. Privacy -- Are analytics and third-party script assumptions privacy-respecting, consent-aware, and minimal?
12. Internationalisation -- Are lang, direction, locale-aware metadata, text wrapping, and language-switcher expectations noted where relevant?
13. Native interaction -- Does the design prefer semantic/native primitives (button, a, details, dialog, Popover API) before custom click handlers and ARIA-heavy widgets?

Validation Against design-system-contract@1

Before presenting the artifact, review the output against all structural (S1-S4), content (C1-C10), and cross-artifact (X1-X5) rules defined in design-system-contract@1 (see ${CLAUDE_SKILL_DIR}/references/design-system-contract.md). If a rule is incomplete, attach evidence, explain the impact, and recommend the fix.

---

Output Constraint: Evidence-Attached Findings

Every finding in the output MUST include all four fields:

• What: The specific pattern, issue, or element detected
• Where: The file path, URL, component, or section where it occurs
• Why: How it fails a diagnostic test, violates a requirement anchor item, or causes measurable harm
• What Instead: The specific alternative, fix, or replacement with enough detail to implement

Findings missing any of these four fields are incomplete and must not appear in the output. A finding without a "Where" is a guess. A finding without a "What Instead" is a complaint, not a recommendation.

Example

• What: The heading font (Source Sans 3) is used identically to the body font (Work Sans) -- same weight, similar size, no contrast
• Where: Homepage hero section, <h1> element
• Why: Fails the Squint Test -- when squinted, headings and body text are indistinguishable, destroying visual hierarchy
• What Instead: Increase heading weight to 700, increase size ratio to 1.5x body, or use a display variant of Source Sans 3

---

Diagnostic Lenses

Apply these named tests during design creation, audit, and review. Each test has a binary or near-binary answer. Name the test explicitly in your findings.

1. The Swap Test: "If I replaced this typeface with the most common alternative, would the design feel different?" If swapping Source Sans 3 for Inter changes nothing, the typography carries no brand weight. The font choice is decorative filler, not a design decision.

2. The Squint Test: "If I blur my eyes, can I still identify the visual hierarchy?" If headings, body, and secondary text blur into a uniform grey mass, the hierarchy is weak. Weight, size, and color contrasts must survive squinting.

3. The Signature Test: "Could you identify which brand this belongs to with the logo removed?" If removing the logo makes the design indistinguishable from a template, the design is generic. Point to 5 specific components where the signature element appears.

4. The Token Test: "Read the CSS variable names aloud -- do they sound like they belong to THIS product?" If the token names are generic (--color-1, --font-large), the design system is not semantically grounded. Token names should evoke the product domain.

5. The Stripe Test: "Would this look out of place sitting next to Stripe's marketing site?" This is not about copying Stripe. It is about matching the level of intentionality, polish, and detail. If the design has rough edges that Stripe would never ship, those edges need attention.

When citing a lens in a finding, use the format: "Fails the [Name] Test -- [specific evidence of failure]."

---

Severity Scale

Use this severity scale for all findings:

Level	Name	Criterion	Action
V0	Cosmetic	Unnecessary but harmless; no maintenance or downstream impact	Note and move on
V1	Local	Has a cost (visual quality, brand impression) but stays contained to one element	Flag for fixing
V2	Structural	Shapes the design system around itself; affects multiple components	Flag for redesign
V3	Contagious	Forces OTHER components, pages, or tokens to be worse	Flag as urgent

V3 is not reserved for the "biggest" issues. It is reserved for issues that SPREAD. A button color that is slightly off-brand is V1. A generic color palette that forces generic typography because "nothing else matches the bland blue" is V3 -- the palette's weakness infects every other design decision.

When assigning severity, always ask: "Does this issue force anything else to be worse?" If yes, it is V3 regardless of its own magnitude.

---

Scale Anchoring

Design Distinctiveness Lens

Design Distinctiveness is an interpreted lens, not a verdict. Most brochure sites should feel clearly branded without becoming experimental. Generic template territory means the design carries no brand identity; avant-garde territory may alienate conservative audiences (dental practices, law firms, medical clinics). For professional service sites, explain whether the design reads as clearly branded, under-distinct, or over-polarizing, and cite the concrete visual evidence.

Anti-Slop Lens

Anti-Slop is an interpreted lens over detected banned patterns (fonts, aesthetics, content, layouts). Report the concrete patterns found, distinguish minor intentional overrides from generic defaults, and recommend the smallest design change that restores project-specific intent. Do not convert the pattern count into a quality score or autonomous verdict.

Contract Compliance Review

Contract Compliance: interpret each S1-S4 structural rule, C1-C10 content rule, and X1-X5 cross-artifact rule from design-system-contract@1 as an evidence checklist. Report complete, incomplete, and intentionally-deferred items with a written interpretation and recommended fix. Do not collapse the review into a pass/fail score, and do not use it as an autonomous delivery or status gate.

---

Locale Awareness

Before generating any design system, identify the target locale. Typography and layout rules vary by language.

Typography Adjustments by Locale

Language	Consideration
Dutch (nl)	Long compound words (e.g., "tandvleeschirurgie", "mondhygienisten"). Set hyphens: auto; overflow-wrap: break-word. Allow 10-15% wider columns than English defaults. Test hero text with longest expected word to verify it does not overflow.
German (de)	Even longer compounds than Dutch (e.g., "Rechtsschutzversicherung"). Same mitigations plus consider word-break: break-word for mobile viewports. Wider column defaults than Dutch.
English (en)	Standard column widths. No special compound-word handling needed.

These adjustments affect Section 5 (Layout) and Section 9 (Agent Prompt Guide) of DESIGN.md. They do not change token values -- they inform how agents apply them.

Locale-Aware Content Patterns

Component stylings for forms and navigation may note locale-specific patterns:

• Dutch phone number format: +31 XX XXX XX XX
• Dutch address format: postcode before city (e.g., 6211 NE Maastricht)
• German formal address conventions: Herr/Frau, Straße format

These belong in DESIGN.md Section 4 as component notes when relevant to the project.

If locale is ambiguous, STOP at the Requirement Anchor and ask. Never silently default to English for Dutch or German brand work.

(See also: the Language Handling section below for runtime output-language policy — Unicode preservation, frontmatter conventions, DESIGN.md prose vs CSS-variable naming, example-prompt language. Locale Awareness is about typography-and-layout adjustments for the language being designed for; Language Handling is about which language Claude responds in while designing.)

---

Reference Loading Instructions

For Create Mode

Step	Reference File	What to Extract
Domain exploration	references/creative-arsenal.md	Non-generic alternatives for each design dimension
Hierarchy	references/hierarchy.md	6 visual hierarchy strategies
Layout and spacing	references/layout-spacing.md	Spacing systems, whitespace rules, responsive density
Typography	references/typography.md	Type scale, font selection, line-height, alignment
Color	references/color.md	HSL model, grey shades, saturation falloff, hue rotation, WCAG contrast
Depth and polish	references/depth-and-polish.md	Light source, elevation, two-part shadows, accent borders
Spec invariants	references/spec-website-design-invariants.md	Design-side obligations from specification.website accessibility, performance, privacy, and i18n topics
Platform primitives	references/modern-css-primitives.md	Popover, View Transitions, scroll-driven animation, containment, viewport, and gutter primitives
Anti-slop	references/ai-tells.md	Banned patterns list
Quality review	references/quality-gates.md	Swap, Squint, Signature, Token test procedures used as advisory lenses

Databases (Create Mode)

Database	What to Look Up
databases/products.csv	Product type match, recommended patterns, styles, color moods
databases/styles.csv	UI style match by keywords, performance/accessibility ratings
databases/colors.csv	Color palette recommendation mapped to product type
databases/typography.csv	Font pairing by mood, best-for, Google Fonts availability
databases/landing-pages.csv	Landing page pattern with section order and CTA strategy
databases/ui-reasoning.csv	Condition-action rules: product type -> all design dimensions

Templates

Template	When to Use
templates/design-system-template.md	Starting template for DESIGN.md 9-section structure
templates/design-tokens-template.json	Starting template for design-tokens.json schema

Spec.website Snapshot

As of 2026-06-12, specification.website describes 137 topics across 10 categories. site-designer does not audit every topic, but it must carry the design-side obligations that downstream implementation depends on: accessibility, performance, privacy, internationalisation, resilience-friendly progressive enhancement, and native web platform primitives. Do not use older topic-count wording.

Language Profiles

Profile	When to Load
profiles/en.json	English-language projects
profiles/de.json	German-language projects
profiles/nl.json	Dutch-language projects (AccentTandartsen, AVG context)

---

Output Format: DESIGN.md + design-tokens.json

When in Create or Extract mode, produce two artifacts conforming to design-system-contract@1 (see ${CLAUDE_SKILL_DIR}/references/design-system-contract.md for the full contract):

DESIGN.md (9-section Google Stitch standard)

Section	Content
1. Visual Theme & Atmosphere	Mood, key characteristics, signature element, font stack summary, shadow philosophy
2. Color Palette & Roles	Primary, interactive, neutral, semantic, surface, shadow colors (>= 12 entries)
3. Typography Rules	Font families, OpenType features, type scale table (>= 5 rows), weight philosophy, tracking
4. Component Stylings	Buttons, cards, navigation, inputs (minimum). Optional: links, badges, carousels, flip-cards
5. Layout Principles	Base unit, spacing scale, max content width, grid system, section spacing, whitespace philosophy
6. Depth & Elevation	Elevation table (>= 3 levels with CSS box-shadow), shadow philosophy, border-radius scale
7. Do's and Don'ts	>= 5 Do's, >= 5 Don'ts, each falsifiable and referencing specific values
8. Responsive Behavior	Breakpoints (>= 3), typography scaling, grid collapsing, touch targets, mobile adaptations
9. Agent Prompt Guide	Quick color reference, >= 2 example prompts with specific values, locale notes if applicable

Write Location (project-workspace-contract@2)

Both artifacts live in the design/ Kind-3 zone at the project root, located and indexed via MANIFEST.md (per project-workspace-contract@2; site-designer is the design/-zone producer, kind: spec):

• Single-instance projects (--type=content / --type=build single design): write design/default/DESIGN.md + design/default/design-tokens.json — default is the single-instance instance name under the canonical design/<instance>/ grammar (matches conversion-designer's conversion/<instance>/, funnel-strategist's funnel/<instance>/, and site-builder's design/<instance>/ consumer prose per contract §5).
• Multi-instance projects (--type=campaign / multi-design --type=build): write design/<instance>/DESIGN.md + design/<instance>/design-tokens.json, where <instance> is the design instance slug.
• Never write to project-root-flat or under workspace/ (opaque AI scratch, never a deliverable destination under v2).

After writing, update MANIFEST.md: add or refresh the design[/<instance>] entry with kind: spec, produced_by: site-designer, the new path:, last_updated:, and status: (translate the artifact's own frontmatter status: to the manifest-entry routing vocabulary per the contract's R61 table — e.g., greenlit → approved, draft → draft). The design/ entry's upstream: references any consumed inputs (e.g., a brand/<brand>/ canonical or a notes/ brief); consumed_by: lists downstream consumers (site-builder, conversion-designer).

If the project has no MANIFEST.md at its root, stop before writing. Surface that the project is not v2-initialized and ask the orchestrator/human to run the project-local bootstrap routine so the design/ zone and routing index exist before site-designer produces artifacts.

DESIGN.md is the source of truth. design-tokens.json is derived from it and must never contain values absent from DESIGN.md.

design-tokens.json also carries semantic compliance tokens derived from DESIGN.md: focus ring, tap target, motion duration/reduced-motion fallback, typography measure, color-scheme, contrast matrix, native interaction guidance, privacy default, and i18n metadata notes. These values guide site-builder and reviewers as interpreted instruments; they do not autonomously approve delivery or set artifact status.

Ownership Boundary

site-designer owns design specification. site-builder owns implementation. site-designer MUST NOT produce framework code (no .svelte, .astro, .tsx files). It produces DESIGN.md and design-tokens.json. site-builder converts those into Tailwind @theme blocks and component code.

---

What This Skill Does NOT Do

• Does not produce framework code. No .svelte, .astro, .tsx, or CSS files. That is site-builder's job.
• Does not implement components. It specifies component styling (Section 4 of DESIGN.md). site-builder implements.
• Does not optimize for conversion. Conversion strategy is owned by conversion-designer. site-designer provides the visual language; conversion-designer decides what to say and where.
• Does not create content. No copywriting, no placeholder text, no "About Us" paragraphs. Content strategy is a separate concern.
• Does not run performance audits. It specifies performance-conscious constraints (font budgets, CSS-native values) but does not run Lighthouse or measure load times.

---

End-of-run (R26 — conditional)

Standard runs (mode determined, requirement anchor honored, references and databases loaded, anti-slop findings resolved or interpreted, quality review completed, DESIGN.md + design-tokens.json delivered conforming to design-system-contract@1) end normally — no self-improvement prompt fires.

The prompt fires only on designer-specific deviation. Triggers and prompt shapes:

• User had an existing design system to honor (Figma, Tailwind config, brand book) → "You had <source> as a brand constraint and I generated against it rather than from the databases. Should Mode C (Extract / /tokenize) add a brand-book ingestion path, or was this case-specific?"
• Color tokens needed semantic restructuring beyond the standard 3-tier taxonomy → "The brand needed <extra-tier> (e.g., per-product-line, per-channel) beyond global > alias > component. Should templates/design-tokens-template.json add a 4-tier variant, or is this brand-specific?"
• Animation / motion specs differed from the depth-and-polish defaults → "The brand wanted <motion-pattern> (e.g., spring physics, scroll-linked, reduced motion as default). Should Section 8 motion guidance or the compliance motion tokens be extended, or is this brand-specific?"
• User overrode the recommended typography scale → "The database recommended <pairing> and you overrode to <other>. Should databases/typography.csv add this product-type case, or was the override judgment-driven?"
• DESIGN.md output structure didn't fit site-builder's expectation → "site-builder consumed <section> differently than I emitted it. Should design-system-contract@1 be revised to formalize the consumer-side expectation, or did site-builder need to adapt?"
• Anti-slop banned-pattern false positive → "The output flagged <pattern> as banned but it was a justified design choice for <reason>. Should references/ai-tells.md add a 'when this is OK' clause for this pattern, or is the strict ban correct?"
• Locale Awareness needed adjustments beyond Dutch/German/English → "The project was in <language> and I had to extrapolate from the existing locale notes. Should the Locale Awareness section / language profile be added for <language>, or was extrapolation acceptable?"

If a trigger fires, surface the specific deviation in context-specific prose (not generic "any feedback?"). If the user confirms, update SKILL.md (or the relevant reference / database / template) inline before going idle. If the user declines, optionally note the suggestion in the project's notes/ or CLAUDE.md.

Standard runs end at DESIGN.md-delivered. No prompt fires for uneventful design runs.

---

Language Handling

• Detect the conversation language; respond in the user's language unless explicitly asked otherwise.
• If MANIFEST.md declares an output_language: field, honor that declaration over inferred conversation language.
• Translate internal checklist labels and headings naturally — do not force English headings into non-English output.
• Preserve legal, financial, and technical terms in their original language (Trennungsjahr, MwSt, BTW, Aufhebungsvertrag, etc.).
• Preserve Unicode characters natively (ü, ö, ä, ß, etc.); never substitute transliterations (ue, oe, ae, ss).
• Frontmatter field names and enum values stay English regardless of content language. Free-text frontmatter values may follow content language where natural.
• DESIGN.md prose (Sections 1, 7, 9 narrative content) follows the project's content language by default; CSS variable names, token IDs, and JSON keys in design-tokens.json stay English.
• Example prompts in DESIGN.md Section 9 should be written in the language a designer / developer on this project will actually use when prompting an agent — usually the project's working language, not always English.

(See also: the Locale Awareness section above for typography-and-layout adjustments per language — long compound words, column widths, hyphenation. Language Handling is about which language Claude responds in; Locale Awareness is about how the design accommodates the language being designed for.)