openxiangda 1.0.28 → 1.0.30

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

@@ -1,499 +1,222 @@
 # OpenXiangda 样式体系参考
 
-> 本文档面向 AI Agent，提供代码页面/表单/工作流自定义节点的推荐样式基线。平台 CSS 变量与语义类是优先选择，不是唯一选择；当业务视觉、品牌表达、图表、看板、动效或复杂布局需要更精确控制时，可以使用 Tailwind 普通工具类、Tailwind 任意值、局部 CSS、页面级 CSS 变量或必要的 inline style。
-
----
-
-## 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                          │
-└──────────────────────────────────────────────────────────────┘
-```
-
-**核心原则**：平台视觉基线优先来源于 Layer 1 的 CSS Variables；AntD 与 Tailwind 默认消费这套变量。业务页面可以在 `.sy-app-workspace` 命名空间内扩展页面级样式，不要求所有视觉值都必须来自内置 Token。
-
-### 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
-
-> 推荐基线。**所有平台变量同时挂载在 `:root` 与 `.sy-app-workspace`**，前者用于全局可用，后者保证命名空间生效时不依赖根选择器。页面可以继续定义自己的局部变量，例如 `--sales-dashboard-accent`、`--kanban-column-width`。
-
-```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 扩展语义化类。语义类适合常规后台页面、表单、列表和状态展示；普通 Tailwind 工具类与任意值适合特殊布局、品牌视觉、图表容器、复杂动效和一次性精调。
-
-### 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`）和任意值（如 `grid-cols-[240px_1fr]`、`bg-[#0f766e]`）都可以使用。常规业务组件优先使用语义类，特殊页面按实际视觉需求选择更合适的 Tailwind/CSS 写法。
+> 面向 AI Agent 的代码页、表单页和自定义节点样式基线。默认直接使用 Tailwind 原生工具类和 Tailwind 任意值；平台 token 是兼容能力和平台组件内部能力，不是业务页面的强制范式。
 
 ---
 
-## 5. 推荐顺序与硬边界
+## 1. 默认规则
 
-| # | 场景 | 推荐做法 | 允许的扩展 |
-|---|---|---|---|
-| 1 | 常规后台、列表、表单、详情页 | 优先用语义类、平台 CSS 变量和 antd token，保证与平台一致 | 可用 `p-4`、`gap-6`、`text-sm` 等 Tailwind 普通类做快速布局 |
-| 2 | 品牌化首页、门户、看板、数据大屏、营销视觉 | 按视觉目标设计，不要为了套 Token 牺牲效果 | 可用 Tailwind 任意值、CSS 渐变、图片背景、页面级变量、局部 CSS |
-| 3 | 精确布局、复杂 Grid、图表容器、动效 | Tailwind 普通类/任意值和 `styles.css` 都可以直接使用 | 例如 `grid-cols-[280px_1fr]`、`h-[calc(100vh-64px)]`、`transition-[height]` |
-| 4 | 需要运行时动态值 | 少量 inline style 可以使用，尤其是动态尺寸、颜色、坐标、图表变量 | 避免把大段静态样式写进 inline style，静态样式优先放到 class/CSS |
-| 5 | antd 主题 | 优先通过 `ConfigProvider.theme`、CSS 变量和 `className` 控制 | 如确实要覆盖内部 class，必须限定在页面命名空间内，并接受升级风险 |
-| 6 | antd 弹层、Drawer、Modal、DatePicker、Select | 这是硬要求：通过 `getPopupContainer` 锚定到 `.sy-app-workspace` 或就近容器 | 否则弹层可能丢样式或被宿主页面污染 |
-| 7 | CSS 作用域 | 这是硬要求：业务 CSS 必须在 `.sy-app-workspace` 或页面根类下收敛作用域 | 避免写全局裸选择器污染宿主平台 |
+1. **业务页面默认写原生 Tailwind**：优先使用 `bg-white`、`border`、`border-slate-200`、`text-slate-600`、`shadow-sm`、`rounded-lg`、`p-4`、`gap-4`、`grid-cols-[240px_1fr]` 这类 Tailwind 原生类和任意值。
+2. **不要强制平台 token**：不要把 `bg-container`、`text-secondary`、`rounded-form`、`shadow-card` 当默认示例或默认范式。历史项目或平台组件需要时可以兼容使用，但新业务页面不推荐主动依赖。
+3. **不要直接套 shadcn token**：`bg-card`、`text-muted-foreground`、`text-foreground`、`bg-background` 等不是 Tailwind 原生类。除非项目已经在 `tailwind.config.cjs` 明确配置这些 token，否则必须改成 Tailwind 原生类或任意值。
+4. **保留 OpenXiangda 隔离能力**：Tailwind 仍通过 `.sy-app-workspace` namespace 输出，workspace 仍扫描 `openxiangda` 包内容，平台组件 safelist 仍保留。
+5. **CSS 作用域要收敛**：页面级 CSS 写在 `styles.css`，选择器限定在 `.sy-app-workspace` 或页面根类下，避免污染宿主平台。
 
 ---
 
-## 6. 推荐示例与可接受变体
+## 2. 推荐写法
 
-### 示例 1：主操作按钮的容器
+### 2.1 页面容器
 
 ```tsx
-// 常规后台表单：推荐用语义类 + antd 组件
-<div className="bg-container p-form rounded-form">
-  <Button type="primary">提交</Button>
-</div>
-
-// 品牌化或特殊视觉：可以使用 Tailwind 任意值 / 自定义 CSS
-<div style={{ background: '#fff', padding: 24, borderRadius: 6 }}>
-  <button style={{ background: '#1677ff', color: '#fff' }}>提交</button>
-</div>
+export function DashboardPage() {
+  return (
+    <main className="min-h-screen bg-slate-50 px-6 py-5 text-slate-900">
+      <section className="rounded-lg border border-slate-200 bg-white p-5 shadow-sm">
+        <h1 className="text-xl font-semibold">排队预约</h1>
+        <p className="mt-1 text-sm text-slate-600">查看排队申请、安排上机时间、处理冲突。</p>
+      </section>
+    </main>
+  );
+}
 ```
 
-### 示例 2：表单字段布局
+### 2.2 卡片和状态
 
 ```tsx
-// 推荐：表单语义类
-<div className="flex flex-col gap-form p-form">
-  <Input />
-  <Input />
+<div className="rounded-lg border border-slate-200 bg-white p-4 shadow-sm">
+  <div className="text-sm text-slate-500">待分配</div>
+  <div className="mt-2 text-2xl font-semibold text-amber-700">2</div>
 </div>
 
-// 可接受：特殊布局精调用 Tailwind 普通类 / 任意值
-<div className="flex flex-col gap-[18px] p-6">
-  <Input className="h-[32px]" />
-  <Input className="h-[32px]" />
-</div>
+<span className="inline-flex rounded-full bg-emerald-50 px-2 py-0.5 text-xs font-medium text-emerald-700">
+  已完成
+</span>
 ```
 
-### 示例 3：状态文案
+### 2.3 精确布局和品牌色
 
 ```tsx
-// 推荐：平台状态语义
-<span className="text-success">已通过</span>
-<span className="text-error">已驳回</span>
+<div className="grid min-h-[calc(100vh-64px)] grid-cols-[280px_1fr] gap-5">
+  <aside className="border-r border-slate-200 bg-white" />
+  <section className="bg-[#f7fafc] p-6" />
+</div>
 
-// 可接受：页面专属状态色
-<span className="text-[#16a34a]">已通过</span>
-<span style={{ color: riskLevelColor }}>风险等级</span>
+<button className="rounded-md bg-[#1677ff] px-4 py-2 text-sm font-medium text-white hover:bg-[#0958d9]">
+  提交
+</button>
 ```
 
-### 示例 4：卡片容器
+### 2.4 局部 CSS
 
-```tsx
-// 推荐：语义类
-<div className="bg-container shadow-card rounded-card">...</div>
-
-// 可接受：特殊卡片视觉
-<div style={{
-  background: '#fff',
-  boxShadow: '0 6px 16px rgba(0,0,0,0.08)',
-  borderRadius: 8
-}}>...</div>
+```css
+.sy-app-workspace .queue-booking-page {
+  min-height: 100%;
+  background: #f8fafc;
+}
+
+.sy-app-workspace .queue-booking-page__calendar-grid {
+  display: grid;
+  grid-template-columns: repeat(7, minmax(120px, 1fr));
+  gap: 12px;
+}
 ```
 
-### 示例 5：次要文本 + 提示
+---
 
-```tsx
-// 推荐：层级语义
-<p className="text-secondary text-sm-sy">提示信息</p>
+## 3. Tailwind 配置要求
+
+OpenXiangda workspace 的 `tailwind.config.cjs` 必须保留：
+
+```js
+const openxiangdaPath = require("node:path");
+const openxiangdaPresetModule = require("openxiangda/tailwind-preset");
+const openxiangdaPreset =
+  openxiangdaPresetModule.default ?? openxiangdaPresetModule;
 
-// 可接受：需要匹配图表或品牌视觉时直接设定
-<p className="text-[13px] text-slate-500">提示信息</p>
+function resolveOpenXiangdaContent() {
+  try {
+    const packagePath = require.resolve("openxiangda");
+    const distDir = openxiangdaPath.dirname(packagePath);
+    return [openxiangdaPath.join(distDir, "..", "**/*.{js,mjs,cjs}")];
+  } catch {
+    return [];
+  }
+}
+
+const openxiangdaContent = resolveOpenXiangdaContent();
+
+module.exports = {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+    ...openxiangdaContent,
+  ],
+  blocklist: ["[-:T]", "[-:TZ.]"],
+  presets: [openxiangdaPreset],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};
 ```
 
-### 示例 6：自定义代码节点的 CSS（局部样式表）
+这个配置的作用：
+
+- `openxiangdaPreset` 保留 `.sy-app-workspace` namespace、平台组件 safelist 和平台组件需要的工具类。
+- `...openxiangdaContent` 确保平台组件内部 class 会被 Tailwind 扫描到。
+- `blocklist` 避免 Tailwind 误生成日期字符串相关的异常类。
+
+不要为了“更自由”移除这些平台构建能力；自由写 Tailwind 原生类和保留构建隔离能力并不冲突。
+
+---
+
+## 4. 入口 CSS 要求
+
+`src/index.css` 默认只需要 Tailwind 指令和少量基础样式：
 
 ```css
-/* 避免：全局裸选择器，容易污染宿主页面 */
-.my-node-card {
-  background: #ffffff;
-  border: 1px solid #d9d9d9;
-  padding: 16px;
+@layer tailwind-base {
+  @tailwind base;
+}
+
+@tailwind components;
+@tailwind utilities;
+
+* {
+  box-sizing: border-box;
 }
 
-/* 推荐：限定在平台命名空间或页面根类下 */
-.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);
+body {
+  margin: 0;
+  min-width: 320px;
+  background: #f8fafc;
+  color: #0f172a;
+  font-family:
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    sans-serif;
 }
 
-/* 可接受：页面专属视觉值，只要作用域收敛 */
-.sy-app-workspace .sales-dashboard .my-node-card {
-  background: linear-gradient(135deg, #0f766e, #0ea5e9);
-  border-radius: 14px;
-  padding: 20px;
+#root {
+  min-height: 100dvh;
 }
 ```
-
----
-
-## 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` |
+
+`openxiangda/styles/tokens.css` 不再是新业务页面的默认依赖。旧项目已经引入时可以保留，或在确实需要平台 CSS 变量统一主题时手动引入。
+
+---
+
+## 5. Ant Design 和弹层
+
+PC 控件优先用 `antd`，移动端控件优先用 `antd-mobile`。弹层必须挂到当前页面容器或 `.sy-app-workspace` 内，避免宿主平台污染或滚动容器裁切：
+
+```tsx
+<ConfigProvider
+  getPopupContainer={(trigger) =>
+    trigger?.closest('.sy-app-workspace') ??
+    (document.querySelector('.sy-app-workspace') as HTMLElement) ??
+    document.body
+  }
+>
+  <App />
+</ConfigProvider>
+```
+
+局部组件也可以使用 `getPopupContainer={(trigger) => trigger.parentElement ?? document.body}`。不要无作用域覆盖 `.ant-select-selector`、`.ant-modal` 等私有 class；确实需要覆盖时限定在页面根类下。
+
+---
+
+## 6. 平台 Token 兼容说明
+
+OpenXiangda 仍保留部分平台语义类和 CSS 变量，主要用于：
+
+- 平台标准表单、数据管理列表、审批时间线等组件内部样式。
+- 老项目兼容。
+- 多应用统一主题或深度主题定制。
+
+常见兼容类包括 `text-primary`、`text-secondary`、`bg-container`、`bg-layout`、`border-secondary`、`rounded-form`、`shadow-card` 等。AI 编写新业务页面时不要默认使用这些类；除非用户明确要求跟随平台变量主题，或当前项目已有一致的 token 体系。
+
+如果需要统一主题，推荐把主题限制在 `.sy-app-workspace` 或应用根类下：
+
+```css
+.sy-app-workspace.theme-brand {
+  --sy-color-primary: #0f766e;
+  --sy-radius-md: 8px;
+}
+```
+
+---
+
+## 7. 构建期提醒
+
+OpenXiangda 构建会扫描源码里的 shadcn token 类。如果发现 `bg-card`、`text-muted-foreground`、`text-foreground` 等类，但项目没有显式配置对应 token，会输出 warning。
+
+收到 warning 时优先修正为：
+
+- Tailwind 原生类：`bg-white border border-slate-200 text-slate-600`
+- Tailwind 任意值：`bg-[#1677ff] text-[13px] grid-cols-[240px_1fr]`
+- 或在 `tailwind.config.cjs` 中显式配置这些 shadcn token
+
+warning 不会阻断构建，但它通常意味着页面会出现“颜色、边框、文本层级异常”的视觉问题。
+
+---
+
+## 8. 提交前检查
+
+- [ ] 页面样式默认使用 Tailwind 原生类和任意值，而不是平台 token 类？
+- [ ] 没有使用未配置的 shadcn token 类，例如 `bg-card`、`text-muted-foreground`、`text-foreground`？
+- [ ] `tailwind.config.cjs` 保留 OpenXiangda preset、content 扫描和 blocklist？
+- [ ] 业务 CSS 限定在 `.sy-app-workspace` 或页面根类下？
+- [ ] antd / antd-mobile 弹层设置了合适的挂载容器？