pi-config/skills/design-build/SKILL.md

name, description

name	description
design-build	Generate production-ready HTML/Tailwind/React UI code from design specifications, visual references, or DESIGN.md design tokens. Incorporates Tastemaker aesthetic rules (anti-AI-slop), Emil Kowalski's design engineering & motion, Jakub Krehel's color/layout/typography systems, and high-converting landing page structures.

/design-build

Generate production-quality UI code. Produces single-file HTML with Tailwind CSS via CDN or React components.

This skill is a complete, self-contained design engineering system that replaces generic AI templates with high-craft, professional UI.

---

🎨 Part 1: Visual Identity & Aesthetic Principles (Tastemaker & Web Design Engineer)

Eliminate "AI Slop"

• NO default gradients: Never default to indigo-to-purple (bg-gradient-to-r from-indigo-500 to-purple-600).
• NO generic cards: Avoid identical rounded-lg white cards with soft shadow-md on light grey backgrounds (bg-gray-50).
• NO cookie-cutter heroes: Avoid generic centered headers with two identical pill buttons ("Get Started" / "Learn More").
• Intentional Aesthetic: Choose a distinct direction:
  • Swiss / Minimal: Monospace/serif contrasts, strict grid, generous whitespace, subtle borders (border-neutral-200/80).
  • High-Contrast Dark: Rich dark backgrounds (#0a0a0c, #121215), subtle surface borders (border-white/10), vibrant accent pops.
  • Warm Editorial: Serif headlines (Playfair/Merriweather), warm neutral backgrounds (#fcfbf7), rich ink text (#1a1917).
  • Neo-Brutalist: Thick black borders (border-2 border-black), sharp shadows (shadow-[4px_4px_0px_0px_rgba(0,0,0,1)]), bold primary colors.
  • Glassmorphism: Semi-transparent surfaces (backdrop-blur-md bg-white/10), fine borders (border-white/20).

---

📐 Part 2: Layout & Grouping (Jakub Krehel Systems)

• Space over lines: Group related items using spacing and background surfaces rather than dividing everything with heavy border lines.
• Hierarchy through contrast: Establish clear visual weight using size, weight, and color value before relying on position.
• Padding & Density:
  • Compact UI (dashboards, tools): p-3, gap-2, tight row heights.
  • Marketing / Landing pages: Generous section padding (py-20 lg:py-32), wide gaps (gap-12 lg:gap-16).
• Responsive alignment: Grid columns (grid-cols-1 md:grid-cols-2 lg:grid-cols-3) with consistent container max-widths (max-w-7xl mx-auto px-4 sm:px-6 lg:px-8).

---

🔤 Part 3: Typography & Colors (Better-Typography & Better-Colors)

• Type Scale:
  • Display / Hero: text-4xl sm:text-5xl lg:text-6xl font-bold tracking-tight leading-[1.1]
  • Section Headings: text-2xl sm:text-3xl font-semibold tracking-tight
  • Body: text-base text-neutral-600 dark:text-neutral-400 leading-relaxed
  • Small / Labels: text-xs font-medium uppercase tracking-wider text-neutral-500
• Color Roles:
  • bg-surface vs bg-background: Surface cards should be 1 step lighter (in dark mode) or tinted (in light mode) relative to background.
  • Text contrast: Ensure WCAG AA compliance (4.5:1 for body text, 3:1 for large display headers).

---

⚡ Part 4: Motion & Micro-Interactions (Emil Kowalski Design Engineering)

• Purposeful motion: Animate state changes, hover interactions, and disclosure toggles. Never animate static content for the sake of it.
• Hover effects:
  • Buttons: transition-all duration-200 ease-out hover:scale-[1.02] active:scale-[0.98]
  • Cards: transition-all duration-300 ease-out hover:-translate-y-1 hover:shadow-lg
• Focus states: Visible, accessible focus rings (focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary).

---

🚀 Part 5: Landing Page & Component Structure

When building landing pages:

1. Hero: Single clear value proposition, primary action button + secondary proof point (ratings, active users, client logos).
2. Feature Grid: Asymmetric or staggered feature cards (bento grid layout md:col-span-2 for key feature).
3. Social Proof / Metrics: Large statistics (text-4xl font-extrabold) with descriptive labels.
4. CTA Section: Distinct background surface with high-contrast primary action.
5. Footer: Clean navigation columns + legal/copyright.

---

🛠 Flow & Execution

Step 1: Gather Requirements

Ask:

1. "What are we building?" — Component, dashboard, page description.
2. "What style/vibe?" — URL to DESIGN.md or style description.

Step 2: Download DESIGN.md (if URL provided)

curl -sL <DESIGN_MD_URL> -o /tmp/design-tokens.md

Step 3: Call coder-pro

Build prompt incorporating the requirements, DESIGN.md tokens, and the 5 design system parts above.

Agent(
  subagent_type: "coder-pro",
  description: "Build UI component/page",
  prompt: <prompt with design rules>,
  max_turns: 3
)

Save generated file to ./designs/<project-name>/index.html. Show preview instructions (python3 -m http.server 3000).