用途:在项目构建开始时运行一次,建立所有组件依赖的 CSS 基础。若 progress.txt 中已有 css_setup_complete: true 则直接跳过。
前置读取:./docs/DESIGN_SYSTEM.md(CSS 变量令牌与字体名)与 ./docs/TECH_STACK.md(框架与 CSS 方案)。若 TECH_STACK.md 缺失,则自动检测:存在 tailwind.config.js/ts 或 package.json 含 tailwindcss 判为 Tailwind;vite.config.* 含 CSS Modules 判为 CSS Modules;无法判断时询问用户使用 Tailwind CSS、纯 CSS 还是 CSS Modules。
版本区分:package.json 中 tailwindcss 为 ^4.* 或 >=4,或 globals.css 含 @import "tailwindcss" 判为 v4,否则 v3。v3 走全部 6 步并使用 @tailwind 指令;v4 使用 @import,无需 tailwind.config.js,自定义令牌写在 @theme {} 中;非 Tailwind 方案跳过 Tailwind 相关步骤。
主要步骤(Tailwind v3):1) 定位或创建 globals.css(常见路径 src/styles/globals.css、src/app/globals.css、src/index.css、styles/globals.css),补齐 Tailwind 指令、CSS 变量、@layer base 三部分;2) 校验 tailwind.config.js 的 content 路径覆盖所有含 Tailwind 类的文件,并检查 theme.extend 设计令牌;3) 确认根布局导入 globals.css(Next.js app/layout.tsx、pages/_app.tsx 或 Vite src/main.tsx);4) 配置字体,Next.js 优先用 next/font,Vite 等用 @import,字体只在根布局或 globals.css 导入一次;5) 将 DESIGN_SYSTEM.md 的 CSS 变量写入 :root 与 .dark;6) 在 progress.txt 写入 css_setup_complete、日期与 globals_css_path,并输出完成报告。
限制与常见问题:Tailwind 类不生成需检查 content 路径;自定义颜色不生效检查 theme.extend.colors;字体异常检查根布局字体变量类;暗色模式失效检查 darkMode: 'class';CSS 变量未定义检查根布局是否导入 globals.css;标题字号错误检查 @layer base 中的 h1-h6 样式。资料未提供具体收费、平台与效果信息。