Skills

design-system-ui

Installation
SKILL.md

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

Task Primary Tools Usage Pattern
Analyze design read_file (image) Read screenshot, extract tokens
Check Tailwind version grep grep '"tailwindcss"' package.json
Detect Mobile First grep grep -rn "sm:|md:|lg:" src/
Audit hardcoded colors grep Pattern scan across src/
Apply changes search_replace Targeted replacements
Verify changes mcp_browser_* Visual verification in browser

🎨 Step 0: Creative Design Thinking

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

Design Context Questions

Dimension Question Your Answer
Purpose What problem does this interface solve? Who uses it? Think this through
Tone Which extreme aesthetic direction? (see library below) Commit to ONE
Differentiation What makes this UNFORGETTABLE? Be specific
📱 Mobile First Design for mobile viewport first. How does this enhance UX? Default: YES

📱 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):

Style Characteristics Use When
Brutally Minimal Extreme whitespace, monochrome, no decoration Developer tools, pro apps
Maximalist Chaos Color explosion, complex layers, dense motion Creative, entertainment
Retro-Futuristic Cyberpunk, neon gradients, tech feel Games, tech products
Luxury/Refined Gold accents, serif fonts, exquisite details Premium, finance
Playful/Toy-like Rounded shapes, high saturation, bouncy motion Children, social apps
Editorial/Magazine Big type, grid systems, generous whitespace Content, blogs
Brutalist/Raw Thick borders, hard shadows, high contrast Art, indie brands

⚠️ 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:

Indicator Mobile First Desktop First
Base styles Mobile layout (stack, full-width) Desktop layout (row, fixed-width)
Breakpoint usage sm:, md:, lg: for enhancements max-width media queries
CSS pattern Progressive enhancement Graceful degradation

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:

Desktop First Pattern Mobile First Pattern
hidden md:block block md:hidden → hidden md:block (verify intent)
flex-row (base) flex-col (base) + md:flex-row
w-1/3 (base) w-full (base) + md:w-1/3
text-lg (base) text-base (base) + md:text-lg
p-8 (base) p-4 (base) + md:p-8
grid-cols-3 (base) grid-cols-1 (base) + md:grid-cols-2 lg:grid-cols-3

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

Hardcoded Replace With
bg-white bg-background or bg-card
bg-gray-50/100 bg-muted
text-gray-900/700 text-foreground
text-gray-600/500/400 text-muted-foreground
border-gray-200/300 border-border
bg-blue-* bg-primary
text-blue-* text-primary
bg-red-* bg-destructive
bg-green-* bg-success
hover:bg-gray-* hover:bg-accent

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">
CSS Variable Light Explicit Dark Explicit
bg-card bg-white dark:bg-slate-900
text-foreground text-gray-900 dark:text-gray-100
border-border border-gray-200 dark:border-slate-700
text-muted-foreground text-gray-500 dark:text-gray-400

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

Layer Component Common Issue
UI dropdown-menu.tsx bg-white → bg-popover
UI dialog.tsx bg-white → bg-card
Layout sidebar/index.tsx All hardcoded colors
Layout Header/index.tsx Background, border, text
Pages *Page.tsx files Page-level backgrounds
Business Loading/Skeleton Animation colors

🎨 Typography Quick Reference

Mood Display Font Body Font
Modern Tech Clash Display Plus Jakarta Sans
Clean Minimal Geist Geist
Editorial Playfair Display Source Serif Pro
Playful Fredoka Nunito
Luxury Cormorant Garamond Lora
Brutalist Archivo Black IBM Plex Mono

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

📱 Mobile First Quick Reference

Breakpoint Strategy

Breakpoint Viewport Usage
(base) < 640px Mobile phones - START HERE
sm: ≥ 640px Large phones / small tablets
md: ≥ 768px Tablets
lg: ≥ 1024px Laptops / small desktops
xl: ≥ 1280px Desktops
2xl: ≥ 1536px Large monitors

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.

Related skills

More from alibaba/opc-starter

Installs
1
Repository
alibaba/opc-starter
GitHub Stars
85
First Seen
3 days ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn