Design System UI

Design System UI

For Claude Opus 4.5: This skill leverages your advanced reasoning and creative capabilities. Use the decision trees for rapid technical choices, and the checkpoints for self-verification.

Transform design references into distinctive, production-ready Tailwind CSS + Shadcn UI projects.

📱 Default Strategy: Mobile First — All new projects use Mobile First by default. Design for mobile viewport first, then progressively enhance for larger screens.

🧠 Execution Strategy

Before starting, determine your execution path:

┌─────────────────────────────────────────────────────────────────┐
│  DECISION: What type of task is this?                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  A) NEW PROJECT from design reference                            │
│     → Execute: Steps 0 → 1 → 2 → 3 → 4 → 5 → 6                  │
│     → Focus: Creative interpretation + technical scaffolding    │
│     → 📱 DEFAULT: Mobile First strategy                          │
│                                                                  │
│  B) RETROFIT existing project with new theme                     │
│     → Execute: Steps 0 → 3 → 7 → 7.5 → 8 → 9 → 10 → 11          │
│     → Focus: Systematic audit + replacement + verification      │
│     → 📱 DETECT: Check for Mobile First → Ask if not found      │
│                                                                  │
│  C) FIX theme/color issues in existing project                   │
│     → Execute: Troubleshooting section → targeted fixes         │
│     → Focus: Diagnosis + minimal surgical changes               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Mobile First Strategy Decision Tree

┌─────────────────────────────────────────────────────────────────┐
│  📱 MOBILE FIRST DETECTION (for Retrofit projects)              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Run detection commands:                                         │
│    grep -rn "sm:" src/ | head -20                               │
│    grep -rn "md:" src/ | head -20                               │
│    grep -rn "@media.*min-width" src/ | head -10                 │
│                                                                  │
│  Analyze results:                                                │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Mobile First indicators found?                            │  │
│  │  (Base styles for mobile, sm:/md:/lg: for larger screens) │  │
│  │                                                            │  │
│  │  YES → Continue with Mobile First strategy                 │  │
│  │        Maintain and enhance existing patterns              │  │
│  │                                                            │  │
│  │  NO  → Desktop First detected (max-width media queries)   │  │
│  │        Or no responsive patterns at all                    │  │
│  │        → ASK USER:                                         │  │
│  │        "是否需要将项目改造为 Mobile First 响应式策略？       │  │
│  │         这将优化移动端体验，但需要重构现有断点逻辑。"        │  │
│  │                                                            │  │
│  │        User says YES → Execute Mobile First Retrofit       │  │
│  │        User says NO  → Preserve existing responsive logic  │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Tool Usage Strategy

🎨 Step 0: Creative Design Thinking

THINK: Before writing any code, pause and commit to a BOLD aesthetic direction.

Design Context Questions

📱 Mobile First Mindset

For NEW projects, always start with:

• Base styles = mobile viewport (< 640px)
• sm: = small tablets (≥ 640px)
• md: = tablets/small laptops (≥ 768px)
• lg: = desktops (≥ 1024px)
• xl: / 2xl: = large screens (≥ 1280px / ≥ 1536px)

// ✅ Mobile First (correct)
<div className="flex flex-col md:flex-row">
<div className="w-full md:w-1/2 lg:w-1/3">
<p className="text-sm md:text-base lg:text-lg">

// ❌ Desktop First (avoid)
<div className="flex flex-row md:flex-col">  // Adding mobile styles later

Aesthetic Direction Library

Choose ONE and execute with conviction (bold maximalism and refined minimalism both work - the key is intentionality):

⚠️ Anti-Patterns (AI Slop)

NEVER use these defaults:

• Inter, Roboto, Arial, Space Grotesk as primary fonts
• Purple gradients on white backgrounds
• Cookie-cutter rounded corners everywhere
• Safe, middle-of-the-road color choices

Step 1: Analyze Design Reference

Accept input as: Screenshots, Figma exports, URLs, or verbal descriptions.

Extraction Checklist

Colors:     Primary → Secondary → Accent → Neutral scale → Semantic
Typography: Display font → Body font → Weights → Sizes → Line heights
Spacing:    Base unit → Component padding → Section margins
Visual:     Border radius → Shadow style → Animation mood
Details:    Gradients → Textures → Patterns → Overlays

🔍 Self-Check: Design Analysis

Before proceeding, verify you have extracted:

• At least 5 distinct color values (primary, secondary, accent, muted, destructive)
• Font family choices that are NOT Inter/Roboto/Arial
• A clear visual mood direction

Step 2: Generate Design Tokens

Convert analysis into structured tokens. Use HSL format for Tailwind compatibility.

const designTokens = {
  colors: {
    primary: { DEFAULT: "hsl(H S% L%)", foreground: "hsl(...)" },
    secondary: { DEFAULT: "hsl(...)", foreground: "hsl(...)" },
    accent: { DEFAULT: "hsl(...)", foreground: "hsl(...)" },
    muted: { DEFAULT: "hsl(...)", foreground: "hsl(...)" },
    destructive: { DEFAULT: "hsl(...)", foreground: "hsl(...)" },
    background: "hsl(...)",
    foreground: "hsl(...)",
    border: "hsl(...)",
  },
  typography: {
    sans: ["Your Choice", "system-ui", "sans-serif"],
    display: ["Your Display Font", "sans-serif"],
  },
  borderRadius: { sm: "...", DEFAULT: "...", lg: "..." },
};

Step 3: Tailwind Version Decision Tree ⚠️ CRITICAL

┌─────────────────────────────────────────────────────────────────┐
│  FIRST: Check Tailwind version                                   │
│  Command: grep '"tailwindcss"' package.json                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Version 3.x? ──────────────────────────────────────────────────┐
│  │                                                               │
│  │  Configuration location: tailwind.config.js                  │
│  │  Dark mode: darkMode: "class"                                │
│  │  CSS variable format: --primary: 262 83% 58%                 │
│  │  Color reference: hsl(var(--primary))                        │
│  │                                                               │
│  └──────────────────────────────────────────────────────────────┘
│                                                                  │
│  Version 4.x? ──────────────────────────────────────────────────┐
│  │                                                               │
│  │  Configuration location: CSS @theme inline                   │
│  │  Dark mode: @variant dark (&:where(.dark, .dark *))          │
│  │  CSS variable format: --primary-color: hsl(262 83% 58%)      │
│  │  Color reference: var(--primary-color)                       │
│  │  Color naming: MUST use --color-* prefix in @theme           │
│  │                                                               │
│  │  ⚠️ tailwind.config.js colors will be IGNORED in v4!        │
│  │                                                               │
│  └──────────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────────┘

Tailwind v4 CSS Template

@import "tailwindcss";

@theme inline {
  --radius-lg: 0.75rem;
  --radius-md: calc(0.75rem - 2px);
  --radius-sm: calc(0.75rem - 4px);

  --color-background: var(--background-color);
  --color-foreground: var(--foreground-color);
  --color-primary: var(--primary-color);
  --color-primary-foreground: var(--primary-foreground-color);
  --color-secondary: var(--secondary-color);
  --color-secondary-foreground: var(--secondary-foreground-color);
  --color-muted: var(--muted-color);
  --color-muted-foreground: var(--muted-foreground-color);
  --color-accent: var(--accent-color);
  --color-accent-foreground: var(--accent-foreground-color);
  --color-destructive: var(--destructive-color);
  --color-destructive-foreground: var(--destructive-foreground-color);
  --color-card: var(--card-color);
  --color-card-foreground: var(--card-foreground-color);
  --color-popover: var(--popover-color);
  --color-popover-foreground: var(--popover-foreground-color);
  --color-border: var(--border-color);
  --color-input: var(--input-color);
  --color-ring: var(--ring-color);
}

@variant dark (&:where(.dark, .dark *));

@layer base {
  :root {
    /* Light mode - USE FULL hsl() VALUES */
    --background-color: hsl(H S% L%);
    --foreground-color: hsl(H S% L%);
    --primary-color: hsl(H S% L%);
    --primary-foreground-color: hsl(H S% L%);
    /* ... complete all semantic colors ... */
  }

  .dark {
    /* Dark mode variants */
    --background-color: hsl(H S% L%);
    --foreground-color: hsl(H S% L%);
    /* ... complete all semantic colors ... */
  }
}

Step 4-6: Project Setup

Standard Shadcn UI setup. Configure components.json, create project structure.

🔧 Retrofit Workflow (Steps 7-11)

For existing projects, execute this complete flow systematically.

Step 7: Audit Hardcoded Colors

Execute these grep commands BEFORE making any changes:

# Primary audit
grep -rn "bg-gray-" src/
grep -rn "text-gray-" src/
grep -rn "border-gray-" src/
grep -rn "bg-white" src/
grep -rn "bg-black" src/

# Secondary audit
grep -rn "bg-blue-\|text-blue-" src/
grep -rn "bg-red-\|text-red-" src/
grep -rn "bg-green-\|text-green-" src/

Step 7.5: 📱 Mobile First Detection & Decision

Execute detection commands:

# Check for Mobile First indicators
grep -rn "sm:" src/ | wc -l
grep -rn "md:" src/ | wc -l
grep -rn "lg:" src/ | wc -l

# Check for Desktop First indicators (max-width = desktop first)
grep -rn "@media.*max-width" src/ | head -5

# Sample responsive patterns
grep -rn "flex.*sm:\|flex.*md:" src/ | head -10

Analyze the results:

Decision flow:

Mobile First detected?
├─ YES → Continue with Mobile First strategy
│        Use mobile-base + sm:/md:/lg: enhancements
│
└─ NO  → ASK USER:
         "检测到项目未采用 Mobile First 策略。
          是否需要改造为 Mobile First 响应式设计？
          
          优点：
          ✓ 更好的移动端性能（加载更少的覆盖样式）
          ✓ 优先保证移动用户体验
          ✓ 符合现代响应式设计标准
          
          缺点：
          ✗ 需要重构现有断点逻辑
          ✗ 可能影响现有桌面布局"
         
         User: YES → Execute Mobile First Retrofit (see below)
         User: NO  → Skip Mobile First, continue with theme retrofit only

Mobile First Retrofit (if user confirms)

Common transformations:

Priority components to retrofit:

1. Layout components (Header, Sidebar, Footer)
2. Navigation components (Navbar, MobileMenu)
3. Grid/List views (CardGrid, PhotoGrid)
4. Forms and inputs (touch-friendly sizing)

Step 8: Ensure Theme Toggle

Check for these components. If missing, create them:

1. src/hooks/useTheme.ts - Theme state management
2. src/components/ui/theme-toggle.tsx - UI toggle component
3. Theme initialization in main.tsx (prevent flash)

Step 9: Color Replacement Map

Step 10: Overlay Components ⚠️ CRITICAL

Mobile overlay components (Sidebar, Modal, Dropdown, Drawer) MUST use explicit colors, NOT CSS variables!

// ❌ WRONG - CSS variables may fail on mobile overlays
<aside className="bg-card text-foreground">

// ✅ CORRECT - Explicit colors with dark: prefix
<aside className="bg-white dark:bg-slate-900 text-gray-900 dark:text-gray-100">

Step 11: Gradient Text Dark Mode

bg-clip-text text-transparent may be invisible in dark mode!

// ❌ DANGEROUS
<h1 className="bg-linear-to-r from-primary to-accent bg-clip-text text-transparent">

// ✅ SAFE
<h1 className="text-foreground font-bold">

🔍 Self-Verification Checkpoints

After Configuration Changes

# Verify Tailwind v4 setup
grep -n "@theme inline" src/index.css
grep -n "@variant dark" src/index.css
grep -n "\-\-.*\-color:" src/index.css | head -5

After Color Replacements

# Should return minimal results (only overlay components)
grep -rn "bg-gray-\|text-gray-" src/ | grep -v "dark:" | wc -l

📱 Mobile First Verification

# Check Mobile First adoption ratio
echo "Mobile First indicators (sm:/md:/lg: prefixes):"
grep -rn "sm:\|md:\|lg:" src/ | wc -l

echo "Desktop First indicators (max-width):"
grep -rn "max-width\|max-md:\|max-lg:" src/ | wc -l

# Verify base styles are mobile-friendly
grep -rn "flex-col" src/ | wc -l    # Should be high
grep -rn "w-full" src/ | wc -l      # Should be high
grep -rn "grid-cols-1" src/ | wc -l # Should be present

Browser Console Verification

// Run in DevTools - should NOT return empty strings
const root = document.documentElement;
console.log('foreground:', getComputedStyle(root).getPropertyValue('--foreground-color'));
console.log('background:', getComputedStyle(root).getPropertyValue('--background-color'));
console.log('primary:', getComputedStyle(root).getPropertyValue('--primary-color'));

📱 Mobile First Browser Verification

// Resize to mobile viewport (375px) and verify:
// 1. No horizontal scrolling
// 2. Touch targets are at least 44x44px
// 3. Text is readable without zooming
// 4. Navigation is accessible

🚨 Troubleshooting Decision Tree

┌─────────────────────────────────────────────────────────────────┐
│  SYMPTOM: Colors not working                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Text nearly invisible / same as background?                     │
│  │                                                               │
│  ├─ Check: Is this Tailwind v4?                                 │
│  │   └─ YES → Ensure @theme inline is configured                │
│  │   └─ NO → Check tailwind.config.js colors                    │
│  │                                                               │
│  dark: prefix not working?                                       │
│  │                                                               │
│  └─ Add: @variant dark (&:where(.dark, .dark *));               │
│                                                                  │
│  Colors visible only when text selected?                         │
│  │                                                               │
│  └─ CSS variables returning empty string                        │
│     └─ Fix: Ensure :root defines --*-color variables            │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

🎯 High-Priority Components Checklist

When retrofitting, always check these components (common sources of issues):

🎨 Typography Quick Reference

AVOID: Inter, Roboto, Arial, Space Grotesk (overused)

📱 Mobile First Quick Reference

Breakpoint Strategy

Common Mobile First Patterns

// Layout: Stack on mobile, row on desktop
<div className="flex flex-col gap-4 md:flex-row md:gap-6">

// Grid: 1 column mobile → 2 tablet → 3 desktop
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">

// Spacing: Tighter on mobile, spacious on desktop  
<section className="px-4 py-6 md:px-8 md:py-12 lg:px-16">

// Typography: Smaller on mobile
<h1 className="text-2xl font-bold md:text-4xl lg:text-5xl">

// Hide/Show: Mobile menu vs desktop nav
<nav className="hidden md:flex">        // Desktop nav
<button className="md:hidden">          // Mobile menu button

// Touch-friendly buttons (min 44x44px touch target)
<button className="min-h-[44px] min-w-[44px] px-4 py-3 md:py-2">

Mobile First Anti-Patterns

// ❌ Desktop First - Don't do this
<div className="flex-row max-md:flex-col">
<div className="w-1/3 max-md:w-full">
<div className="text-lg max-md:text-sm">

// ❌ Forgetting mobile base
<div className="md:flex">  // Hidden on mobile!
// ✅ Fix:
<div className="flex flex-col md:flex-row">

📋 Retrofit Completion Checklist

□ Tailwind version confirmed and correct config approach used
□ CSS variables defined for :root and .dark
□ [v4] @theme inline configured with --color-* variables
□ [v4] @variant dark defined
□ useTheme hook exists and works
□ ThemeToggle component integrated
□ All bg-gray-* scanned and replaced
□ All text-gray-* scanned and replaced  
□ All border-gray-* scanned and replaced
□ All bg-white scanned and replaced
□ Overlay components use explicit colors
□ Gradient text verified in dark mode
□ Browser verification passed

📱 Mobile First Checklist:
□ Mobile First detection executed
□ User decision recorded (if not Mobile First)
□ Base styles are mobile-friendly (flex-col, w-full, etc.)
□ Breakpoints enhance for larger screens (sm: → md: → lg:)
□ Touch targets are 44x44px minimum on mobile
□ Mobile navigation tested

💡 For Claude Opus 4.5

Your creative capabilities are extraordinary. When implementing designs:

1. Think deeply about the aesthetic direction before writing code
2. Commit boldly to a distinctive vision - don't default to safe choices
3. 📱 Mobile First always - design for the smallest screen first, then enhance
4. Verify systematically using the checkpoints provided
5. Use tools efficiently - grep for audit, search_replace for changes, browser for verification

Every design should be unique. Vary between light/dark themes, different fonts, different aesthetics. Never converge on the same choices across implementations.

Mobile First mindset: Remember that the majority of web traffic is mobile. Starting with mobile constraints forces you to prioritize content and interactions, resulting in cleaner, more focused designs that scale gracefully to larger screens.