@morya-ui/setup 0.3.5 → 0.3.7

package/template/.cursor/rules/design-system.mdc

@@ -1,17 +1,18 @@
----
-description: Morya UI 设计系统第一信源。生成或修改 UI 前必读 DESIGN.md。
-alwaysApply: true
----
-
-# Morya UI 设计系统
-
-1. **先读** 项目根目录 `DESIGN.md`。组件选型用 MCP `recommend_component`（含 recipe + `relatedSnippets`），或 skill `references/decision-recipes.md` / `component-index.md`。
-2. **只用** `morya-ui` 的 `M*` 组件；全局样式 `morya-ui/styles.css`。
-3. **颜色/间距/圆角** 使用 `--m-*` CSS 变量，禁止裸 hex/rgb（见 `scripts/check-raw-colors.mjs`）。
-4. **页面组装（composition-first）**：用 MCP `recommend_page` → `suggestedSnippets` / `get_page_snippet` + `recommend_component` 拼装；`page-layouts` 块顺序作 checklist。`get_golden_page` **可选**（核对整页块顺序或用户明确要求对齐样例时）。**视觉方向**：有明确参考或明确描述 → 必须跟用户；提示词有清晰线索 → 推断并说明；不确定 → 先问（`get_style_direction`）。**没有命名风格预设表。** 禁止未询问就套 AI 默认渐变/霓虹/毛玻璃。已安装 `frontend-design` / `impeccable` 时只加深已定方向，**不得**换组件库或推翻块顺序 / 用户指定。
-5. **表单选项** 用 `MSelect` / `MTreeSelect`；**动作菜单** 用 `MDropdown`。
-6. 不确定 API 时查文档站或 MCP `get_component`，**禁止臆造 prop**；写完后必须 `validate_usage`。
-7. 根节点用 `MConfigProvider`；后台布局用 `MLayout` 系列。
-8. **操作反馈默认 `message` API**；仅 `summary + detail` 或异步通知用 `toast`；表单常驻错误用字段 `errorMessage` 或 token 样式的 `role="alert"`（`<MMessage>` 只是 message 宿主）。见 skill `references/feedback.md`。
-
-Token / 风格 / companion：MCP `get_design_rules`、`get_style_direction`；skill `optional-companions.md`（运行时以 `morya-ui/styles.css` 为准）
+---
+description: Morya UI 设计系统第一信源。生成或修改 UI 前必读 DESIGN.md。
+alwaysApply: true
+---
+
+# Morya UI 设计系统
+
+1. **先读** 项目根目录 `DESIGN.md`。组件选型用 MCP `recommend_component`（含 recipe + `relatedSnippets`），或 skill `references/decision-recipes.md` / `component-index.md`。
+2. **只用** `morya-ui` 的 `M*` 组件；全局样式 `morya-ui/styles.css`。
+3. **颜色/间距/圆角** 使用 `--m-*` CSS 变量，禁止裸 hex/rgb（见 `scripts/check-raw-colors.mjs`）。品牌差异优先主题覆盖 `--m-color-primary` / 字体（见 DESIGN.md § 主题覆盖）。
+4. **页面组装（composition-first）**：有参考时先 `map_reference`（或 `recommend_page` + `brief` / `density`）→ 按 `mapping` / `suggestedSnippets` 用 `get_page_snippet` 拼装；`page-layouts` 作块顺序 checklist。`get_golden_page` **可选**。Account / Express / Flow 签名壳用 `get_style_shells`。**视觉方向**：明确参考/描述 → 跟用户；线索清晰 → 推断并说明；不确定 → 先问（`get_style_direction`）。**没有命名风格预设表。** 禁止未询问就套 AI 默认渐变/霓虹/毛玻璃。
+5. **表单选项** 用 `MSelect` / `MTreeSelect`；**动作菜单** 用 `MDropdown`。
+6. 不确定 API 时查文档站或 MCP `get_component`，**禁止臆造 prop**；写完后必须 `validate_usage`。
+7. 根节点用 `MConfigProvider`；后台布局用 `MLayout` 系列。
+8. **操作反馈默认 `message` API**；仅 `summary + detail` 或异步通知用 `toast`；表单常驻错误用字段 `errorMessage` 或 token 样式的 `role="alert"`（`<MMessage>` 只是 message 宿主）。见 skill `references/feedback.md`。
+9. 交付前 `validate_page`（同一 `brief`）：契约 `ok` 必须为 true；工艺建议可说明后放过。
+
+Token / 风格 / companion：MCP `get_design_rules`、`get_style_direction`、`get_style_shells`、`map_reference`；skill `optional-companions.md`（运行时以 `morya-ui/styles.css` 为准）

package/template/.cursor/rules/page-layout.mdc

@@ -1,97 +1,97 @@
----
-description: 生成 Morya UI 业务页面（列表/表单/仪表盘）时的布局规范
-alwaysApply: false
----
-
-# 页面布局（Agent Requested）
-
-生成完整页面时，先确定类型，按 **块顺序 checklist** 用 MCP **`get_page_snippet`** / `recommend_page.suggestedSnippets` 拼装（composition-first）。仅在不确定整页顺序或用户要求对齐样例时再读 `get_golden_page`。
-
-| 类型 | 主要 snippets | 可选黄金样例 |
-| --- | --- | --- |
-| 列表页 | `layout-app-shell` / `page-header-actions` / **`list-filters-stack`**（dense → `list-filters-dense`）/ `list-table` / `form-in-dialog` / `confirm-delete` | `list-page` |
-| 表单页 | `form-header` / `form-body` / `form-actions` | `form-page`（仅长表单 / 独立配置页） |
-| 列表内弹窗表单 | **`form-in-dialog`** | `form-in-dialog` |
-| 详情页 | `detail-toolbar` / `form-in-dialog` | `detail-page` |
-| 结果 / 阻断页 | **`result-block`** | `result-page` |
-| 设置页 | `form-header` / `form-body` / `form-actions` | `settings-page` |
-| 分步向导 | **`wizard-steps`** | `wizard-form` |
-| 仪表盘 | `dashboard-kpi-grid` / `dashboard-chart-card` / `dashboard-recent-table` | `dashboard-page` |
-| 登录页 | **`auth-split-shell`** | `login-page` |
-| 营销落地 | —（见 surfaces） | `landing-page` |
-| 空状态 | **`empty-block`** | `empty-state` |
-
-## 列表内新建 / 编辑（默认）
-
-后台 CRUD **优先**：列表页 + `MDialog`（或 `MDrawer`）内 `MForm`（snippets `form-in-dialog` / `form-in-drawer`），不要把「新建用户 / 编辑角色」做成单独路由，除非字段很多或多步骤。
-
-## 列表页区块顺序
-
-1. `MLayout fillViewport` + 可选 `MLayoutSider bordered`
-2. 侧栏 `MMenu`
-3. `MLayoutHeader` → `MBreadcrumb`
-4. `MLayoutContent` → `MPageContent`（**仅在下方高度规则适用时**再加 `fill`）
-5. `MPageHeader`（页面标题 + `#actions` 主操作；视口内 **唯一** filled primary）→ `page-header-actions`
-6. `MPageFilters`（默认 **`list-filters-stack`**：折叠高级 + FilterChips；查询/重置 secondary；dense → `list-filters-dense`）
-7. 可选独立 `MPageFilterChips`（若未用 stack）
-8. 可选 `MPageToolbar`（仅批量操作，**不要**页面标题）
-9. `MTable`（直接放置；`#empty` → `MEmpty`）
-10. 分页由 `MTable paginator` 或同级 `MPagination`
-11. 短新建/编辑：同页 `MDialog` + `MForm`；删除：`MConfirmDialog`（`confirm-delete`）
-
-### 列表高度 — 先判断，再决定是否 fill
-
-仅当 **多数** 条件成立时使用 `MPageContent fill` + `MTable fill paginator`：
-
-- 全视口后台列表（`MLayout fillViewport`），页面主任务就是浏览一张表
-- 表格按内容高度会留下大块空白、分页悬在中间不好看
-- 希望表体内部滚动、分页贴在页面最下方
-
-以下情况 **不要** 用 `fill`：
-
-- 嵌入/次要表格（仪表盘「最近」、详情关联表、Card 内）
-- 内容本身很短，内容高度表格即可
-- 整页应作为文档滚动（长筛选 + 说明 + 表格）
-- Dialog / Drawer 内表格
-- 表格不是中间唯一主区域的混合布局
-
-适合 `fill` 时不要手写 `min-height` / `calc`；不适合时不要硬套 `fill`。
-
-## 表单页区块顺序
-
-1. `MLayout fillViewport` → `MLayoutHeader` → `MBreadcrumb`
-2. `MPageContent width="narrow"`
-3. `MPageHeader`（标题 + 说明）
-4. `MPageSection variant="form"` → `MForm`
-5. `MPageSection variant="actions"`：保存（primary）+ 取消（secondary）
-
-## 仪表盘区块顺序
-
-1. `MLayout fillViewport` → `MLayoutHeader` → `MBreadcrumb`
-2. `MPageContent density="spacious"` → `MPageHeader`
-3. KPI：`MGrid` + `MPageStat`（4 列或响应式）
-4. 主区两栏：`MCard shadow="always"` + `MEmpty`（图表未接入）/ 最近列表 `MTable`
-
-## 页面标准
-
-推荐实践（非强制），完整列表见 MCP `get_design_rules` → `standards`：
-
-| 主题 | 推荐 | 通常不必 |
-| --- | --- | --- |
-| 骨架 | `MLayout fillViewport` + `MPageContent` | `MLayoutContent` 再写 padding |
-| 区块 | `MPageFilters` / `MPageToolbar` / `MPageSection` | 手写 `.page-*`；`MCard` 再包一层 |
-| 列表表格 | `MTable` 直接放 `MPageContent`；高度规则适用时再 `fill` | 用 `MCard` 再包 bordered 表格；不适合时硬套 `fill` |
-| 控件间距 | 同行用 `MSpace` / `MFlex`；区块靠 `MPageContent` gap | 外包 padded `div` 叠间距 |
-| 滚动 | 全视口主列表可表体滚动（`fill`）；否则 Layout / 局部 `MScrollbar` | 在用户内容区强行内置滚动；无理由双滚动条 |
-| 颜色 | `--m-*` Token | 页面级 hex / 裸 rgb() |
-| 反馈 | 单行结果用 `message`；危险操作用 `MConfirmDialog` | 仅一行文案却用 toast |
-| 无障碍 | 图标按钮 `aria-label`、表单可见 label | — |
-
-仅允许控件宽度等局部 inline style（如筛选项 `width: 14rem`）。
-
-## MCP
-
-- 整页：`recommend_page`（可传 `style`）→ **`suggestedSnippets` / `get_page_snippet`** + `recommend_component` → `get_design_rules` / `get_style_direction`；可选 `get_golden_page` 核对块顺序
-- 风格：有明确参考或明确描述 → 跟用户；有提示词线索 → 推断并说明；不确定 → 先问（无预设表）
-- 局部：`get_page_snippet`（如 `form-in-dialog` / `confirm-delete` / `list-filters` / `wizard-steps`）
-- 可选：`validate_page`（参考建议，不阻断）
+---
+description: 生成 Morya UI 业务页面（列表/表单/仪表盘）时的布局规范
+alwaysApply: false
+---
+
+# 页面布局（Agent Requested）
+
+生成完整页面时，先确定类型，按 **块顺序 checklist** 用 MCP **`get_page_snippet`** / `recommend_page.suggestedSnippets` 拼装（composition-first）。仅在不确定整页顺序或用户要求对齐样例时再读 `get_golden_page`。
+
+| 类型 | 主要 snippets | 可选黄金样例 |
+| --- | --- | --- |
+| 列表页 | `layout-app-shell` / `page-header-actions` / **`list-filters-stack`**（dense → `list-filters-dense`）/ `list-table` / `form-in-dialog` / `confirm-delete` | `list-page` |
+| 表单页 | `form-header` / `form-body` / `form-actions` | `form-page`（仅长表单 / 独立配置页） |
+| 列表内弹窗表单 | **`form-in-dialog`** | `form-in-dialog` |
+| 详情页 | `detail-toolbar` / `form-in-dialog` | `detail-page` |
+| 结果 / 阻断页 | **`result-block`** | `result-page` |
+| 设置页 | `form-header` / `form-body` / `form-actions` | `settings-page` |
+| 分步向导 | **`wizard-steps`** | `wizard-form` |
+| 仪表盘 | `dashboard-kpi-grid` / `dashboard-chart-card` / `dashboard-recent-table` | `dashboard-page` |
+| 登录页 | **`auth-split-shell`** | `login-page` |
+| 营销落地 | —（见 surfaces） | `landing-page` |
+| 空状态 | **`empty-block`** | `empty-state` |
+
+## 列表内新建 / 编辑（默认）
+
+后台 CRUD **优先**：列表页 + `MDialog`（或 `MDrawer`）内 `MForm`（snippets `form-in-dialog` / `form-in-drawer`），不要把「新建用户 / 编辑角色」做成单独路由，除非字段很多或多步骤。
+
+## 列表页区块顺序
+
+1. `MLayout fillViewport` + 可选 `MLayoutSider bordered`
+2. 侧栏 `MMenu`
+3. `MLayoutHeader` → `MBreadcrumb`
+4. `MLayoutContent` → `MPageContent`（**仅在下方高度规则适用时**再加 `fill`）
+5. `MPageHeader`（页面标题 + `#actions` 主操作；视口内 **唯一** filled primary）→ `page-header-actions`
+6. `MPageFilters`（默认 **`list-filters-stack`**：折叠高级 + FilterChips；查询/重置 secondary；dense → `list-filters-dense`）
+7. 可选独立 `MPageFilterChips`（若未用 stack）
+8. 可选 `MPageToolbar`（仅批量操作，**不要**页面标题）
+9. `MTable`（直接放置；`#empty` → `MEmpty`）
+10. 分页由 `MTable paginator` 或同级 `MPagination`
+11. 短新建/编辑：同页 `MDialog` + `MForm`；删除：`MConfirmDialog`（`confirm-delete`）
+
+### 列表高度 — 先判断，再决定是否 fill
+
+仅当 **多数** 条件成立时使用 `MPageContent fill` + `MTable fill paginator`：
+
+- 全视口后台列表（`MLayout fillViewport`），页面主任务就是浏览一张表
+- 表格按内容高度会留下大块空白、分页悬在中间不好看
+- 希望表体内部滚动、分页贴在页面最下方
+
+以下情况 **不要** 用 `fill`：
+
+- 嵌入/次要表格（仪表盘「最近」、详情关联表、Card 内）
+- 内容本身很短，内容高度表格即可
+- 整页应作为文档滚动（长筛选 + 说明 + 表格）
+- Dialog / Drawer 内表格
+- 表格不是中间唯一主区域的混合布局
+
+适合 `fill` 时不要手写 `min-height` / `calc`；不适合时不要硬套 `fill`。
+
+## 表单页区块顺序
+
+1. `MLayout fillViewport` → `MLayoutHeader` → `MBreadcrumb`
+2. `MPageContent width="narrow"`
+3. `MPageHeader`（标题 + 说明）
+4. `MPageSection variant="form"` → `MForm`
+5. `MPageSection variant="actions"`：保存（primary）+ 取消（secondary）
+
+## 仪表盘区块顺序
+
+1. `MLayout fillViewport` → `MLayoutHeader` → `MBreadcrumb`
+2. `MPageContent density="spacious"` → `MPageHeader`
+3. KPI：`MGrid` + `MPageStat`（4 列或响应式）
+4. 主区两栏：`MCard shadow="always"` + `MEmpty`（图表未接入）/ 最近列表 `MTable`
+
+## 页面标准
+
+推荐实践（非强制），完整列表见 MCP `get_design_rules` → `standards`：
+
+| 主题 | 推荐 | 通常不必 |
+| --- | --- | --- |
+| 骨架 | `MLayout fillViewport` + `MPageContent` | `MLayoutContent` 再写 padding |
+| 区块 | `MPageFilters` / `MPageToolbar` / `MPageSection` | 手写 `.page-*`；`MCard` 再包一层 |
+| 列表表格 | `MTable` 直接放 `MPageContent`；高度规则适用时再 `fill` | 用 `MCard` 再包 bordered 表格；不适合时硬套 `fill` |
+| 控件间距 | 同行用 `MSpace` / `MFlex`；区块靠 `MPageContent` gap | 外包 padded `div` 叠间距 |
+| 滚动 | 全视口主列表可表体滚动（`fill`）；否则 Layout / 局部 `MScrollbar` | 在用户内容区强行内置滚动；无理由双滚动条 |
+| 颜色 | `--m-*` Token | 页面级 hex / 裸 rgb() |
+| 反馈 | 单行结果用 `message`；危险操作用 `MConfirmDialog` | 仅一行文案却用 toast |
+| 无障碍 | 图标按钮 `aria-label`、表单可见 label | — |
+
+仅允许控件宽度等局部 inline style（如筛选项 `width: 14rem`）。
+
+## MCP
+
+- 整页：`recommend_page`（可传 `style`）→ **`suggestedSnippets` / `get_page_snippet`** + `recommend_component` → `get_design_rules` / `get_style_direction`；可选 `get_golden_page` 核对块顺序
+- 风格：有明确参考或明确描述 → 跟用户；有提示词线索 → 推断并说明；不确定 → 先问（无预设表）
+- 局部：`get_page_snippet`（如 `form-in-dialog` / `confirm-delete` / `list-filters` / `wizard-steps`）
+- 可选：`validate_page`（参考建议，不阻断）

package/template/AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS — morya-ui consumer projects
+
+Editor-neutral always-on guidance for AI agents (Cursor, VS Code, Zed, Copilot, CLI agents). Cursor also ships `.cursor/rules/`; this file is the portable subset.
+
+## Before generating or editing UI
+
+1. Read project-root `DESIGN.md` (design contract).
+2. Prefer skill `.agents/skills/morya-ui-pages/` for page workflows.
+3. Prefer MCP `@morya-ui/mcp` for real Props / Events / snippets — never invent API names.
+
+## Hard rules
+
+1. Use only `morya-ui` `M*` components; global styles `morya-ui/styles.css`.
+2. Colors / spacing / radius use `--m-*` CSS variables — no raw hex/rgb in business UI (see `scripts/check-raw-colors.mjs`). Brand differences go in theme overrides (`--m-color-primary`, fonts) per `DESIGN.md`.
+3. **Composition-first**: with a reference, call MCP `map_reference` (or `recommend_page` + `brief` / `density`) → assemble via `get_page_snippet` from `mapping` / `suggestedSnippets`. Use `page-layouts` as a block-order checklist. `get_golden_page` is optional. Account / Express / Flow signature shells: `get_style_shells`.
+4. **Visual direction**: clear reference/description → follow the user; clear cues → infer and say so; unsure → ask (`get_style_direction`). There is no named style-preset table. Do not apply default AI gradients / neon / glass without asking.
+5. Form options: `MSelect` / `MTreeSelect`. Action menus: `MDropdown`.
+6. Uncertain API → docs site or MCP `get_component`. After writing code: `validate_usage`.
+7. Root: `MConfigProvider`. Admin chrome: `MLayout` family.
+8. Feedback defaults to `message` API; use `toast` only for summary + detail or async feel; persistent form errors use field `errorMessage` or token-styled `role="alert"`.
+9. Before delivery: `validate_page` with the same `brief` — contract `ok` must be true; craft suggestions may be waived with a short note.
+
+## MCP / skills map
+
+| Need | Use |
+| --- | --- |
+| Page plan + snippets | `recommend_page`, `map_reference`, `get_page_snippet` |
+| Signature shells | `get_style_shells` |
+| Tokens / composition | `get_design_rules` |
+| Component pick | `recommend_component`, `get_component`, `get_example` |
+| Offline recipes | skill `references/` under `morya-ui-pages` |
+
+Setup writes editor MCP configs (Cursor / VS Code / Zed) and root `.mcp.json`. Reload MCP after `npx @morya-ui/setup ai`.

package/template/DESIGN.md

@@ -1,59 +1,81 @@
-# Morya UI 设计系统（AI 第一信源）
-
-> 生成或审查使用 `morya-ui` 的界面时，**必须先遵守本文**。  
-> 本文只写与页面类型无关的契约。某一类页面怎么拼、用哪个组件，见 `morya-ui-pages` skill 与 MCP，不要从本文推断出唯一布局。
-
-## 1. 设计原则
-
-1. **组件优先**：交互与布局使用库内 `M*`，不手写等价 DOM。
-2. **令牌优先**：颜色、间距、圆角、阴影、动效使用 `--m-*`；禁止裸 `#hex` / `rgb()`（`scripts/check-raw-colors.mjs` 可扫描）。
-3. **语义一致**：主操作 `severity="primary"`；破坏性操作用 `severity="danger"` 或确认。
-4. **可访问性**：控件有可访问名称；仅图标的按钮带 `aria-label`；浮层可键盘关闭。
-5. **单一事实源**：组件 API 以 MCP / 文档为准，禁止臆造 prop、event、slot。
-
-## 2. 应用根
-
-- 入口引入 `morya-ui/styles.css`（或按需子路径样式）。
-- 应用根使用 `MConfigProvider`，统一 locale、主题、密度与浮层挂载。
-- 外壳随场景选择，不要把侧栏后台当成所有页面的默认结构。
-
-## 3. 设计令牌（摘要）
-
-完整定义见 MCP `get_design_rules`。运行时以已安装的 `morya-ui/styles.css` 为准。
-
-| 用途 | 变量 |
-| --- | --- |
-| 页面背景 | `--m-color-surface` |
-| 正文 | `--m-color-text` |
-| 次要文字 | `--m-color-text-muted` |
-| 边框 | `--m-color-border` |
-| 品牌 / 链接 | `--m-color-primary` |
-| 错误 | `--m-color-danger` |
-| 区块间距 | `--m-space-4` / `--m-space-6` |
-| 圆角 / 阴影 | `--m-radius-md` / `--m-shadow-md` |
-| 动效时长 | `--m-motion-fast/normal/enter/exit` |
-| 进出场位移 / 缓动 | `--m-motion-distance` / `--m-motion-ease` |
-
-动效强度用 `useMotion`（`data-m-motion`：`full` / `reduced` / `none`），不跟随系统 `prefers-reduced-motion`；进出场预设用 `motion.transitions` / 组件 `transition`（见文档站「动效」）。
-
-## 4. 禁止项
-
-- 禁止同一界面混用第二套 UI 库。
-- 禁止业务 CSS 写死主题色；暗色须能随 `[data-theme="dark"]` 生效。
-- 禁止用不可聚焦的容器冒充按钮。
-- 禁止跳过样式入口。
-- 禁止把某一类页面的配方写成所有页面的默认结构。
-
-## 5. AI 工作流
-
-1. 读本文，确认契约。
-2. 加载 `morya-ui-pages`，由 skill 选定表面与布局；可选 companion 只补充视觉或无障碍，冲突时本文 + skill + MCP 优先。
-3. 用 MCP 查真实 API 与样例后再写代码。
-4. 完成后可运行 `pnpm check:colors`（若已配置）。
-
-## 6. 相关资源
-
-- 包：`morya-ui` · 样式：`morya-ui/styles.css`
-- 页面配方：`.agents/skills/morya-ui-pages/`（及 setup 时勾选的 companion）
-- 主题 API：`useTheme` / `useDensity` / `useMotion`
-- 动效预设：`createMoryaUI({ motion })`、`componentDefaults.*.transition`、浮层 `transition` prop；详情见文档 `/docs/motion`
+# Morya UI 设计系统（AI 第一信源）
+
+> 生成或审查使用 `morya-ui` 的界面时，**必须先遵守本文**。  
+> 本文只写与页面类型无关的契约。某一类页面怎么拼、用哪个组件，见 `morya-ui-pages` skill 与 MCP，不要从本文推断出唯一布局。
+
+## 1. 设计原则
+
+1. **组件优先**：交互与布局使用库内 `M*`，不手写等价 DOM。
+2. **令牌优先**：颜色、间距、圆角、阴影、动效使用 `--m-*`；禁止裸 `#hex` / `rgb()`（`scripts/check-raw-colors.mjs` 可扫描）。
+3. **语义一致**：主操作 `severity="primary"`；破坏性操作用 `severity="danger"` 或确认。
+4. **可访问性**：控件有可访问名称；仅图标的按钮带 `aria-label`；浮层可键盘关闭。
+5. **单一事实源**：组件 API 以 MCP / 文档为准，禁止臆造 prop、event、slot。
+
+## 2. 应用根
+
+- 入口引入 `morya-ui/styles.css`（或按需子路径样式）。
+- 应用根使用 `MConfigProvider`，统一 locale、主题、密度与浮层挂载。
+- 外壳随场景选择，不要把侧栏后台当成所有页面的默认结构。
+
+## 3. 设计令牌（摘要）
+
+完整定义见 MCP `get_design_rules`。运行时以已安装的 `morya-ui/styles.css` 为准。
+
+| 用途 | 变量 |
+| --- | --- |
+| 页面背景 | `--m-color-surface` |
+| 正文 | `--m-color-text` |
+| 次要文字 | `--m-color-text-muted` |
+| 边框 | `--m-color-border` |
+| 品牌 / 链接 | `--m-color-primary` |
+| 错误 | `--m-color-danger` |
+| 区块间距 | `--m-space-4` / `--m-space-6` |
+| 圆角 / 阴影 | `--m-radius-md` / `--m-shadow-md` |
+| 动效时长 | `--m-motion-fast/normal/enter/exit` |
+| 进出场位移 / 缓动 | `--m-motion-distance` / `--m-motion-ease` |
+
+动效强度用 `useMotion`（`data-m-motion`：`full` / `reduced` / `none`），不跟随系统 `prefers-reduced-motion`；进出场预设用 `motion.transitions` / 组件 `transition`（见文档站「动效」）。
+
+## 3.1 主题覆盖（品牌差异放这里）
+
+换品牌时**优先改主题变量**，不要在每个业务页写死色：
+
+```css
+/* 例如 src/styles/brand.css，在 styles.css 之后引入 */
+:root {
+  --m-color-primary: #0b6e4f; /* 仅主题入口允许；页面仍用 var(--m-*) */
+  --m-font-family: "Your Brand Sans", system-ui, sans-serif;
+}
+[data-theme="dark"] {
+  --m-color-primary: #3ecf8e;
+}
+```
+
+也可用 `createMoryaUI` / `MConfigProvider` 的主题 API（见文档「主题」）。`pnpm check:colors` 扫描业务源码中的裸 hex；主题入口文件可按项目约定排除。
+
+登录 / 落地页的「好看」用 MCP `get_style_shells` 的 token 壳（`account-split`、`express-hero` 等），签名仍映射到 `--m-*`。
+
+## 4. 禁止项
+
+- 禁止同一界面混用第二套 UI 库。
+- 禁止业务 CSS 写死主题色；暗色须能随 `[data-theme="dark"]` 生效。
+- 禁止用不可聚焦的容器冒充按钮。
+- 禁止跳过样式入口。
+- 禁止把某一类页面的配方写成所有页面的默认结构。
+
+## 5. AI 工作流
+
+1. 读本文，确认契约与主题覆盖位置。
+2. 加载 `morya-ui-pages`，由 skill 选定表面与布局；有参考图/描述时先 MCP `map_reference`（或 `recommend_page` + `brief`）。
+3. 用 MCP 查真实 API 与片段后再写代码；签名壳用 `get_style_shells`。
+4. `validate_usage` + `validate_page`（同一 `brief`）；契约问题必须修，工艺建议可说明后放过。
+5. 可选：起本地页对照参考截首屏（见 skill review-checklist「截图自检」）。
+6. 完成后可运行 `pnpm check:colors`（若已配置）。
+
+## 6. 相关资源
+
+- 包：`morya-ui` · 样式：`morya-ui/styles.css`
+- 页面配方：`.agents/skills/morya-ui-pages/`（及 setup 时勾选的 companion）
+- 主题 API：`useTheme` / `useDensity` / `useMotion`
+- 动效预设：`createMoryaUI({ motion })`、`componentDefaults.*.transition`、浮层 `transition` prop；详情见文档 `/docs/motion`
+- MCP：`map_reference` · `get_style_shells` · `recommend_page` · `validate_page`

package/template/scripts/check-raw-colors.mjs

@@ -1,74 +1,74 @@
-#!/usr/bin/env node
-/**
- * Scan source files for raw color literals outside design-tokens/ and theme/.
- * Usage: node scripts/check-raw-colors.mjs [dir...]
- * Exit 1 if violations found.
- */
-import { readdirSync, readFileSync, statSync } from 'node:fs'
-import path from 'node:path'
-
-const roots = process.argv.slice(2).length ? process.argv.slice(2) : ['src']
-const IGNORE_DIRS = new Set(['node_modules', 'dist', 'coverage', 'design-tokens', 'theme', '.git'])
-const EXT = new Set(['.vue', '.css', '.scss', '.ts', '.tsx', '.js', '.jsx'])
-
-const HEX = /#[0-9a-f]{3,8}\b/gi
-const RGB = /\brgb\s*\(/g
-const HSL = /\bhsl\s*\(/g
-
-/** Allow transparent, currentColor, inherit in CSS values */
-const ALLOW_LINE = /var\s*\(\s*--m-|color-mix\s*\(|transparent|currentColor|inherit|none/
-
-/** Skip demo IDs like '#1024' or 'WO-1024' in script/template strings */
-const DEMO_ID = /['"]#?[A-Z0-9-]{2,}['"]/
-
-const violations = []
-
-function walk(dir) {
-  for (const name of readdirSync(dir)) {
-    const full = path.join(dir, name)
-    const st = statSync(full)
-    if (st.isDirectory()) {
-      if (IGNORE_DIRS.has(name)) continue
-      walk(full)
-      continue
-    }
-    const ext = path.extname(name)
-    if (!EXT.has(ext)) continue
-    const normalized = full.replace(/\\/g, '/')
-    if (normalized.includes('design-tokens/') || normalized.includes('/theme/')) continue
-    if (normalized.includes('.test.') || normalized.includes('/__tests__/')) continue
-
-    const text = readFileSync(full, 'utf8')
-    const lines = text.split(/\r?\n/)
-    lines.forEach((line, index) => {
-      if (ALLOW_LINE.test(line)) return
-      if (DEMO_ID.test(line)) return
-      if (HEX.test(line) || RGB.test(line) || HSL.test(line)) {
-        HEX.lastIndex = 0
-        RGB.lastIndex = 0
-        HSL.lastIndex = 0
-        violations.push({ file: full, line: index + 1, text: line.trim() })
-      }
-    })
-  }
-}
-
-for (const root of roots) {
-  try {
-    walk(path.resolve(root))
-  } catch (error) {
-    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') continue
-    throw error
-  }
-}
-
-if (violations.length) {
-  console.error(`Found ${violations.length} raw color literal(s). Use --m-* tokens instead:\n`)
-  for (const v of violations) {
-    console.error(`  ${v.file}:${v.line}`)
-    console.error(`    ${v.text}\n`)
-  }
-  process.exit(1)
-}
-
-console.log('No raw color literals found.')
+#!/usr/bin/env node
+/**
+ * Scan source files for raw color literals outside design-tokens/ and theme/.
+ * Usage: node scripts/check-raw-colors.mjs [dir...]
+ * Exit 1 if violations found.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+const roots = process.argv.slice(2).length ? process.argv.slice(2) : ['src']
+const IGNORE_DIRS = new Set(['node_modules', 'dist', 'coverage', 'design-tokens', 'theme', '.git'])
+const EXT = new Set(['.vue', '.css', '.scss', '.ts', '.tsx', '.js', '.jsx'])
+
+const HEX = /#[0-9a-f]{3,8}\b/gi
+const RGB = /\brgb\s*\(/g
+const HSL = /\bhsl\s*\(/g
+
+/** Allow transparent, currentColor, inherit in CSS values */
+const ALLOW_LINE = /var\s*\(\s*--m-|color-mix\s*\(|transparent|currentColor|inherit|none/
+
+/** Skip demo IDs like '#1024' or 'WO-1024' in script/template strings */
+const DEMO_ID = /['"]#?[A-Z0-9-]{2,}['"]/
+
+const violations = []
+
+function walk(dir) {
+  for (const name of readdirSync(dir)) {
+    const full = path.join(dir, name)
+    const st = statSync(full)
+    if (st.isDirectory()) {
+      if (IGNORE_DIRS.has(name)) continue
+      walk(full)
+      continue
+    }
+    const ext = path.extname(name)
+    if (!EXT.has(ext)) continue
+    const normalized = full.replace(/\\/g, '/')
+    if (normalized.includes('design-tokens/') || normalized.includes('/theme/')) continue
+    if (normalized.includes('.test.') || normalized.includes('/__tests__/')) continue
+
+    const text = readFileSync(full, 'utf8')
+    const lines = text.split(/\r?\n/)
+    lines.forEach((line, index) => {
+      if (ALLOW_LINE.test(line)) return
+      if (DEMO_ID.test(line)) return
+      if (HEX.test(line) || RGB.test(line) || HSL.test(line)) {
+        HEX.lastIndex = 0
+        RGB.lastIndex = 0
+        HSL.lastIndex = 0
+        violations.push({ file: full, line: index + 1, text: line.trim() })
+      }
+    })
+  }
+}
+
+for (const root of roots) {
+  try {
+    walk(path.resolve(root))
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') continue
+    throw error
+  }
+}
+
+if (violations.length) {
+  console.error(`Found ${violations.length} raw color literal(s). Use --m-* tokens instead:\n`)
+  for (const v of violations) {
+    console.error(`  ${v.file}:${v.line}`)
+    console.error(`    ${v.text}\n`)
+  }
+  process.exit(1)
+}
+
+console.log('No raw color literals found.')