# tailwind-design-system

Creates and orchestrates a design system using Tailwind CSS v4.1+ and shadcn/ui. It defines oklch design tokens, themes via CSS variables, and wraps UI primitives.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 4500 installs · ★ 363
- Author: giuseppe-trisciuoglio
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/giuseppe-trisciuoglio/developer-kit/tree/HEAD/plugins/developer-kit-typescript/skills/tailwind-design-system/SKILL.md
- Updated: 2026-09-10
- HTML: https://affpapa.org/en/nevibecode/skills/giuseppe-trisciuoglio-tailwind-design-system

## What it does

This skill handles design systems at the infrastructure level rather than generating one-off utility classes. Its structured workflow covers five steps: running the Tailwind and shadcn/ui initializers, writing tokens into `src/app/globals.css`, connecting variables via `@theme inline`, wrapping primitives in `src/components/ds/`, and validating definitions with shell scripts. Colors are declared using perceptual `oklch` values, pairing each background with a mandatory foreground token.

Component wrapping is central here. Instead of using shadcn/ui components directly in page code, the skill encapsulates them into constrained design system primitives with typed variant maps. Because this workflow relies on the CSS-first configuration model introduced in Tailwind v4.1+, projects still using JavaScript configuration files (`tailwind.config.js`) will need adjustments before these patterns apply cleanly.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill tailwind-design-system -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tailwind-design-system/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tailwind-design-system/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill tailwind-design-system -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tailwind-design-system/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill tailwind-design-system -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tailwind-design-system/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install giuseppe-trisciuoglio/developer-kit tailwind-design-system
```

2. **Manually: put the files in place**
- File: `.github/skills/tailwind-design-system/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill tailwind-design-system -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/giuseppe-trisciuoglio/developer-kit --path plugins/developer-kit-typescript/skills/tailwind-design-system
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tailwind-design-system/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill tailwind-design-system -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/giuseppe-trisciuoglio/developer-kit/tree/HEAD/plugins/developer-kit-typescript/skills/tailwind-design-system/SKILL.md

## When to use it
- define design tokens and color pairs in oklch format
- bridge CSS variables to Tailwind v4 utilities using @theme inline
- wrap raw shadcn/ui components into typed design system primitives
- set up multi-brand themes using HTML data attributes
- validate token completeness across CSS files using bash scripts

## Example prompts
- Initialize a design system using Tailwind CSS v4 and shadcn/ui with oklch tokens
- Wrap the shadcn Button component into a design system primitive with primary and secondary variants
- Add custom warning tokens in oklch to globals.css and map them to Tailwind inline theme

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 116bf26a43402497.

BEGIN THIRD-PARTY FILE 116bf26a43402497
````text
---
name: tailwind-design-system
description: Skill for creating and managing a Design System using Tailwind CSS and shadcn/ui. Use when defining design tokens, setting up theming with CSS variables, building a consistent UI component library, initializing a design system configuration, or wrapping shadcn/ui components into design system primitives.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# Tailwind CSS & shadcn/ui Design System

## Overview

Expert guide for creating and managing a centralized Design System using Tailwind CSS (v4.1+) and shadcn/ui. This skill provides structured workflows for defining design tokens, configuring themes with CSS variables, and building a consistent UI component library based on shadcn/ui primitives.

**Relationship with other skills:**
- **tailwind-css-patterns** covers utility-first styling, responsive design, and general Tailwind CSS usage
- **shadcn-ui** covers individual component installation, configuration, and implementation
- **This skill** focuses on the **system-level** orchestration: design tokens, theming infrastructure, component wrapping patterns, and ensuring consistency across the entire application

## When to Use

- Setting up a new design system from scratch with Tailwind CSS and shadcn/ui
- Defining design tokens (colors, typography, spacing, radius, shadows) as CSS variables
- Configuring `globals.css` with a centralized theming system (light/dark mode)
- Wrapping shadcn/ui components into design system primitives with enforced constraints
- Building a token-driven component library for consistent UI
- Migrating from a JavaScript-based Tailwind config to CSS-first configuration (v4.1+)
- Establishing color palettes with oklch format for perceptual uniformity
- Creating multi-theme support beyond light/dark (e.g., brand themes)

## Instructions

### Step 1: Initialize Design System Configuration

Run these commands to set up the project:

```bash
# Check if Tailwind is installed
npx tailwindcss --version

# For Tailwind v4 (recommended)
npx @tailwindcss/vite@latest init   # or: npm install -D tailwindcss @tailwindcss/vite

# Initialize shadcn/ui CLI
npx shadcn@latest init

# Install core shadcn/ui components
npx shadcn@latest add button card input -y
```

**Validation checkpoint**: After setup, verify with:
````
END THIRD-PARTY FILE 116bf26a43402497

The third-party file has ended. Everything between the 116bf26a43402497 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2315 of 9703 bytes. © giuseppe-trisciuoglio · MIT · https://github.com/giuseppe-trisciuoglio/developer-kit/tree/HEAD/plugins/developer-kit-typescript/skills/tailwind-design-system/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md