@morya-ui/setup 0.2.5 → 0.2.7

package/README.md

@@ -4,10 +4,12 @@ One-shot setup for consumer Vue projects using [`morya-ui`](https://www.npmjs.co
 
 Docs (zh/en):
 
-- [AI setup](https://morya-space.github.io/morya-ui/docs/ai-setup) — one-shot CLI
+- [One-shot setup](https://morya-space.github.io/morya-ui/docs/setup) — CLI commands and options
+- [AI setup](https://morya-space.github.io/morya-ui/docs/ai-setup) — Agent workflow
 - [Agent Skill](https://morya-space.github.io/morya-ui/docs/agent-skill) — `morya-ui-pages` behavior
+- [Quick start](https://morya-space.github.io/morya-ui/docs/quick-start) — install and first component
 
-Installs the UI library, copies Agent skill / Cursor rules / design docs from `ai-design-config`, merges Cursor MCP for [`@morya-ui/mcp`](https://www.npmjs.com/package/@morya-ui/mcp), and tries to inject `import 'morya-ui/styles.css'` into the app entry.
+Installs the UI library, copies Agent skill / Cursor rules / design docs from `design-kit`, merges Cursor MCP for [`@morya-ui/mcp`](https://www.npmjs.com/package/@morya-ui/mcp), injects `import 'morya-ui/styles.css'`, and writes `src/styles/morya-app-shell.css` with its entry import.
 
 ## Usage
 
@@ -17,6 +19,16 @@ In your app project root:
 npx @morya-ui/setup
 ```
 
+Other common commands:
+
+```bash
+# AI config + MCP only (library already installed)
+npx @morya-ui/setup ai
+
+# Library + styles only
+npx @morya-ui/setup app
+```
+
 ### Options
 
 | Flag | Meaning |
@@ -28,10 +40,16 @@ npx @morya-ui/setup
 | `--skip-install` | Do not install `morya-ui` |
 | `--skip-template` | Do not copy AI skill / rules / docs / tokens |
 | `--skip-mcp` | Do not write `.cursor/mcp.json` |
-| `--skip-styles` | Do not inject `styles.css` import |
+| `--skip-styles` | Do not inject `styles.css` / write app-shell CSS |
 | `--skip-scripts` | Do not add `check:colors` to `package.json` |
 | `-h`, `--help` | Show help |
 
+Example: MCP only:
+
+```bash
+npx @morya-ui/setup ai --skip-template --skip-scripts
+```
+
 ### Conflict policy
 
 - Template files and `.cursor/rules/*`: **skip** if the destination exists (unless `--force`).
@@ -41,7 +59,7 @@ npx @morya-ui/setup
 
 ### What gets copied
 
-From the package `template/` (synced from repo `ai-design-config/`):
+From the package `template/` (synced from repo `design-kit/`):
 
 - `DESIGN.md`
 - `.agents/skills/morya-ui-pages/`
@@ -51,6 +69,8 @@ From the package `template/` (synced from repo `ai-design-config/`):
 - `scripts/check-raw-colors.mjs`
 - `src/examples/`
 
+`morya-app-shell.css` is written by the CLI (not copied from the template tree).
+
 ### MCP (Cursor)
 
 Writes / merges:
@@ -76,6 +96,7 @@ Looks for `src/main.ts` / `.js` / `.tsx` / `.jsx`, root `main.*`, `src/app.ts` /
 
 ```ts
 import 'morya-ui/styles.css'
+import './styles/morya-app-shell.css'
 ```
 
 The CLI does **not** call `app.use(MoryaUI)` or edit `App.vue`.
@@ -83,7 +104,7 @@ The CLI does **not** call `app.use(MoryaUI)` or edit `App.vue`.
 ## Local development (this monorepo)
 
 ```bash
-pnpm setup:sync-template   # refresh packages/setup/template from ai-design-config
+pnpm setup:sync-template   # refresh packages/setup/template from design-kit
 pnpm setup:build
 node packages/setup/bin/morya-ui-setup.js --cwd /path/to/app --dry-run
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morya-ui/setup",
   "type": "module",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "One-shot setup for morya-ui: install the library, Cursor MCP, Agent skills, and design config.",
   "license": "MIT",
   "homepage": "https://github.com/morya-space/morya-ui/tree/main/packages/setup#readme",

package/src/cli.mjs

@@ -1,15 +1,37 @@
+import { existsSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { copyTemplate } from './copy-template.mjs'
+import { readJson } from './fs-utils.mjs'
 import { installMoryaUi } from './install.mjs'
 import { mergeMcpConfig } from './mcp.mjs'
 import { ensureCheckColorsScript } from './package-json.mjs'
-import { ensureStylesImport } from './styles.mjs'
+import { ensureShellStyles, ensureStylesImport } from './styles.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const PKG_ROOT = resolve(__dirname, '..')
 const TEMPLATE_ROOT = join(PKG_ROOT, 'template')
 
+const MODES = new Set(['app', 'ai', 'full'])
+
+/** AI pack paths under template/ (excludes runtime src/styles — owned by app mode). */
+const AI_TEMPLATE_INCLUDE = [
+  'DESIGN.md',
+  '.agents/skills/morya-ui-pages',
+  '.cursor/rules',
+  'docs',
+  'design-tokens',
+  'scripts/check-raw-colors.mjs',
+  'src/examples',
+]
+
+/** Mode → default skips (user --skip-* can only add more skips). */
+const MODE_DEFAULTS = {
+  full: {},
+  app: { skipTemplate: true, skipMcp: true, skipScripts: true },
+  ai: { skipInstall: true, skipStyles: true },
+}
+
 const SKIP_FLAGS = {
   '--skip-install': 'skipInstall',
   '--skip-template': 'skipTemplate',
@@ -19,13 +41,20 @@ const SKIP_FLAGS = {
 }
 
 export function printHelp() {
-  console.log(`Usage: morya-ui-setup [options]
+  console.log(`Usage: morya-ui-setup [command] [options]
 
-One-shot setup for morya-ui in a consumer Vue project:
+Commands:
+  (default) / full  Install morya-ui, AI template, MCP, styles, check:colors
+  app               Install morya-ui and inject styles / app-shell CSS
+  ai                Copy Agent skill / rules / DESIGN / docs / tokens / examples,
+                    merge Cursor MCP, add check:colors
+
+Default command:
   - install morya-ui
   - copy DESIGN.md, Agent skill, Cursor rules, docs, tokens, examples
   - merge .cursor/mcp.json for @morya-ui/mcp
   - inject import 'morya-ui/styles.css' into the app entry when found
+  - write src/styles/morya-app-shell.css and inject its import
   - add check:colors script when missing
 
 Options:
@@ -36,7 +65,7 @@ Options:
   --skip-install    Skip dependency install
   --skip-template   Skip copying AI template files
   --skip-mcp        Skip writing .cursor/mcp.json
-  --skip-styles     Skip injecting styles.css import
+  --skip-styles     Skip injecting styles.css / app-shell CSS
   --skip-scripts    Skip adding check:colors to package.json
   -h, --help        Show this help
 `)
@@ -47,6 +76,7 @@ Options:
  */
 export function parseArgs(argv) {
   const options = {
+    mode: 'full',
     cwd: process.cwd(),
     pm: undefined,
     force: false,
@@ -65,6 +95,10 @@ export function parseArgs(argv) {
       options.help = true
       continue
     }
+    if (MODES.has(arg)) {
+      options.mode = arg
+      continue
+    }
     if (arg === '--force') {
       options.force = true
       continue
@@ -100,6 +134,11 @@ export function parseArgs(argv) {
     throw new Error(`Unknown argument: ${arg}`)
   }
 
+  const defaults = MODE_DEFAULTS[options.mode] || {}
+  for (const [key, value] of Object.entries(defaults)) {
+    if (value) options[key] = true
+  }
+
   return options
 }
 
@@ -108,11 +147,30 @@ function rel(cwd, path) {
   return path.startsWith(cwd) ? path.slice(cwd.length).replace(/^[\\/]/, '') || path : path
 }
 
+/**
+ * @param {string} cwd
+ */
+function hasMoryaUiDependency(cwd) {
+  const path = join(cwd, 'package.json')
+  if (!existsSync(path)) return false
+  try {
+    const pkg = readJson(path)
+    return Boolean(
+      pkg.dependencies?.['morya-ui']
+      || pkg.devDependencies?.['morya-ui']
+      || pkg.peerDependencies?.['morya-ui'],
+    )
+  } catch {
+    return false
+  }
+}
+
 /**
  * @param {ReturnType<typeof parseArgs>} options
  */
 export async function runSetup(options) {
   const {
+    mode,
     cwd,
     force,
     dryRun,
@@ -124,14 +182,25 @@ export async function runSetup(options) {
     pm,
   } = options
 
-  console.log(`@morya-ui/setup → ${cwd}${dryRun ? ' (dry-run)' : ''}`)
+  console.log(`@morya-ui/setup [${mode}] → ${cwd}${dryRun ? ' (dry-run)' : ''}`)
   console.log('')
 
+  if (mode === 'ai' && !hasMoryaUiDependency(cwd)) {
+    console.log(
+      'Warning: morya-ui is not listed in package.json. Run `npx @morya-ui/setup app` first (or pnpm add morya-ui).',
+    )
+    console.log('')
+  }
+
   const install = installMoryaUi(cwd, { pm, dryRun, skipInstall })
 
   const template = skipTemplate
     ? { copied: [], skipped: [], forced: [], skippedStep: true }
-    : copyTemplate(TEMPLATE_ROOT, cwd, { force, dryRun })
+    : copyTemplate(TEMPLATE_ROOT, cwd, {
+        force,
+        dryRun,
+        include: mode === 'ai' || mode === 'full' ? AI_TEMPLATE_INCLUDE : undefined,
+      })
 
   const mcp = skipMcp
     ? { path: join(cwd, '.cursor', 'mcp.json'), action: 'skipped-flag' }
@@ -141,6 +210,10 @@ export async function runSetup(options) {
     ? { action: 'skipped', reason: 'skip-styles' }
     : ensureStylesImport(cwd, { dryRun })
 
+  const shell = skipStyles
+    ? { fileAction: 'skipped', importAction: 'skipped', reason: 'skip-styles' }
+    : ensureShellStyles(cwd, { dryRun, force })
+
   const scripts = skipScripts
     ? { action: 'skipped-flag' }
     : ensureCheckColorsScript(cwd, { force, dryRun })
@@ -153,7 +226,7 @@ export async function runSetup(options) {
   }
 
   if (template.skippedStep) {
-    console.log('Template: skipped (--skip-template)')
+    console.log('Template: skipped (--skip-template or app mode)')
   } else {
     console.log(
       `Template: ${template.copied.length} copied, ${template.forced.length} overwritten, ${template.skipped.length} skipped`,
@@ -167,13 +240,13 @@ export async function runSetup(options) {
   }
 
   if (mcp.action === 'skipped-flag') {
-    console.log('MCP: skipped (--skip-mcp)')
+    console.log('MCP: skipped (--skip-mcp or app mode)')
   } else {
     console.log(`MCP: ${mcp.action} (${rel(cwd, mcp.path) || '.cursor/mcp.json'})`)
   }
 
   if (styles.reason === 'skip-styles') {
-    console.log('Styles: skipped (--skip-styles)')
+    console.log('Styles: skipped (--skip-styles or ai mode)')
   } else if (styles.action === 'injected') {
     console.log(`Styles: injected into ${rel(cwd, styles.path)}`)
   } else if (styles.action === 'skipped') {
@@ -183,18 +256,38 @@ export async function runSetup(options) {
     console.log("  import 'morya-ui/styles.css'")
   }
 
+  if (shell.reason === 'skip-styles') {
+    console.log('Shell CSS: skipped (--skip-styles or ai mode)')
+  } else {
+    console.log(
+      `Shell CSS: file ${shell.fileAction}`
+        + (shell.path ? ` (${rel(cwd, shell.path)})` : '')
+        + `, import ${shell.importAction}`
+        + (shell.entry ? ` (${rel(cwd, shell.entry)})` : ''),
+    )
+  }
+
   if (scripts.action === 'skipped-flag') {
-    console.log('Scripts: skipped (--skip-scripts)')
+    console.log('Scripts: skipped (--skip-scripts or app mode)')
   } else {
     console.log(`Scripts: check:colors ${scripts.action}`)
   }
 
   console.log('')
   console.log('Next:')
-  console.log('  1. Ensure the styles import is in your app entry (if not injected).')
-  console.log('  2. Restart Cursor (or reload MCP) so morya-ui MCP tools appear.')
-  console.log('  3. Have the agent read DESIGN.md before generating pages.')
-  console.log('  4. Optional: pnpm check:colors')
+  if (mode === 'app') {
+    console.log('  1. Ensure styles.css + morya-app-shell.css imports are in your app entry.')
+    console.log('  2. Optional AI pack: npx @morya-ui/setup ai')
+  } else if (mode === 'ai') {
+    console.log('  1. Restart Cursor (or reload MCP) so morya-ui MCP tools appear.')
+    console.log('  2. Have the agent read DESIGN.md before generating pages.')
+    console.log('  3. Optional: pnpm check:colors')
+  } else {
+    console.log('  1. Ensure styles.css + morya-app-shell.css imports are in your app entry.')
+    console.log('  2. Restart Cursor (or reload MCP) so morya-ui MCP tools appear.')
+    console.log('  3. Have the agent read DESIGN.md before generating pages.')
+    console.log('  4. Optional: pnpm check:colors')
+  }
 
-  return { install, template, mcp, styles, scripts }
+  return { mode, install, template, mcp, styles, shell, scripts }
 }

package/src/copy-template.mjs

@@ -20,11 +20,27 @@ function listFiles(dir) {
   return out
 }
 
+/**
+ * @param {string} rel
+ * @param {string[] | undefined} include
+ */
+function matchesInclude(rel, include) {
+  if (!include || include.length === 0) return true
+  const norm = rel.replace(/\\/g, '/')
+  return include.some((prefix) => {
+    const p = prefix.replace(/\\/g, '/')
+    return norm === p || norm.startsWith(`${p}/`)
+  })
+}
+
 /**
  * Copy template tree into target cwd.
+ * @param {string} templateRoot
+ * @param {string} cwd
+ * @param {{ force?: boolean, dryRun?: boolean, include?: string[] }} [options]
  * @returns {{ copied: string[], skipped: string[], forced: string[] }}
  */
-export function copyTemplate(templateRoot, cwd, { force = false, dryRun = false } = {}) {
+export function copyTemplate(templateRoot, cwd, { force = false, dryRun = false, include } = {}) {
   const copied = []
   const skipped = []
   const forced = []
@@ -35,7 +51,7 @@ export function copyTemplate(templateRoot, cwd, { force = false, dryRun = false
     )
   }
 
-  const files = listFiles(templateRoot)
+  const files = listFiles(templateRoot).filter((rel) => matchesInclude(rel, include))
   for (const rel of files) {
     const from = join(templateRoot, rel)
     const to = join(cwd, rel)

package/src/fs-utils.mjs

@@ -2,7 +2,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname } from 'node:path'
 
 export function readJson(path) {
-  return JSON.parse(readFileSync(path, 'utf8'))
+  const text = readFileSync(path, 'utf8').replace(/^\uFEFF/, '')
+  return JSON.parse(text)
 }
 
 export function writeJson(path, value, { dryRun = false } = {}) {

package/src/styles.mjs

@@ -1,8 +1,10 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
 
 const STYLE_IMPORT = "import 'morya-ui/styles.css'"
 const STYLE_MARKER = 'morya-ui/styles.css'
+const SHELL_MARKER = 'morya-app-shell.css'
+const SHELL_REL = 'src/styles/morya-app-shell.css'
 
 const CANDIDATES = [
   'src/main.ts',
@@ -15,6 +17,14 @@ const CANDIDATES = [
   'src/app.js',
 ]
 
+const SHELL_CSS = `html,
+body,
+#app {
+  height: 100%;
+  margin: 0;
+}
+`
+
 /**
  * @param {string} cwd
  * @returns {string | null} absolute path
@@ -41,11 +51,13 @@ export function findEntryFile(cwd) {
 }
 
 /**
- * Insert style import after the last leading import, or at top.
+ * Insert an import after the last leading import, or at top.
  * @param {string} source
+ * @param {string} importLine
+ * @param {string} marker substring that means "already present"
  */
-export function injectStyleImport(source) {
-  if (source.includes(STYLE_MARKER)) {
+export function injectImportLine(source, importLine, marker) {
+  if (source.includes(marker)) {
     return { source, changed: false, reason: 'already-present' }
   }
 
@@ -69,17 +81,35 @@ export function injectStyleImport(source) {
   }
 
   if (lastImportIndex >= 0) {
-    lines.splice(lastImportIndex + 1, 0, STYLE_IMPORT)
-  } else {
-    // After shebang / 'use strict' if present
+    lines.splice(lastImportIndex + 1, 0, importLine)
+  }
+  else {
     let insertAt = 0
     if (lines[0]?.startsWith('#!')) insertAt = 1
-    lines.splice(insertAt, 0, STYLE_IMPORT, '')
+    lines.splice(insertAt, 0, importLine, '')
   }
 
   return { source: lines.join('\n'), changed: true }
 }
 
+/**
+ * @param {string} source
+ * @deprecated use injectImportLine
+ */
+export function injectStyleImport(source) {
+  return injectImportLine(source, STYLE_IMPORT, STYLE_MARKER)
+}
+
+/**
+ * @param {string} entryFile absolute
+ * @param {string} shellFile absolute
+ */
+export function shellImportLine(entryFile, shellFile) {
+  let rel = relative(dirname(entryFile), shellFile).replace(/\\/g, '/')
+  if (!rel.startsWith('.')) rel = `./${rel}`
+  return `import '${rel}'`
+}
+
 /**
  * @returns {{
  *   action: 'injected' | 'skipped' | 'missing-entry',
@@ -95,7 +125,7 @@ export function ensureStylesImport(cwd, { dryRun = false } = {}) {
   }
 
   const original = readFileSync(entry, 'utf8')
-  const { source, changed, reason } = injectStyleImport(original)
+  const { source, changed, reason } = injectImportLine(original, STYLE_IMPORT, STYLE_MARKER)
 
   if (!changed) {
     return { action: 'skipped', path: entry, reason: reason || 'already-present' }
@@ -107,3 +137,68 @@ export function ensureStylesImport(cwd, { dryRun = false } = {}) {
 
   return { action: 'injected', path: entry, dryRun }
 }
+
+/**
+ * Write morya-app-shell.css (height chain) and inject its import into the entry.
+ * @returns {{
+ *   fileAction: 'written' | 'skipped' | 'dry-run',
+ *   importAction: 'injected' | 'skipped' | 'missing-entry',
+ *   path?: string,
+ *   entry?: string,
+ *   reason?: string,
+ *   dryRun?: boolean
+ * }}
+ */
+export function ensureShellStyles(cwd, { dryRun = false, force = false } = {}) {
+  const shellFile = join(cwd, SHELL_REL)
+  const entry = findEntryFile(cwd)
+
+  let fileAction = 'skipped'
+  if (!existsSync(shellFile) || force) {
+    if (dryRun) {
+      fileAction = 'dry-run'
+    }
+    else {
+      mkdirSync(dirname(shellFile), { recursive: true })
+      writeFileSync(shellFile, SHELL_CSS, 'utf8')
+      fileAction = 'written'
+    }
+  }
+
+  if (!entry) {
+    return {
+      fileAction,
+      importAction: 'missing-entry',
+      path: shellFile,
+      reason: 'no-entry-found',
+      dryRun,
+    }
+  }
+
+  const importLine = shellImportLine(entry, shellFile)
+  const original = readFileSync(entry, 'utf8')
+  const { source, changed, reason } = injectImportLine(original, importLine, SHELL_MARKER)
+
+  if (!changed) {
+    return {
+      fileAction,
+      importAction: 'skipped',
+      path: shellFile,
+      entry,
+      reason: reason || 'already-present',
+      dryRun,
+    }
+  }
+
+  if (!dryRun) {
+    writeFileSync(entry, source, 'utf8')
+  }
+
+  return {
+    fileAction,
+    importAction: 'injected',
+    path: shellFile,
+    entry,
+    dryRun,
+  }
+}

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

@@ -47,8 +47,8 @@ Full API: docs site `/components` or MCP (`get_component`, `search`, `validate_u
 | Intent | Prefer |
 | --- | --- |
 | Searchable list + paging | `MPageFilters` + `MTable` (+ paginator) |
-| Create / edit entity page | Form golden layout + `MForm` |
-| Create / edit in place | `MDialog` or `MDrawer` + form |
+| Create / edit from a list (few–medium fields) | **`MDialog` + `MForm`** (stay on the list) |
+| Create / edit long / multi-section entity | Form golden page **or** `MDrawer` |
 | Delete | `MConfirmDialog` |
 | Lightweight inline status | `MStatus` (dot + label) |
 | Status chip / closable label | `MTag` severities |
@@ -60,6 +60,7 @@ Full API: docs site `/components` or MCP (`get_component`, `search`, `validate_u
 | Empty list / zero state | `MEmpty` (+ `empty-state` golden or `MTable` `#empty`) |
 | Submit success / HTTP error page | `MResult` |
 | Local capped scroll | Explicit `MScrollbar` |
+| Admin sider nav | `MMenu` |
 
 ## Common mistakes
 

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

@@ -21,7 +21,14 @@ import 'morya-ui/styles.css'
 <template>
   <MConfigProvider :locale="zhCN">
     <MLayout fill-viewport has-sider>
-      <MLayoutSider bordered>...</MLayoutSider>
+      <MLayoutSider bordered>
+        <MMenu
+          :model="[
+            { key: 'users', label: 'Users', icon: 'user', to: '/users' },
+            { key: 'roles', label: 'Roles', icon: 'shield', to: '/roles' },
+          ]"
+        />
+      </MLayoutSider>
       <MLayout>
         <MLayoutHeader>...</MLayoutHeader>
         <MLayoutContent>...</MLayoutContent>
@@ -34,6 +41,7 @@ import 'morya-ui/styles.css'
 | Role | Prefer |
 | --- | --- |
 | Admin chrome | `MLayout fillViewport` + sider / header / content |
+| Sider nav | `MMenu` |
 | Page stack | `MPageContent` inside `MLayoutContent` |
 | Filters / toolbar | `MPageFilters` + `MPageToolbar` |
 | Form surfaces | `MPageHeader` + `MPageSection variant="form|actions"` |

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

@@ -16,12 +16,14 @@ Via MCP: `recommend_page` → `get_golden_page`; local edits: `get_page_snippet`
 ## 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`
+2. Sider `MMenu`
+3. `MLayoutHeader` → `MBreadcrumb`
+4. `MLayoutContent` → `MPageContent`
+5. `MPageFilters` — inner `MSpace` + Input/Select + query/reset
+6. `MPageToolbar` — title + `#actions` primary action
+7. `MTable` directly in content (usually **no** wrapping `MCard`)
+8. Pagination via `MTable` paginator or sibling `MPagination`
+9. Short create/edit → `MDialog` + `MForm` on the same page (default)
 
 ## Form page — block order
 
@@ -42,7 +44,7 @@ Via MCP: `recommend_page` → `get_golden_page`; local edits: `get_page_snippet`
 
 | Topic | Prefer | Usually avoid |
 | --- | --- | --- |
-| Shell | `MLayout fillViewport` + `MPageContent` | Hand `min-height: 100vh`; padding on `MLayoutContent` |
+| Shell | `MLayout fillViewport` + `MPageContent` | 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 |

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

@@ -6,12 +6,12 @@ Pick a lane, then a surface. Prefer project golden pages for **Ops**; use the re
 
 | Surface | Job | Compose from |
 | --- | --- | --- |
-| List | Scan, filter, act on many rows | Golden list + [page-layouts.md](page-layouts.md) |
-| Form | Create / edit one entity | Golden form |
+| List | Scan, filter, act on many rows | Golden list + [page-layouts.md](page-layouts.md); **create/edit with ≤~8 fields → `MDialog` on the list** |
+| Form | Create / edit one entity as a **dedicated page** | Golden form — only when multi-section, many fields, or user asked for an independent form route |
 | Dashboard | Orient + jump to work | Golden dashboard |
-| Detail | Read-heavy record + secondary actions | `MPageHeader` + `MDescriptions`-style sections via `MCard`/`MPageSection`, actions in toolbar; edit via route or `MDrawer`/`MDialog` |
+| Detail | Read-heavy record + secondary actions | `MPageHeader` + sections via `MCard`/`MPageSection`; edit via `MDialog` / `MDrawer` (prefer over a second form route) |
 | Settings | Grouped preferences | Narrow `MPageContent` + stacked `MPageSection` / `MTabs` + `MForm` |
-| Hybrid list | List + drawer/dialog | List golden + overlay recipe |
+| Hybrid list | List + drawer/dialog | **Default Ops CRUD pattern**: list golden + `MDialog`/`MDrawer` form |
 
 ## Account
 

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

@@ -10,21 +10,27 @@ alwaysApply: false
 | 类型 | 模板 |
 | --- | --- |
 | 列表页 | `docs/golden-pages/list-page.vue` |
-| 表单页 | `docs/golden-pages/form-page.vue` |
+| 表单页 | `docs/golden-pages/form-page.vue`（仅长表单 / 独立配置页） |
 | 仪表盘 | `docs/golden-pages/dashboard-page.vue` |
 | 登录页 | `docs/golden-pages/login-page.vue` |
 | 营销落地 | `docs/golden-pages/landing-page.vue` |
 | 空状态 | `docs/golden-pages/empty-state.vue` |
 
+## 列表内新建 / 编辑（默认）
+
+后台 CRUD **优先**：列表页 + `MDialog`（或 `MDrawer`）内 `MForm`，不要把「新建用户 / 编辑角色」做成单独路由，除非字段很多或多步骤。
+
 ## 列表页区块顺序
 
 1. `MLayout fillViewport` + 可选 `MLayoutSider bordered`
-2. `MLayoutHeader` → `MBreadcrumb`
-3. `MLayoutContent` → `MPageContent`
-4. `MPageFilters`（内 `MSpace` + Input/Select + 查询/重置）
-5. `MPageToolbar`（标题 + `#actions` 主操作）
-6. `MTable`（直接放置，通常不必包 `MCard`）
-7. 分页由 `MTable paginator` 或同级 `MPagination`
+2. 侧栏 `MMenu`
+3. `MLayoutHeader` → `MBreadcrumb`
+4. `MLayoutContent` → `MPageContent`
+5. `MPageFilters`（内 `MSpace` + Input/Select + 查询/重置）
+6. `MPageToolbar`（标题 + `#actions` 主操作）
+7. `MTable`（直接放置，通常不必包 `MCard`）
+8. 分页由 `MTable paginator` 或同级 `MPagination`
+9. 短新建/编辑：同页 `MDialog` + `MForm`
 
 ## 表单页区块顺序
 
@@ -47,7 +53,7 @@ alwaysApply: false
 
 | 主题 | 推荐 | 通常不必 |
 | --- | --- | --- |
-| 骨架 | `MLayout fillViewport` + `MPageContent` | 手写 `min-height:100vh`；`MLayoutContent` 再写 padding |
+| 骨架 | `MLayout fillViewport` + `MPageContent` | `MLayoutContent` 再写 padding |
 | 区块 | `MPageFilters` / `MPageToolbar` / `MPageSection` | 手写 `.page-*`；`MCard` 再包一层 |
 | 列表表格 | `MTable` 直接放在 `MPageContent` | 用 `MCard` 再包 bordered 表格 |
 | 控件间距 | 同行用 `MSpace` / `MFlex`；区块靠 `MPageContent` gap | 外包 padded `div` 叠间距 |

package/template/DESIGN.md

@@ -1,6 +1,6 @@
 # Morya UI 设计系统（AI 第一信源）
 
-> 基于 `morya-ui` v0.1.x。生成或审查业务页面时，**必须先遵守本文**，再查阅 `docs/components.md` 与 `docs/golden-pages/`。
+> 基于 `morya-ui` v0.2.6。生成或审查业务页面时，**必须先遵守本文**，再查阅 `docs/components.md` 与 `docs/golden-pages/`。
 
 ## 1. 设计原则
 
@@ -20,8 +20,15 @@ import 'morya-ui/styles.css'
 
 <template>
   <MConfigProvider :locale="zhCN">
-    <MLayout has-sider>
-      <MLayoutSider>...</MLayoutSider>
+    <MLayout has-sider fill-viewport>
+      <MLayoutSider bordered>
+        <MMenu
+          :model="[
+            { key: 'users', label: '用户管理', icon: 'user', to: '/users' },
+            { key: 'roles', label: '角色管理', icon: 'shield', to: '/roles' },
+          ]"
+        />
+      </MLayoutSider>
       <MLayout>
         <MLayoutHeader>...</MLayoutHeader>
         <MLayoutContent>...</MLayoutContent>
@@ -32,6 +39,7 @@ import 'morya-ui/styles.css'
 ```
 
 - 管理后台：`MLayout fillViewport` + `MLayoutSider` + `MLayoutHeader` + `MLayoutContent`
+- 侧栏导航：`MMenu`
 - 页面内容堆叠：`MPageContent`（内置于 `MLayoutContent`）
 - 列表筛选 / 工具栏：`MPageFilters` + `MPageToolbar`
 - 表单引导 / 表面：`MPageHeader` + `MPageSection variant="form|actions"`
@@ -56,9 +64,11 @@ import 'morya-ui/styles.css'
 ## 4. 表单约定
 
 - 使用 `MForm` + `MFormItem`，`name` 与校验规则对应。
+- **从列表新建/编辑（字段约 ≤8、单段表单）默认用 `MDialog` + `MForm`，不要为每个实体再开独立路由表单页。**
+- 多分组、长流程、向导式录入再用独立表单页（`docs/golden-pages/form-page.vue`）或 `MDrawer`。
 - 字段组件自带 `label` / `invalid` / `helpText` 时优先用组件 prop（如 `MInput`、`MSelect`），复杂表单再用 `MFormItem` 包一层。
 - 尺寸：默认 medium；密集后台可 `size="small"` 或 ConfigProvider `globalDensity`。
-- 宽度：筛选项 `fluid` 慎用；表单页主栏 `max-width: 40rem` 左右。
+- 宽度：筛选项 `fluid` 慎用；独立表单页主栏 `max-width: 40rem` 左右。
 
 ## 5. 数据展示
 
@@ -98,7 +108,7 @@ import 'morya-ui/styles.css'
 
 ## 8. 禁止项
 
-- 禁止引入第二套 UI 库（Element Plus、Naive UI 等）混用同一页面。
+- 禁止引入第二套 UI 库混用同一页面。
 - 禁止在业务 CSS 中写死主题色；暗色模式必须能随 `[data-theme="dark"]` 生效。
 - 禁止用 `<div onclick>` 代替 `<button>` / `MButton`。
 - 禁止 Select 与 Dropdown 混用：选项选择用 `MSelect` / `MTreeSelect`；动作菜单用 `MDropdown`。

package/template/design-tokens/tokens.json

@@ -2,7 +2,7 @@
   "$schema": "https://design-tokens.github.io/community-group/format/",
   "meta": {
     "name": "morya-ui",
-    "version": "0.1.1",
+    "version": "0.2.6",
     "source": "morya-ui/src/theme/styles.css",
     "prefix": "m"
   },

package/template/docs/components.md

@@ -114,7 +114,8 @@
 | 我要做… | 首选组件 |
 | --- | --- |
 | 用户列表 + 搜索 + 分页 | `MTable` + `MInput` + `MPagination` |
-| 新建/编辑实体 | `MForm` + 字段组件 + `MDialog` 或独立路由页 |
+| 新建/编辑实体（短表单，列表内） | **`MDialog` + `MForm` + 字段组件**（首选） |
+| 新建/编辑实体（长表单 / 多分组） | `MForm` + 独立表单页或 `MDrawer` |
 | 删除确认 | `MConfirmDialog` |
 | 筛选侧栏 | `MDrawer` + 表单控件 |
 | 状态指示（行内） | `MStatus`（圆点 + 文案） |

package/template/docs/feedback-message-vs-toast.md

@@ -88,13 +88,13 @@ message.error('操作失败')
 | 删除确认用 Message/Toast | `MConfirmDialog` |
 | 所有反馈都用 Toast | 默认改 Message，仅 detail 场景保留 Toast |
 
-## 与 Naive / Element Plus 的对应
+## 概念对照
 
-| Morya UI | 近似概念 |
+| API | 用途 |
 | --- | --- |
-| `message` | Naive `message` / Element `ElMessage` |
-| `toast` | Naive `notification` / Element `ElNotification` |
-| `<MMessage>` | 页面内 `el-alert` / 表单顶部错误条 |
+| `message` | 轻量、短暂的操作反馈（默认首选） |
+| `toast` | 带摘要 + 详情、或需停留更久的通知 |
+| `<MMessage>` | 页面内常驻提示条（如表单顶部错误） |
 
 ## 相关文档
 

package/template/docs/golden-pages/list-page.vue

@@ -26,6 +26,12 @@ import { ref } from 'vue'
 
 const keyword = ref('')
 const status = ref<string | undefined>()
+const siderCollapsed = ref(false)
+
+const menuModel = [
+  { key: 'users', label: '用户管理', icon: 'user', to: '/users' },
+  { key: 'roles', label: '角色管理', icon: 'shield', to: '/roles' },
+]
 
 const statusOptions = [
   { label: '全部', value: '' },
@@ -52,8 +58,13 @@ const rows = [
 <template>
   <MConfigProvider :locale="zhCN">
     <MLayout has-sider fill-viewport>
-      <MLayoutSider bordered>
-        <MMenu :model="[{ label: '用户管理', key: 'users' }, { label: '角色管理', key: 'roles' }]" />
+      <MLayoutSider v-model:collapsed="siderCollapsed" bordered :collapsed-width="72">
+        <MMenu
+          :model="menuModel"
+          :collapsed="siderCollapsed"
+          :collapsed-width="72"
+          selected-key="users"
+        />
       </MLayoutSider>
 
       <MLayout>

package/template/src/examples/ListPageExample.vue

@@ -26,6 +26,12 @@ import { ref } from 'vue'
 
 const keyword = ref('')
 const status = ref<string | undefined>()
+const siderCollapsed = ref(false)
+
+const menuModel = [
+  { key: 'users', label: '用户管理', icon: 'user', to: '/users' },
+  { key: 'roles', label: '角色管理', icon: 'shield', to: '/roles' },
+]
 
 const statusOptions = [
   { label: '全部', value: '' },
@@ -52,8 +58,13 @@ const rows = [
 <template>
   <MConfigProvider :locale="zhCN">
     <MLayout has-sider fill-viewport>
-      <MLayoutSider bordered>
-        <MMenu :model="[{ label: '用户管理', key: 'users' }, { label: '角色管理', key: 'roles' }]" />
+      <MLayoutSider v-model:collapsed="siderCollapsed" bordered :collapsed-width="72">
+        <MMenu
+          :model="menuModel"
+          :collapsed="siderCollapsed"
+          :collapsed-width="72"
+          selected-key="users"
+        />
       </MLayoutSider>
 
       <MLayout>

package/template/src/styles/morya-app-shell.css

@@ -0,0 +1,6 @@
+html,
+body,
+#app {
+  height: 100%;
+  margin: 0;
+}