openxiangda 1.0.28 → 1.0.30

package/openxiangda-skills/references/component-guide.md

@@ -9,7 +9,7 @@
 1. **平台组件优先**：所有平台组件已经接入了组织架构、文件存储、权限、多端适配等平台能力，重写一遍 = 丢能力 + 后续无法维护。
 2. **基于 antd / antd-mobile 包装**：自定义组件必须站在 antd 之上，保证 PC 和移动端的基础体验一致。
 3. **成熟能力先调研开源方案**：图表、动画、拖拽、虚拟列表、富文本、日历、导入导出、复杂表格等，不要直接手写。先查当前项目依赖、官方文档和维护状态，再决定使用库或轻量封装。
-4. **样式优先走变量与语义类**：常规后台体验优先使用 CSS 变量、Tailwind 语义类和 Ant Design token；当业务视觉需要时，可以使用 Tailwind 普通类、任意值、局部 CSS、页面级变量或少量动态 inline style。
+4. **样式默认走 Tailwind 原生类**：业务页面默认使用 Tailwind 原生工具类和任意值；平台变量、平台语义类和 Ant Design token 主要用于平台组件、主题兼容或确实需要统一主题时，不作为业务页面的强制范式。
 5. **谨慎覆盖组件内部 class**：组件库内部类名（`ant-select-selector` 等）是私有 API，下个版本就可能变；确实需要覆盖时要限定页面作用域，并优先考虑组件 props、`className`、CSS 变量或 `ConfigProvider`。
 
 ---
@@ -86,7 +86,7 @@ import {
 
 ## 4. 自定义组件开发规范
 
-### 4.1 推荐：基于 antd 包装 + CSS 变量 + 语义类
+### 4.1 推荐：基于 antd 包装 + 原生 Tailwind 类
 
 ```tsx
 import { Select, SelectProps } from 'antd';
@@ -100,8 +100,8 @@ interface CustomSelectProps extends Omit<SelectProps, 'options'> {
 
 export function CustomSelect({ options, className, ...rest }: CustomSelectProps) {
   return (
-    <Select
-      className={clsx('w-full rounded-form', className)}
+    <Select
+      className={clsx('w-full rounded-md', className)}
       popupClassName="sy-app-workspace"
       getPopupContainer={(trigger) => trigger.parentElement ?? document.body}
       options={options}
@@ -115,7 +115,7 @@ export function CustomSelect({ options, className, ...rest }: CustomSelectProps)
 - 透传 `...rest`，保留 antd 全部 API。
 - `popupClassName="sy-app-workspace"` 确保弹层应用平台样式作用域。
 - `getPopupContainer` 解决弹层被裁切问题（详见第 7 节常见错误）。
-- 使用 `w-full`、`rounded-form` 等语义类作为默认基线；如果组件视觉需要精调，可以继续使用 Tailwind 普通类、任意值或局部 CSS。
+- 使用 `w-full`、`rounded-md`、`text-slate-600`、`border-slate-200` 等 Tailwind 原生类作为默认基线；如果组件视觉需要精调，可以继续使用 Tailwind 任意值或局部 CSS。
 
 ### 4.2 错误：从头实现选择器
 
@@ -146,7 +146,7 @@ function BadSelect({ options }) {
 
 按推荐顺序由轻到重：
 
-1. **className 注入 Tailwind 语义类**
+1. **className 注入 Tailwind 原生类**
    ```tsx
    <UserSelectField className="w-full max-w-md" />
    ```
@@ -162,7 +162,7 @@ function BadSelect({ options }) {
    }
    ```
 
-   > 优先覆盖 `style-system.md` 中定义的 `--sy-color-*`、`--sy-radius-*`、`--sy-spacing-*` 等平台变量。需要页面专属视觉时，可以新增页面级 CSS 变量，建议加业务前缀，避免与平台变量冲突。
+   > 平台变量可用于统一主题或平台组件兼容，但业务页面不必为了使用 token 牺牲视觉效果。需要页面专属视觉时，可以新增页面级 CSS 变量，建议加业务前缀，避免与平台变量冲突。
 
 3. **antd `ConfigProvider` 主题**
    ```tsx
@@ -207,7 +207,7 @@ export function ActionButton(props) {
 | 用 `<input type="file">` 上传 | 用 `AttachmentField` / `ImageField` |
 | 用第三方富文本（TinyMCE 等） | 用 `EditorField` |
 | 自己写列表 + 分页 + 导出 | 用 `DataManagementList` |
-| 常规组件大量写 `style={{ color: '#333', padding: 16 }}` | 优先 Tailwind 语义类、普通工具类、CSS 变量或局部 CSS；动态值和少量精调 inline style 可接受 |
+| 常规组件大量写 `style={{ color: '#333', padding: 16 }}` | 优先 Tailwind 原生工具类、任意值或局部 CSS；动态值和少量精调 inline style 可接受 |
 | Select / Date / Modal 弹层错位、被滚动容器裁切 | 加 `getPopupContainer={(trigger) => trigger.parentElement}`，并在弹层 `popupClassName` 上加 `sy-app-workspace` |
 | 不分端，PC 组件直接放移动端 | 按端拆页 + 端内用对应 UI 库 |
 | 无作用域覆盖 `.ant-xxx` 内部 class | 优先用 `className`、CSS 变量或 `ConfigProvider` 主题；必要覆盖时限定到页面命名空间 |
@@ -219,6 +219,6 @@ export function ActionButton(props) {
 
 - [ ] 涉及人员 / 部门 / 文件 / 图片 / 富文本 / 签名 / 地图 / 列表 → 用了平台组件？
 - [ ] 自定义组件 → 基于 antd / antd-mobile 包装并透传 props？
-- [ ] 样式 → 常规区域优先 Tailwind 语义类 / CSS 变量 / ConfigProvider；特殊视觉用 Tailwind 任意值、局部 CSS 或页面级变量且作用域收敛？
+- [ ] 样式 → 默认用 Tailwind 原生类 / 任意值 / 局部 CSS；平台 token 只在主题兼容或平台组件需要时使用，且作用域收敛？
 - [ ] 弹层 → 设置了 `getPopupContainer` 与 `sy-app-workspace` 弹层样式作用域？
 - [ ] 多端 → PC 用 antd、Mobile 用 antd-mobile，业务逻辑共享？