react-tailwind

用途

使用此技能可将 React 项目转变为结构良好、由 Tailwind 驱动的 UI，也可将现有的 Tailwind 配置重构为更简洁、基于设计令牌的样式和可复用模式。

你可以协助完成以下工作：

• 在 React 工具链中安装和接入 Tailwind
• 规划和管理依赖（Tailwind + 插件 + 组件库）
• 在 tailwind.config 中设计语义化令牌层（颜色、间距、排版、圆角、阴影）
• 将组件从临时编写的 CSS 重构为 Tailwind 工具类
• 应用经过验证的 UI 方案（表单、数据表格、导航、模态框、布局基础组件）

始终假定用户需要实用、可直接复制粘贴的步骤，以及具体的组件示例。

检测 React + 构建配置

提供命令或代码之前，先检测应用的构建方式，并据此调整说明：

• 如果 package.json 中有 react-scripts：按 Create React App 处理。
• 如果 devDependencies 或脚本中有 vite：按 Vite React 处理。
• 如果出现 next：按 Next.js 处理（如果存在 app/，则使用 App Router；否则使用 Pages Router）。
• 如果没有 react-scripts/vite/next：按使用 webpack 或类似工具的通用 React SPA 处理；提供与框架无关的指导。

不确定时，默认采用 类似 Vite 的 Tailwind 配置，并明确说明如何调整：

• 说明要更新哪些配置文件（tailwind.config.js、postcss.config.js、入口 CSS）。
• 适用时分别提供 npm 和 yarn 命令。

安装与配置流程

在 React 项目中设置 Tailwind 时，始终遵循以下顺序：

1. 添加依赖
   • 核心依赖：tailwindcss postcss autoprefixer
   • 对于暗色模式和主题，使用 Tailwind 核心功能；只有在用户需要预构建方案时，才添加 UI 库（例如 @headlessui/react、@heroicons/react、Radix 等）。
   • 构建时使用的包优先放在 devDependencies 中。
2. 初始化 Tailwind
   • 根据检测到的工具链运行推荐的初始化命令（例如 npx tailwindcss init -p）。
   • 确保已创建或更新 tailwind.config.* 和 postcss.config.*。
3. 配置 content 路径
   • 包含所有 React 源码根目录，例如：
     • ./index.html（如果使用 Vite）
     • ./src/**/*.{js,ts,jsx,tsx}
     • Next.js 项目使用 ./app/**/*.{js,ts,jsx,tsx,mdx} 和/或 ./pages/**/*.{js,ts,jsx,tsx}。
   • 避免使用范围过大的 glob，以免包含 node_modules 或构建产物。
4. 在 CSS 中接入 Tailwind
   • 创建或更新全局 CSS 文件（例如 src/index.css、src/globals.css、app/globals.css），内容包括：
     • @tailwind base;
     • @tailwind components;
     • @tailwind utilities;
   • 确保此 CSS 在应用入口处（main.tsx、_app.tsx、layout.tsx 等）只导入一次。
5. 验证集成
   • 指导用户添加一个简单的测试工具类（例如 className="text-red-500"），并确认它能正确渲染。
   • 如果失败，请检查：
     • 是否缺少 content 路径
     • 是否未导入 CSS
     • 是否存在冲突的 CSS 框架（例如 Bootstrap），并建议迁移或共存方案。

安装额外的 UI 库（例如 Tailwind UI、Headless UI、Radix）时，始终遵循以下要求：

• 在 Tailwind 核心功能正常运行后再添加这些库。
• 检查并说明对等依赖（例如 React 版本、@floating-ui）。
• 明确给出安装命令和导入位置。

Tailwind 配置与语义化令牌

目标是设计语义化主题层，而不是到处散落原始品牌颜色和间距。

编辑 tailwind.config.* 时：

• 按语义用途组织 theme.colors 和 theme.extend.colors，而非按字面品牌十六进制颜色名称组织。
• 使用中性色 + 主色/次色 + 反馈色阶：

// Example shape – adapt values and names to user brand
theme: {
  extend: {
    colors: {
      bg: {
        canvas: '#020617',
        subtle: '#0b1120',
        elevated: '#020617'
      },
      border: {
        subtle: '#1e293b',
        strong: '#475569',
        focus: '#38bdf8'
      },
      text: {
        primary: '#e5e7eb',
        secondary: '#9ca3af',
        muted: '#6b7280',
        danger: '#fecaca'
      },
      primary: {
        DEFAULT: '#38bdf8',
        foreground: '#0f172a',
        soft: '#0ea5e9'
      },
      danger: {
        DEFAULT: '#ef4444',
        subtle: '#fee2e2'
      },
      success: {
        DEFAULT: '#22c55e',
        subtle: '#dcfce7'
      }
    },
    borderRadius: {
      sm: '0.375rem',
      md: '0.5rem',
      lg: '0.75rem',
      xl: '1rem'
    },
    boxShadow: {
      soft: '0 1px 2px 0 rgba(15,23,42,0.35)',
      raised: '0 10px 30px rgba(15,23,42,0.6)'
    }
  }
}

指南：

• 优先使用基于用途的名称（bg.canvas、text.secondary、border.focus），而非原始品牌名称。
• 将现有 CSS 变量（如果有）映射到 Tailwind 主题键，以保留原有行为。
• 对于深色/浅色模式：
  • 优先使用 Tailwind dark 类策略（darkMode: 'class'）。
  • 指导用户使用 React 状态或小型主题 Hook，在 html/body/根元素上切换 dark 类。

每当引入或更改令牌时，也要展示一到两个使用这些令牌的组件片段，让用户看到具体用法。

组件改造工作流

当用户希望用 Tailwind“改造”或“现代化”组件时：

1. 审查组件
   • 请用户提供或检查现有的 JSX + CSS。
   • 确认：
     • 布局原语（堆叠、网格、侧边栏、卡片）
     • 排版层级（标题、标签、正文）
     • 交互元素（按钮、链接、输入框）
2. 设计 Tailwind 结构
   • 用 Tailwind 原语（flex、grid、gap、space-y-*、max-w-*、overflow-*）替换布局 CSS。
   • 将 CSS 变量或设计令牌映射到 Tailwind 主题键。
   • 将重复模式封装为小型可复用组件（例如 Button、Card、Input、Modal）。
3. 渐进式重构
   • 从一次一个组件开始（例如单个表单或卡片列表）。
   • 保持行为和 props 稳定；只更改 JSX 结构和类。
4. 提取共享构件
   • 发现重复的类组合后，建议使用：
     • 带有 className 扩展钩子的 React 组件。
     • 用于组合类名的实用函数（例如 clsx、cva）。
5. 检查无障碍性
   • 确保保留或改进角色、 aria 属性和焦点环。
   • 使用语义化边框/焦点令牌演示焦点样式。

尽可能始终提供前后对比片段：旧版 JSX/CSS 与 Tailwind 驱动的 JSX。

常见 UI 配方

使用这些模式作为起点，并根据用户的主题调整令牌。优先使用语义化 Tailwind 令牌（例如 bg-bg-elevated、text-text-secondary）；如果没有，则回退到常见默认值。

表单

目标：间距一致、标签与输入框对齐清晰、焦点样式易于访问、错误文本清晰。

表单模式：

• 将每个字段放在具有较小 gap 的纵向堆叠布局中。
• 使用带有 htmlFor 的标签，并保持排版一致。
• 输入框使用：
  • 全宽 w-full
  • 语义化背景、边框和焦点令牌
  • 适当的圆角和柔和阴影

重构时，确保：

• 错误状态使用语义化危险色令牌（例如 border-danger、text-danger）。
• 禁用状态降低不透明度并移除悬停样式。

数据表格

目标：行易读、密度可控、排序/选择提示清晰。

表格模式：

• 使用滚动容器：overflow-x-auto，并添加响应式内边距。
• 表格基础样式：min-w-full divide-y divide-border-subtle。
• 表头：
  • 使用对比度柔和的背景（例如 bg-bg-subtle）。
  • 可按需使用大写或小型大写字母，并设置字距。
  • 使用 text-text-secondary 减少视觉干扰。
• 行：
  • divide-y divide-border-subtle。
  • 悬停：hover:bg-bg-subtle/60。
  • 已选中：bg-primary/5 border-l-2 border-primary。

对于行内操作，建议使用：

• 带有无障碍标签的行内图标按钮。
• 清晰的间距（space-x-2）和点击区域（p-1.5–p-2）。

导航（顶栏 + 侧边栏）

导航布局：

• 使用 shell 布局，其中包含：
  • 顶栏：flex items-center justify-between h-14 px-4 border-b border-border-subtle bg-bg-elevated。
  • 侧边栏（可选）：hidden md:flex md:w-64 md:flex-col border-r border-border-subtle bg-bg-subtle。
  • 主区域：flex-1 overflow-y-auto p-4 md:p-6。

导航项：

• 基础样式：flex items-center gap-2 rounded-md px-2.5 py-2 text-sm font-medium。
• 默认文本：text-text-secondary。
• 激活状态：bg-bg-elevated text-text-primary。
• 悬停状态：hover:bg-bg-elevated/70 hover:text-text-primary。

优先将导航分组为配置对象数组（包含 label、icon、href、active），再映射到 JSX；这样之后更容易调整样式。

模态框 / 对话框

为确保模态框的可访问性：

• 尽可能使用无头库或基于原语的库（例如 @headlessui/react 或 Radix Dialog）。
• 如果手动实现，务必包含：
  • ARIA 角色（role="dialog"、aria-modal="true"）。
  • 焦点陷阱和 Escape 键处理。
  • 带透明度的背景遮罩。

样式：

• 遮罩：fixed inset-0 bg-black/60 backdrop-blur-sm。
• 容器：fixed inset-0 flex items-center justify-center px-4。
• 面板：
  • w-full max-w-lg rounded-lg bg-bg-elevated shadow-raised p-6
  • 使用令牌化的颜色和间距。

模态框中的按钮应复用应用的主按钮 / 次按钮组件，而不是临时编写类名。

依赖管理与安装顺序

当用户要求“设置 Tailwind”或“添加 Tailwind 组件”时，请明确列出操作顺序：

1. 确保已安装 React + 打包工具依赖（React、ReactDOM、框架专用工具）。
2. 安装 Tailwind + PostCSS + Autoprefixer，并将其作为 devDependencies。
3. 初始化 Tailwind 配置 + PostCSS 配置。
4. 将 Tailwind CSS 接入应用入口文件并进行验证。
5. 如有需要，引入组件库或无头原语：
   • 安装库。
   • 如有需要，导入样式（某些库包含基础 CSS）。
   • 展示如何将其与 Tailwind 类和主题令牌集成。
6. 逐步重构现有组件，从以下部分开始：
   • 按钮和排版。
   • 表单。
   • 布局外壳（导航、侧边栏、主内容）。
   • 数据密集型视图（表格、列表、详情面板）。

始终确保 package.json 与建议保持同步（devDependencies 与 dependencies），并在相关时指出所需的 Node 或 React 版本。

常见问题及处理方法

调试 Tailwind + React 设置时，请检查以下问题：

• 类样式未生效
  • content glob 未匹配文件路径或扩展名。
  • 包含 @tailwind 指令的 CSS 文件没有在任何地方导入。
  • 构建缓存；建议重启开发服务器或清除缓存。
• 生产构建未应用样式或只应用了部分样式
  • content 路径错误，导致过度清除样式。
  • 以 Purge 无法检测的方式动态构造类；建议：
    • 在代码中使用规范的类名。
    • 提取变体类名映射，而不是根据任意输入拼接完整字符串。
• 与其他框架冲突
  • 旧版全局 CSS（例如 Bootstrap）覆盖了 Tailwind；建议：
    • 逐步移除冲突的导入。
    • 尽可能为旧版 CSS 添加命名空间。
• 设计不一致
  • 颜色和间距反复临时设置；建议：
    • 整合到 Tailwind 语义令牌中。
    • 将重复的类名组合重构为共享组件。

修复或诊断问题时，请提供一份简短的检查清单，方便用户下次重新检查（例如“验证配置路径、CSS 导入和开发服务器重启情况”）。