Web Design Engineer Skill (garden-skills)

---
name: garden-skills-web-design-engineer
description: AI agent skill that transforms AI-generated web pages from functional to stunning using design systems, oklch colors, curated typography, and anti-cliché rules
triggers:
  - make this web page look better
  - improve the design of this HTML page
  - create a beautiful landing page
  - design a stunning web interface
  - apply web design engineer skill
  - transform this from functional to stunning
  - use garden skills for web design
  - generate a high quality web page design
---

# Web Design Engineer Skill (garden-skills)

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

An AI agent skill that elevates AI-generated HTML/CSS/JavaScript artifacts from generic and functional to polished and visually compelling. Inspired by Claude Design's system prompt, this skill encodes design taste, anti-pattern rules, typography pairings, and a structured six-step workflow directly into your agent's decision-making process.

---

## What This Skill Does

- **Bans AI design clichés** — no purple-pink gradients, no emoji icons, no Inter font, no fabricated testimonials
- **Enforces oklch color theory** — perceptually uniform color derivation for harmonious palettes
- **Provides curated font × color pairings** — six validated visual systems for common use cases
- **Defines a six-step workflow** — from requirements gathering through verification
- **Ships a pattern library** — ready-to-use code templates for advanced UI patterns

---

## Installation

Copy the skill directory into your project root:

your-project/ ├── .agents/skills/web-design-engineer/ │ ├── SKILL.md │ └── references/ │ └── advanced-patterns.md └── ...

For Cursor or tools using `.claude/`:

your-project/ ├── .claude/skills/web-design-engineer/ │ ├── SKILL.md │ └── references/ │ └── advanced-patterns.md └── ...

Clone directly from GitHub:

```bash
git clone https://github.com/ConardLi/garden-skills.git _tmp_garden
mkdir -p .agents/skills/web-design-engineer/references
cp _tmp_garden/.agents/skills/web-design-engineer/SKILL.md .agents/skills/web-design-engineer/
cp _tmp_garden/.agents/skills/web-design-engineer/references/advanced-patterns.md .agents/skills/web-design-engineer/references/
rm -rf _tmp_garden

The agent picks up the skill automatically when your request involves visual or interactive front-end work.

---

The Six-Step Workflow

When this skill is active, the agent follows this structured process:

1. Understand requirements  →  Ask only when information is insufficient
2. Gather design context    →  Examine existing code/screenshots; never start from nothing
3. Declare design system    →  Colors, fonts, spacing, motion — written in Markdown before any code
4. Show v0 draft early      →  Placeholders + layout + tokens; allow course correction
5. Full build               →  Components, states, motion; pause at key decision points
6. Verify                   →  Pre-delivery checklist: no console errors, no rogue hues

---

Design System Declaration (Step 3)

Before writing any code, the agent declares the design system in plain Markdown:

## Design System

### Colors (oklch)
- Primary:    oklch(55% 0.18 265)   /* blue-violet */
- Surface:    oklch(98% 0.005 265)  /* near-white with hue tint */
- On-surface: oklch(18% 0.02 265)   /* near-black */
- Accent:     oklch(72% 0.14 145)   /* muted green */

### Typography
- Display:  "Space Grotesk", sans-serif  — weights 400 600 700
- Body:     "Inter", sans-serif          — weights 400 500
- Mono:     "JetBrains Mono", monospace  — weight 400

### Spacing scale (rem)
0.25 / 0.5 / 0.75 / 1 / 1.5 / 2 / 3 / 4 / 6 / 8 / 12

### Motion
- Easing:    cubic-bezier(0.16, 1, 0.3, 1)
- Duration:  150ms micro / 300ms element / 600ms page

---

oklch Color System

Colors use the perceptually uniform oklch(lightness% chroma hue) space. Unlike HSL, equal lightness values look equally bright across all hues.

:root {
  /* Primary scale — same lightness steps, perceptually consistent */
  --color-primary-900: oklch(25% 0.18 265);
  --color-primary-700: oklch(40% 0.20 265);
  --color-primary-500: oklch(55% 0.22 265);  /* base */
  --color-primary-300: oklch(72% 0.16 265);
  --color-primary-100: oklch(93% 0.05 265);

  /* Surface tokens */
  --color-surface:        oklch(98% 0.005 265);
  --color-surface-raised: oklch(100% 0 0);
  --color-on-surface:     oklch(18% 0.02 265);
  --color-on-surface-dim: oklch(48% 0.04 265);

  /* Semantic */
  --color-success: oklch(62% 0.17 145);
  --color-warning: oklch(75% 0.18 75);
  --color-danger:  oklch(58% 0.22 25);
}

Derive tints and shades by adjusting only the lightness% value while keeping chroma and hue fixed:

/* Hover state: lighten by ~8% */
--color-primary-hover: oklch(63% 0.22 265);

/* Disabled: desaturate (reduce chroma) */
--color-primary-disabled: oklch(55% 0.06 265);

---

Curated Font × Color Pairings

Style	Primary Color (oklch)	Display Font	Body Font	Use Case
Modern tech	oklch(55% 0.20 265)	Space Grotesk	Inter	SaaS, dev tools
Elegant editorial	oklch(42% 0.12 55)	Newsreader	Outfit	Content, blogs
Premium brand	oklch(22% 0.03 265)	Sora	Plus Jakarta Sans	Luxury, finance
Lively consumer	oklch(60% 0.22 22)	Plus Jakarta Sans	Outfit	E-commerce, social
Minimal professional	oklch(52% 0.14 195)	Outfit	Space Grotesk	Dashboards, B2B
Artisan warmth	oklch(58% 0.14 60)	Caveat	Newsreader	Food, education

Load Google Fonts for a pairing:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<!-- Modern tech pairing -->
<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;600;700&family=Inter:wght@400;500&family=JetBrains+Mono&display=swap" rel="stylesheet">

---

Anti-Cliché Rules

The skill explicitly bans the following patterns. The agent will refuse to use them:

BANNED colors/gradients:
  - Purple-pink-blue gradient backgrounds (linear-gradient with purple + pink + blue)
  - Neon glow effects as primary design elements
  - #3b82f6 (Tailwind blue-500) as default primary

BANNED layout patterns:
  - Left-border accent cards (border-left: 4px solid var(--primary))
  - Feature grids with emoji + heading + one-line description
  - "Trusted by X companies" fake logo walls
  - Fabricated testimonials with stock avatar initials
  - Fabricated statistics ("10,000+ users", "99.9% uptime")

BANNED typography:
  - Inter, Roboto, Arial, Fraunces, system-ui as display fonts
  - All-caps headings as the primary typographic move
  - Font size hero text above 96px on desktop

BANNED components:
  - Emoji as icon substitutes in production UI
  - Poorly approximated SVG icons (stick to [icon] placeholders)
  - Blue primary buttons as default without justification

---

Placeholder Philosophy

When assets are missing, use honest text markers rather than broken SVGs:

<!-- Icon placeholder -->
<span class="icon-placeholder" aria-label="settings icon">[icon: settings]</span>

<!-- Image placeholder -->
<div class="img-placeholder" role="img" aria-label="Hero product shot">
  <span>Hero image — 1440 × 800 — product in use</span>
</div>

<!-- Logo placeholder -->
<div class="logo-placeholder">[Logo: CompanyName]</div>

.icon-placeholder {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 1.25em;
  height: 1.25em;
  background: oklch(92% 0.03 265);
  border-radius: 3px;
  font-size: 0.6em;
  color: oklch(45% 0.08 265);
  font-family: "Space Grotesk", sans-serif;
  vertical-align: middle;
}

.img-placeholder {
  background: oklch(94% 0.02 265);
  display: flex;
  align-items: center;
  justify-content: center;
  color: oklch(55% 0.04 265);
  font-size: 0.875rem;
  font-style: italic;
}

---

Complete Page Template

A minimal but well-structured starting point using the skill's conventions:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Page Title</title>
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;600;700&family=Inter:wght@400;500&display=swap" rel="stylesheet">
  <style>
    /* ── Design Tokens ───────────────────────────────────────── */
    :root {
      --c-primary:      oklch(55% 0.20 265);
      --c-primary-dim:  oklch(40% 0.18 265);
      --c-surface:      oklch(98% 0.005 265);
      --c-surface-2:    oklch(95% 0.008 265);
      --c-on-surface:   oklch(18% 0.02 265);
      --c-on-dim:       oklch(48% 0.04 265);
      --c-border:       oklch(88% 0.01 265);

      --font-display: "Space Grotesk", sans-serif;
      --font-body:    "Inter", sans-serif;

      --sp-1: 0.25rem;  --sp-2: 0.5rem;  --sp-3: 0.75rem;
      --sp-4: 1rem;     --sp-6: 1.5rem;  --sp-8: 2rem;
      --sp-12: 3rem;    --sp-16: 4rem;   --sp-24: 6rem;

      --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
      --dur-fast: 150ms;
      --dur-base: 300ms;
    }

    /* ── Reset ───────────────────────────────────────────────── */
    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
    html { font-size: 16px; -webkit-font-smoothing: antialiased; }
    body {
      background: var(--c-surface);
      color: var(--c-on-surface);
      font-family: var(--font-body);
      line-height: 1.6;
    }

    /* ── Typography scale ────────────────────────────────────── */
    h1, h2, h3, h4 {
      font-family: var(--font-display);
      font-weight: 700;
      line-height: 1.15;
      letter-spacing: -0.02em;
    }
    h1 { font-size: clamp(2.5rem, 6vw, 4.5rem); }
    h2 { font-size: clamp(1.75rem, 4vw, 3rem); }
    h3 { font-size: clamp(1.25rem, 2.5vw, 1.75rem); }

    /* ── Layout utilities ────────────────────────────────────── */
    .container {
      width: min(1200px, 100% - var(--sp-8) * 2);
      margin-inline: auto;
    }
    .section { padding-block: var(--sp-24); }

    /* ── Nav ─────────────────────────────────────────────────── */
    .nav {
      position: sticky; top: 0; z-index: 100;
      background: oklch(98% 0.005 265 / 0.85);
      backdrop-filter: blur(12px);
      border-bottom: 1px solid var(--c-border);
      padding-block: var(--sp-4);
    }
    .nav-inner {
      display: flex;
      align-items: center;
      justify-content: space-between;
    }
    .nav-logo {
      font-family: var(--font-display);
      font-weight: 700;
      font-size: 1.125rem;
      color: var(--c-on-surface);
      text-decoration: none;
    }
    .nav-links {
      display: flex; gap: var(--sp-6);
      list-style: none;
    }
    .nav-links a {
      color: var(--c-on-dim);
      text-decoration: none;
      font-size: 0.9375rem;
      transition: color var(--dur-fast) ease;
    }
    .nav-links a:hover { color: var(--c-on-surface); }

    /* ── Button ──────────────────────────────────────────────── */
    .btn {
      display: inline-flex;
      align-items: center;
      gap: var(--sp-2);
      padding: var(--sp-3) var(--sp-6);
      border: none;
      border-radius: 6px;
      font-family: var(--font-display);
      font-weight: 600;
      font-size: 0.9375rem;
      cursor: pointer;
      text-decoration: none;
      transition:
        background var(--dur-fast) ease,
        transform  var(--dur-fast) ease,
        box-shadow var(--dur-fast) ease;
    }
    .btn:active { transform: scale(0.98); }

    .btn-primary {
      background: var(--c-primary);
      color: white;
    }
    .btn-primary:hover {
      background: var(--c-primary-dim);
      box-shadow: 0 4px 16px oklch(55% 0.20 265 / 0.35);
    }

    .btn-ghost {
      background: transparent;
      color: var(--c-on-surface);
      border: 1px solid var(--c-border);
    }
    .btn-ghost:hover { background: var(--c-surface-2); }

    /* ── Hero ────────────────────────────────────────────────── */
    .hero {
      padding-block: var(--sp-24);
      display: grid;
      grid-template-columns: 1fr 1fr;
      gap: var(--sp-16);
      align-items: center;
    }
    .hero-eyebrow {
      font-size: 0.8125rem;
      font-weight: 600;
      letter-spacing: 0.1em;
      text-transform: uppercase;
      color: var(--c-primary);
      margin-bottom: var(--sp-4);
    }
    .hero-heading { margin-bottom: var(--sp-6); }
    .hero-body {
      font-size: 1.125rem;
      color: var(--c-on-dim);
      margin-bottom: var(--sp-8);
      max-width: 44ch;
    }
    .hero-actions { display: flex; gap: var(--sp-3); flex-wrap: wrap; }

    .hero-visual {
      aspect-ratio: 4/3;
      background: var(--c-surface-2);
      border-radius: 12px;
      border: 1px solid var(--c-border);
      display: flex;
      align-items: center;
      justify-content: center;
      color: var(--c-on-dim);
      font-size: 0.875rem;
      font-style: italic;
    }

    /* ── Card ────────────────────────────────────────────────── */
    .card {
      background: white;
      border: 1px solid var(--c-border);
      border-radius: 10px;
      padding: var(--sp-8);
      transition:
        transform var(--dur-base) var(--ease-out-expo),
        box-shadow var(--dur-base) var(--ease-out-expo);
    }
    .card:hover {
      transform: translateY(-4px);
      box-shadow: 0 12px 32px oklch(18% 0.02 265 / 0.08);
    }
    .card-grid {
      display: grid;
      grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
      gap: var(--sp-6);
    }

    /* ── Footer ──────────────────────────────────────────────── */
    .footer {
      background: var(--c-on-surface);
      color: oklch(70% 0.02 265);
      padding-block: var(--sp-12);
    }
    .footer a { color: oklch(70% 0.02 265); text-decoration: none; }
    .footer a:hover { color: white; }
  </style>
</head>
<body>

  <header class="nav">
    <div class="container nav-inner">
      <a href="/" class="nav-logo">Brand</a>
      <nav>
        <ul class="nav-links">
          <li><a href="#features">Features</a></li>
          <li><a href="#pricing">Pricing</a></li>
          <li><a href="#docs">Docs</a></li>
        </ul>
      </nav>
      <a href="#signup" class="btn btn-primary">Get started</a>
    </div>
  </header>

  <main>
    <section class="section">
      <div class="container hero">
        <div>
          <p class="hero-eyebrow">New in 2026</p>
          <h1 class="hero-heading">Your compelling headline here</h1>
          <p class="hero-body">
            A concise value proposition in two sentences. Focus on the outcome
            the user gets, not the features you ship.
          </p>
          <div class="hero-actions">
            <a href="#signup" class="btn btn-primary">Start for free</a>
            <a href="#demo" class="btn btn-ghost">Watch demo</a>
          </div>
        </div>
        <div class="hero-visual">
          [Hero image — 800 × 600 — product screenshot]
        </div>
      </div>
    </section>

    <section class="section" id="features">
      <div class="container">
        <h2 style="margin-bottom: var(--sp-12)">Key features</h2>
        <div class="card-grid">
          <article class="card">
            <div style="margin-bottom: var(--sp-4); color: var(--c-primary); font-weight: 600;">
              [icon: feature-1] Feature one
            </div>
            <p style="color: var(--c-on-dim); font-size: 0.9375rem;">
              Describe the concrete benefit in one or two sentences.
            </p>
          </article>
          <article class="card">
            <div style="margin-bottom: var(--sp-4); color: var(--c-primary); font-weight: 600;">
              [icon: feature-2] Feature two
            </div>
            <p style="color: var(--c-on-dim); font-size: 0.9375rem;">
              Describe the concrete benefit in one or two sentences.
            </p>
          </article>
          <article class="card">
            <div style="margin-bottom: var(--sp-4); color: var(--c-primary); font-weight: 600;">
              [icon: feature-3] Feature three
            </div>
            <p style="color: var(--c-on-dim); font-size: 0.9375rem;">
              Describe the concrete benefit in one or two sentences.
            </p>
          </article>
        </div>
      </div>
    </section>
  </main>

  <footer class="footer">
    <div class="container">
      <p style="font-size: 0.875rem;">
        &copy; 2026 Brand. Built with care.
      </p>
    </div>
  </footer>

</body>
</html>

---

Motion Patterns

/* Entrance animation — staggered children */
@keyframes fade-up {
  from {
    opacity: 0;
    transform: translateY(24px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

.animate-in {
  animation: fade-up 600ms cubic-bezier(0.16, 1, 0.3, 1) both;
}

/* Apply stagger via custom property */
.card:nth-child(1) { --delay: 0ms; }
.card:nth-child(2) { --delay: 80ms; }
.card:nth-child(3) { --delay: 160ms; }
.card:nth-child(4) { --delay: 240ms; }
.card { animation-delay: var(--delay, 0ms); }

/* Intersection Observer trigger */
const observer = new IntersectionObserver(
  (entries) => entries.forEach(e => {
    if (e.isIntersecting) {
      e.target.classList.add("animate-in");
      observer.unobserve(e.target);
    }
  }),
  { threshold: 0.15 }
);
document.querySelectorAll(".card").forEach(el => observer.observe(el));

---

Supported Output Types

Type	What the skill produces
Landing pages	Marketing sites, product pages, portfolios
Interactive prototypes	Clickable app mockups with device frames
Slide decks	1920×1080 HTML presentations with keyboard nav
Dashboards	Data visualizations with Chart.js or D3.js
Animations	CSS/JS motion design, timeline-driven demos
Design systems	Token exploration pages, component variant galleries

---

Pre-Delivery Verification Checklist

Before delivering any page, the agent runs through:

□ No console errors or warnings
□ oklch values used for all colors (no stray hex codes except white/black)
□ No banned fonts loaded (Inter, Roboto, Arial, Fraunces, system-ui as display)
□ No purple-pink-blue gradients present
□ No emoji used as functional icons
□ No fabricated data (stats, testimonials, logo walls)
□ All placeholder assets clearly marked with [bracket notation]
□ Hover and focus states present on all interactive elements
□ No inline styles that contradict design tokens
□ Page renders correctly at 375px, 768px, and 1440px
□ Images have meaningful alt text or role="presentation"
□ Font weights actually loaded from Google Fonts link

---

Troubleshooting

Agent keeps using Inter or system-ui fonts Ensure SKILL.md is in the correct skill directory for your tool. Verify the agent acknowledges the skill at the start of the session. Explicitly say "apply the web design engineer skill."

Colors look inconsistent across browsers oklch() has excellent support in modern browsers (Chrome 111+, Firefox 113+, Safari 15.4+). For older targets, provide a fallback:

.btn-primary {
  background: #5b4fcf; /* fallback */
  background: oklch(55% 0.20 265);
}

Agent ignores the six-step workflow Prompt explicitly: "Follow the six-step design workflow from the web design engineer skill — start by declaring the design system before writing any code."

v0 draft never shown Ask: "Show me a v0 draft with placeholders before building the full page."

oklch colors not rendering (older Safari) Check Safari version. Safari 15.4+ supports oklch. For Safari 15.3 and below, add CSS @supports fallbacks:

@supports not (color: oklch(0% 0 0)) {
  :root {
    --c-primary: #5b4fcf;
    --c-surface: #f9f9fe;
  }
}

---

References

• SKILL.md — Main skill definition (~400 lines)
• references/advanced-patterns.md — Code template library (~520 lines)
• demo/demo1.html — Space museum without skill (baseline)
• demo/demo1-with-skill.html — Space museum with skill applied
• demo/demo2-with-skill.html — Photographer portfolio with skill applied
• prompt/system.md — Original Claude Design system prompt (reference only)