openxiangda 1.0.27 → 1.0.29

package/openxiangda-skills/SKILL.md

@@ -144,7 +144,7 @@ Workflow / automation / permissions:
 Platform domain knowledge (read these first when generating forms or pages so the output matches the live platform behavior):
 
 - `references/platform-data-model.md` — how the platform persists field values (JSONB, `{label, value}` for option fields, attachment shape, etc.). Use this whenever you write, render, or diagnose form data.
-- `references/style-system.md` — three-layer style architecture, CSS namespace, and the no-hardcoded-color rule. Use this before writing any page or form CSS.
+- `references/style-system.md` — three-layer style architecture, CSS namespace, and flexible Tailwind/CSS guidance. Use this before writing substantial page or form CSS.
 - `references/architecture-patterns.md` — CRUD data flow, `DataManagementList` pattern, recommended directory layout for `src/pages` and `src/forms`. Use this before scaffolding a new page or list view.
 - `references/best-practices.md` — read this before implementing app-level business patterns; it points to `examples/best-practices/` and explains when to use status fields instead of workflow.
 - `references/component-guide.md` — when to pick platform components vs. raw Ant Design vs. custom components, with the rules for option fields. Use this before introducing a new component.

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

@@ -9,8 +9,8 @@
 1. **平台组件优先**：所有平台组件已经接入了组织架构、文件存储、权限、多端适配等平台能力，重写一遍 = 丢能力 + 后续无法维护。
 2. **基于 antd / antd-mobile 包装**：自定义组件必须站在 antd 之上，保证 PC 和移动端的基础体验一致。
 3. **成熟能力先调研开源方案**：图表、动画、拖拽、虚拟列表、富文本、日历、导入导出、复杂表格等，不要直接手写。先查当前项目依赖、官方文档和维护状态，再决定使用库或轻量封装。
-4. **样式走变量与语义类**：使用 CSS 变量、Tailwind 语义类，**禁止**在 JSX 中硬编码颜色、间距、字号、圆角。
-5. **不覆盖组件内部 class**：组件库内部类名（`ant-select-selector` 等）是私有 API，下个版本就可能变。
+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` 等语义类，不写 `style={{ width: '100%' }}`。
+- 使用 `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-*` 等变量名，自创变量不会生效。
+   > 平台变量可用于统一主题或平台组件兼容，但业务页面不必为了使用 token 牺牲视觉效果。需要页面专属视觉时，可以新增页面级 CSS 变量，建议加业务前缀，避免与平台变量冲突。
 
 3. **antd `ConfigProvider` 主题**
    ```tsx
@@ -171,7 +171,7 @@ function BadSelect({ options }) {
    </ConfigProvider>
    ```
 
-4. **禁止**：直接覆盖组件内部 class（`.ant-select-selector { ... }`）—— fragile，升级即坏。
+4. **谨慎**：直接覆盖组件内部 class（`.ant-select-selector { ... }`）属于私有 API，升级风险较高。确实需要时必须限定在页面根类或 `.sy-app-workspace` 下，并优先考虑 `ConfigProvider`、`className`、组件 props 或 CSS 变量是否能解决。
 
 ---
 
@@ -207,10 +207,10 @@ export function ActionButton(props) {
 | 用 `<input type="file">` 上传 | 用 `AttachmentField` / `ImageField` |
 | 用第三方富文本（TinyMCE 等） | 用 `EditorField` |
 | 自己写列表 + 分页 + 导出 | 用 `DataManagementList` |
-| `style={{ color: '#333', padding: 16 }}` 硬编码 | Tailwind 语义类或 CSS 变量 |
+| 常规组件大量写 `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` 主题 |
+| 无作用域覆盖 `.ant-xxx` 内部 class | 优先用 `className`、CSS 变量或 `ConfigProvider` 主题；必要覆盖时限定到页面命名空间 |
 | 在自定义组件中不透传 `...rest` / `ref` | 透传 props 与 `forwardRef`，保留底层组件全部能力 |
 
 ---
@@ -219,6 +219,6 @@ export function ActionButton(props) {
 
 - [ ] 涉及人员 / 部门 / 文件 / 图片 / 富文本 / 签名 / 地图 / 列表 → 用了平台组件？
 - [ ] 自定义组件 → 基于 antd / antd-mobile 包装并透传 props？
-- [ ] 样式 → 全部走 Tailwind 语义类 / CSS 变量 / ConfigProvider，无硬编码？
+- [ ] 样式 → 默认用 Tailwind 原生类 / 任意值 / 局部 CSS；平台 token 只在主题兼容或平台组件需要时使用，且作用域收敛？
 - [ ] 弹层 → 设置了 `getPopupContainer` 与 `sy-app-workspace` 弹层样式作用域？
 - [ ] 多端 → PC 用 antd、Mobile 用 antd-mobile，业务逻辑共享？