ui-styling

UI 样式技能

综合性技能，用于创建美观且无障碍的用户界面，结合 shadcn/ui 组件、Tailwind CSS 实用类样式，以及基于画布的视觉设计系统。

参考资料

• shadcn/ui：https://ui.shadcn.com/llms.txt
• Tailwind CSS：https://tailwindcss.com/docs

何时使用此技能

适用于以下场景：

• 使用基于 React 的框架（Next.js、Vite、Remix、Astro）构建 UI
• 实现无障碍组件（对话框、表单、表格、导航）
• 采用实用类优先的方式编写样式
• 创建响应式、移动优先的布局
• 实现深色模式与主题定制
• 使用统一的设计令牌构建设计系统
• 生成视觉设计、海报或品牌物料
• 通过即时视觉反馈快速原型开发
• 添加复杂的 UI 模式（数据表格、图表、命令面板）

核心技术栈

组件层：shadcn/ui

• 基于 Radix UI 原语的预构建无障碍组件
• 复制粘贴式分发模式（组件存放在你的代码库中）
• 以 TypeScript 为先，具备完整类型安全
• 可组合的原语，用于构建复杂 UI
• 基于 CLI 的安装与管理

样式层：Tailwind CSS

• 实用类优先的 CSS 框架
• 构建时处理，无运行时开销
• 移动优先的响应式设计
• 统一的设计令牌（颜色、间距、排版）
• 自动清除未使用的代码

视觉设计层：Canvas

• 博物馆级别的视觉构图
• 以设计理念为驱动的设计方法
• 精致的视觉表达
• 文字精简，视觉冲击力最大化
• 系统化的图案与精炼的美学

脚本路径

本技能及其 references/ 中的脚本路径，均相对于包含 SKILL.md 的目录，而非项目目录：scripts/<file> 指本技能自身的 scripts/ 文件夹，../<skill>/scripts/<file> 指与其一同安装的同级子技能。请从该目录构建完整路径（Claude Code 在加载技能时会将其报告为该技能的基础目录），并将工作目录保持在项目根目录。这些脚本会相对于项目根目录读写项目文件，例如 docs/brand-guidelines.md、assets/design-tokens.json 或 src/。

快速开始

组件 + 样式设置

安装带 Tailwind 的 shadcn/ui：

npx shadcn@latest init

CLI 会询问框架、TypeScript、路径和主题偏好。此过程会同时配置 shadcn/ui 与 Tailwind CSS。

添加组件：

npx shadcn@latest add button card dialog form

结合实用类样式使用组件：

import { Button } from "@/components/ui/button"
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"

export function Dashboard() {
  return (
    <div className="container mx-auto p-6 grid gap-6 md:grid-cols-2 lg:grid-cols-3">
      <Card className="hover:shadow-lg transition-shadow">
        <CardHeader>
          <CardTitle className="text-2xl font-bold">Analytics</CardTitle>
        </CardHeader>
        <CardContent className="space-y-4">
          <p className="text-muted-foreground">View your metrics</p>
          <Button variant="default" className="w-full">
            View Details
          </Button>
        </CardContent>
      </Card>
    </div>
  )
}

替代方案：仅使用 Tailwind

Vite 项目：

npm install -D tailwindcss @tailwindcss/vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite'
export default { plugins: [tailwindcss()] }

/* src/index.css */
@import "tailwindcss";

组件库指南

完整的组件目录，包含使用模式、安装方法与组合示例。

参见：references/shadcn-components.md

涵盖内容：

• 表单与输入组件（Button、Input、Select、Checkbox、Date Picker、表单校验）
• 布局与导航（Card、Tabs、Accordion、Navigation Menu）
• 浮层与对话框（Dialog、Drawer、Popover、Toast、Command）
• 反馈与状态（Alert、Progress、Skeleton）
• 展示组件（Table、Data Table、Avatar、Badge）

主题与定制

主题配置、CSS 变量、深色模式实现与组件定制。

参见：references/shadcn-theming.md

涵盖内容：

• 使用 next-themes 设置深色模式
• CSS 变量系统
• 颜色定制与调色板
• 组件变体定制
• 主题切换实现

无障碍模式

ARIA 模式、键盘导航、屏幕阅读器支持以及无障碍组件的使用。

参见：references/shadcn-accessibility.md

涵盖内容：

• Radix UI 的无障碍特性
• 键盘导航模式
• 焦点管理
• 屏幕阅读器播报
• 表单校验的无障碍处理

Tailwind 工具类

用于布局、间距、排版、颜色、边框和阴影的核心工具类。

参见：references/tailwind-utilities.md

涵盖：

• 布局工具类（Flexbox、Grid、定位）
• 间距系统（padding、margin、gap）
• 排版（字号、字重、对齐方式、行高）
• 颜色与背景
• 边框与阴影
• 用于自定义样式的任意值

响应式设计

移动优先断点、响应式工具类与自适应布局。

参见：references/tailwind-responsive.md

涵盖：

• 移动优先方法
• 断点系统（sm、md、lg、xl、2xl）
• 响应式工具类模式
• 容器查询
• 最大宽度查询
• 自定义断点

Tailwind 自定义

配置文件结构、自定义工具类、插件与主题扩展。

参见：references/tailwind-customization.md

涵盖：

• 用于自定义 token 的 @theme 指令
• 自定义颜色与字体
• 间距与断点扩展
• 自定义工具类的创建
• 自定义变体
• 样式分层组织（@layer base、components、utilities）
• 用于提取组件的 apply 指令

视觉设计系统

基于画布的设计理念、视觉传达原则与精致的构图。

参见：references/canvas-design-system.md

涵盖：

• 设计理念方法
• 以视觉传达代替文字
• 系统化模式与构图
• 色彩、形态与空间设计
• 少量文字的融合
• 博物馆级别的执行标准
• 多页面设计系统

实用脚本

用于组件安装与配置生成的 Python 自动化脚本。

shadcn_add.py

添加 shadcn/ui 组件并处理依赖：

python scripts/shadcn_add.py button card dialog

tailwind_config_gen.py

根据自定义主题生成 tailwind.config.js：

python scripts/tailwind_config_gen.py --colors brand:blue --fonts display:Inter

当同目录下已存在 tailwind.config.js、.cjs、.mjs 或 .ts 文件时，生成器会拒绝创建或替换配置。请先检查报告中的配置文件，只有在确实需要保留冲突输出时，才传入 --force：

python scripts/tailwind_config_gen.py --colors brand:blue --force

最佳实践

1. 组件组合：由简单、可组合的基础单元构建复杂界面
2. 工具类优先的样式：直接使用 Tailwind 类名，只有在确实重复时才提取组件
3. 移动优先的响应式：从移动端样式开始，逐层叠加响应式变体
4. 无障碍优先：利用 Radix UI 基础组件，添加焦点状态，使用语义化 HTML
5. 设计 Token：统一使用间距刻度、调色板和排版系统
6. 深色模式一致性：为所有带主题的元素应用深色变体
7. 性能：利用自动 CSS 清除机制，避免动态类名
8. TypeScript：使用完整的类型安全，提升开发体验
9. 视觉层级：让构图引导注意力，有意识地使用间距与颜色
10. 匠心工艺：每个细节都很重要，把 UI 当作一门手艺来对待

参考导航

组件库

• references/shadcn-components.md：完整的组件目录
• references/shadcn-theming.md：主题与自定义
• references/shadcn-accessibility.md：无障碍模式

样式系统

• references/tailwind-utilities.md：核心工具类
• references/tailwind-responsive.md：响应式设计
• references/tailwind-customization.md：配置与扩展

视觉设计

• references/canvas-design-system.md：设计理念与画布工作流

自动化

• scripts/shadcn_add.py：组件安装
• scripts/tailwind_config_gen.py：配置生成

常见模式

带校验的表单：

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { Button } from "@/components/ui/button"

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8)
})

export function LoginForm() {
  const form = useForm({
    resolver: zodResolver(schema),
    defaultValues: { email: "", password: "" }
  })

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(console.log)} className="space-y-6">
        <FormField control={form.control} name="email" render={({ field }) => (
          <FormItem>
            <FormLabel>Email</FormLabel>
            <FormControl>
              <Input type="email" {...field} />
            </FormControl>
            <FormMessage />
          </FormItem>
        )} />
        <Button type="submit" className="w-full">Sign In</Button>
      </form>
    </Form>
  )
}

带深色模式的响应式布局：

<div className="min-h-screen bg-white dark:bg-gray-900">
  <div className="container mx-auto px-4 py-8">
    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
      <Card className="bg-white dark:bg-gray-800 border-gray-200 dark:border-gray-700">
        <CardContent className="p-6">
          <h3 className="text-xl font-semibold text-gray-900 dark:text-white">
            Content
          </h3>
        </CardContent>
      </Card>
    </div>
  </div>
</div>

资源

• shadcn/ui 文档：https://ui.shadcn.com
• Tailwind CSS 文档：https://tailwindcss.com
• Radix UI：https://radix-ui.com
• Tailwind UI：https://tailwindui.com
• Headless UI：https://headlessui.com
• v0（AI UI 生成器）：https://v0.dev