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 | 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) ```tsx // ✅ 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. ```typescript 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 ```css @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:** ```bash # 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:** ```bash # 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 |