ONE-OS/axhub-make/rules/theme-guide.md

主题指南（Design Tokens + Tailwind CSS + 演示页）

本文档约束"主题"的生成产物与实现方式，供 AI 在用户提供任意形式输入（token、设计规范文档、截图、样式提取结果等）时，稳定产出可用的主题文件与演示页面。

🎯 交付物

每个主题推荐生成以下文件（根据信息完整度灵活调整）：

src/themes/<theme-key>/
├── globals.css             # Tailwind CSS 定义（可选，优先使用）
├── designToken.json        # 主题 Token（可选，兼容传统模式）
├── DESIGN.md          # 设计规范文档（可选，信息充分时推荐）
├── index.tsx               # 主题演示页（必需）
├── components/             # 演示组件 2-3 个（推荐）
│   ├── Button.tsx
│   ├── Card.tsx
│   └── Input.tsx
└── templates/              # 页面模板 2-3 个（推荐）
    ├── LoginTemplate.tsx
    └── DashboardTemplate.tsx

约束：

• <theme-key> 使用 kebab-case（如 antd、my-brand、trae-dark）
• 二选一原则：globals.css 和 designToken.json 只生成一个，避免维护负担。
• 优先 Tailwind CSS：默认生成 globals.css（现代化、易维护）。
• 例外情况：仅当使用场景明确不支持 Tailwind CSS 时，才生成 designToken.json。
• 禁止干扰性依赖：主题演示页不得引入与该主题/设计系统无关的 UI 库，以免影响视觉表达。默认只使用原生 HTML + CSS Variables（或该设计系统指定的组件库）。

1) globals.css 规范 (Tailwind CSS)

这是主题的核心定义文件（若生成）。

1.1 格式要求

• 使用 CSS Variables 定义主题变量（:root 和 .dark）。
• 支持 Tailwind CSS v4 语法（如 @theme inline）。
• 必须包含基础配色、圆角、字体等定义。

示例结构：

@import "tailwindcss";

/* 自定义变体 */
@custom-variant dark (&:is(.dark *));

:root {
  /* 基础色变量 */
  --background: #ffffff;
  --foreground: #000000;
  --primary: #3b82f6;
  /* ... */
}

.dark {
  /* 深色模式变量 */
  --background: #000000;
  --foreground: #ffffff;
  /* ... */
}

@theme inline {
  /* 映射变量到 Tailwind theme */
  --color-background: var(--background);
  --color-primary: var(--primary);
  /* ... */
}

2) designToken.json 规范

2.1 必须字段

• name：主题名称（必需，字符串，用于 UI 展示与演示页标题）

推荐字段：

• description：主题描述（字符串）
• token：Ant Design 风格的 Token 对象（如果存在 globals.css，推荐引用变量如 var(--primary)）

2.2 何时生成

仅在以下情况生成 designToken.json：

• 使用场景明确不支持 Tailwind CSS（如纯 JS 环境、特定框架限制）
• 用户明确要求使用 JSON Token 格式
• 需要与不支持 CSS Variables 的组件库集成

默认情况下优先生成 globals.css，避免维护两套配置。

3) DESIGN.md 规范（设计规范文档）

可选但推荐的产物，用于系统化记录主题的设计价值、使用约束和实现细节。

3.1 推荐结构

参考 src/themes/firecrawl/DESIGN.md，包含：

• 设计系统价值（品牌定位、核心价值、设计原则）
• 能力边界（适合/不适合的场景）
• 色彩/字体/间距/圆角/阴影/图标系统
• 组件规范（Button、Card、Input 等样式规范）
• 使用约束（必须遵守、建议做法、禁止做法）

3.2 生成策略

• 信息充分时生成完整文档
• 信息不足时可省略或生成简化版本

4) index.tsx（主题演示页）规范

主题演示页的目标：在本项目环境中直观看到主题 token 的内容与效果。

4.1 基本约束

• 文件必须 export default Component
• 按需引入：
  • 如果有 globals.css，必须 import './globals.css';
  • 如果有 designToken.json，导入并使用它。
  • 如果有 DESIGN.md，在演示页中提供查看入口。
• 演示页应展示主题效果。
• 默认只使用原生 HTML 元素（div/button/input 等）与 CSS Variables 展示效果。

4.2 演示内容优先级

1. 优先自定义演示：根据当前主题的设计规范，从零创建符合该主题风格的演示页面、组件和模板
2. 避免照搬已有主题：不要直接参考或复制其他主题的演示页面，因为它们是按各自设计规范定制的

4.3 注入方式

• 若有 globals.css：使用 CSS 变量展示（推荐）。
• 若有 designToken.json：通过 ConfigProvider 注入。
• 不会同时存在两者（避免维护负担）。

5) components/ 规范（演示组件）

推荐生成 2-3 个核心组件（如 Button、Card、Input），展示主题在具体 UI 组件上的应用效果。

5.1 组件结构

import React from 'react';

interface ComponentSectionProps {
  tokens: Record<string, any>;
}

export const ButtonSection: React.FC<ComponentSectionProps> = ({ tokens }) => {
  return (
    <div className="space-y-8 animate-in fade-in duration-500">
      <div>
        <h1 className="text-3xl font-bold mb-2">按钮 Button</h1>
        <p className="text-neutral-600">按钮用于开始一个即时操作。</p>
      </div>
      <div className="canvas-panel p-8">
        {/* 展示多种变体、尺寸、状态 */}
      </div>
    </div>
  );
};

5.2 演示内容

• 多种变体（primary、secondary、ghost 等）
• 多种尺寸（large、default、small）
• 多种状态（normal、hover、disabled、loading）

6) templates/ 规范（页面模板）

推荐生成 2-3 个典型页面（如登录页、仪表盘、表单页），展示主题在完整页面场景中的应用效果。

6.1 推荐模板类型

模板类型	适用场景	展示重点
登录页	通用	表单、按钮、品牌展示
仪表盘	数据密集型产品	卡片、图表、数据展示
表单页	业务系统	表单组件、布局、验证
列表页	内容管理	表格、筛选、分页

6.2 模板要求

• 展示完整的页面布局和交互流程
• 使用真实/模拟数据
• 严格遵循主题的设计规范

7) 输入来源与生成策略

优先级原则：用户提供 > 项目主题 > 默认设计指导

用户输入可能包含：

• Tailwind CSS 文件或配置（最高优先级）
• CSS 变量定义
• JSON Token
• 设计规范文档或截图

7.1 生成策略（按输入类型）

1. 用户提供 CSS/Tailwind：

   • 必须生成 globals.css
   • 不生成 designToken.json（除非明确不支持 TW）
   • 推荐生成 DESIGN.md + 组件 + 模板

2. 用户提供 JSON Token：

   • 必须生成 designToken.json
   • 不生成 globals.css（除非用户要求迁移到 TW）
   • 推荐生成 DESIGN.md + 组件 + 模板

3. 用户提供设计规范文档：

   • 必须生成 DESIGN.md
   • 优先生成 globals.css（现代化方案）
   • 生成符合规范的组件和模板

4. 截图提取/无明确格式：

   • 默认生成 globals.css（推荐）
   • 尽量生成 DESIGN.md + 组件 + 模板

7.2 默认设计指导（兜底方案）

仅在以下条件同时满足时查阅：

• 用户未提供设计规范文档
• 项目中无可复用的主题
• 需要设计风格指导

参考文档（渐进式披露）：

业务场景	参考文档	判断依据
基础型界面 / ToB / 工具类	/skills/third-party/interface-design/SKILL.md	• 目标用户：企业员工或专业用户 • 使用频率：高频操作 • 核心任务：完成工作、处理数据、执行操作
风格化页面 / ToC / App / 移动端	/skills/third-party/frontend-design/SKILL.md	• 目标用户：普通消费者或品牌受众 • 使用频率：低频浏览或内容消费 • 核心任务：获取信息、建立品牌感知、提升视觉吸引力
混合场景	基础区用 /skills/third-party/interface-design/SKILL.md，展示区用 /skills/third-party/frontend-design/SKILL.md	核心功能简洁稳定，展示区域可适度风格化

重要：不要提前加载设计指导文档，仅在真正需要且无其他参考时查阅。

8) 开发后验收流程

8.1 运行验收脚本

node scripts/check-app-ready.mjs /themes/[主题名]

8.2 根据状态处理

• 状态为 ERROR：根据错误信息修复。
• 状态为 READY：访问预览 URL，检查主题展示效果（颜色、字体、深色模式切换等）。