Design System Consultation

Core Concepts / How It Works

Components of a Design System

The design system generated by the Design Consultation skill covers the following 6 areas.

1. Aesthetic: Brand personality — modern/minimal, warm/friendly, professional/trustworthy, etc.
2. Typography: Font families, size scale (xs–5xl), line height, letter spacing
3. Color: Primary / Secondary / Neutral / Semantic (success, warning, error, info) palettes and dark mode tokens
4. Layout: Grid system, maximum width, responsive breakpoints
5. Spacing: 4px-based spacing scale, rules for component internal/external margins
6. Motion: Transition duration, easing curves, animation principles

When to Use

• When starting a new project with no existing DESIGN.md or design system
• When receiving requests like "create a design system for me" or "I need brand guidelines"
• When you want to finalize the visual language before starting frontend development
• When you want to systematically define color tokens and font scales to reflect in tailwind.config.ts
• When team members keep asking "what color should I use?" or "what size is the button?"

If you already have a site and need to reverse-engineer the current design system, use /plan-design-review instead.

DESIGN.md — Design SSOT

The output of running the skill is a DESIGN.md file at the project root. This file serves as:

• A Single Source of Truth for design decisions within the team
• A reference document for customizing tailwind.config.ts
• An onboarding reference that conveys "this is how our UI looks" to new team members within 1 minute
• A source for consistent results when telling Claude Code to "build this referencing DESIGN.md"

Font & Color Preview Page

In addition to DESIGN.md, the skill generates a renderable HTML preview page at the /design-preview route for visually verifying actual font and color combinations.

One-Line Summary

A skill that understands the product, surveys the design environment, and then proposes a complete design system including color, typography, layout, spacing, and motion, and generates DESIGN.md as the project's design Single Source of Truth (SSOT).

Getting Started

/design-consultation

SKILL.md location: ~/.claude/skills/design-consultation/SKILL.md

To customize, copy and modify the SKILL.md content.

Practical Example

Scenario: Building a "Student Club Notice Board" from scratch with Next.js 15. The desired design direction is "university club feel — friendly, clean, mobile-first." Let's create DESIGN.md and the Tailwind configuration together.

Step 1 — Start Design Consultation

> Create a design system for the student club notice board using the design-consultation skill.
> Feel: Friendly and clean university club vibe, mobile-first, dark mode support

Step 2 — Example of Generated DESIGN.md

# DESIGN.md — Student Club Notice Board Design System

## Aesthetic
- Personality: Friendly & Clean
- Inspiration: KakaoTalk Open Chat + Notion sidebar
- Principles: Clear information hierarchy, breathing room through whitespace, touch-friendly

## Typography
- Headings: Pretendard (optimized for Korean text)
- Body: Pretendard Regular
- Code: JetBrains Mono
- Scale: 12/14/16/18/20/24/30/36/48px

## Color
### Light mode
- Primary: #3B82F6 (blue-500) — primary actions, links
- Primary Dark: #1D4ED8 (blue-700) — hover
- Neutral-50: #F8FAFC — background
- Neutral-900: #0F172A — default text

### Dark mode
- Primary: #60A5FA (blue-400)
- Background: #0F172A

### Semantic
- Success: #22C55E, Warning: #F59E0B, Error: #EF4444

## Spacing (4px base)
- xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px, 2xl: 48px

## Layout
- Max width: 768px (mobile-focused)
- Grid: 4-column (mobile) / 8-column (tablet+)
- Breakpoints: sm 640px / md 768px / lg 1024px

## Motion
- Default transition: 150ms ease-in-out
- Page transition: 200ms ease-out
- Principle: Use functional motion only, avoid excessive animation

Step 3 — Reflect in Tailwind Configuration

// tailwind.config.ts
import type { Config } from 'tailwindcss'

const config: Config = {
  content: ['./app/**/*.{ts,tsx}', './components/**/*.{ts,tsx}'],
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: '#3B82F6',
          dark: '#1D4ED8',
        },
        // Reflect color tokens from DESIGN.md directly
      },
      fontFamily: {
        sans: ['Pretendard', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
      spacing: {
        // Custom 4px-based scale (used alongside default Tailwind)
        'xs': '4px',
        'sm': '8px',
      },
    },
  },
}

export default config

Step 4 — Reference DESIGN.md in Components

// components/NoticeCard.tsx
// DESIGN.md: Apply primary color, md spacing, 150ms transition
export function NoticeCard({ title, date, preview }: NoticeCardProps) {
  return (
    <article className="
      rounded-xl
      bg-white dark:bg-neutral-800
      p-4                      // md spacing (16px)
      transition-shadow duration-150  // 150ms transition
      hover:shadow-md
      cursor-pointer
    ">
      <h2 className="text-lg font-semibold text-neutral-900 dark:text-white">
        {title}
      </h2>
      <time className="text-sm text-neutral-500">{date}</time>
      <p className="mt-2 text-sm text-neutral-600 dark:text-neutral-300 line-clamp-2">
        {preview}
      </p>
    </article>
  )
}

Learning Points / Common Pitfalls

• Starting without a design system costs double later: Building UI ad hoc leads to 7 different button colors and 11 font sizes. A single DESIGN.md prevents this chaos.
• Common mistake — relying only on Tailwind defaults: Hardcoding colors like text-blue-500 directly in components means a full manual search-and-replace when you change the color theme. Define tokens in tailwind.config.ts and use semantic names like text-primary.
• Korean font considerations: Pretendard is the de facto standard for Korean web projects. Loading it via next/font optimizes it without FOUT.
• DESIGN.md is a living document: The DESIGN.md generated after running the skill is a starting point. Continuously refining it as you see the actual design is the normal process.
• Distinction from /plan-design-review: When you already have a UI and want to analyze "what the current design system is," use /plan-design-review. Design Consultation is the work of creating something from scratch.

Related Resources

• design-shotgun — Explore multiple design variations (fine-grained UI decisions after Consultation)
• design-html — Implement approved design in HTML/CSS
• design-review — Visual quality inspection of a completed site

---

Field	Value
Source URL	https://docs.anthropic.com/en/docs/claude-code/skills
Author / Source	Anthropic
License	Commentary MIT, original for reference only
Translation Date	2026-04-13