# What Is the Web-Design-Engineer Skill? A Complete Guide to AI Design Engineering

> Discover the web-design-engineer skill. Transform AI web artifacts into production-ready interfaces with a disciplined design-first workflow. Learn more today.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: getting-started
- Published: 2026-09-01

---

**The web-design-engineer skill transforms AI-generated web artifacts from generic mock-ups into polished, production-ready interfaces by enforcing a disciplined design-first workflow that mandates design system declarations before code, blocks overused AI clichés, and validates work through a calibrated five-dial framework.**

The web-design-engineer skill in the ConardLi/garden-skills repository provides a structured persona for AI coding agents. It ensures that front-end development emerges from intentional visual decisions rather than ad-hoc styling, creating web experiences that feel custom-crafted and brand-consistent rather than templated.

## Core Mechanisms of the Web-Design-Engineer Skill

The skill operates through six specific guardrails defined in [`skills/web-design-engineer/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/SKILL.md) and [`skills/web-design-engineer/README.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/README.md).

### 1. Design-First Mindset (Mandatory Pre-Code Declaration)

Before emitting any HTML, CSS, or JSX, the agent must declare a complete design system. According to "Step 3: Declare the Design System…" in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md), this includes:

- **Color palette**: Primary, secondary, neutral, and accent tokens with specific hex or OKLCH values
- **Typography**: Heading and body font families (e.g., Space Grotesk, Outfit)
- **Spacing system**: Base unit and multipliers (e.g., base = 8px, multiples 1–4)
- **Border-radius** and **shadow hierarchy** specifications
- **Motion style**: Easing functions and duration (e.g., ease-out-quad, 200ms)

This prevents the agent from using arbitrary values mid-implementation and forces intentional token choices.

### 2. Anti-Cliché Guardrails

The skill maintains a curated block-list of overused AI patterns. As documented in the "Anti-AI-cliché checklist" in [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md), the agent is prohibited from using:

- Purple-pink gradients
- Emoji icons
- Generic Inter font (unless brand-specified)
- Fabricated testimonials

These elements are only permitted when an explicit brand specification requires them, ensuring outputs avoid the "generic AI look."

### 3. Five-Dial Design Read Framework

Every project brief is translated into five calibrated dials defined in the "Five-dial Design Read" section of [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md):

1. **Visual variance**: How distinctive or conservative the aesthetic should be
2. **Motion intensity**: Level of animation and interaction richness
3. **Information density**: Layout compression and whitespace ratios
4. **Asset dependence**: Reliance on custom imagery versus generative placeholders
5. **Brand fidelity**: Alignment with existing brand constraints versus exploration

These dials steer token selection, layout density, and interaction complexity throughout the build process.

### 4. Preservation-Aware Redesigns

When working with existing UI, the skill classifies the scope of work before touching any code. The "Preservation-aware redesigns" section in [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md) defines three modes:

- **Extension**: Adding new sections that match existing visual contracts
- **Preserve**: Refactoring logic while maintaining exact visual parity
- **Overhaul**: Complete visual redesign with explicit user consent

This ensures existing design systems are respected unless explicitly overridden.

### 5. Early v0 Drafts for Rapid Validation

Following "Step 4: Show a v0 Draft Early" in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md), the agent presents a low-fidelity draft containing placeholder content, core layout structures, and declared design tokens. This enables stakeholder feedback on visual direction before the agent invests tokens in high-fidelity implementation, reducing costly rework.

### 6. Optional Browser Acceptance Testing

The skill includes a lightweight browser-acceptance harness documented in "Opt-in browser acceptance" in [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md). Developers can run this to verify:

- Responsive behavior across breakpoints
- Interaction states (hover, focus, active)
- Visual regression against baseline screenshots

This runs only when explicitly requested via `npm run test-browser` in the demo directory, avoiding unnecessary overhead during rapid iteration.

## How to Implement the Web-Design-Engineer Skill

### Installation

Add the skill to your Claude or Cursor-compatible project using the npx installer:

```bash
npx skills add ConardLi/garden-skills -s web-design-engineer

```

This copies the skill folder into `.claude/skills/web-design-engineer` or `.agents/skills/web-design-engineer` in your project root, as specified in the installation instructions in [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md).

### Declaring Your Design System

Before writing code, output a Design Decisions block that maps your five-dial read to concrete tokens:

```markdown
Design Decisions:
- Design Read: artifact=landing-page, visual-variance=7, motion-intensity=4, information-density=6, asset-dependence=5, brand-fidelity=8
- Anchor / recipe: linear
- Color palette: primary=#0f62fe, secondary=#e0e7ff, neutral=#f5f7fa, accent=#ff4081
- Typography: heading=Space Grotesk, body=Outfit
- Spacing system: base = 8px, multiples = 1–4
- Border-radius: small
- Shadow hierarchy: elevation = 2
- Motion style: ease-out-quad, duration = 200ms

```

The agent must present this block before emitting any `<style>` tags or JSX components, as enforced by the workflow in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md).

### Creating v0 Drafts

Generate a low-fidelity HTML prototype that establishes layout and token structure without final assets:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Landing v0</title>
  <style>
    :root {
      --color-primary: oklch(0.6 0.18 250);
      --color-bg: oklch(0.98 0.02 120);
      --font-heading: "Space Grotesk", sans-serif;
      --font-body: "Outfit", sans-serif;
      --spacing: 8px;
    }
    body { margin: var(--spacing); font-family: var(--font-body); background: var(--color-bg); }
    h1 { font-family: var(--font-heading); color: var(--color-primary); }
    .hero { height: 40vh; background: #ccc; display: flex; align-items: center; justify-content: center; }
    .cta { padding: calc(var(--spacing) * 2); background: var(--color-primary); color: #fff; border-radius: 4px; }
  </style>
</head>
<body>
  <section class="hero"><h1>[Hero Title]</h1></section>
  <section class="cta">[Primary Call-to-Action]</section>
  <!-- placeholders for images, icons, etc. -->
</body>
</html>

```

This draft contains only layout scaffolding, CSS custom properties, and placeholder text, inviting user confirmation before proceeding to high-fidelity implementation.

### Running Browser Acceptance Tests

Validate responsiveness and interaction states using the optional test harness:

```bash
cd demo/web-design-engineer-demo
npm install && npm run test-browser

```

This executes the acceptance script defined in [`references/browser-acceptance.md`](https://github.com/ConardLi/garden-skills/blob/main/references/browser-acceptance.md), verifying that the implementation meets the design specifications across viewport sizes.

## Key Files in the Web-Design-Engineer Skill

Understanding the repository structure helps developers customize the workflow:

- **[`skills/web-design-engineer/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/SKILL.md)**: Core skill definition containing the workflow steps, five-dial framework, and anti-cliché rules
- **[`skills/web-design-engineer/README.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/README.md)**: High-level overview, quick-start commands, and feature summaries
- **[`skills/web-design-engineer/manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/manifest.json)**: Metadata (name, version, compatibility) used by Claude-Code, Cursor, and other AI IDEs
- **[`skills/web-design-engineer/agents/openai.yaml`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/agents/openai.yaml)**: Host-facing display metadata and default prompt invocation
- **[`skills/web-design-engineer/references/style-recipes/INDEX.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/references/style-recipes/INDEX.md)**: Catalog of 25 anchored style recipes providing concrete token sets for specific visual directions
- **[`demo/web-design-engineer-demo/README.md`](https://github.com/ConardLi/garden-skills/blob/main/demo/web-design-engineer-demo/README.md)**: Instructions for running the React/Vite gallery showcasing full-page artifacts for each recipe

## Summary

The web-design-engineer skill provides a structured methodology for AI-generated front-end development:

- **Mandates design system declarations** before any code is written, ensuring intentional token choices
- **Blocks overused AI visual clichés** such as purple-pink gradients and emoji icons unless explicitly brand-required
- **Translates briefs into five calibrated dials** (visual variance, motion intensity, information density, asset dependence, brand fidelity) that guide implementation decisions
- **Respects existing codebases** through preservation-aware redesign classifications (Extension, Preserve, Overhaul)
- **Validates direction early** via low-fidelity v0 drafts shown before high-fidelity implementation
- **Offers optional quality assurance** through a browser-acceptance harness that verifies responsiveness and interaction states

## Frequently Asked Questions

### What makes the web-design-engineer skill different from standard AI coding assistants?

Standard AI coding assistants often generate functional but visually generic code using arbitrary values and trending design clichés. The web-design-engineer skill imposes a disciplined design-engineer persona that requires explicit design system declarations before code generation, as specified in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md). This transforms the agent from a code generator into a design partner that understands product context and maintains visual consistency.

### How does the five-dial Design Read work in practice?

The five-dial framework assigns numeric values (typically 1-10) to visual variance, motion intensity, information density, asset dependence, and brand fidelity. These values constrain the agent's choices when selecting from the 25 style recipes in [`references/style-recipes/INDEX.md`](https://github.com/ConardLi/garden-skills/blob/main/references/style-recipes/INDEX.md). For example, a project with high visual variance (8+) and low brand fidelity (3) might select an experimental recipe with bold colors and unconventional layouts, while high brand fidelity (9) forces adherence to existing brand tokens regardless of other dial settings.

### Can I use the web-design-engineer skill with existing codebases?

Yes. The skill includes preservation-aware redesign logic defined in [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md) that classifies work as Extension, Preserve, or Overhaul. When set to Preserve, the agent analyzes existing CSS custom properties and component structures to maintain visual parity while refactoring logic. This ensures the skill enhances legacy projects without unintentionally breaking established design contracts.

### Is the browser acceptance testing mandatory?

No. According to "Opt-in browser acceptance" in [`README.md`](https://github.com/ConardLi/garden-skills/blob/main/README.md), the browser-acceptance harness runs only when explicitly requested. Developers can invoke it via `npm run test-browser` in the demo directory to verify responsiveness and interaction states, but the skill functions fully without it. This opt-in approach keeps the workflow lightweight for rapid prototyping while providing rigorous validation when needed for production deployments.