playbooks

home / skills / anilcancakir / my-claude-code / tailwindcss-design

tailwindcss-design skill

/skills/tailwindcss-design

This skill translates Refactoring UI principles into Tailwind utility patterns, enabling consistent branding, responsive layouts, and accessible components.

npx playbooks add skill anilcancakir/my-claude-code --skill tailwindcss-design

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
8.5 KB
---
name: tailwindcss-design
description: "TailwindCSS implementation patterns for Refactoring UI principles. COMPANION skill for web-design-mastery. ALWAYS activate for: TailwindCSS, Tailwind classes, utility classes, Tailwind config, Tailwind components, Tailwind dark mode, Tailwind responsive, Tailwind spacing, Tailwind typography, Tailwind colors, Tailwind shadows. Provides class recipes, component patterns, dark mode implementation, responsive patterns. Turkish: Tailwind kullanımı, Tailwind class, utility CSS, Tailwind config. English: Tailwind patterns, utility-first CSS, Tailwind best practices."
---

# 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**:

```js
// 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:**

```html
<!-- ✅ CORRECT: Use project colors -->
<button class="bg-primary-600 hover:bg-primary-700 text-white">
<a class="text-primary-600 hover:text-primary-700">
<div class="border-primary-500 bg-primary-50">
<input class="focus:border-primary-500 focus:ring-primary-500">

<!-- Active/selected states -->
<nav class="bg-primary-50 text-primary-700">

<!-- ❌ AVOID when project colors exist -->
<button class="bg-blue-600">  <!-- Generic, ignores brand -->
<button class="bg-zinc-900">  <!-- Only if no primary defined -->
```

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

```html
<!-- Headlines: tighter -->
<h1 class="text-3xl font-semibold tracking-tight">

<!-- All-caps: wider -->
<span class="text-xs font-medium uppercase tracking-wide">
```

---

## Color Hierarchy

### Text Colors (4-Level System)

```html
<!-- Light mode -->
<span class="text-zinc-900">Primary</span>
<span class="text-zinc-600">Secondary</span>
<span class="text-zinc-400">Muted</span>
<span class="text-zinc-300">Faint</span>

<!-- Dark mode -->
<span class="dark:text-zinc-100">Primary</span>
<span class="dark:text-zinc-400">Secondary</span>
<span class="dark:text-zinc-500">Muted</span>
<span class="dark:text-zinc-600">Faint</span>
```

### Status Colors

```html
<span class="text-emerald-600 dark:text-emerald-400">Success</span>
<span class="text-amber-600 dark:text-amber-400">Warning</span>
<span class="text-red-600 dark:text-red-400">Error</span>
<span class="text-blue-600 dark:text-blue-400">Info</span>
```

### Brand Colors (Priority)

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

```html
<button class="bg-primary-600 hover:bg-primary-700">
<a class="text-primary-600 hover:text-primary-700">
<div class="border-primary-500 bg-primary-50">
```

---

## Shadow & Depth Strategies

**Pick ONE per project:**

### Strategy A: Flat (Borders)

```html
<div class="border border-zinc-200 dark:border-zinc-800">
```

### Strategy B: Subtle Lift

```html
<div class="shadow-sm border border-zinc-200/50">
```

### Strategy C: Layered (Premium)

```html
<div class="shadow-sm ring-1 ring-black/5">
```

### Strategy D: Surface Shift

```html
<div class="bg-zinc-50"> <!-- page -->
  <div class="bg-white"> <!-- elevated -->
```

**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

```html
<!-- Flat -->
<div class="rounded-lg border border-zinc-200 bg-white p-4 dark:border-zinc-800 dark:bg-zinc-900">

<!-- Elevated -->
<div class="rounded-lg bg-white p-4 shadow-sm ring-1 ring-black/5 dark:bg-zinc-900">
```

### Buttons

```html
<!-- Primary -->
<button class="rounded-md bg-zinc-900 px-3 py-1.5 text-sm font-medium text-white hover:bg-zinc-800 dark:bg-zinc-100 dark:text-zinc-900 dark:hover:bg-zinc-200">

<!-- Secondary -->
<button class="rounded-md border border-zinc-300 bg-white px-3 py-1.5 text-sm font-medium text-zinc-700 hover:bg-zinc-50 dark:border-zinc-700 dark:bg-zinc-800 dark:text-zinc-300">

<!-- Ghost -->
<button class="rounded-md px-3 py-1.5 text-sm font-medium text-zinc-600 hover:bg-zinc-100 hover:text-zinc-900 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-100">
```

### Inputs

```html
<input class="w-full rounded-md border border-zinc-300 bg-white px-3 py-2 text-sm text-zinc-900 placeholder:text-zinc-400 focus:border-zinc-500 focus:outline-none focus:ring-1 focus:ring-zinc-500 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-100" />
```

### Navigation Item

```html
<!-- Default -->
<a class="flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium text-zinc-600 hover:bg-zinc-100 hover:text-zinc-900 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-100">

<!-- Active -->
<a class="flex items-center gap-2 rounded-md bg-zinc-100 px-3 py-2 text-sm font-medium text-zinc-900 dark:bg-zinc-800 dark:text-zinc-100">
```

---

## Animation Classes

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

```html
<div class="transition-all duration-200 ease-out">
<div class="transition-colors duration-150">
```

**Staggered Animation:**

```html
<div class="animate-fade-in [animation-delay:0ms]">
<div class="animate-fade-in [animation-delay:50ms]">
<div class="animate-fade-in [animation-delay:100ms]">
```

---

## Dark Mode Pattern

```html
<div class="bg-white dark:bg-zinc-950">
  <h1 class="text-zinc-900 dark:text-zinc-100">
  <p class="text-zinc-600 dark:text-zinc-400">
  <div class="border-zinc-200 dark:border-zinc-800">
```

**Dark mode adjustments:**

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

---

## Anti-Patterns

```html
<!-- ❌ NEVER -->
<div class="shadow-2xl">           <!-- Too dramatic -->
<button class="rounded-2xl px-3">  <!-- Radius too large for size -->
<div class="pt-8 pb-2 pl-6 pr-3">  <!-- Asymmetric without reason -->
<div class="border-4 border-purple-500"> <!-- Thick decorative -->
<div class="animate-bounce">       <!-- Bouncy in enterprise UI -->

<!-- ✅ INSTEAD -->
<div class="shadow-sm">
<button class="rounded-md px-3">
<div class="p-4">
<div class="border border-zinc-200">
<div class="transition-all duration-200">
```

---

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

Overview

This skill provides TailwindCSS implementation patterns that translate Refactoring UI principles into production-ready utility-class recipes. It is a companion to design theory guidance and focuses on concrete Tailwind class choices, component recipes, dark mode handling, spacing, typography, shadows, and responsive patterns. Use it to standardize UI implementations across projects and enforce brand-first color usage.

How this skill works

The skill inspects project Tailwind configuration (tailwind.config.js) for custom colors and preferred tokens, then recommends class recipes that prioritize project-defined colors over generic Tailwind palettes. It supplies spacing and typography scales, shadow strategies, component examples (cards, buttons, inputs, nav items), animation timings, and dark-mode variations. Outputs are concise utility-class patterns you can copy into templates or component libraries.

When to use it

  • When implementing UI from a design system or Refactoring UI guidance
  • When you need consistent Tailwind class patterns across components
  • When onboarding developers to project-specific Tailwind conventions
  • When adding or auditing dark mode support and responsive behavior
  • When defining spacing, typography, and shadow scale for a project

Best practices

  • Always check tailwind.config.js and use project-defined colors (primary, secondary, brand) before generic colors
  • Adopt one depth strategy per project (flat, subtle lift, layered, or surface shift) and apply consistently
  • Use symmetric spacing tokens from a 4px grid and prefer p-4/m-4 over asymmetric padding unless justified
  • Map semantic roles (primary/secondary/neutral) to color tokens, not concrete color names
  • Prefer subtle durations (150–200ms) for hover/interaction transitions; use staggered delays for list reveals

Example use cases

  • Create a primary CTA button using bg-primary-600 hover:bg-primary-700 text-white with rounded-md and duration-150
  • Build card components with either border-based flat style or elevated shadow-sm + ring-1 for premium look
  • Implement inputs with consistent focus rings: focus:border-primary-500 focus:ring-primary-500 and dark variants
  • Convert a legacy UI to utility-first by applying the spacing scale (gap-4, p-4, gap-6) and typography tokens (text-base, text-lg, font-semibold)
  • Standardize navigation items with default and active recipes to ensure accessible contrast and consistent spacing

FAQ

What if my project has no custom colors defined?

Fallback to neutral palettes (zinc/gray/slate) and pick a single accent from Tailwind colors. Document the chosen tokens in tailwind.config.js for future consistency.

How strict should I be about choosing one shadow strategy?

Pick one strategy per project to avoid visual noise. Use flat borders for content-dense UIs, subtle lift for general surfaces, and layered or surface-shift for premium products.