@deernova/style 0.1.0 → 0.3.0

package/README.md

@@ -1,16 +1,18 @@
 # @deernova/style
 
-Versioned Deernova design skill installer and static website template. Requires Node.js 22+. No runtime dependencies.
+Install the Deernova design skill into an existing repository, so AI agents follow Deernova when they build or review interfaces there. Requires Node.js 22+. No runtime dependencies.
 
 ```sh
-npx @deernova/style@latest install
+npx @deernova/style@latest install                  # writes .agents/skills/deernova-style/
+npx @deernova/style@latest install --agent claude   # writes .claude/skills/deernova-style/
 npx @deernova/style@latest update
 npx @deernova/style@latest doctor
-npx @deernova/style@latest init ./my-site
 ```
 
-Default installation: `.agents/skills/deernova-style` in the current project. Use `--global` for Codex user skills (`$CODEX_HOME/skills` or `~/.codex/skills`), `--agent claude|codex|agents` to choose the agent directory, or `--dir <skills-parent>` for a custom destination. Repeat the same options when updating.
+Run these inside the target project, or pass `--repo <path>`. The CLI writes only the skill directory. It does not add application code, CSS imports or package dependencies.
 
-The skill bundles full foundations, component usage and SwiftUI examples, token reference, web/native integration guidance, review criteria, CSS/HTML assets and images. The CLI and website ship the same version and source hash.
+The skill is guidance, not a component library: `SKILL.md` picks the scene (macOS, iOS, iPadOS, web app, website) and routes to `references/` (`foundations/`, `components/` with size tables and reference CSS/SwiftUI, `scenes/`, the token table and a review checklist). `assets/` holds `tokens.json` and the files generated from it — `tokens.css` (themes × densities), `tailwind.css` (Tailwind v4) and `DeernovaTokens.swift` — plus reference screenshots. Agents apply it through the project's existing framework and components.
 
-Updates are explicit: use `@latest update` to fetch the latest release. Locally modified skills are protected; `--force` backs up before replacing them. doctor returns nonzero if missing, modified or out of sync. init refuses nonempty directories. Serve the generated website with any static HTTP server.
+Use `--agent claude|codex|agents` to choose the skill directory, `--dir <skills-parent>` for a custom destination, or `--global` for a user installation; these three destination modes are mutually exclusive. Repeat the same options on update.
+
+Updates are explicit. Modified skills are protected; `--force` backs up before replacing them. `doctor` exits non-zero if the skill is missing, modified or out of date.

package/bin/cli.mjs

@@ -1,32 +1,215 @@
 #!/usr/bin/env node
-import { cp, mkdir, readFile, readdir, rename, rm, lstat } from 'node:fs/promises';
-import { resolve, join, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createHash } from 'node:crypto';
-const pkg = fileURLToPath(new URL('../',import.meta.url));
-const args=process.argv.slice(2), command=args.shift()||'help';
-const options={};let positional;
-for(let i=0;i<args.length;i++){const a=args[i];if(['--global','--force'].includes(a))options[a.slice(2)]=true;else if(['--dir','--agent'].includes(a)){if(!args[i+1]||args[i+1].startsWith('--'))throw Error(`${a} needs a value`);options[a.slice(2)]=args[++i];}else if(a.startsWith('-'))throw Error(`Unknown option: ${a}`);else if(positional)throw Error('Too many arguments');else positional=a;}
-async function exists(p){try{return await lstat(p);}catch(e){if(e.code==='ENOENT')return null;throw e;}}
-async function main(){
- if(['help','--help','-h'].includes(command)){console.log(`deernova-style install|update|doctor [--global] [--agent codex|claude|agents] [--dir <skills-parent>] [--force]\ndeernova-style init <empty-directory>\ndeernova-style version\nDefault: project .agents/skills/deernova-style. --global defaults to CODEX_HOME/skills.\nupdate installs the version bundled in this CLI; use npx @deernova/style@latest update to fetch latest.\n--force keeps a timestamped backup before replacing a locally modified skill.`);return;}
- const manifest=JSON.parse(await readFile(join(pkg,'skill/manifest.json'),'utf8'));
- if(command==='version'){console.log(manifest.version);return;}
- if(command==='init'){if(!positional)throw Error('Usage: deernova-style init <empty-directory>');const dest=resolve(positional);const stat=await exists(dest);if(stat&&(!stat.isDirectory()||(await readdir(dest)).length))throw Error('Destination must be an empty directory');await mkdir(dest,{recursive:true});await cp(join(pkg,'template'),dest,{recursive:true});console.log(`Created Deernova website v${manifest.version} at ${dest}\nServe with any static HTTP server.`);return;}
- if(!['install','update','doctor'].includes(command))throw Error(`Unknown command: ${command}`);
- if(positional)throw Error('Use --dir to specify a skills parent directory');
- const agent=options.agent||(options.global?'codex':'agents');if(!['codex','claude','agents'].includes(agent))throw Error('Agent must be codex, claude or agents');
- const base=options.dir?resolve(options.dir):options.global?(agent==='codex'?join(process.env.CODEX_HOME||join(homedir(),'.codex'),'skills'):join(homedir(),'.'+agent,'skills')):resolve('.'+agent,'skills');
- const dest=join(base,'deernova-style');const state=await exists(dest);
- if(state?.isSymbolicLink()||(state&&!state.isDirectory()))throw Error('Destination is not a regular directory');
- let installed=null;try{installed=JSON.parse(await readFile(join(dest,'manifest.json'),'utf8'));}catch{}
- const clean=state&&installed?.installedHash ? await installedDigest(dest)===installed.installedHash:false;
- if(command==='doctor'){console.log(JSON.stringify({path:dest,installedVersion:installed?.version||null,bundledVersion:manifest.version,sourceMatches:installed?.sourceHash===manifest.sourceHash,localChanges:state?!clean:null},null,2));if(!installed||!clean||installed.sourceHash!==manifest.sourceHash)process.exitCode=1;return;}
- if(command==='update'&&!installed)throw Error('No managed installation found. Run install first.');
- if(state&&!options.force&&(!clean||command==='install'))throw Error('Skill exists or contains local changes. Use update for clean installs, or --force to back up and replace.');
- await mkdir(base,{recursive:true});const temp=join(base,`.deernova-style-${process.pid}-${Date.now()}`);let backup;
- try{await cp(join(pkg,'skill'),temp,{recursive:true});const hash=await installedDigest(temp);const {writeFile}=await import('node:fs/promises');await writeFile(join(temp,'manifest.json'),JSON.stringify({...manifest,installedHash:hash},null,2)+'\n');if(state){backup=dest+'.backup-'+Date.now();await rename(dest,backup);}try{await rename(temp,dest);}catch(e){if(backup)await rename(backup,dest);throw e;}if(backup&&clean&&!options.force)await rm(backup,{recursive:true});console.log(`Installed Deernova v${manifest.version}: ${dest}`);if(backup&&(!clean||options.force))console.log(`Backup: ${backup}`);}finally{await rm(temp,{recursive:true,force:true});}
-}
-async function installedDigest(dir){const manifestPath=join(dir,'manifest.json');const original=JSON.parse(await readFile(manifestPath,'utf8'));const hash=createHash('sha256');async function walk(p,relative=''){for(const e of (await readdir(p,{withFileTypes:true})).sort((a,b)=>a.name.localeCompare(b.name))){const name=relative+e.name;if(name==='manifest.json')continue;if(e.isSymbolicLink())throw Error('Symlink in installed skill');hash.update(name);if(e.isDirectory())await walk(join(p,e.name),name+'/');else hash.update(await readFile(join(p,e.name)));}}await walk(dir);hash.update(original.sourceHash);hash.update(original.version);return hash.digest('hex');}
-main().catch(e=>{console.error(`deernova-style: ${e.message}`);process.exitCode=1;});
+
+const bundledSkill = fileURLToPath(new URL('../skill/', import.meta.url));
+const HELP = `deernova-style install|update|doctor [--repo <existing-repository>] [--global] [--agent codex|claude|agents] [--dir <skills-parent>] [--force]
+deernova-style init [existing-repository]  (alias for install --repo)
+deernova-style version
+Installs design reference files only; does not add app code or package dependencies. Default: project .agents/skills/deernova-style. --global defaults to CODEX_HOME/skills.
+update installs the version bundled in this CLI; use npx @deernova/style@latest update to fetch latest.
+--force keeps a timestamped backup before replacing a locally modified skill.`;
+
+function parseArgs(args) {
+  let [command = 'help', ...flags] = args;
+  const options = {};
+  let positional;
+
+  for (let i = 0; i < flags.length; i++) {
+    const flag = flags[i];
+    if (['--global', '--force'].includes(flag)) {
+      options[flag.slice(2)] = true;
+    } else if (['--dir', '--agent', '--repo'].includes(flag)) {
+      if (!flags[i + 1] || flags[i + 1].startsWith('--')) {
+        throw Error(`${flag} needs a value`);
+      }
+      options[flag.slice(2)] = flags[++i];
+    } else if (flag.startsWith('-')) {
+      throw Error(`Unknown option: ${flag}`);
+    } else if (positional !== undefined) {
+      throw Error('Too many arguments');
+    } else {
+      positional = flag;
+    }
+  }
+
+  if (command === 'init') {
+    if (options.repo && positional) throw Error('Specify the repository once');
+    options.repo = positional || options.repo || process.cwd();
+    positional = undefined;
+    command = 'install';
+  }
+
+  return { command, options, positional };
+}
+
+async function statIfExists(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function resolveDestination(options) {
+  if ([options.repo, options.global, options.dir].filter(Boolean).length > 1) {
+    throw Error('--repo, --global and --dir are mutually exclusive');
+  }
+
+  const repo = resolve(options.repo || process.cwd());
+  if (!options.global && !options.dir && !(await statIfExists(repo))?.isDirectory()) {
+    throw Error('Repository must be an existing directory');
+  }
+
+  const agent = options.agent || (options.global ? 'codex' : 'agents');
+  if (!['codex', 'claude', 'agents'].includes(agent)) {
+    throw Error('Agent must be codex, claude or agents');
+  }
+
+  let base;
+  if (options.dir) {
+    base = resolve(options.dir);
+  } else if (options.global) {
+    base = agent === 'codex'
+      ? join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'skills')
+      : join(homedir(), `.${agent}`, 'skills');
+  } else {
+    base = join(repo, `.${agent}`, 'skills');
+  }
+
+  return { base, dest: join(base, 'deernova-style') };
+}
+
+// Keep this digest compatible with existing installations. The manifest is not
+// hashed as a file: only its source hash and version participate in the digest.
+async function installedDigest(dir, manifest) {
+  const hash = createHash('sha256');
+
+  async function walk(path, relative = '') {
+    const entries = await readdir(path, { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const name = relative + entry.name;
+      if (name === 'manifest.json') continue;
+      if (entry.isSymbolicLink()) throw Error('Symlink in installed skill');
+
+      hash.update(name);
+      if (entry.isDirectory()) await walk(join(path, entry.name), `${name}/`);
+      else hash.update(await readFile(join(path, entry.name)));
+    }
+  }
+
+  await walk(dir);
+  hash.update(manifest.sourceHash);
+  hash.update(manifest.version);
+  return hash.digest('hex');
+}
+
+async function inspectInstallation(dest) {
+  const state = await statIfExists(dest);
+  if (state?.isSymbolicLink() || (state && !state.isDirectory())) {
+    throw Error('Destination is not a regular directory');
+  }
+
+  let manifest = null;
+  try {
+    manifest = JSON.parse(await readFile(join(dest, 'manifest.json'), 'utf8'));
+  } catch {
+    // A folder without a readable manifest is an unmanaged installation.
+  }
+
+  const clean = Boolean(state && manifest?.installedHash)
+    && await installedDigest(dest, manifest) === manifest.installedHash;
+  return { exists: Boolean(state), manifest, clean };
+}
+
+function reportInstallation(dest, installed, bundled) {
+  const sourceMatches = installed.manifest?.sourceHash === bundled.sourceHash;
+  console.log(JSON.stringify({
+    path: dest,
+    installedVersion: installed.manifest?.version || null,
+    bundledVersion: bundled.version,
+    sourceMatches,
+    localChanges: installed.exists ? !installed.clean : null
+  }, null, 2));
+
+  if (!installed.manifest || !installed.clean || !sourceMatches) process.exitCode = 1;
+}
+
+async function replaceInstallation({ base, dest }, installed, manifest, force) {
+  await mkdir(base, { recursive: true });
+  const temp = await mkdtemp(join(base, '.deernova-style-'));
+  let backup;
+
+  try {
+    // Prepare the complete replacement before touching the installed directory.
+    await cp(bundledSkill, temp, { recursive: true });
+    const installedHash = await installedDigest(temp, manifest);
+    await writeFile(join(temp, 'manifest.json'), JSON.stringify({
+      ...manifest,
+      installedHash
+    }, null, 2) + '\n');
+
+    if (installed.exists) {
+      backup = `${dest}.backup-${Date.now()}`;
+      await rename(dest, backup);
+    }
+
+    try {
+      await rename(temp, dest);
+    } catch (error) {
+      if (backup) await rename(backup, dest);
+      throw error;
+    }
+
+    const keepBackup = backup && (!installed.clean || force);
+    if (backup && !keepBackup) await rm(backup, { recursive: true });
+    console.log(`Installed Deernova v${manifest.version}: ${dest}`);
+    if (keepBackup) console.log(`Backup: ${backup}`);
+  } finally {
+    await rm(temp, { recursive: true, force: true });
+  }
+}
+
+async function main() {
+  const { command, options, positional } = parseArgs(process.argv.slice(2));
+  if (['help', '--help', '-h'].includes(command)) {
+    console.log(HELP);
+    return;
+  }
+  if (!['version', 'install', 'update', 'doctor'].includes(command)) {
+    throw Error(`Unknown command: ${command}`);
+  }
+
+  const manifest = JSON.parse(await readFile(join(bundledSkill, 'manifest.json'), 'utf8'));
+  if (command === 'version') {
+    console.log(manifest.version);
+    return;
+  }
+  if (positional !== undefined) {
+    throw Error('Use --repo to specify a repository or --dir to specify a skills parent');
+  }
+
+  const destination = await resolveDestination(options);
+  const installed = await inspectInstallation(destination.dest);
+  if (command === 'doctor') {
+    reportInstallation(destination.dest, installed, manifest);
+    return;
+  }
+  if (command === 'update' && !installed.manifest) {
+    throw Error('No managed installation found. Run install first.');
+  }
+  if (installed.exists && !options.force && (!installed.clean || command === 'install')) {
+    throw Error('Skill exists or contains local changes. Use update for clean installs, or --force to back up and replace.');
+  }
+
+  await replaceInstallation(destination, installed, manifest, options.force);
+}
+
+main().catch(error => {
+  console.error(`deernova-style: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deernova/style",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -13,8 +13,7 @@
   },
   "files": [
     "bin",
-    "skill",
-    "template"
+    "skill"
   ],
-  "description": "Deernova design skill installer and website template CLI"
+  "description": "Install the Deernova design reference skill into an existing repository"
 }

package/skill/SKILL.md

@@ -1,36 +1,106 @@
 ---
 name: deernova-style
-description: Apply Deernova's monochrome design language to Deernova apps, websites and components; implement or review semantic tokens, typography, paper and glass hierarchy, platform density and accessibility. Use when a project requests Deernova styling or adopts this design system.
+description: Deernova 的界面设计语言：只用黑白灰，内容放在不透明纸面上，原生端的操作层用系统 Liquid Glass，Web 应用用不透明平面加 1px 线；界面和 AI 回答用无衬线，衬线只给大标题和长文；按场景（Web 应用、macOS、iOS、iPadOS、官网与文档）切换密度。在 Deernova 的应用或网站里新建、修改或审查界面时使用，包括颜色、字体、间距、圆角、线条、阴影、按钮、输入框、侧边栏、顶栏、列表、卡片、弹窗、空状态、AI 对话和任务清单，以及对应的 CSS、Tailwind 或 SwiftUI 实现。
 ---
 
-# Deernova Style
+# Deernova 设计语言
 
-Build coherent Deernova interfaces using the versioned resources bundled with this skill. Preserve the user's product, platform, framework and requested scope. The HTML previews demonstrate appearance; they are not production SwiftUI components or proof of functional behavior.
+只用黑、白、灰；内容放在不透明的纸面上，原生端的操作层交给系统玻璃；界面文字用系统无衬线，衬线只用来点题；整体安静、克制、层次清楚，像一件趁手的工具。
 
-## Start with the relevant source
+桌面端的骨架和密度参照 Claude 桌面端（Code）：288 宽的侧边栏、44 高的顶栏、居中的对话栏、底部的输入区、可以并排打开的侧面板，正文 15/24。颜色、玻璃和衬线是 Deernova 自己的。
 
-- Read [foundations](references/foundations.md) for principles, writing, layout, platform behavior, motion and accessibility.
-- Read [tokens](references/tokens.md) when choosing semantic values. Exact structured values and typography live in `assets/design/tokens.json`; use `assets/design/tokens.css` for web projects.
-- Search [components](references/components.md) for the component being implemented, then inspect `assets/design/components/<Name>/preview.html` for its anatomy and variants. Native implementation examples live in that component's README.
-- For web implementation and validation, read [web](references/web.md). For native implementation, read [native](references/native.md).
-- For design review, read [review](references/review.md). Report concrete mismatches and locations; do not redesign unrelated screens.
+这份 skill 是规范和数据，不是组件库：不需要安装任何包。用项目现有的技术栈和组件实现这些规则，缺的部分按这里的规格和参考写法补上。
 
-## Core decisions
+## 第一步：确定场景
 
-Content lives on opaque paper surfaces; transient actions may use glass. Use neutral grayscale and contrast for emphasis. Color communicates status with supporting text or symbols. Use semantic tokens rather than copying literals. `accent` maps to ink; primary labels use `on-accent`, never hardcoded white.
+所有尺寸都按场景取值。先看你在做哪一种界面，再去读对应的场景说明。
 
-Serif communicates titles and sustained reading; system sans supports controls; monospace supports code and aligned data. Preserve platform differences: compact macOS controls, Dynamic Type and 44 pt hit regions on iOS, responsive web layouts. Do not impose desktop dimensions on touch screens.
+<!-- tokens:scenes -->
+| 场景 | 密度 | 输入 | 怎么启用 | 读这里 |
+| --- | --- | --- | --- | --- |
+| Web 应用 | 桌面（`desktop`） | 指针 | tokens.css 的默认值 | [scenes/web.md](references/scenes/web.md) |
+| Web 触屏 | 触控（`touch`） | 触摸 | `@media (pointer: coarse)` 自动切换 | [scenes/web.md](references/scenes/web.md) |
+| macOS | 桌面（`desktop`） | 指针 | 系统控件用系统尺寸；内容区用 `DeernovaTokens.swift` 的 `#if os(macOS)` | [scenes/macos.md](references/scenes/macos.md) |
+| iOS | 触控（`touch`） | 触摸 | `DeernovaTokens.swift` 的 `#else` | [scenes/ios.md](references/scenes/ios.md) |
+| iPadOS | 触控（`touch`） | 触摸和指针 | 同 iOS；分栏布局另见场景说明 | [scenes/ipados.md](references/scenes/ipados.md) |
+| 官网与文档 | 舒展（`comfortable`） | 指针 | 根元素加 `data-density="comfortable"` | [scenes/web-marketing.md](references/scenes/web-marketing.md) |
+<!-- /tokens -->
 
-Cards use thin borders without floating shadows. System-native controls and glass take precedence on supported Apple platforms. The supplied CSS glass values are web approximations only. Honor the project's deployment target rather than silently raising it to the source guide's iOS/macOS 26 baseline.
+后台、工具、编辑器、AI 对话这类应用界面，不论是不是网页，都不要用官网的尺寸。
 
-## Workflow
+## 场景速查
 
-1. Identify target platform, screen purpose, existing components and styling integration.
-2. Select tokens and component patterns from the bundled source. Retain existing product behavior and content.
-3. Implement normal, selected, disabled, loading, empty and error states where the product needs them. Give demonstrations explicit demo behavior; do not invent backend operations.
-4. Verify both themes, keyboard navigation, focus, overflow, status clarity and relevant touch/text scaling. Use the review reference for concrete criteria.
-5. Report implementation and verification limits. Do not claim native parity or accessibility compliance based only on the visual preview.
+<!-- tokens:summary -->
+| | 桌面<br>Web 应用 · macOS 内容区 | 触控<br>iOS · iPadOS · Web 触屏 | 舒展<br>官网与文档 |
+| --- | --- | --- | --- |
+| 正文 | 15 / 24 | 17 / 23 | 15 / 24 |
+| 长文、AI 回答（衬线） | 16 / 26 | 17 / 26 | 17 / 28 |
+| 默认按钮（可见高度） | 28，圆角 6 | 36，胶囊 | 36，胶囊 |
+| 小 / 大按钮 | 24 / 32 | 30 / 46 | 32 / 44 |
+| 最小点击区域 | 24 | 44 | 24 |
+| 输入框 | 28 | 44 | 40 |
+| 列表行 | 32 | 44 | 40 |
+| 卡片：圆角 / 内边距 | 12 / 12 × 16 | 12 / 14 × 16 | 12 / 24 × 24 |
+| 页面边距 | 32 | 16 | 32 |
+| 侧边栏宽度 | 288 | 320 | 260 |
+<!-- /tokens -->
 
-## Version and updates
+所有数值都来自 `assets/tokens.json`，按密度生成在 `assets/tokens.css` 里。写代码时引用变量名（`var(--button-height-md)`、`Deernova.buttonHeightMd`），不要抄数字。
 
-`manifest.json` identifies the package version and source hash. Website, CSS and skill references are generated together from the repository's `design/` source. Update through `npx @deernova/style@latest update` in the same project; for global installations append `--global` and the same agent choice. This is an explicit update, not a background network service. Preserve local changes; the CLI refuses to overwrite them unless `--force` is requested, in which case it keeps a backup. Never edit generated references as the upstream source.
+## 核心规则
+
+1. **纸面承载内容，玻璃交给系统。** 文字、列表、卡片、代码、消息、输入区是内容，放在不透明的纸面上：`canvas` → `surface` → `surface-raised`，代码块和展开的详情用 `surface-sunken`。操作层按平台处理：**SwiftUI 端**（macOS、iOS、iPadOS）的侧边栏、工具栏、标签栏、浮动按钮直接用系统 Liquid Glass，这是原生端的优势，不要盖掉；**Web 应用**不模拟玻璃，操作层是不透明平面加 1px 分隔线；只有官网与文档的页眉可以用轻玻璃。玻璃上不放段落，内容不做成玻璃，玻璃不叠玻璃。
+2. **黑白灰，强调靠对比。** `accent` 就是墨色 `ink`：主按钮在浅色主题是黑底白字，在深色主题是白底黑字，文字用 `on-accent`，不要写死白色。唯一的彩色是状态色 `success`、`warning`、`danger`、`info`，只用来表达状态，而且必须同时带图标或文字。
+3. **线条代替阴影。** 区块之间用 `line` 色的 1px 线分隔（`stroke-line`）。卡片不加阴影；只有菜单、弹窗、浮动面板和 Composer 这类真正浮起来的东西才用 `shadow-float`。
+4. **无衬线做界面，衬线点题。** 界面文字、AI 回答、用户消息、标题栏都用系统无衬线（SF Pro）；代码和需要对齐的数字用等宽（SF Mono）。衬线（New York）只用在页面大标题和空状态标题（`display`、`title`）、官网与文档，以及文章类的长文阅读（`prose`）。中文统一落到苹方。
+5. **层次靠字号和灰度，少用粗体。** 600 只给真正的标题（`display`、`title`、`headline`）。分组标题、会话名、说明、时间戳用常规字重，靠 `ink-secondary`、`ink-tertiary` 和小一号的字区分层级。
+6. **控件高度由 token 决定，点击区域单独补。** 按钮、输入框、列表行的可见高度直接用 `button-height-*`、`field-height`、`row-height`，上下内边距为 0，不让页面行高把它撑高。可见尺寸小于 `hit-min` 时，用透明的命中区补足，不加大可见的控件。
+7. **间距成组。** 间距走 4pt 网格。组内用 `gap-stack`，组与组之间用 `gap-group`（至少 2 倍）；内容区里段落、工具调用、卡片之间 `space-4`。用细线和少量留白分组，不靠大块空白和外框。
+8. **原生端用系统控件，Web 端用同一套自绘组件。** SwiftUI 端的导航结构、侧边栏、工具栏、菜单、表单、弹窗直接用系统控件和系统尺寸，只通过颜色和字体让它们融入；自己画的内容区（对话、卡片、输入区、任务清单）用 token。Web 应用没有系统控件可借，按组件说明里的规格画，骨架见 [Web 应用](references/scenes/web.md)。
+
+## 读什么
+
+| 你在做 | 先读 |
+| --- | --- |
+| 任何界面 | 上面的核心规则，加上对应的场景说明 `references/scenes/` |
+| 某个组件 | [组件](#组件)里对应的文件：用途、尺寸表、状态、Web 和 SwiftUI 写法 |
+| 需要具体数值 | [设计变量](references/tokens.md)；数据在 `assets/tokens.json` |
+| 接入变量 | CSS：`assets/tokens.css`；Tailwind v4：`assets/tailwind.css`；SwiftUI：`assets/DeernovaTokens.swift` |
+| 某条规则为什么这样 | [基础](#基础)里对应的主题 |
+| 审查已有界面 | [审查清单](references/review.md) |
+| 先看原生端的玻璃效果 | `assets/screens/` 里的截图，各有浅色和深色 |
+
+### 基础
+
+[颜色](references/foundations/color.md) · [字体](references/foundations/typography.md) · [间距与布局](references/foundations/spacing.md) · [圆角](references/foundations/radius.md) · [线条](references/foundations/stroke.md) · [层级与阴影](references/foundations/elevation.md) · [玻璃](references/foundations/glass.md) · [动效](references/foundations/motion.md) · [图标](references/foundations/iconography.md) · [文案](references/foundations/writing.md) · [无障碍](references/foundations/accessibility.md)
+
+### 组件
+
+[按钮](references/components/button.md) · [顶栏与侧面板](references/components/toolbar.md) · [玻璃操作层](references/components/glass-controls.md) · [分段控件](references/components/segmented.md) · [文本框](references/components/text-field.md) · [Composer](references/components/composer.md) · [侧边栏](references/components/sidebar.md) · [分组列表](references/components/list.md) · [卡片](references/components/card.md) · [标签](references/components/tag.md) · [代码块](references/components/code-block.md) · [任务清单](references/components/task-list.md) · [空状态](references/components/empty-state.md) · [横幅与轻提示](references/components/banner.md) · [弹窗](references/components/sheet.md) · [消息](references/components/message.md) · [工具调用与执行步骤](references/components/step-row.md)
+
+### 场景
+
+[Web 应用](references/scenes/web.md) · [官网与文档](references/scenes/web-marketing.md) · [macOS](references/scenes/macos.md) · [iOS](references/scenes/ios.md) · [iPadOS](references/scenes/ipados.md) · [SwiftUI 共用](references/scenes/swiftui.md)
+
+## 工作流程
+
+1. **先看项目。** 确认场景（上面的表）、最低系统版本、现有组件，以及颜色和样式怎么管理（CSS 变量、Tailwind 主题、Asset Catalog）。
+2. **接入变量。** 把对应的生成文件接进项目现有的体系，用语义名引用（`ink`、`surface`、`button-height-md`），不要在代码里散落十六进制颜色和尺寸数字。
+3. **按组件实现。** 找到对应的组件说明，用项目的组件实现，并补齐需要的状态：默认、悬停或按下、选中、禁用、加载、空、错误。
+4. **检查。** 浅色和深色两套主题；量一下默认按钮的实际高度是否等于 `button-height-md`；键盘焦点、点击区域、长文本和最大字号、减弱动态效果和降低透明度。审查时按 [审查清单](references/review.md) 逐项看。
+5. **汇报。** 说明做了什么、哪些没有验证。不要因为这份 skill 就提高项目的最低系统版本、引入新的 UI 库或改动无关的页面。
+
+## 不要做
+
+- 加品牌色、渐变、彩色图标，或用 emoji 当图标。
+- 在 SwiftUI 端给系统工具栏、侧边栏加实色背景盖掉玻璃；在 Web 应用里用模糊效果模仿玻璃。
+- 给卡片加阴影；在玻璃上放正文或列表。
+- 给界面文字、AI 回答或按钮用衬线；到处用粗体。
+- 用上下内边距撑出按钮高度；为了凑 44 点击区域把可见的按钮做大。
+- 把官网的大按钮、大字号搬进应用界面；把桌面端的尺寸直接搬到触屏上。
+- 一屏出现两个主按钮；用「确定」「OK」当按钮文字。
+- 只靠颜色表达状态。
+
+## 版本与更新
+
+通过 `npx @deernova/style` 安装时，同一目录下的 `manifest.json` 记录版本和内容哈希；更新运行 `npx @deernova/style@latest update`。不要直接修改安装后的文件，规范的源文件在 deernova-style 仓库的 `skills/deernova-style/`。