Tailwindcss Design

TailwindCSS Design Patterns

TailwindCSS implementation companion for web-design-mastery skill. Translates Refactoring UI principles into Tailwind utility classes.

> Prerequisite: This skill provides Tailwind-specific syntax. For design theory and decision-making, reference web-design-mastery skill.

---

⚠️ CRITICAL: Project Brand Colors First

ALWAYS check tailwind.config.js for custom colors before using generic colors.

If the project defines primary, secondary, brand, or similar custom colors, USE THEM:

// tailwind.config.js
colors: {
  primary: { 50: '...', 500: '...', 900: '...' },
  secondary: { ... },
  brand: { ... }
}

Priority order:

1. Project-defined colors (primary, secondary, brand, accent)
2. Generic Tailwind colors (zinc, gray, slate) as fallback only

Usage examples with project colors:

Rules:

• Primary = main CTAs, active states, links, focus rings
• Secondary = alternative actions, supporting elements
• Brand/Accent = highlights, decorative elements
• Neutral (zinc/gray) = structure, text, borders only

---

Spacing Classes (4px Grid)

| Token | Size | Classes | Use Case | |-------|------|---------|----------| | 1 | 4px | gap-1, p-1, m-1 | Micro gaps | | 2 | 8px | gap-2, p-2, m-2 | Tight, within components | | 3 | 12px | gap-3, p-3, m-3 | Related elements | | 4 | 16px | gap-4, p-4, m-4 | Standard padding | | 6 | 24px | gap-6, p-6, m-6 | Between sections | | 8 | 32px | gap-8, p-8, m-8 | Major separation | | 12 | 48px | gap-12, p-12 | Large gaps | | 16 | 64px | gap-16, py-16 | Hero spacing |

Rule: Symmetric padding by default. p-4 not pt-6 pb-2 pl-4 pr-8.

---

Typography Classes

| Size | Class | Use Case | |------|-------|----------| | 12px | text-xs | Labels, meta, fine print | | 14px | text-sm | Body text, default | | 16px | text-base | Emphasis | | 18px | text-lg | Subheadings | | 20px | text-xl | Card titles | | 24px | text-2xl | Page titles | | 30px | text-3xl | Hero subheading | | 36px+ | text-4xl, text-5xl | Hero heading |

Weight Classes:

| Role | Class | |------|-------| | Body | font-normal | | Labels | font-medium | | Headings | font-semibold |

Tracking (Letter-spacing):

---

Color Hierarchy

Text Colors (4-Level System)

Primary
Secondary
Muted
Faint

Primary
Secondary
Muted
Faint

Status Colors

Success
Warning
Error
Info

Brand Colors (Priority)

Check tailwind.config.js first. If primary/secondary defined, use them:

---

Shadow & Depth Strategies

Pick ONE per project:

Strategy A: Flat (Borders)

Strategy B: Subtle Lift

Strategy C: Layered (Premium)

Strategy D: Surface Shift

Shadow Scale:

| Level | Class | Use Case | |-------|-------|----------| | 1 | shadow-sm | Cards, buttons | | 2 | shadow | Dropdowns | | 3 | shadow-md | Popovers | | 4 | shadow-lg | Modals | | 5 | shadow-xl | Full-screen overlays |

---

Component Recipes

Cards

Buttons

Inputs

Navigation Item

---

Animation Classes

| Duration | Class | Use Case | |----------|-------|----------| | 150ms | duration-150 | Hovers, toggles | | 200ms | duration-200 | Standard transitions | | 300ms | duration-300 | Page transitions |

Staggered Animation:

---

Dark Mode Pattern

Dark mode adjustments:

• Borders > shadows (shadows less visible)
• Desaturate status colors slightly
• Reduce contrast on secondary elements

---

Anti-Patterns

---

Reference Files

| Topic | File | |-------|------| | Component depth patterns | [depth-strategies.md](references/depth-strategies.md) | | Complete component library | [components.md](references/components.md) | | Responsive patterns | [responsive.md](references/responsive.md) |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: anilcancakir
• Source: anilcancakir/my-claude-code
• License: MIT

Install and usage instructions live in the source repository linked above.