Tailwind CSS & shadcn/ui 设计系统构建指南：从设计令牌到组件库

tailwind-design-system by giuseppe-trisciuoglio/developer-kit

221 周安装量

193 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill tailwind-design-system

UI组件库 CSS 前端架构

🇨🇳中文介绍

Tailwind CSS & shadcn/ui 设计系统

概述

使用 Tailwind CSS (v4.1+) 和 shadcn/ui 创建和管理集中式设计系统的专家指南。此技能提供了结构化的工作流程，用于定义设计令牌、使用 CSS 变量配置主题，以及基于 shadcn/ui 基础组件构建一致的 UI 组件库。

与其他技能的关系：

tailwind-css-patterns 涵盖实用优先的样式设计、响应式设计和一般的 Tailwind CSS 使用
shadcn-ui 涵盖单个组件的安装、配置和实现
本技能 专注于系统级的编排：设计令牌、主题化基础设施、组件包装模式，并确保整个应用程序的一致性

使用时机

使用 Tailwind CSS 和 shadcn/ui 从头开始建立新的设计系统
将设计令牌（颜色、排版、间距、圆角、阴影）定义为 CSS 变量
使用集中式主题系统（浅色/深色模式）配置 globals.css
将 shadcn/ui 组件包装成具有强制约束的设计系统基础组件
构建令牌驱动的组件库以实现一致的 UI
从基于 JavaScript 的 Tailwind 配置迁移到 CSS 优先的配置 (v4.1+)
使用 oklch 格式建立颜色调色板以实现感知均匀性
创建超越浅色/深色的多主题支持（例如，品牌主题）

使用说明

步骤 1：初始化设计系统配置

评估项目：检查是否已安装 Tailwind CSS 和 shadcn/ui
创建 globals.css：使用设计令牌设置中心 CSS 文件
配置 Tailwind：使用 @theme 指令 (v4.1+) 或 (v3)

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 2：定义设计令牌

设计令牌是基础。在 globals.css 中将它们定义为 CSS 自定义属性：

颜色：品牌调色板、语义颜色、表面颜色
排版：字体系列、大小、粗细、行高
间距：一致的间距比例
边框：圆角、宽度
阴影：层级阴影
动画：过渡持续时间和缓动函数

步骤 3：配置主题化基础设施

设置浅色/深色模式支持，并通过 @theme inline 将令牌暴露给 Tailwind。

步骤 4：包装 shadcn/ui 组件

创建强制使用令牌并提供一致 API 的设计系统基础组件。

步骤 5：文档化与验证

创建动态样式指南，并验证整个代码库中的令牌使用情况。

包含设计令牌的完整 globals.css

查看 references/globals.css.example 获取一个完整的、可用于生产的 globals.css 示例，其中配置了所有设计令牌。

添加自定义令牌的快速示例：

:root {
  --warning: oklch(0.84 0.16 84);
  --warning-foreground: oklch(0.28 0.07 46);
}

.dark {
  --warning: oklch(0.41 0.11 46);
  --warning-foreground: oklch(0.99 0.02 95);
}

@theme inline {
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
}

用法：<div className="bg-warning text-warning-foreground">警告</div>

将 shadcn/ui 组件包装为设计系统基础组件

创建强制使用令牌的受约束设计系统组件。查看 references/component-wrapping.md 获取完整示例，包括 Button、Text 和 Stack 基础组件。

import { Button as ShadcnButton } from "@/components/ui/button";

export function Button({ variant = "primary", size = "md", ...props }) {
  const variantMap = { primary: "default", secondary: "secondary" };
  const sizeMap = { sm: "sm", md: "default", lg: "lg" };
  return (
    <ShadcnButton
      variant={variantMap[variant]}
      size={sizeMap[size]}
      {...props}
    />
  );
}

对于需要超越浅色/深色的多个品牌主题的应用程序：

[data-theme="ocean"] {
  --primary: oklch(0.55 0.18 230);
  --primary-foreground: oklch(0.985 0 0);
}

[data-theme="forest"] {
  --primary: oklch(0.50 0.15 145);
  --primary-foreground: oklch(0.985 0 0);
}



const [theme, setTheme] = useState("light");
useEffect(() => {
  document.documentElement.setAttribute("data-theme", theme);
}, [theme]);

验证所有必需的令牌是否已定义：

#!/bin/bash
REQUIRED=("--background" "--foreground" "--primary" "--primary-foreground")
for token in "${REQUIRED[@]}"; do
  grep -q "$token:" src/styles/globals.css || echo "Missing: $token"
done

oklch 颜色格式：使用 oklch 实现感知均匀性。并非所有浏览器都原生支持 oklch；如果目标浏览器较旧，请检查兼容性
令牌命名：遵循 shadcn/ui 约定（--primary、--primary-foreground）以实现无缝集成
@theme inline 与 @theme：将 CSS 变量桥接到 Tailwind 实用程序时使用 @theme inline；直接定义令牌时使用 @theme
组件包装：保持包装组件精简。仅添加强制执行设计系统规则的约束；避免重复 shadcn/ui 逻辑
深色模式：始终为 :root 中的每个令牌定义深色模式值。缺少深色令牌会导致视觉回归
CSS 变量作用域：在 :root 中定义的令牌是全局的。使用 [data-theme] 选择器实现多主题且无冲突
性能：避免过多的 CSS 自定义属性链。每个 var() 查找都会增加最小但非零的开销
Tailwind v4 与 v3：@theme 指令和 @theme inline 是 v4.1+ 的功能。对于 v3 项目，请使用带有 theme.extend 的 tailwind.config.js

单一事实来源：所有设计令牌都存在于 globals.css 中。切勿在组件中硬编码颜色值
语义化命名：使用基于用途的名称（--primary、--destructive），而不是基于外观的名称（--blue-500、--red-600）
前景色配对：每个背景令牌必须有一个匹配的 -foreground 令牌以确保对比度合规
令牌比例：为自定义调色板定义完整的比例（50-950）以提供灵活性
组件桶式导出：从单个 index.ts 导出所有设计系统组件以实现简洁的导入
可访问性：确保所有令牌对（背景/前景）满足 WCAG AA 对比度要求（文本 4.5:1，大文本 3:1）
记录令牌：为团队维护所有令牌的视觉参考
一致的间距：通过设计系统组件使用 Tailwind 的间距比例（gap-2、gap-4、gap-6），而不是任意值

Tailwind CSS v4 主题配置：https://tailwindcss.com/docs/theme
Tailwind CSS 函数与指令：https://tailwindcss.com/docs/functions-and-directives
shadcn/ui 主题指南：https://ui.shadcn.com/docs/theming
shadcn/ui 安装（手动）：https://ui.shadcn.com/docs/installation/manual
oklch 色彩空间：https://oklch.com

🇺🇸English

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

Assess the project : Check if Tailwind CSS and shadcn/ui are already installed
Create the globals.css : Set up the central CSS file with design tokens
Configure Tailwind : Use the @theme directive (v4.1+) or tailwind.config.js (v3)
Install shadcn/ui : Initialize with the CLI and configure the theme

Step 2: Define Design Tokens

Design tokens are the foundation. Define them as CSS custom properties in globals.css:

Colors : Brand palette, semantic colors, surface colors
Typography : Font families, sizes, weights, line heights
Spacing : Consistent spacing scale
Borders : Radius, widths
Shadows : Elevation levels
Animations : Transition durations and easing functions

Step 3: Configure Theming Infrastructure

Set up light/dark mode support and expose tokens to Tailwind via @theme inline.

Step 4: Wrap shadcn/ui Components

Create design system primitives that enforce token usage and provide consistent API.

Step 5: Document and Validate

Create a living style guide and validate token usage across the codebase.

Examples

Complete globals.css with Design Tokens

See references/globals.css.example for a complete, production-ready globals.css with all design tokens configured.

Quick example for adding custom tokens:

:root {
  --warning: oklch(0.84 0.16 84);
  --warning-foreground: oklch(0.28 0.07 46);
}

.dark {
  --warning: oklch(0.41 0.11 46);
  --warning-foreground: oklch(0.99 0.02 95);
}

@theme inline {
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
}

Usage: <div className="bg-warning text-warning-foreground">Warning</div>

Wrapping shadcn/ui Components as Design System Primitives

Create constrained design system components that enforce token usage. See references/component-wrapping.md for complete examples including Button, Text, and Stack primitives.

Quick example:

import { Button as ShadcnButton } from "@/components/ui/button";

export function Button({ variant = "primary", size = "md", ...props }) {
  const variantMap = { primary: "default", secondary: "secondary" };
  const sizeMap = { sm: "sm", md: "default", lg: "lg" };
  return (
    <ShadcnButton
      variant={variantMap[variant]}
      size={sizeMap[size]}
      {...props}
    />
  );
}

Multi-Theme Support

For applications requiring multiple brand themes beyond light/dark:

[data-theme="ocean"] {
  --primary: oklch(0.55 0.18 230);
  --primary-foreground: oklch(0.985 0 0);
}

[data-theme="forest"] {
  --primary: oklch(0.50 0.15 145);
  --primary-foreground: oklch(0.985 0 0);
}



const [theme, setTheme] = useState("light");
useEffect(() => {
  document.documentElement.setAttribute("data-theme", theme);
}, [theme]);

Design Token Validation

Verify all required tokens are defined:

#!/bin/bash
REQUIRED=("--background" "--foreground" "--primary" "--primary-foreground")
for token in "${REQUIRED[@]}"; do
  grep -q "$token:" src/styles/globals.css || echo "Missing: $token"
done

Constraints and Warnings

oklch color format : Use oklch for perceptual uniformity. Not all browsers support oklch natively; check compatibility if targeting older browsers
Token naming : Follow the shadcn/ui convention (--primary, --primary-foreground) for seamless integration
@theme inline vs @theme: Use @theme inline when bridging CSS variables to Tailwind utilities; use @theme for direct token definition
Component wrapping : Keep wrapper components thin. Only add constraints that enforce design system rules; avoid duplicating shadcn/ui logic
Dark mode : Always define dark mode values for every token in :root. Missing dark tokens cause visual regressions
CSS variable scoping : Tokens defined in :root are global. Use selectors for multi-theme without conflicts

Best Practices

Single source of truth : All design tokens live in globals.css. Never hardcode color values in components
Semantic naming : Use purpose-based names (--primary, --destructive) not appearance-based (--blue-500, --red-600)
Foreground pairing : Every background token must have a matching -foreground token for contrast compliance
Token scale : Define a complete scale for custom palettes (50-950) to provide flexibility
Component barrel exports : Export all DS components from a single index.ts for clean imports
Accessibility : Ensure all token pairs (background/foreground) meet WCAG AA contrast (4.5:1 for text, 3:1 for large text)
Document tokens : Maintain a visual reference of all tokens for the team

References

Tailwind CSS v4 Theme Configuration: https://tailwindcss.com/docs/theme
Tailwind CSS Functions and Directives: https://tailwindcss.com/docs/functions-and-directives
shadcn/ui Theming Guide: https://ui.shadcn.com/docs/theming
shadcn/ui Installation (Manual): https://ui.shadcn.com/docs/installation/manual
oklch Color Space: https://oklch.com

Weekly Installs

155

Repository

giuseppe-trisci…oper-kit

GitHub Stars

173

First Seen

Feb 26, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

gemini-cli136

codex136

github-copilot133

cursor132

opencode132

amp131

TanStack Table 中文指南：React 无头表格库，实现排序过滤分页

500 周安装

Performance : Avoid excessive CSS custom property chains. Each var() lookup adds minimal but non-zero overhead

Tailwind v4 vs v3 : The @theme directive and @theme inline are v4.1+ features. For v3 projects, use tailwind.config.js with theme.extend

Consistent spacing : Use Tailwind's spacing scale (gap-2, gap-4, gap-6) through DS components rather than arbitrary values