openxiangda 1.0.0

package/openxiangda-skills/references/style-system.md

@@ -0,0 +1,492 @@
+# OpenXiangda 样式体系参考
+
+> 本文档面向 AI Agent，约束代码页面/表单/工作流自定义节点的样式编写规范。**严禁硬编码颜色、间距、圆角、字号、阴影**，统一通过三层变量体系消费设计 Token。
+
+---
+
+## 1. 样式体系总览
+
+### 1.1 三层结构
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ Layer 3: Tailwind Utilities (原子类层)                       │
+│   语义化类名 → 引用 CSS Variables                            │
+│   例: text-primary, bg-container, gap-form, rounded-form     │
+└──────────────────────────────────────────────────────────────┘
+                              ▲
+                              │ 引用
+                              │
+┌──────────────────────────────────────────────────────────────┐
+│ Layer 2: AntD Theme Token (组件库层)                         │
+│   ConfigProvider.theme.token → 映射到 CSS Variables          │
+│   例: colorPrimary: var(--sy-color-primary)                  │
+└──────────────────────────────────────────────────────────────┘
+                              ▲
+                              │ 映射
+                              │
+┌──────────────────────────────────────────────────────────────┐
+│ Layer 1: CSS Variables (基础层 / Single Source of Truth)     │
+│   --sy-color-*, --sy-spacing-*, --sy-radius-*, --sy-shadow-* │
+│   定义在 :root 与 .sy-app-workspace                          │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**核心原则**：所有视觉 Token 来源于 Layer 1 的 CSS Variables；AntD 与 Tailwind 都只是 Layer 1 的消费者。
+
+### 1.2 为什么不使用 Shadow DOM
+
+| 维度 | Shadow DOM | CSS Namespace（当前方案）|
+|---|---|---|
+| antd 弹层（Modal/Drawer/Select 下拉/DatePicker）| **失效** —— 默认挂载到 `document.body`，逃出 Shadow 边界后丢失样式 | **正常** —— 通过 `getPopupContainer` 挂载到 `.sy-app-workspace` 内 |
+| 全局样式继承 | 完全隔离，需重写所有基础样式 | 受控隔离，通过命名空间避免冲突 |
+| 调试体验 | DevTools 跨边界困难 | 与普通 DOM 一致 |
+| 主题切换 | 必须穿透 Shadow Root | 直接覆盖 `.sy-app-workspace` 上的 CSS 变量 |
+
+**结论**：Shadow DOM 与 antd 的 Portal 弹层机制不兼容；改用 `.sy-app-workspace` 命名空间方案。
+
+### 1.3 CSS Namespace 隔离原理
+
+- 应用根节点统一加 `class="sy-app-workspace"`。
+- 所有自定义样式（Tailwind、业务 CSS）通过 `.sy-app-workspace` 前缀限定作用域。
+- AntD CSS-in-JS 通过 `ConfigProvider.theme.cssVar.prefix = 'sy-ant'` 输出独立变量名，避免与宿主页面碰撞。
+- 弹层容器通过 `getPopupContainer={() => document.querySelector('.sy-app-workspace')}` 锚定到命名空间内部。
+
+---
+
+## 2. Layer 1：CSS Variables 设计 Token
+
+> 唯一真源（Single Source of Truth）。**所有变量同时挂载在 `:root` 与 `.sy-app-workspace`**，前者用于全局可用，后者保证命名空间生效时不依赖根选择器。
+
+```css
+:root, .sy-app-workspace {
+  /* ───── 品牌色 ───── */
+  --sy-color-primary: #1677ff;
+  --sy-color-primary-hover: #4096ff;
+  --sy-color-primary-active: #0958d9;
+  --sy-color-success: #52c41a;
+  --sy-color-warning: #faad14;
+  --sy-color-error: #ff4d4f;
+
+  /* ───── 文本 ───── */
+  --sy-color-text: rgba(0, 0, 0, 0.88);
+  --sy-color-text-secondary: rgba(0, 0, 0, 0.65);
+  --sy-color-text-tertiary: rgba(0, 0, 0, 0.45);
+  --sy-color-text-disabled: rgba(0, 0, 0, 0.25);
+
+  /* ───── 背景 ───── */
+  --sy-color-bg-container: #ffffff;
+  --sy-color-bg-layout: #f5f5f5;
+  --sy-color-bg-elevated: #ffffff;
+
+  /* ───── 边框 ───── */
+  --sy-color-border: #d9d9d9;
+  --sy-color-border-secondary: #f0f0f0;
+
+  /* ───── 间距 ───── */
+  --sy-spacing-xs: 4px;
+  --sy-spacing-sm: 8px;
+  --sy-spacing-md: 16px;
+  --sy-spacing-lg: 24px;
+  --sy-spacing-xl: 32px;
+
+  /* ───── 圆角 ───── */
+  --sy-radius-sm: 4px;
+  --sy-radius-md: 6px;
+  --sy-radius-lg: 8px;
+
+  /* ───── 字体 ───── */
+  --sy-font-size-sm: 12px;
+  --sy-font-size-base: 14px;
+  --sy-font-size-lg: 16px;
+  --sy-font-size-xl: 20px;
+  --sy-font-size-2xl: 24px;
+
+  /* ───── 阴影 ───── */
+  --sy-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.03), 0 1px 6px -1px rgba(0, 0, 0, 0.02);
+  --sy-shadow-md: 0 6px 16px rgba(0, 0, 0, 0.08), 0 3px 6px -4px rgba(0, 0, 0, 0.12);
+  --sy-shadow-lg: 0 12px 40px rgba(0, 0, 0, 0.12);
+
+  /* ───── 表单特定 ───── */
+  --sy-form-gap: 16px;
+  --sy-form-padding: 24px;
+  --sy-form-field-height: 32px;
+}
+```
+
+### 2.1 Token 速查表
+
+| 类别 | 变量 | 默认值 | 用途 |
+|---|---|---|---|
+| 品牌 | `--sy-color-primary` | `#1677ff` | 主按钮、主色链接、激活态 |
+| 品牌 | `--sy-color-primary-hover` | `#4096ff` | 主色 hover |
+| 品牌 | `--sy-color-primary-active` | `#0958d9` | 主色 active/pressed |
+| 状态 | `--sy-color-success` | `#52c41a` | 成功/通过 |
+| 状态 | `--sy-color-warning` | `#faad14` | 警示 |
+| 状态 | `--sy-color-error` | `#ff4d4f` | 错误/危险操作 |
+| 文本 | `--sy-color-text` | `rgba(0,0,0,.88)` | 主文本 |
+| 文本 | `--sy-color-text-secondary` | `rgba(0,0,0,.65)` | 次文本 |
+| 文本 | `--sy-color-text-tertiary` | `rgba(0,0,0,.45)` | 提示/占位 |
+| 文本 | `--sy-color-text-disabled` | `rgba(0,0,0,.25)` | 禁用 |
+| 背景 | `--sy-color-bg-container` | `#ffffff` | 卡片/输入框 |
+| 背景 | `--sy-color-bg-layout` | `#f5f5f5` | 页面底色 |
+| 背景 | `--sy-color-bg-elevated` | `#ffffff` | 浮层/抽屉 |
+| 边框 | `--sy-color-border` | `#d9d9d9` | 实体边框 |
+| 边框 | `--sy-color-border-secondary` | `#f0f0f0` | 分隔线 |
+| 间距 | `--sy-spacing-{xs\|sm\|md\|lg\|xl}` | 4/8/16/24/32 | 通用间距 |
+| 圆角 | `--sy-radius-{sm\|md\|lg}` | 4/6/8 | 通用圆角 |
+| 字号 | `--sy-font-size-{sm\|base\|lg\|xl\|2xl}` | 12/14/16/20/24 | 字号阶梯 |
+| 阴影 | `--sy-shadow-{sm\|md\|lg}` | 见上 | 卡片/浮层阴影 |
+| 表单 | `--sy-form-gap` | `16px` | 表单字段间距 |
+| 表单 | `--sy-form-padding` | `24px` | 表单容器内边距 |
+| 表单 | `--sy-form-field-height` | `32px` | 输入框高度 |
+
+---
+
+## 3. Layer 2：AntD Theme Token 映射
+
+通过 `ConfigProvider` 让 antd 组件读取 CSS 变量，实现"改变量即改主题"。
+
+```tsx
+import { ConfigProvider } from 'antd';
+
+export function AppThemeProvider({ children }: { children: React.ReactNode }) {
+  return (
+    <ConfigProvider
+      // 让弹层挂载到命名空间容器内（关键：保证 CSS 变量可达）
+      getPopupContainer={() =>
+        (document.querySelector('.sy-app-workspace') as HTMLElement) ?? document.body
+      }
+      theme={{
+        cssVar: { prefix: 'sy-ant' },     // 输出 --sy-ant-* 变量，避免冲突
+        hashed: false,                     // 与 cssVar 配合，禁用 hash
+        token: {
+          // 颜色
+          colorPrimary: 'var(--sy-color-primary)',
+          colorSuccess: 'var(--sy-color-success)',
+          colorWarning: 'var(--sy-color-warning)',
+          colorError: 'var(--sy-color-error)',
+          colorText: 'var(--sy-color-text)',
+          colorTextSecondary: 'var(--sy-color-text-secondary)',
+          colorTextTertiary: 'var(--sy-color-text-tertiary)',
+          colorTextDisabled: 'var(--sy-color-text-disabled)',
+          colorBgContainer: 'var(--sy-color-bg-container)',
+          colorBgLayout: 'var(--sy-color-bg-layout)',
+          colorBgElevated: 'var(--sy-color-bg-elevated)',
+          colorBorder: 'var(--sy-color-border)',
+          colorBorderSecondary: 'var(--sy-color-border-secondary)',
+
+          // 度量（antd token 不支持 var()，需用数值；通过 components 精细控制时再用 var）
+          borderRadius: 6,
+          borderRadiusLG: 8,
+          borderRadiusSM: 4,
+          fontSize: 14,
+          controlHeight: 32,
+        },
+        components: {
+          Form: { itemMarginBottom: 16 },
+          Card: { paddingLG: 24 },
+        },
+      }}
+    >
+      {children}
+    </ConfigProvider>
+  );
+}
+```
+
+> **注意**：antd token 中数值类（borderRadius/fontSize/controlHeight）需直接写数值，与 Layer 1 的 `--sy-radius-md`/`--sy-font-size-base`/`--sy-form-field-height` 保持同步即可。
+
+---
+
+## 4. Layer 3：Tailwind 语义化工具类
+
+`tailwind-preset.ts` 基于 CSS Variables 扩展语义化类，**优先使用语义类**而非数值类。
+
+### 4.1 颜色类
+
+| Tailwind 类 | 等价 CSS | 场景 |
+|---|---|---|
+| `text-primary` | `color: var(--sy-color-primary)` | 主色文本/链接 |
+| `text-success` | `color: var(--sy-color-success)` | 成功文本 |
+| `text-warning` | `color: var(--sy-color-warning)` | 警示文本 |
+| `text-error` | `color: var(--sy-color-error)` | 错误文本 |
+| `text-default` | `color: var(--sy-color-text)` | 主文本 |
+| `text-secondary` | `color: var(--sy-color-text-secondary)` | 次文本 |
+| `text-tertiary` | `color: var(--sy-color-text-tertiary)` | 提示文本 |
+| `text-disabled` | `color: var(--sy-color-text-disabled)` | 禁用文本 |
+| `bg-container` | `background: var(--sy-color-bg-container)` | 卡片底 |
+| `bg-layout` | `background: var(--sy-color-bg-layout)` | 页面底 |
+| `bg-elevated` | `background: var(--sy-color-bg-elevated)` | 浮层底 |
+| `border-default` | `border-color: var(--sy-color-border)` | 边框 |
+| `border-secondary` | `border-color: var(--sy-color-border-secondary)` | 分隔 |
+
+### 4.2 间距 / 布局类
+
+| Tailwind 类 | 等价 CSS |
+|---|---|
+| `gap-form` | `gap: var(--sy-form-gap)` |
+| `p-form` | `padding: var(--sy-form-padding)` |
+| `px-form` / `py-form` | `padding-inline / padding-block: var(--sy-form-padding)` |
+| `space-y-form > * + *` | `margin-top: var(--sy-form-gap)` |
+| `h-field` | `height: var(--sy-form-field-height)` |
+
+### 4.3 圆角 / 阴影 / 字号
+
+| Tailwind 类 | 等价 CSS |
+|---|---|
+| `rounded-form` | `border-radius: var(--sy-radius-md)` |
+| `rounded-card` | `border-radius: var(--sy-radius-lg)` |
+| `rounded-pill` | `border-radius: var(--sy-radius-sm)` |
+| `shadow-card` | `box-shadow: var(--sy-shadow-md)` |
+| `shadow-popover` | `box-shadow: var(--sy-shadow-lg)` |
+| `shadow-subtle` | `box-shadow: var(--sy-shadow-sm)` |
+| `text-sm-sy` | `font-size: var(--sy-font-size-sm)` |
+| `text-base-sy` | `font-size: var(--sy-font-size-base)` |
+| `text-lg-sy` | `font-size: var(--sy-font-size-lg)` |
+| `text-xl-sy` | `font-size: var(--sy-font-size-xl)` |
+| `text-2xl-sy` | `font-size: var(--sy-font-size-2xl)` |
+
+> 通用 Tailwind 数值类（如 `p-4`、`text-sm`）仍可使用，但**当存在语义类时优先用语义类**。
+
+---
+
+## 5. 禁止规则（AI Agent 必须遵守）
+
+| # | 规则 | 反例 | 正例 |
+|---|---|---|---|
+| 1 | **禁止硬编码颜色** | `color: #333`、`className="bg-[#1677ff]"` | `text-default`、`bg-container` 或 `var(--sy-color-primary)` |
+| 2 | **禁止硬编码间距** | `padding: 16px`、`className="p-[24px]"` | `p-form`、`var(--sy-spacing-md)` |
+| 3 | **禁止用数值类替代语义类** | `className="rounded-md gap-4"`（用于表单时）| `className="rounded-form gap-form"` |
+| 4 | **禁止内联颜色/间距** | `<div style={{ color: '#1677ff', padding: 16 }}>` | `<div className="text-primary p-form">` |
+| 5 | **禁止绕过 ConfigProvider 直接覆盖 antd 类名** | `.ant-btn { background: red }` | 通过 `theme.token.colorPrimary` 或自定义类组合 |
+| 6 | **禁止 antd 弹层挂到 body** | 默认行为 | 通过 `getPopupContainer` 锚定到 `.sy-app-workspace` |
+| 7 | **禁止在样式中假设白色/黑色背景** | `color: #fff`（在深色主题失效）| `text-default`，让 Token 决定 |
+
+---
+
+## 6. 正确示例 vs 错误示例
+
+### 示例 1：主操作按钮的容器
+
+```tsx
+// ❌ 错误：硬编码颜色 + 硬编码间距
+<div style={{ background: '#fff', padding: 24, borderRadius: 6 }}>
+  <button style={{ background: '#1677ff', color: '#fff' }}>提交</button>
+</div>
+
+// ✅ 正确：语义类 + antd 组件
+<div className="bg-container p-form rounded-form">
+  <Button type="primary">提交</Button>
+</div>
+```
+
+### 示例 2：表单字段布局
+
+```tsx
+// ❌ 错误：随意数值类
+<div className="flex flex-col gap-[16px] p-[24px]">
+  <Input className="h-[32px]" />
+  <Input className="h-[32px]" />
+</div>
+
+// ✅ 正确：表单语义类
+<div className="flex flex-col gap-form p-form">
+  <Input />
+  <Input />
+</div>
+```
+
+### 示例 3：状态文案
+
+```tsx
+// ❌ 错误：直接写颜色值
+<span style={{ color: '#52c41a' }}>已通过</span>
+<span style={{ color: '#ff4d4f' }}>已驳回</span>
+
+// ✅ 正确：状态语义类
+<span className="text-success">已通过</span>
+<span className="text-error">已驳回</span>
+```
+
+### 示例 4：卡片容器
+
+```tsx
+// ❌ 错误：阴影硬编码
+<div style={{
+  background: '#fff',
+  boxShadow: '0 6px 16px rgba(0,0,0,0.08)',
+  borderRadius: 8
+}}>...</div>
+
+// ✅ 正确：语义类
+<div className="bg-container shadow-card rounded-card">...</div>
+```
+
+### 示例 5：次要文本 + 提示
+
+```tsx
+// ❌ 错误：rgba 硬编码
+<p style={{ color: 'rgba(0,0,0,0.65)', fontSize: 12 }}>提示信息</p>
+
+// ✅ 正确：层级语义
+<p className="text-secondary text-sm-sy">提示信息</p>
+```
+
+### 示例 6：自定义代码节点的 CSS（局部样式表）
+
+```css
+/* ❌ 错误 */
+.my-node-card {
+  background: #ffffff;
+  border: 1px solid #d9d9d9;
+  padding: 16px;
+}
+
+/* ✅ 正确 */
+.sy-app-workspace .my-node-card {
+  background: var(--sy-color-bg-container);
+  border: 1px solid var(--sy-color-border);
+  padding: var(--sy-spacing-md);
+  border-radius: var(--sy-radius-md);
+}
+```
+
+---
+
+## 7. 自定义主题
+
+### 7.1 全局主题切换
+
+直接覆盖 `.sy-app-workspace` 上的 CSS 变量即可，**无需重新构建**：
+
+```css
+/* 应用 A —— 默认蓝 */
+.sy-app-workspace.theme-default {
+  --sy-color-primary: #1677ff;
+  --sy-color-primary-hover: #4096ff;
+  --sy-color-primary-active: #0958d9;
+}
+
+/* 应用 B —— 品牌绿 */
+.sy-app-workspace.theme-brand-green {
+  --sy-color-primary: #00b96b;
+  --sy-color-primary-hover: #2fd58a;
+  --sy-color-primary-active: #008a4f;
+}
+
+/* 应用 C —— 暗色 */
+.sy-app-workspace.theme-dark {
+  --sy-color-text: rgba(255, 255, 255, 0.88);
+  --sy-color-text-secondary: rgba(255, 255, 255, 0.65);
+  --sy-color-bg-container: #1f1f1f;
+  --sy-color-bg-layout: #141414;
+  --sy-color-border: #424242;
+}
+```
+
+```tsx
+// 运行时切换
+document.querySelector('.sy-app-workspace')?.classList.toggle('theme-dark');
+```
+
+由于 antd token 与 Tailwind 语义类都引用相同 CSS 变量，**变量一改，三层全变**。
+
+### 7.2 单应用差异化
+
+不同应用可在自身 workspace 入口注入差异化变量：
+
+```tsx
+// app-workspace.config.ts（应用级）
+export default {
+  theme: {
+    '--sy-color-primary': '#722ed1',
+    '--sy-radius-md': '10px',
+  }
+};
+```
+
+入口处将 `theme` 对象 inline 到根容器 `style` 上即可。
+
+---
+
+## 8. CSS Namespace 下的特殊注意事项
+
+### 8.1 根容器要求
+
+```tsx
+// 应用入口必须包裹 .sy-app-workspace
+<div className="sy-app-workspace">
+  <AppThemeProvider>
+    <YourApp />
+  </AppThemeProvider>
+</div>
+```
+
+### 8.2 Tailwind 配置（关键）
+
+`tailwind.config.cjs` 中：
+
+```js
+module.exports = {
+  important: '.sy-app-workspace',  // 所有 Tailwind 工具类都受命名空间限定
+  corePlugins: {
+    preflight: false,              // 避免污染宿主页面
+  },
+  content: ['./src/**/*.{ts,tsx}'],
+  presets: [require('./tailwind-preset')],
+};
+```
+
+`important: '.sy-app-workspace'` 让所有原子类输出形如 `.sy-app-workspace .text-primary { ... }`，自动隔离。
+
+### 8.3 antd 弹层挂载
+
+任何 `Modal` / `Drawer` / `Select` / `DatePicker` / `Tooltip` 等组件，**必须**通过 `ConfigProvider.getPopupContainer` 或局部 `getPopupContainer` 锚定到命名空间容器：
+
+```tsx
+<ConfigProvider
+  getPopupContainer={() =>
+    (document.querySelector('.sy-app-workspace') as HTMLElement) ?? document.body
+  }
+>
+  ...
+</ConfigProvider>
+```
+
+否则弹层会挂到 `document.body`，导致 CSS 变量无法继承、Tailwind 工具类失效。
+
+### 8.4 第三方组件库
+
+引入第三方组件时，若其样式依赖全局 reset，需在 `.sy-app-workspace` 内手动补齐；不要依赖 Tailwind preflight。
+
+### 8.5 字体与基础样式
+
+基础 `font-family` / `line-height` 应在 `.sy-app-workspace` 上设置一次，避免逐组件重复：
+
+```css
+.sy-app-workspace {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC',
+               'Hiragino Sans GB', 'Microsoft YaHei', sans-serif;
+  font-size: var(--sy-font-size-base);
+  color: var(--sy-color-text);
+  line-height: 1.5715;
+}
+```
+
+---
+
+## 速查 Cheatsheet
+
+| 想做什么 | 用什么 |
+|---|---|
+| 主色按钮 | `<Button type="primary">` |
+| 主色文本 | `className="text-primary"` |
+| 卡片容器 | `className="bg-container shadow-card rounded-card p-form"` |
+| 表单纵向布局 | `className="flex flex-col gap-form"` |
+| 错误状态文本 | `className="text-error"` |
+| 次要说明文本 | `className="text-secondary text-sm-sy"` |
+| 浮层背景 | `className="bg-elevated shadow-popover"` |
+| 分隔线 | `className="border-t border-secondary"` |
+| 切换主题 | 改 `.sy-app-workspace` 的 CSS 变量 |
+| 弹层挂载 | `getPopupContainer` 指向 `.sy-app-workspace` |