@morya-ui/setup 0.2.5

package/src/styles.mjs

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const STYLE_IMPORT = "import 'morya-ui/styles.css'"
+const STYLE_MARKER = 'morya-ui/styles.css'
+
+const CANDIDATES = [
+  'src/main.ts',
+  'src/main.js',
+  'src/main.tsx',
+  'src/main.jsx',
+  'main.ts',
+  'main.js',
+  'src/app.ts',
+  'src/app.js',
+]
+
+/**
+ * @param {string} cwd
+ * @returns {string | null} absolute path
+ */
+export function findEntryFile(cwd) {
+  for (const rel of CANDIDATES) {
+    const full = join(cwd, rel)
+    if (existsSync(full)) return full
+  }
+
+  const indexHtml = join(cwd, 'index.html')
+  if (existsSync(indexHtml)) {
+    const html = readFileSync(indexHtml, 'utf8')
+    const match = html.match(/<script[^>]*type=["']module["'][^>]*src=["']([^"']+)["']/i)
+      || html.match(/<script[^>]*src=["']([^"']+)["'][^>]*type=["']module["']/i)
+    if (match?.[1]) {
+      const src = match[1].replace(/^\//, '')
+      const full = resolve(cwd, src)
+      if (existsSync(full)) return full
+    }
+  }
+
+  return null
+}
+
+/**
+ * Insert style import after the last leading import, or at top.
+ * @param {string} source
+ */
+export function injectStyleImport(source) {
+  if (source.includes(STYLE_MARKER)) {
+    return { source, changed: false, reason: 'already-present' }
+  }
+
+  const lines = source.split(/\r?\n/)
+  let lastImportIndex = -1
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim()
+    if (!line) {
+      if (lastImportIndex >= 0) continue
+      continue
+    }
+    if (line.startsWith('//') || line.startsWith('/*') || line.startsWith('*')) {
+      if (lastImportIndex < 0) continue
+      break
+    }
+    if (/^import\s/.test(line) || /^import["']/.test(line)) {
+      lastImportIndex = i
+      continue
+    }
+    break
+  }
+
+  if (lastImportIndex >= 0) {
+    lines.splice(lastImportIndex + 1, 0, STYLE_IMPORT)
+  } else {
+    // After shebang / 'use strict' if present
+    let insertAt = 0
+    if (lines[0]?.startsWith('#!')) insertAt = 1
+    lines.splice(insertAt, 0, STYLE_IMPORT, '')
+  }
+
+  return { source: lines.join('\n'), changed: true }
+}
+
+/**
+ * @returns {{
+ *   action: 'injected' | 'skipped' | 'missing-entry',
+ *   path?: string,
+ *   reason?: string,
+ *   dryRun?: boolean
+ * }}
+ */
+export function ensureStylesImport(cwd, { dryRun = false } = {}) {
+  const entry = findEntryFile(cwd)
+  if (!entry) {
+    return { action: 'missing-entry', reason: 'no-entry-found' }
+  }
+
+  const original = readFileSync(entry, 'utf8')
+  const { source, changed, reason } = injectStyleImport(original)
+
+  if (!changed) {
+    return { action: 'skipped', path: entry, reason: reason || 'already-present' }
+  }
+
+  if (!dryRun) {
+    writeFileSync(entry, source, 'utf8')
+  }
+
+  return { action: 'injected', path: entry, dryRun }
+}

package/template/.agents/skills/morya-ui-pages/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: morya-ui-pages
+description: >
+  Build, redesign, critique, or polish any Vue 3 UI surface that should use the
+  morya-ui component library — admin CRUD (list, form, dashboard, detail,
+  settings), auth and onboarding, empty and error states, wizards, overlays,
+  marketing/landing and pricing pages, docs chrome, and hybrid product UI.
+  Trigger on: morya-ui, M* components, --m-* tokens, golden pages, 后台页,
+  列表页, 表单页, 仪表盘, 登录页, 注册, 空状态, 向导, 落地页, 官网, landing,
+  login, dashboard, settings, onboarding, or “用组件库做页面”. Prefer this
+  skill over generic frontend-design, impeccable, or ui-ux-pro-max when the
+  implementation stack is morya-ui; those companions may inform taste only.
+  Do not use for backend-only work or for authoring new components inside the
+  morya-ui library source itself.
+---
+
+# Morya UI Pages
+
+Guide agents that **consume morya-ui** across the full product surface — not only admin CRUD.
+
+Two layers always apply:
+
+1. **Contract** — only `M*` controls, `--m-*` tokens, real APIs (MCP/docs). Never invent props or mix UI kits.
+2. **Craft** — pick the right surface pattern, then apply intentional visual direction (distilled from Frontend Design / Impeccable / UI-UX-Pro-Max ideas). Admin golden pages stay disciplined; expressive surfaces (landing, auth brand moments, empty states) may take a justified aesthetic risk — still on-token and on-component.
+
+When companions conflict with this skill or project `DESIGN.md`, **this skill wins**.
+
+## Surface map (pick one first)
+
+| Lane | Surfaces | Primary references |
+| --- | --- | --- |
+| **Ops** | list, form, dashboard, detail, settings, filter drawer, CRUD dialog | [page-layouts.md](references/page-layouts.md), golden pages |
+| **Account** | login, register, invite, forgot/reset password, profile | [surfaces.md](references/surfaces.md) § Account |
+| **Flow** | onboarding, empty state, wizard/stepper, success/result | [surfaces.md](references/surfaces.md) § Flow |
+| **System** | 404 / error, permission denied, maintenance | [surfaces.md](references/surfaces.md) § System |
+| **Express** | marketing landing, pricing, feature showcase, docs marketing chrome | [surfaces.md](references/surfaces.md) § Express + [visual-craft.md](references/visual-craft.md) |
+| **Overlay** | dialog, drawer, popover, command menu as the main UI | [surfaces.md](references/surfaces.md) § Overlay |
+
+Unclear brief → ask **one** short question, or default: Ops → closest golden page; public marketing → Express.
+
+Full taxonomy: [references/surfaces.md](references/surfaces.md).
+
+## Prerequisites
+
+1. `morya-ui` installed; `morya-ui/styles.css` imported.
+2. Prefer `@morya-ui/mcp` — never invent prop / event / slot names.
+3. If the AI config pack is merged, prefer project files over bundled copies:
+   - `DESIGN.md`
+   - `docs/golden-pages/*.vue`, `docs/components.md`, `docs/feedback-message-vs-toast.md`
+
+## Workflow
+
+### 1. Pin subject, audience, surface, job
+
+State explicitly (even briefly in thinking):
+
+- **Subject** — product / domain vernacular (not generic “SaaS”)
+- **Audience** — who uses this screen
+- **Surface** — from the map above
+- **Single job** — what the first viewport must accomplish
+
+For Express / branded Account moments, also draft a tiny **design plan** (see [visual-craft.md](references/visual-craft.md)): palette roles mapped to `--m-*` (extend only if the project already customizes theme), type roles, layout concept, one signature element. Skip the full plan for routine Ops CRUD unless the user asks for a redesign.
+
+### 2. Load the smallest useful references
+
+| Need | Prefer (MCP) | Else read |
+| --- | --- | --- |
+| Ops pattern | `recommend_page` → `get_golden_page` | [page-layouts.md](references/page-layouts.md) |
+| Account / Express / empty | `recommend_page` → `get_golden_page` (`login-page` / `landing-page` / `empty-state`) | [surfaces.md](references/surfaces.md) |
+| Visual direction | — | [visual-craft.md](references/visual-craft.md) (Express / polish / anti-defaults) |
+| Components | `search` / `get_component` / `recommend_component` | [component-index.md](references/component-index.md) |
+| Tokens / rules | `get_design_rules` | [design-system.md](references/design-system.md) |
+| Snippet | `get_page_snippet` | golden / surface excerpt |
+| Feedback API | — | [feedback.md](references/feedback.md) |
+| Soft check | `validate_page` | [review-checklist.md](references/review-checklist.md) |
+
+### 3. Compose
+
+**Ops:** mirror golden-page block order; prefer `MPage*` over custom chrome.
+
+**Account / Flow / System:** centered or split shells with `MCard` / `MForm` / `MMessage` / `MEmpty` / `MResult` (see surfaces); keep controls as `M*`.
+
+**Express:** hero + sections with intentional hierarchy; interactive bits still `MButton` / `MTag` / etc.; atmosphere via layout, motion, and tokens — not a second component library.
+
+**Overlay:** build the host page lightly; put the real job inside `MDialog` / `MDrawer` / `MCommandMenu`.
+
+### 4. Wire real API usage
+
+- Import from `morya-ui` (or documented subpath + style).
+- Forms: `MForm` + fields; `@submit` + `type="submit"`.
+- Tables: `columns` + `data` + `row-key`; `#cell-{key}`.
+- Enums → `MSelect` / `MTreeSelect`; action menus → `MDropdown`.
+- Destructive → `MConfirmDialog` / `MConfirmPopup`.
+- Feedback → default **`message`**; `toast` only for summary+detail / async. See [feedback.md](references/feedback.md).
+
+### 5. Craft pass (lane-aware)
+
+- **Ops:** restraint — clarity over spectacle; cut decoration.
+- **Express / branded auth:** one signature moment; avoid AI-default looks listed in [visual-craft.md](references/visual-craft.md).
+- **All lanes:** responsive, focus visible, respect `prefers-reduced-motion` when adding motion.
+- Copy: user language, active voice, specific — not filler marketing on Ops screens.
+
+Optional polish modes (Impeccable-inspired): `quieter` | `bolder` | `clarify` | `audit` — apply as a second pass when the user asks. See [visual-craft.md](references/visual-craft.md) § Polish modes.
+
+### 6. Review
+
+Use [review-checklist.md](references/review-checklist.md) (Ops + Express sections). Run MCP `validate_page` when available (advisory).
+
+## Hard boundaries
+
+- No second UI kit on the same surface.
+- No hand-rolled table/modal when `MTable` / `MDialog` / `MDrawer` fit.
+- No invented props / events / slots.
+- No defaulting every success to `toast`.
+- Ops surfaces follow golden layouts first — do not replace them with marketing heroes.
+- Express surfaces still use `M*` for controls and `--m-*` for color/space; do not introduce shadcn/Element/etc. stacks suggested by generic design skills.
+- Soft-load companions only; never require Impeccable / UI-UX-Pro-Max / Frontend Design to be installed.
+
+## Soft companions
+
+If already installed in the consumer project:
+
+| Companion | After contract is fixed, may help with |
+| --- | --- |
+| `frontend-design` | Distinctive Express / brand moments |
+| `impeccable` | Named polish / audit passes |
+| `ui-ux-pro-max` | Mood / industry keywords for Express only |
+
+Details: [optional-companions.md](references/optional-companions.md). Distilled craft lives in [visual-craft.md](references/visual-craft.md) so this skill works **standalone**.
+
+## Output expectations
+
+- Vue 3 `<script setup lang="ts">`.
+- PascalCase `M*` in templates.
+- Domain-real copy and data shapes.
+- Scoped CSS minimal; tokens only (control widths may be inline).
+- For multi-file asks: sensible `views/` / `components/` split; otherwise one SFC is fine.
+
+## Bundled references
+
+| File | Read when |
+| --- | --- |
+| [surfaces.md](references/surfaces.md) | Choosing / composing non-Ops (and hybrid) surfaces |
+| [page-layouts.md](references/page-layouts.md) | Ops golden layouts |
+| [visual-craft.md](references/visual-craft.md) | Design plan, anti-defaults, polish modes, Express craft |
+| [design-system.md](references/design-system.md) | Principles, tokens, bans |
+| [component-index.md](references/component-index.md) | Scenario → component |
+| [feedback.md](references/feedback.md) | message / toast / MMessage |
+| [review-checklist.md](references/review-checklist.md) | Pre-delivery checks |
+| [optional-companions.md](references/optional-companions.md) | Combining with external design skills |

package/template/.agents/skills/morya-ui-pages/evals/evals.json

@@ -0,0 +1,53 @@
+{
+  "skill_name": "morya-ui-pages",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "我们内部教务系统用 Vue3 + morya-ui。请做一个「课程列表」后台页：按课程名搜索、按开课状态（全部/开课中/已结课）筛选；表格列：名称、状态 Tag、学分、更新时间；行内「编辑」进抽屉表单，「删除」要二次确认；右上角「新建课程」。保存/删除成功只要一句话提示。输出单个 Vue SFC，结构对齐列表黄金样例。",
+      "expected_output": "Ops list: MLayout/MPageFilters/MPageToolbar/MTable, MSelect status, MDrawer or route edit, MConfirmDialog delete, message not toast, MTag for status, no second UI kit.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "同一个 morya-ui 项目里，生成「新建员工」独立表单页：姓名、工作邮箱、部门（下拉）、入职日期；窄栏；页头有标题和一句说明；底栏保存（primary）/取消（secondary）。不要做成营销落地页，不要用 Toast 提示「已保存」。输出单个 Vue SFC。",
+      "expected_output": "Ops form golden: narrow MPageContent, MPageHeader, MPageSection form/actions, MForm + MSelect/MDatePicker, message for success if shown, no landing hero.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "运营后台首页仪表盘：四个 KPI（今日订单、待处理、转化率、退款率）、中间一块图表占位、右侧或下方「最近告警」表格（级别、内容、时间）。Vue3 + morya-ui，可先用静态假数据。",
+      "expected_output": "Dashboard: MPageStat grid, MPagePlaceholder/chart card, recent MTable, MLayout shell, --m-* only.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "给「青禾书房」这个独立书店品牌做登录页：左品牌、右表单（邮箱+密码+登录）。要有一点品牌感，但控件必须用 morya-ui；登录失败用表单区常驻错误，不要一闪而过的 Toast。输出单个 Vue SFC。",
+      "expected_output": "Account+craft: split shell, MForm/MInputPassword/MButton, MMessage or field error for failure, brand panel without second UI kit, tokens for colors.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "课程列表在零数据时太空了。请设计一个空状态区块（可嵌在列表页内容区）：说明还没有课程、引导「创建第一门课程」，视觉克制但有一个记忆点。只要空状态相关模板片段或带空状态的列表 SFC 均可，须 morya-ui。",
+      "expected_output": "Flow empty: clear next action CTA with MButton, short copy, one signature visual, no emoji clutter, fits list content slot.",
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "为「流水线 CI」产品写一个营销落地首页（不是后台）：首屏只有品牌名、一句主标题、一句副文、一组 CTA；下面再分「为何选择」「能力」「客户」三节。技术实现用 Vue3 + morya-ui 组件做按钮/标签/折叠 FAQ；颜色走 --m-*，避免紫渐变和奶油衬线陶土那套 AI 默认脸。输出单个 Vue SFC。",
+      "expected_output": "Express landing: single-job hero, MButton CTAs, sections with one job each, MAccordion FAQ optional, no purple/cream-terracotta defaults, no admin MPageFilters shell.",
+      "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "做一个三步「创建工作空间」向导：1 名称与地区 2 邀请成员（邮箱标签）3 确认。用 morya-ui 的 Stepper + Form；每步一个主任务；最后提交成功进入结果页（查看工作空间 / 返回）。输出一个或两个 SFC。",
+      "expected_output": "Flow wizard: MStepper, per-step MForm, MInputTags or similar for invites, clear next/back/submit, success with next actions, message/toast per feedback rules.",
+      "files": []
+    },
+    {
+      "id": 8,
+      "prompt": "用户点了删除项目但权限不足：做一张「无权限」系统页（或全页占位），说明原因，并提供返回上一页、联系管理员。用 morya-ui，文案直接别玩梗。",
+      "expected_output": "System surface: plain explanation, escape actions with MButton, no jokey 404 essay, on-token.",
+      "files": []
+    }
+  ]
+}

package/template/.agents/skills/morya-ui-pages/references/component-index.md

@@ -0,0 +1,72 @@
+# Component index (scenario map)
+
+Full API: docs site `/components` or MCP (`get_component`, `search`, `validate_usage`). This file is for **selection**, not prop manuals.
+
+## Shell
+
+| Component | Use |
+| --- | --- |
+| `MConfigProvider` | Root locale / theme / density / defaults |
+| `MLayout` family | Admin chrome |
+| `MBreadcrumb` | Path |
+| `MPageContent` / `MPageFilters` / `MPageToolbar` / `MPageHeader` / `MPageSection` / `MPageStat` / `MPagePlaceholder` | Page composition |
+
+## Forms · inputs
+
+`MForm`, `MFormItem`, `MInput`, `MInputPassword`, `MInputNumber`, `MTextarea`, `MSelect`, `MTreeSelect`, `MCascadeSelect`, `MDatePicker`, `MAutoComplete`, `MCheckbox` / `MCheckboxGroup`, `MRadio` / `MRadioGroup`, `MSwitch`, `MSlider`, `MRating`, `MInputTags`, `MFileUpload`, `MFloatLabel`, `MIconField`
+
+## Layout helpers
+
+`MGrid` / `MGridItem`, `MFlex`, `MSpace`, `MFluid`, `MDivider`, `MFieldset`
+
+## Data
+
+`MTable`, `MTreeTable`, `MDataView`, `MTree`, `MPagination`, `MStatus` / `MTag` / `MChip` / `MBadge`, `MAvatar` / `MAvatarGroup`, `MTimeline`, `MMeterGroup`, `MVirtualScroller`
+
+## Feedback
+
+| API / component | When |
+| --- | --- |
+| `message` | **Default** one-line CRUD result |
+| `toast` | `summary` + `detail`, or async / background feel |
+| `<MMessage>` | Persistent in-page error / warning |
+| `MEmpty` | No-data / first-use / filtered empty (not an error) |
+| `MResult` | Terminal outcome: success, failure, 403 / 404 / 500 |
+| `MProgressBar` / `MProgressSpinner` / `MSkeleton` / `MBlockUI` | Loading / blocking |
+
+## Overlays & menus
+
+`MDialog`, `MDrawer`, `MConfirmDialog` / `MConfirmPopup`, `MPopover`, `MTooltip`, `MDropdown` (**actions only**), `MMenu` / `MMenubar` / `MTieredMenu` / `MMegaMenu`, `MTabs`, `MStepper`, `MCommandMenu`
+
+## Surfaces / media
+
+`MCard`, `MPanel`, `MAccordion`, `MCarousel`, `MGallery`, `MIcon`, `MScrollbar`
+
+## Scenario → pick
+
+| Intent | Prefer |
+| --- | --- |
+| Searchable list + paging | `MPageFilters` + `MTable` (+ paginator) |
+| Create / edit entity page | Form golden layout + `MForm` |
+| Create / edit in place | `MDialog` or `MDrawer` + form |
+| Delete | `MConfirmDialog` |
+| Lightweight inline status | `MStatus` (dot + label) |
+| Status chip / closable label | `MTag` severities |
+| Primary / secondary actions | `MSpace` + `MButton` |
+| Dashboard KPIs | `MGrid` + `MPageStat` |
+| Org tree | `MTree` / `MTreeSelect` |
+| Login / auth | `login-page` golden + `MInputPassword` |
+| Marketing landing | `landing-page` golden + `MButton` / `MTag` / `MAccordion` |
+| Empty list / zero state | `MEmpty` (+ `empty-state` golden or `MTable` `#empty`) |
+| Submit success / HTTP error page | `MResult` |
+| Local capped scroll | Explicit `MScrollbar` |
+
+## Common mistakes
+
+| Wrong | Right |
+| --- | --- |
+| `MDropdown` as form enum | `MSelect` |
+| Hand `<table>` | `MTable` |
+| Hand modal div | `MDialog` |
+| Extra `MCard` around every `MPage*` block | Use page components' own surface/gap |
+| Assume undocumented props | MCP / docs lookup |

package/template/.agents/skills/morya-ui-pages/references/design-system.md

@@ -0,0 +1,90 @@
+# Design system (consumer summary)
+
+Canonical long form lives in project-root `DESIGN.md` when the AI config pack is merged. This file is the portable subset for agents.
+
+## Principles
+
+1. **Components first** — layout, forms, tables, overlays use `M*` from `morya-ui`, not equivalent hand-rolled DOM.
+2. **Tokens first** — color, space, radius, shadow, motion via `--m-*`. No raw `#hex` / `rgb()` in page styles.
+3. **Semantic actions** — primary work uses `MButton severity="primary"`; destructive uses `severity="danger"` or confirm dialogs.
+4. **Accessibility** — fields have visible labels; icon buttons have `aria-label`; overlays dismiss with Esc (library default).
+5. **ConfigProvider** — wrap the app (or isolated demo) in `MConfigProvider` for locale, theme, density, overlay mount.
+
+## App shell
+
+```vue
+<script setup lang="ts">
+import { MConfigProvider, zhCN } from 'morya-ui'
+import 'morya-ui/styles.css'
+</script>
+
+<template>
+  <MConfigProvider :locale="zhCN">
+    <MLayout fill-viewport has-sider>
+      <MLayoutSider bordered>...</MLayoutSider>
+      <MLayout>
+        <MLayoutHeader>...</MLayoutHeader>
+        <MLayoutContent>...</MLayoutContent>
+      </MLayout>
+    </MLayout>
+  </MConfigProvider>
+</template>
+```
+
+| Role | Prefer |
+| --- | --- |
+| Admin chrome | `MLayout fillViewport` + sider / header / content |
+| Page stack | `MPageContent` inside `MLayoutContent` |
+| Filters / toolbar | `MPageFilters` + `MPageToolbar` |
+| Form surfaces | `MPageHeader` + `MPageSection variant="form|actions"` |
+| Dashboard KPI | `MPageStat` + `MPagePlaceholder` |
+| Module cards | `MCard` / `MPanel` / `MFieldset` |
+| Grid / spacing | `MGrid` + `MGridItem`, or `MFlex` / `MSpace` |
+
+## Forms
+
+- `MForm` + `MFormItem` with `name` aligned to rules.
+- Prefer field props (`label`, `invalid`, `helpText`) when the control supports them; wrap with `MFormItem` for denser / complex forms.
+- Default size medium; dense apps may use `size="small"` or ConfigProvider density.
+- Form pages: keep the main column narrow (`MPageContent width="narrow"` or ~`40rem`).
+
+## Data display
+
+- `MTable` with columns + data + `row-key`.
+- Row actions: text/link `MButton` or `MDropdown`.
+- Pagination: table `paginator` or sibling `MPagination`.
+- Empty states: `MEmpty` in `#empty` / Flow golden — never a silent blank table.
+- Terminal outcomes (success / 403 / 404 / 500): `MResult` — do not reuse `MEmpty` for errors.
+
+## Overlays
+
+| Need | Component |
+| --- | --- |
+| Delete confirm | `MConfirmDialog` / `MConfirmPopup` |
+| Detail / edit modal | `MDialog` |
+| Side filter / detail | `MDrawer` |
+| Field hint | `MTooltip` |
+
+## Token cheat sheet
+
+| Use | Variable |
+| --- | --- |
+| Page background | `--m-color-surface` |
+| Body text | `--m-color-text` |
+| Muted text | `--m-color-text-muted` |
+| Border | `--m-color-border` |
+| Brand / link | `--m-color-primary` |
+| Danger | `--m-color-danger` |
+| Section gap | `--m-space-4` / `--m-space-6` |
+| Card radius | `--m-radius-md` |
+| Card shadow | `--m-shadow-md` |
+
+Full machine-readable set: project `design-tokens/tokens.json` (runtime truth remains `morya-ui/styles.css`).
+
+## Bans
+
+- Second UI library on the same page.
+- Hard-coded theme colors that break `[data-theme="dark"]`.
+- `<div @click>` instead of `MButton` / `<button>`.
+- Using `MDropdown` for form enum selection (use `MSelect` / `MTreeSelect`).
+- Skipping `import 'morya-ui/styles.css'`.

package/template/.agents/skills/morya-ui-pages/references/feedback.md

@@ -0,0 +1,66 @@
+# Message / Toast / MMessage
+
+**Default rule:** operation feedback uses the `message` API. Use `toast` only when you need a title plus detail, or an async / background notification feel.
+
+## Three different things
+
+| Name | Shape | API | Typical use |
+| --- | --- | --- | --- |
+| Message service | Top-centered one-liner | `message.success('已保存')` | Most CRUD results |
+| Toast service | Corner notice with `summary` + optional `detail` | `toast.success({ summary, detail })` | Extra explanation, job results |
+| `MMessage` | In-page bar, stays | `<MMessage severity="error">…</MMessage>` | Persistent form / auth errors |
+
+## Decision tree
+
+```
+Need immediate feedback after a user action?
+├─ No → maybe confirm dialog or field errorMessage only
+└─ Yes → must the error stay in the form until fixed?
+    ├─ Yes → field invalid / errorMessage; form-level token alert (see login-page)
+    └─ No → only one short line (no separate detail)?
+        ├─ Yes → message.*          ← default
+        └─ No → summary + detail / async feel → toast.*
+```
+
+## Prefer `message`
+
+```ts
+import { message } from 'morya-ui'
+
+message.success('已创建')
+message.info('已移入回收站')
+message.error('操作失败')
+```
+
+## Prefer `toast`
+
+```ts
+import { toast } from 'morya-ui'
+
+toast.success({
+  summary: '导入完成',
+  detail: '成功 128 条，失败 2 条',
+})
+```
+
+## Prefer `<MMessage>` / form-level errors
+
+- Field validation: component `invalid` / `errorMessage` (preferred).
+- Form-level persistent errors (login/auth): token-styled `role="alert"` bar as in `docs/golden-pages/login-page.vue`.
+- Note: `<MMessage>` today is primarily the **message service host** (`messages` / teleport). Do not invent a `severity` + default-slot Alert API unless docs add it.
+
+```vue
+<p v-if="formError" class="form-alert" role="alert">{{ formError }}</p>
+```
+
+```css
+.form-alert {
+  margin: 0 0 var(--m-space-4);
+  padding: var(--m-space-3) var(--m-space-4);
+  border: 1px solid color-mix(in srgb, var(--m-color-danger) 40%, var(--m-color-border));
+  border-radius: var(--m-radius-md);
+  background: color-mix(in srgb, var(--m-color-danger) 10%, var(--m-color-surface));
+  color: var(--m-color-danger);
+}
+```
+

package/template/.agents/skills/morya-ui-pages/references/optional-companions.md

@@ -0,0 +1,29 @@
+# Optional companions
+
+This skill is **standalone**. Distilled craft lives in [visual-craft.md](visual-craft.md). Companions are optional soft upgrades when already present in the consumer repo.
+
+## Conflict rule
+
+`morya-ui-pages` + project `DESIGN.md` + MCP APIs **override** companion advice whenever they disagree (component choice, tokens, Ops layout, feedback API).
+
+## How to combine
+
+| Installed companion | Safe use | Unsafe use |
+| --- | --- | --- |
+| `frontend-design` | Express / brand panel taste after surface + contract are fixed | Replacing Ops golden shell with a custom landing |
+| `impeccable` | Named passes (`audit`, `quieter`, …) aligned with [visual-craft.md](visual-craft.md) polish modes | Swapping `M*` for raw HTML controls or new token schema |
+| `ui-ux-pro-max` | Mood / industry keywords for Express | Adopting its React/shadcn/Flutter stack suggestions |
+
+Suggested prompt glue:
+
+> Follow morya-ui-pages for surface, components, and tokens. Optionally apply \<companion\> only for visual taste on Express sections; remediate with M* and --m-*.
+
+## Load budget
+
+- Default: **this skill only**
+- Max: this skill + **one** companion
+- Broad redesign review: this skill + impeccable-style `audit` (or the real skill if installed) — still one companion
+
+## If companions are absent
+
+Do **not** tell the user to install them mid-task. Use [visual-craft.md](visual-craft.md) and continue.

package/template/.agents/skills/morya-ui-pages/references/page-layouts.md

@@ -0,0 +1,76 @@
+# Page layouts
+
+When generating a full page, pick a type and **mirror the golden-page block order**. Prefer project files when present:
+
+| Type | Golden page | Runnable example |
+| --- | --- | --- |
+| List | `docs/golden-pages/list-page.vue` | `src/examples/ListPageExample.vue` |
+| Form | `docs/golden-pages/form-page.vue` | `src/examples/FormPageExample.vue` |
+| Dashboard | `docs/golden-pages/dashboard-page.vue` | `src/examples/DashboardPageExample.vue` |
+| Login | `docs/golden-pages/login-page.vue` | `src/examples/LoginPageExample.vue` |
+| Landing | `docs/golden-pages/landing-page.vue` | `src/examples/LandingPageExample.vue` |
+| Empty | `docs/golden-pages/empty-state.vue` | `src/examples/EmptyStateExample.vue` |
+
+Via MCP: `recommend_page` → `get_golden_page`; local edits: `get_page_snippet` (`filters`, `toolbar`, `form-actions`, `scrollable-panel`, …).
+
+## List page — block order
+
+1. `MLayout fillViewport` + optional `MLayoutSider bordered`
+2. `MLayoutHeader` → `MBreadcrumb`
+3. `MLayoutContent` → `MPageContent`
+4. `MPageFilters` — inner `MSpace` + Input/Select + query/reset
+5. `MPageToolbar` — title + `#actions` primary action
+6. `MTable` directly in content (usually **no** wrapping `MCard`)
+7. Pagination via `MTable` paginator or sibling `MPagination`
+
+## Form page — block order
+
+1. `MLayout fillViewport` → `MLayoutHeader` → `MBreadcrumb`
+2. `MPageContent width="narrow"`
+3. `MPageHeader` (title + description)
+4. `MPageSection variant="form"` → `MForm`
+5. `MPageSection variant="actions"` — save (`primary`) + cancel (`secondary`)
+
+## Dashboard — block order
+
+1. `MLayout fillViewport` → `MLayoutHeader` → `MBreadcrumb`
+2. `MPageContent density="spacious"` → `MPageHeader`
+3. KPI row: `MGrid` + `MPageStat` (4 columns or responsive)
+4. Main split: `MCard` + `MPagePlaceholder` and/or recent `MTable`
+
+## Composition standards
+
+| Topic | Prefer | Usually avoid |
+| --- | --- | --- |
+| Shell | `MLayout fillViewport` + `MPageContent` | Hand `min-height: 100vh`; padding on `MLayoutContent` |
+| Sections | `MPageFilters` / `MPageToolbar` / `MPageSection` | Custom `.page-*`; extra `MCard` wrappers |
+| List table | `MTable` in `MPageContent` | Border card solely to wrap the table |
+| Spacing | `MSpace` / `MFlex` for peers; page gap from `MPageContent` | Nested padded divs stacking gaps |
+| Scroll | Rely on layout scroll; explicit `MScrollbar` for local panes | Forcing overflow on every content slot |
+| Color | `--m-*` | Page-level hex / rgb |
+| Feedback | One-line → `message`; danger → confirm dialog | Toast for a single short string |
+| A11y | Labels + icon `aria-label` | Unlabeled icon controls |
+
+Inline style is acceptable for control widths (e.g. filter `width: 14rem`).
+
+## Detail page — suggested order
+
+1. Same admin chrome as list (breadcrumb → `MPageContent`)
+2. `MPageHeader` — title, status via `MStatus` (light) or `MTag` (chip), primary/secondary actions
+3. Summary `MCard` or definition sections via `MPageSection`
+4. Related data: nested `MTabs` + `MTable` / timeline
+5. Edit via route, or `MDrawer` / `MDialog` — do not turn detail into a marketing page
+
+## Settings page — suggested order
+
+1. Admin chrome + `MPageContent width="narrow"` (or split: side `MMenu`/`MTabs` + content)
+2. Grouped `MPageSection` or `MTabs` by concern (资料 / 通知 / 安全)
+3. Each group: `MForm` + save actions (section-level or page-level — be consistent)
+4. Dangerous zone last: `severity="danger"` + confirm
+
+## Hybrids
+
+- List + row edit dialog → list golden page + `MDialog` form body.
+- List + side detail → list + `MDrawer`.
+- Settings without admin chrome → still use `MPageContent` + `MPageSection`; omit sider only if the host app already provides chrome.
+- Non-Ops surfaces (auth, landing, empty, wizard) → [surfaces.md](surfaces.md), not these golden orders.