# Web Design Engineer Skill **An AI agent skill that transforms AI-generated web pages from "functional" to "stunning."** [中文文档](./README.zh-CN.md) · [Back to collection root](../../README.md) ![Web Design Skill](https://cdn.jsdelivr.net/gh/ConardLi/assets@main/imgs/web-design-skill.webp) --- ## What Is This? This is a reusable **Skill** (structured system prompt) for AI coding agents — such as [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com), and other tools that support the `SKILL.md` format — that dramatically improves the design quality of AI-generated HTML/CSS/JavaScript artifacts. It distills the core design philosophy from [Claude Design](https://www.anthropic.com/news/claude-design-anthropic-labs)'s system prompt into an open, portable, and customizable skill file that you can drop into any project. ### The Problem Modern LLMs can already produce functional web pages from simple prompts. But their output tends to converge on the same aesthetic: Inter font, blue primary buttons, purple-pink gradients, large-radius cards, emoji as icons, fabricated testimonials. Technically correct, visually generic. ### The Solution This skill injects **design taste** into the AI's decision-making process through: - **Anti-cliché rules** — an explicit blocklist of overused AI design patterns - **Design system declaration** — forces the AI to articulate color, typography, spacing, and motion choices *before writing code* - **oklch color theory** — perceptually uniform color derivation instead of random hex guessing - **Curated font & color pairings** — high-quality starting points that replace the default Inter + #3b82f6 - **Placeholder philosophy** — honest `[icon]` markers instead of poorly drawn SVG fakes - **Five-dial Design Read** — turns audience, artifact, brand, and constraints into visible variance / motion / density / asset / fidelity decisions - **Preservation-aware redesigns** — separates extension, preserve, and overhaul modes before touching an existing product - **Contextual failure patterns** — detects recurring layout, content, imagery, motion, and dashboard failures without turning taste into universal bans - **Structured workflow** — requirements → context → calibrated design system → v0 draft → full build → verification - **Opt-in browser acceptance** — executable responsive / interaction / runtime QA only when the user explicitly requests acceptance or browser testing --- ## Quick Start ### For Claude Code / Cursor / AI Agents Copy this skill folder into your project: ``` your-project/ ├── .agents/skills/web-design-engineer/ # or .claude/skills/web-design-engineer/ │ ├── SKILL.md # Main skill file │ ├── agents/openai.yaml # Host-facing display metadata and default prompt │ └── references/ │ ├── advanced-patterns.md # Code template library (slide engine, device frames, motion timelines, data viz) │ ├── block-library.md # Index of implemented reusable blocks │ ├── browser-acceptance.md # Explicit-request-only executable browser QA harness │ ├── design-calibration.md # Design Read + five dials + optional image-first branch │ ├── design-directions.md # Design Direction Advisor (6 schools, differentiated 3-pick recommendation) │ ├── failure-patterns.md # Contextual AI-design failure taxonomy and repairs │ ├── redesign-protocol.md # Extension / Preserve / Overhaul audit and protected contracts │ ├── style-recipes/ # 25 anchored style recipes — one .md file per anchor, loaded on demand │ │ ├── INDEX.md # Catalog index + 3 cross-indexes + cross-cutting anti-patterns │ │ ├── linear.md / aesop.md / pentagram.md / ... # 25 single-recipe files │ └── critique-guide.md # 5-dimension scoring rubric + common issues catalog └── ... ``` Or use the Claude Code plugin marketplace from the collection root — see the [top-level README](../../README.md#install). The agent will automatically pick up the skill when your request involves visual/interactive front-end work. ### What It Covers | Output Type | Examples | |---|---| | Web pages & landing pages | Marketing sites, product pages, portfolios | | Interactive prototypes | Clickable app mockups with device frames | | Slide decks | HTML presentations (1920×1080, keyboard nav) | | Data visualizations | Dashboards with Chart.js or D3.js | | Animations | CSS/JS motion design, timeline-driven demos | | Design systems | Token exploration, component variants | --- ## How It Works ### The Calibrated Workflow ``` 1. Understand requirements → Ask only when information is insufficient 2. Gather design context → Code > screenshots; classify existing-work mode 3. Produce a Design Read → Five dials connect the brief to visible decisions 4. Declare design system → Colors, fonts, spacing, motion — in Markdown, before code 5. Show v0 draft early → Placeholders + layout + tokens; let the user course-correct 6. Full build → Components, states, motion; pause at key decision points 7. Verify → Lightweight self-check; browser harness only on explicit request ``` ### Key Design Principles **Anti-AI-cliché checklist.** The skill explicitly bans: - Purple-pink-blue gradient backgrounds - Left-border accent cards - Inter / Roboto / Arial / Fraunces / system-ui fonts - Emoji as icon substitutes - Fabricated stats, fake logo walls, dummy testimonials **oklch color system.** Colors are derived in the perceptually uniform oklch space. Same lightness values actually *look* the same brightness to the human eye — unlike HSL, where yellow-at-50% looks much brighter than blue-at-50%. **Curated starting points.** Six pre-validated color × font pairings for common use cases: | Style | Color | Fonts | Use Case | |---|---|---|---| | Modern tech | Blue-violet | Space Grotesk + Inter | SaaS, dev tools | | Elegant editorial | Warm brown | Newsreader + Outfit | Content, blogs | | Premium brand | Near-black | Sora + Plus Jakarta Sans | Luxury, finance | | Lively consumer | Coral | Plus Jakarta Sans + Outfit | E-commerce, social | | Minimal professional | Teal-blue | Outfit + Space Grotesk | Dashboards, B2B | | Artisan warmth | Caramel | Caveat + Newsreader | Food, education | **Anchored style-recipe library (25 named recipes, progressively loaded).** When the user names an anchor ("Linear-style", "Aesop feeling", "Pentagram-grade type"), the agent reads **only the matching file** at `references/style-recipes/.md` (~50 lines). The catalog index, 3 cross-indexes, and cross-cutting anti-patterns live in `references/style-recipes/INDEX.md` (~150 lines). The full catalog is never loaded at once. The 25 recipes are spread across 7 schools (the 6 Direction-Advisor schools plus a *Specialty / Genre* school reachable only via direct anchor names): | School | Recipes | |---|---| | Editorial / Minimalist | `apple-hig` · `muji-kenya-hara` · `aesop` · `dieter-rams-braun` · `monocle-magazine` | | Information Architecture | `pentagram` · `vignelli-swiss-helvetica` · `bloomberg-terminal` · `tufte-dataink` · `nyt-the-daily` | | Modern Tool / Builder SaaS | `linear` · `vercel-mesh` · `raycast` · `notion-pre-ai` | | Motion / Experimental | `field-io` · `active-theory` · `resn-storytelling` | | Brutalist / Raw | `are-na` · `bloomberg-businessweek-turley` · `balenciaga-post-2017` | | Warm Humanist | `mailchimp-freddie` · `stripe-press` · `headspace-meditation` | | Specialty / Genre | `y2k-retrofuturism` · `mid-century-modern` | --- ## Style Recipe Gallery The skill ships **25 named recipes**, each tied to a real brand, studio, or designer. Every recipe has a working, full-page artefact in the demo gallery — not a shared template, not a thumbnail mood-board, but the form each recipe was actually designed for: an apothecary product page for Aesop, a trading workstation for Bloomberg Terminal, a Saul-Bass poster for Mid-Century, a Y2K portal for Retrofuturism. Browse by school below, pick the one whose vibe matches your brief, or read the spec file at `references/style-recipes/.md`. Click any preview to open the full-resolution 2:1 frame. > Frames are real artefacts rendered by the live React + Vite gallery at [`demo/web-design-engineer-demo`](../../demo/web-design-engineer-demo/) — same fonts, same palettes, same signature moves as the recipe spec. Each demo is in `src/recipes/.tsx`. ### Editorial / Minimalist · 5 recipes > Whitespace, refined typography, quiet luxury — the apothecary, the museum catalogue, the hardware product page.
apple-hig preview
apple-hig
SF Pro Display, generous whitespace, soft elevation — the Apple Store voice
Best for · hardware product pages · device launches · premium consumer tech 		muji-kenya-hara preview
muji-kenya-hara
Emptiness as canvas, ash & paper, every object photographed in air
Best for · object catalogues · houseware brands · slow-living storefronts
aesop preview
aesop
Warm chamois, sage & amber, serif copy that reads like a literary magazine
Best for · apothecary product pages · beauty & wellness · independent retailers 		dieter-rams-braun preview
dieter-rams-braun
Ten principles, monochrome grids, technical orthographics — function as form
Best for · industrial-design archives · hardware specs · brand-principle pages
monocle-magazine preview
monocle-magazine
Cosmopolitan briefings, navy & coral, footnoted curiosity
Best for · magazine contents · city & travel briefings · lifestyle journals
Best when the brief says
"refined" · "premium" · "quiet" · "editorial" · "less is more"

See specs in style-recipes/

### Information Architecture · 5 recipes > Rational, data-driven, restrained — wayfinding, terminals, footnoted essays, the newspaper of record.
pentagram preview
pentagram
One bold typeface used as artwork, grid as scaffold, ink + ground only
Best for · identity specimens · type-led portfolios · gallery announcements 		vignelli-swiss-helvetica preview
vignelli-swiss-helvetica
Helvetica at every size, six primary colours, the NYC Subway diagram
Best for · wayfinding & transit · public-info posters · brand-system specimens
bloomberg-terminal preview
bloomberg-terminal
Amber on navy-black, mono everywhere, density over comfort
Best for · trading dashboards · ops consoles · power-user dense tools 		tufte-dataink preview
tufte-dataink
Sparklines in body copy, small multiples, no chartjunk
Best for · data narratives · research write-ups · academic essays
nyt-the-daily preview
nyt-the-daily
Cheltenham over Imperial, dateline above all, the gravity of the broadsheet
Best for · news features · podcast hubs · long-form journalism
Best when the brief says
"data-heavy" · "wayfinding" · "dense" · "rational" · "of record"

See specs in style-recipes/

### Modern Tool / Builder SaaS · 4 recipes > Hairline detail, warm dark, single accent — the developer-tool aesthetic of the late 2020s.
linear preview
linear
Warm dark, hairline borders, purple flicks of accent, shortcut chips
Best for · dev-tool landing pages · issue / project SaaS · API & infra products 		vercel-mesh preview
vercel-mesh
Pure black, geometric mesh gradient, Geist Sans, command-line clarity
Best for · deploy / runtime tools · framework launches · technical hero pages
raycast preview
raycast
Glass card on red-tinted void, keyboard-first, condensed list cells
Best for · command palettes · launcher apps · keyboard-driven tooling 		notion-pre-ai preview
notion-pre-ai
Off-white pages, drag-handle dots, casual emoji headings, callouts everywhere
Best for · workspace docs · internal wikis · friendly productivity apps
### Motion / Experimental · 3 recipes > Bold, generative, sensory — when the brief asks for "cinematic", "WebGL", or "award-bait".
field-io preview
field-io
Particle systems behind editorial type, code-art aesthetic, dark studio
Best for · creative-tech studios · generative-art case studies · WebGL portfolios 		active-theory preview
active-theory
WebGL ambitions, full-bleed type, candy colours over deep black
Best for · cinematic product launches · campaign sites · award-bait microsites
resn-storytelling preview
resn-storytelling
Surreal, lush, every frame a tableau, headlines on textured noise
Best for · narrative scrolls · entertainment / IP sites · agency reels
Best when the brief says
"cinematic" · "WebGL" · "experiential" · "Awwwards-grade"

See specs in style-recipes/

### Brutalist / Raw · 3 recipes > Anti-design, honest, unpolished — the system-default web, tabloid covers, anti-luxury luxury.
are-na preview
are-na
System fonts on purpose, browser-default blue links, the honest web
Best for · research channels · indie communities · anti-design content tools 		bloomberg-businessweek-turley preview
bloomberg-businessweek-turley
Yellow caution + black ink, type as collage, hand-cut headlines
Best for · editorial covers · opinion pieces · campaign posters
balenciaga-post-2017 preview
balenciaga-post-2017
All caps, broken grids, deadpan product on white, anti-luxury luxury
Best for · fashion collections · drop announcements · contrarian luxury
Best when the brief says
"raw" · "honest" · "anti-design" · "tabloid" · "uncomfortable"

See specs in style-recipes/

### Warm Humanist · 3 recipes > Approachable, organic, hand-touched — small-business cheerleader, hand-bound book, daily reset.
mailchimp-freddie preview
mailchimp-freddie
Cavendish yellow, hand-drawn doodles, conversational copy, the SMB cheerleader
Best for · onboarding flows · SMB marketing tools · friendly consumer apps 		stripe-press preview
stripe-press
Cream paper, GT Super, hand-bound luxury, ideas as objects
Best for · book detail pages · long-form essays · publisher / press sites
headspace-meditation preview
headspace-meditation
Orange suns, rounded blobs, hand-illustrated calm, a daily reset
Best for · meditation & wellness · habit / mood apps · cosy consumer cards
Best when the brief says
"friendly" · "approachable" · "human" · "cosy" · "hand-touched"

See specs in style-recipes/

### Specialty / Genre · 2 recipes > Period-coded, decade-coded, theme-coded — only reachable by direct anchor name.
y2k-retrofuturism preview
y2k-retrofuturism
Chrome bevels, frosted glass, lava blobs, MSN-blue everywhere
Best for · Y2K nostalgia · early-web portals · gen-Z brand stunts 		mid-century-modern preview
mid-century-modern
Mustard, brick, cyan; cut-paper geometry; the optimism of 1957
Best for · poster homages · cultural events · vintage-print brand voice
### Run the gallery yourself ```bash cd demo/web-design-engineer-demo npm install && npm run dev # http://localhost:5181/ ``` Hash-routed URLs (`#/linear`, `#/aesop`, …) deep-link to any recipe. Press `H` to toggle the recipe HUD, `Esc` to return to the gallery. See the demo's own [README](../../demo/web-design-engineer-demo/README.md) for layout details. --- ## Before & after: skill on / off The repository's [`demo/web-design-demo/`](../../demo/web-design-demo) directory contains side-by-side comparisons of pages generated with and without this skill, using identical prompts. Open [`demo/web-design-demo/demo2/index.html`](../../demo/web-design-demo/demo2/index.html) for a side-by-side viewer. ### Demo 1: Space Exploration Museum **Prompt:** *"Build a homepage for a fictional 'Space Exploration Museum' — full-screen hero, 4 exhibition sections, a timeline with 6+ milestones, a booking CTA, and a footer. Deep, immersive, cosmic feel."* | | Without Skill | With Skill | |---|---|---| | **File** | `demo/web-design-demo/demo2/demo1.html` | `demo/web-design-demo/demo2/demo1-with-skill.html` | | **Color system** | Hardcoded hex values (#7cf0ff, #b388ff) | oklch-based token system with CSS custom properties | | **Typography** | Orbitron + Noto Serif SC | Instrument Serif + Space Grotesk + JetBrains Mono | | **Layout** | Standard landing-page structure | Editorial magazine-style layout with grid compositions | | **Details** | Heavy glow effects, neon gradients | Restrained palette, typographic hierarchy, decorative data elements | | **Overall feel** | Enthusiastic junior designer | Experienced design director | ### Demo 2: Photographer Portfolio **Prompt:** *"Build a homepage for an independent photographer's portfolio."* | | With Skill | |---|---| | **File** | `demo/web-design-demo/demo2/demo2-with-skill.html` | | **Character** | Creates a fictional Nordic photographer "Mira Høst" with a complete visual identity | | **Color** | Paper-warm light (#f2efe8) + ink-dark (#161513) — extremely restrained two-tone palette | | **Typography** | Instrument Serif (display) + Space Grotesk (UI) with extensive italic usage | | **Layout** | Magazine-editorial structure with numbered sections, asymmetric grids, side rails | | **Motion** | Slow Ken Burns on hero image (24s cycle), film-grain texture overlay | | **Navigation** | `mix-blend-mode: difference` masthead — seamless across light/dark sections | > The original Claude Design system prompt that inspired this skill is preserved at [`dist/prompt/claude-design-system-prompt.md`](../../dist/prompt/claude-design-system-prompt.md). --- ## Background This skill is inspired by the system prompt of [Claude Design](https://www.anthropic.com/news/claude-design-anthropic-labs), Anthropic's visual design product launched in April 2026. Claude Design's system prompt (~420 lines) encodes a sophisticated set of design principles, anti-patterns, and workflow constraints that make its output consistently high-quality. This project extracts and refines those core ideas into a portable skill that works with any AI coding agent — giving you Claude-Design-level design taste without the product lock-in or usage limits. Key additions beyond the original Claude Design prompt: - **Design system declaration step** — forces the AI to articulate design tokens in natural language before coding - **v0 draft strategy** — a concrete methodology for showing work-in-progress early - **Extended anti-cliché list** — additional patterns identified from real-world AI output - **Placeholder philosophy** — a complete framework for handling missing assets professionally - **Color × font pairing table** — six validated visual system starting points - **Design Direction Advisor** — six-school conversational tool for vague requests, with explicit handoff to the recipe library - **25-recipe anchored style library** — each recipe tied to a real brand / studio / designer with concrete copy-able values; defends against AI-default mush - **Advanced pattern library** — ready-to-use code templates for common UI patterns --- ## License MIT