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

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 and 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, 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, 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:

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 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, 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. 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:

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.

Declaring Your Design System

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

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.

Creating v0 Drafts

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

<!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:

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

This executes the acceptance script defined in 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: Core skill definition containing the workflow steps, five-dial framework, and anti-cliché rules
• skills/web-design-engineer/README.md: High-level overview, quick-start commands, and feature summaries
• 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: Host-facing display metadata and default prompt invocation
• 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: 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. 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. 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}