design-style

name	design-style
description	Define visual directions (stylescapes), generate fully styled standalone pages, source assets, and produce presentation artifacts for client review. Triggers on 'style this', 'create visual direction', 'build stylescape', 'define the look and feel'.
allowed-tools	["Read","Write","Bash","Glob","Grep","Edit","Agent","WebFetch","WebSearch","AskUserQuestion","Skill"]

Design Style Skill

Transform locked wireframe screens into 3 distinct visual directions by generating fully self-contained styled HTML pages. Each styled page is built from scratch with all CSS inlined — real backgrounds, shadows, gradients, card treatments, and visual hierarchy. Do NOT simply copy wireframe HTML and swap CSS variables — that produces wireframes-with-different-colors, not actual designs.

1. Pre-flight

Read the following files in parallel to gather context:

• {project}/state.json — confirm wireframe phase is complete or screens are locked
• {project}/wireframe/*.html — understand what screens exist and which ds- components they use
• {project}/decomposition.json — project name, audience, domain
• {project}/references.json — any style references the designer provided
• references/token-override-guide.md — how to create shade cards and remap semantic tokens
• references/stylescape-layouts.md — the two presentation layout templates
• references/direction-schema.md — JSON schemas for directions.json and tokens-update.json

If wireframe screens are not locked, warn: "No locked wireframe screens found. Run /design-wireframe first, or confirm which screens to style." Stop if no screens exist.

Create the output directory: {project}/style/.

2. Gather Visual References FIRST

Before generating ANY directions, ask:

Do you have a reference design, app, or website whose visual style you like? Share a URL, screenshot, or Figma link.

This dramatically improves the quality of directions — I'll extract the color palette, typography feel, spacing density, and overall vibe from your reference.

If the designer provides a reference:

1. Capture it via Playwright (browser_navigate + browser_take_screenshot) or read the screenshot.
2. Analyze: dominant colors, typography style, spacing density, card treatments, shadow depth, corner radius, image treatment, illustration style.
3. Use this as the baseline for one of the 3 directions (mark it as "★ Based on your reference").
4. The other 2 directions should explore meaningfully different visual territories.

If no reference is provided, proceed — but note that directions based on references have a much higher approval rate.

3. Vibe Definition (3 Directions)

Walk through defining 3 visual directions. For each direction, work through every ingredient with the designer.

3a. Visual Keywords

Ask: "Pick 3-5 words that describe this direction. Examples: premium, playful, minimal, bold, warm, cool, editorial, friendly, futuristic, organic, corporate, artisan."

Store as the keywords array.

3b. Typography

Recommend 2-3 Google Fonts pairings per direction. Present each pairing with:

• Heading font name, style (serif/sans/display), and why it fits the keywords
• Body font name and why it pairs well
• The full googleFontsUrl

Example: "For 'Sleek Luxe', I recommend Playfair Display (heading, serif — elegant editorial feel) + Inter (body, sans — clean readability). Alternative: DM Serif Display + Satoshi."

Ask the designer to confirm or request alternatives.

3c. Color

Define the color philosophy, then generate a primary shade card (11 shades from 50-950). Follow the lightness targets in token-override-guide.md.

Present the shade card as a visual list with hex values. Ask: "This {color} palette feels right for {keyword}. Want warmer, cooler, more saturated, or more muted?"

If the direction needs a secondary accent, generate a second shade card.

Then build the full semantic overrides mapping using the template from token-override-guide.md. Choose the right shade-to-token mapping based on whether the brand is dark, vibrant, or light.

3d. Corner Radius

Present three strategies with specific pixel values from token-override-guide.md:

• Sharp — fintech, editorial, minimal (xs: 0px, sm: 2px, md: 4px, lg: 6px, xl: 8px)
• Rounded — friendly, consumer (keep base system defaults)
• Pill — playful, bubbly (xs: 8px, sm: 16px, md: 24px, lg: 32px, xl: 48px)

Ask which strategy fits this direction.

3e. Icon Library

Recommend a library and variant based on the keywords:

• Lucide (default stroke) — clean, minimal, versatile
• Phosphor (regular/bold/fill) — friendly, has more variants
• Tabler (outline) — developer-focused, comprehensive
• Heroicons (outline/solid) — Tailwind ecosystem, polished
• Remix (line/fill) — extensive, good for complex UIs

Provide the CDN URL. Ask the designer to browse the library and confirm.

3f. Illustration and Image Style

Ask: "Which illustration style? flat 2D / 3D / line art / hand-drawn / isometric" Ask: "Image treatment? full bleed / rounded corners / masked / overlaid / duotone" Ask: "Spacing density? compact / comfortable / spacious"

3g. Store the Direction

After all ingredients are confirmed, write the direction object to {project}/style/directions.json following the schema in direction-schema.md. Repeat for all 3 directions.

4. Screen Production

For EACH of the 3 directions, generate ALL locked wireframe screens as fully self-contained styled HTML pages.

Create directory: {project}/style/direction-{n}/

DO NOT copy wireframe HTML and inject CSS overrides. That produces wireframes-with-different-colors, not real designs. Instead, for each screen:

1. Read the wireframe HTML to understand the page structure, sections, data fields, and component layout.
2. Read the direction's ingredients (typography, colors, radius, icon library, image style).
3. Build a completely new HTML file with:
   • All CSS inlined in a <style> block — no external design-system.css dependency
   • Real backgrounds, gradients, shadows, card treatments, and visual hierarchy
   • The direction's Google Fonts loaded via <link>
   • The direction's icon library loaded via CDN
   • Proper spacing, section dividers, and visual rhythm
   • ALL sections from the wireframe — do not omit any. If the wireframe has 15 sections, the styled page has 15 sections.
4. Use domain-relevant images from Unsplash — NEVER use picsum.photos or random placeholder images:
   • Search Unsplash with terms specific to the product domain (e.g., for furniture: "wooden furniture", "modern sofa", "craft workshop")
   • Use https://images.unsplash.com/photo-{id}?w=800&h=600&fit=crop format for sized images
   • Or invoke /design-assets via the Skill tool for AI-generated illustrations matching the direction
5. Save to style/direction-{n}/{page-name}.html.

Verify each styled screen opens correctly in a browser.

5. Stylescape Generation

For each direction, generate a stylescape HTML presentation.

Ask: "Which layout for the stylescapes? A) Horizontal strip — structured, slide-ready. B) Bento grid — modern, dynamic. I recommend {recommendation} for this project."

Default recommendation: Bento grid for consumer apps, Horizontal strip for enterprise/B2B.

Follow the chosen layout template from stylescape-layouts.md. Include:

1. Direction name and keywords — header tile or slide title
2. Typography specimen — "Aa" in heading font, weight samples (Regular/Medium/Bold), full alphabet in body font
3. Color swatches — all 11 shades as colored rectangles with hex labels
4. Icon samples — 8-12 icons from the chosen library rendered via CDN
5. Styled component strip — ds-button, ds-chip, ds-badge, ds-input with token overrides applied
6. Screen thumbnails — 2-3 styled screens wrapped in device frames from design-tools/device-frames/
7. Illustration sample — one image matching the illustration style

Save to {project}/style/direction-{n}/stylescape.html.

Ensure the stylescape is fully self-contained: inline the token override <style> block, link to design-system.css (relative path), and include the Google Fonts and icon CDN links.

6. Client Review and Lock-in

Present all 3 directions:

"Here are your 3 visual directions:

• Direction 1: {name} — {keywords}
• Direction 2: {name} — {keywords}
• Direction 3: {name} — {keywords}

Open each stylescape in the browser to compare:

• open {project}/style/direction-1/stylescape.html
• open {project}/style/direction-2/stylescape.html
• open {project}/style/direction-3/stylescape.html"

Ask: "Which direction should we go with? Pick one, or describe a 4th direction combining elements from multiple."

If a combination is requested:

• Create direction-4 with mixed ingredients from the specified directions
• Run screen production and stylescape generation for direction-4
• Present for final approval

Once confirmed:

• Set selectedDirection in directions.json to the chosen direction ID
• Copy the selected direction's screens to {project}/style/final/
• Generate {project}/style/tokens-update.json with the exact token changeset, following the schema in direction-schema.md

7. Cohesion Pass (Mandatory)

After the direction is locked and all screens are in style/final/, perform a mandatory cohesion pass across all pages:

1. Read every HTML file in style/final/.
2. Audit and unify:
   • Section dividers — consistent spacing, border-style, or background transitions between sections
   • Card styles — same shadow depth, border-radius, padding, and background across all card variants
   • Typography scale — consistent heading sizes, line heights, and font weights across pages
   • Button styles — same padding, radius, font-size, hover states everywhere
   • Spacing — unified section padding, card gaps, content margins
   • Border colors — single consistent border color throughout
   • Color usage — brand color applied consistently for CTAs, links, active states
3. Fix any inconsistencies found. Write the updated files.
4. Report: "Cohesion pass complete — fixed {N} inconsistencies across {M} pages."

This step is mandatory because building pages individually always introduces subtle inconsistencies in spacing, shadows, borders, and typography that accumulate.

Announce: "Locked in '{direction name}'. Final styled screens are in style/final/. Token changes are in tokens-update.json."

8. State Update

Update {project}/state.json:

• Set phases.style.status to "complete"
• Set phases.style.selectedDirection to the direction name
• Set phases.style.completedAt to the current ISO timestamp

Print a summary:

• Direction name and keywords
• Typography pairing
• Primary color (base hex)
• Radius strategy
• Icon library
• Number of styled screens
• Path to tokens-update.json