Stop Your AI Agent from Generating Generic UI — Introducing the Design System Skill

#ai #designsystem #flutter #webdev

Every AI coding agent has the same problem: left to its own devices, it generates generic UI.

Blue buttons. White cards. 12px spacing that feels off. A hero section with three identical feature columns. Gradient backgrounds. Center-aligned body text. You've seen it a hundred times.

The agent isn't broken — it just doesn't know your design system. So it makes things up.

The Design System Skill fixes this. It's a single skill.md file that works across all major AI coding agents — Claude Code, Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot CLI, Aider, Hermes, Trae, and Google Antigravity — and enforces a real design system before any UI code gets written.

How it works

On first use in a project, the skill runs a 6-step onboarding flow:

Form factor — Website / Mobile App / Wearable / Desktop App
App type — Landing page, SaaS dashboard, social app, productivity tool, etc.
Framework / Platform — React/Next.js, Flutter, SwiftUI, Vanilla HTML, etc.
App identity — Name, target user, core action, and three vibe words
Visual reference — URL, logo, screenshot, or "feels like [App X]"
Color direction — Extracted from logo or chosen from AI-generated palette options

App type comes before framework — design rules are driven by what the app does, not how it's built.

The skill then generates:

design-tokens.json — canonical token source (colors, type, spacing, motion)
Design.md — your complete design system
tailwind.config.js — Tailwind CSS token mapping
Flutter ThemeData — Dart theme file
AGENTS.md — always-on hook for Claude, Codex, OpenCode, Aider, Trae, Hermes
.cursor/rules/design-system.mdc — Cursor alwaysApply: true
.agent/rules/design-system.md — Google Antigravity always-on rules

Every future session in that project — regardless of which agent you use — automatically loads Design.md before writing any UI code.

What rules does it enforce?

Spacing — Every margin, padding, and gap must land on the 8pt grid (8, 16, 24, 32...). No arbitrary pixel values.

Tokens-first — All values live in design-tokens.json. No hardcoded values in components.

Atomic hierarchy — Atoms → Molecules → Organisms. No skipping levels.

Section isolation — Every section uses exactly one of: surface shift, whitespace, divider, border, or color fill. Never two same-surface sections stacked without separation.

Visual hierarchy — One primary action per view. Text flows through three levels: primary → muted → faint.

Contrast — WCAG AA mandatory. Body text 4.5:1 minimum. Large text 3:1 minimum.

Anti-patterns blocked — Gradient backgrounds, colored card borders, 3-column identical feature grids, center-aligned body text, arbitrary spacing, generic AI hero copy.

What the audit looks like

Ask any agent to audit my UI or check src/components/Card.tsx and you get:

DESIGN AUDIT — Card.tsx
----------------------------------------
PASSES (9)
  Spacing: all values on 8pt grid
  Typography: heading matches Level 2 spec
  Contrast: 7.1:1 on --color-surface

WARNINGS (2)
  line 47: padding: 12px — use 8px or 16px
  line 89: font-size: 15px — use 14px or 16px

VIOLATIONS (2)
  line 23: #e5e5e5 on #f0f0f0 — contrast 1.3:1 (FAIL WCAG AA)
  line 67: margin-top: 37px — not on 8pt grid

AUTO-FIX? [y/n]

Install

curl -fsSL https://raw.githubusercontent.com/Jaywalker-not-a-whitewalker/DesignSystem/main/install.sh | bash

Or clone and run:

git clone https://github.com/Jaywalker-not-a-whitewalker/DesignSystem.git
cd DesignSystem
chmod +x install.sh
./install.sh

All global installs are symlinks — update skill.md once and every agent picks it up automatically.

Usage

cd your-project

# Trigger the onboarding flow
new project
# or
create design system
# or
/design

After Design.md exists, just build:

build the homepage
build the dashboard
audit my UI
check src/components/Card.tsx

Why one source of truth matters

The key insight is the symlink architecture. You install the skill once globally, and it symlinks into Claude's skills folder, Codex's skills folder, Gemini CLI's skills folder, and so on. When you update skill.md, every agent picks up the change automatically.

And per-project, Design.md + design-tokens.json + the hook files get committed to git — so every teammate's agent loads the same design system, regardless of which tool they use.