openxiangda 1.0.27 → 1.0.28

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. **样式优先走变量与语义类**：常规后台体验优先使用 CSS 变量、Tailwind 语义类和 Ant Design token；当业务视觉需要时，可以使用 Tailwind 普通类、任意值、局部 CSS、页面级变量或少量动态 inline style。
+5. **谨慎覆盖组件内部 class**：组件库内部类名（`ant-select-selector` 等）是私有 API，下个版本就可能变；确实需要覆盖时要限定页面作用域，并优先考虑组件 props、`className`、CSS 变量或 `ConfigProvider`。
 
 ---
 
@@ -86,7 +86,7 @@ import {
 
 ## 4. 自定义组件开发规范
 
-### 4.1 正确：基于 antd 包装 + CSS 变量 + 语义类
+### 4.1 推荐：基于 antd 包装 + CSS 变量 + 语义类
 
 ```tsx
 import { Select, SelectProps } from 'antd';
@@ -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-form` 等语义类作为默认基线；如果组件视觉需要精调，可以继续使用 Tailwind 普通类、任意值或局部 CSS。
 
 ### 4.2 错误：从头实现选择器
 
@@ -162,7 +162,7 @@ function BadSelect({ options }) {
    }
    ```
 
-   > 覆盖时只能使用 `style-system.md` 中定义的 `--sy-color-*`、`--sy-radius-*`、`--sy-spacing-*` 等变量名，自创变量不会生效。
+   > 优先覆盖 `style-system.md` 中定义的 `--sy-color-*`、`--sy-radius-*`、`--sy-spacing-*` 等平台变量。需要页面专属视觉时，可以新增页面级 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 变量或局部 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 变量 / ConfigProvider；特殊视觉用 Tailwind 任意值、局部 CSS 或页面级变量且作用域收敛？
 - [ ] 弹层 → 设置了 `getPopupContainer` 与 `sy-app-workspace` 弹层样式作用域？
 - [ ] 多端 → PC 用 antd、Mobile 用 antd-mobile，业务逻辑共享？

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

@@ -1,6 +1,6 @@
-# OpenXiangda 样式体系参考
-
-> 本文档面向 AI Agent，约束代码页面/表单/工作流自定义节点的样式编写规范。**严禁硬编码颜色、间距、圆角、字号、阴影**，统一通过三层变量体系消费设计 Token。
+# OpenXiangda 样式体系参考
+
+> 本文档面向 AI Agent，提供代码页面/表单/工作流自定义节点的推荐样式基线。平台 CSS 变量与语义类是优先选择，不是唯一选择；当业务视觉、品牌表达、图表、看板、动效或复杂布局需要更精确控制时，可以使用 Tailwind 普通工具类、Tailwind 任意值、局部 CSS、页面级 CSS 变量或必要的 inline style。
 
 ---
 
@@ -32,7 +32,7 @@
 └──────────────────────────────────────────────────────────────┘
 ```
 
-**核心原则**：所有视觉 Token 来源于 Layer 1 的 CSS Variables；AntD 与 Tailwind 都只是 Layer 1 的消费者。
+**核心原则**：平台视觉基线优先来源于 Layer 1 的 CSS Variables；AntD 与 Tailwind 默认消费这套变量。业务页面可以在 `.sy-app-workspace` 命名空间内扩展页面级样式，不要求所有视觉值都必须来自内置 Token。
 
 ### 1.2 为什么不使用 Shadow DOM
 
@@ -54,9 +54,9 @@
 
 ---
 
-## 2. Layer 1：CSS Variables 设计 Token
-
-> 唯一真源（Single Source of Truth）。**所有变量同时挂载在 `:root` 与 `.sy-app-workspace`**，前者用于全局可用，后者保证命名空间生效时不依赖根选择器。
+## 2. Layer 1：CSS Variables 设计 Token
+
+> 推荐基线。**所有平台变量同时挂载在 `:root` 与 `.sy-app-workspace`**，前者用于全局可用，后者保证命名空间生效时不依赖根选择器。页面可以继续定义自己的局部变量，例如 `--sales-dashboard-accent`、`--kanban-column-width`。
 
 ```css
 :root, .sy-app-workspace {
@@ -199,9 +199,9 @@ export function AppThemeProvider({ children }: { children: React.ReactNode }) {
 
 ---
 
-## 4. Layer 3：Tailwind 语义化工具类
-
-`tailwind-preset.ts` 基于 CSS Variables 扩展语义化类，**优先使用语义类**而非数值类。
+## 4. Layer 3：Tailwind 语义化工具类
+
+`tailwind-preset.ts` 基于 CSS Variables 扩展语义化类。语义类适合常规后台页面、表单、列表和状态展示；普通 Tailwind 工具类与任意值适合特殊布局、品牌视觉、图表容器、复杂动效和一次性精调。
 
 ### 4.1 颜色类
 
@@ -247,110 +247,117 @@ export function AppThemeProvider({ children }: { children: React.ReactNode }) {
 | `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);
-}
-```
+> 通用 Tailwind 数值类（如 `p-4`、`text-sm`）和任意值（如 `grid-cols-[240px_1fr]`、`bg-[#0f766e]`）都可以使用。常规业务组件优先使用语义类，特殊页面按实际视觉需求选择更合适的 Tailwind/CSS 写法。
+
+---
+
+## 5. 推荐顺序与硬边界
+
+| # | 场景 | 推荐做法 | 允许的扩展 |
+|---|---|---|---|
+| 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` 或页面根类下收敛作用域 | 避免写全局裸选择器污染宿主平台 |
+
+---
+
+## 6. 推荐示例与可接受变体
+
+### 示例 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>
+```
+
+### 示例 2：表单字段布局
+
+```tsx
+// 推荐：表单语义类
+<div className="flex flex-col gap-form p-form">
+  <Input />
+  <Input />
+</div>
+
+// 可接受：特殊布局精调用 Tailwind 普通类 / 任意值
+<div className="flex flex-col gap-[18px] p-6">
+  <Input className="h-[32px]" />
+  <Input className="h-[32px]" />
+</div>
+```
+
+### 示例 3：状态文案
+
+```tsx
+// 推荐：平台状态语义
+<span className="text-success">已通过</span>
+<span className="text-error">已驳回</span>
+
+// 可接受：页面专属状态色
+<span className="text-[#16a34a]">已通过</span>
+<span style={{ color: riskLevelColor }}>风险等级</span>
+```
+
+### 示例 4：卡片容器
+
+```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>
+```
+
+### 示例 5：次要文本 + 提示
+
+```tsx
+// 推荐：层级语义
+<p className="text-secondary text-sm-sy">提示信息</p>
+
+// 可接受：需要匹配图表或品牌视觉时直接设定
+<p className="text-[13px] text-slate-500">提示信息</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);
+}
+
+/* 可接受：页面专属视觉值，只要作用域收敛 */
+.sy-app-workspace .sales-dashboard .my-node-card {
+  background: linear-gradient(135deg, #0f766e, #0ea5e9);
+  border-radius: 14px;
+  padding: 20px;
+}
+```
 
 ---
 

package/openxiangda-skills/skills/openxiangda-page/SKILL.md

@@ -60,7 +60,7 @@ Read these references only when editing page code:
 - `../../references/pages/page-sdk.md`
 - `../../references/notifications.md` — notification resources and `sdk.notification` usage. Read before adding reminders, alerts, or message templates to a page.
 - `../../references/pages/publish-flow.md`
-- `../../references/style-system.md` — three-layer style architecture, CSS namespace, and the no-hardcoded-color rule. Read before writing any page CSS or Tailwind class.
+- `../../references/style-system.md` — three-layer style architecture, CSS namespace, and flexible Tailwind/CSS guidance. Read before writing substantial page CSS or Tailwind classes.
 - `../../references/architecture-patterns.md` — CRUD data flow, `DataManagementList` pattern, and recommended `src/pages/<pageCode>/` layout. Read before scaffolding a new page or list view.
 - `../../references/component-guide.md` — when to pick platform components, raw Ant Design, or custom components. Read before introducing a new component.
 - `../../references/troubleshooting.md` — known failure modes (missing styles, `options` runtime errors, broken option rendering, etc.) and their fixes. Read when something does not behave as expected.
@@ -82,7 +82,7 @@ Read these references only when editing page code:
 - Do not scatter hardcoded `/view/...&isRenderNav=false` URLs through page code. Use the runtime navigation API or the local route helper generated for the app shell.
 - Platform menus should bind only the formal app-shell code page for user-facing entry points. Original forms, workflows, and native view pages may remain as development / maintenance resources or permission targets, but should not become the product navigation shell.
 - For prod, explicitly run with `--profile prod`; never rely on the current profile for release operations.
-- Follow the style system in `../../references/style-system.md`: never hardcode colors, fonts, spacing, or radii — use the platform CSS variables and the page CSS namespace.
+- Follow the style system in `../../references/style-system.md`: prefer platform CSS variables, semantic Tailwind classes, and the page CSS namespace for consistency, but do not force every visual value through built-in tokens. Tailwind ordinary utilities, Tailwind arbitrary values, local CSS, page-level CSS variables, and small dynamic inline styles are allowed when they better match the product design.
 - For list / detail / CRUD pages, follow `../../references/architecture-patterns.md` (e.g. `DataManagementList`) before writing custom data-fetching loops.
 - Query pages must use pagination with structured conditions. Do not fetch a large `pageSize` and filter in the browser; avoid default `searchKeyWord`, and build multi-field fuzzy search with explicit `filterGroup` + `OR`.
 - Pick components per `../../references/component-guide.md`: prefer the platform component, fall back to Ant Design, and only build a custom component when neither fits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.27",
+  "version": "1.0.28",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {

package/templates/sy-lowcode-app-workspace/examples/best-practices/design-style.md

@@ -24,6 +24,10 @@ OpenXiangda business apps should feel like focused operational tools.
 
 - Use platform CSS variables, Tailwind semantic classes, Ant Design, and
   antd-mobile.
+- Treat platform tokens as the default baseline, not a hard limit. Tailwind
+  ordinary utilities, arbitrary values, page CSS variables, scoped CSS, and
+  small dynamic inline styles are acceptable when they better match the product
+  design.
 - Use mature packages for mature interactions: antd controls instead of native
   inputs, ECharts for charts, GSAP for complex animation timelines, and
   maintained drag/drop or virtual-list libraries when those behaviors are