Deernova 的设计仓库。现在有两个包:@deernova/style(设计语言)和 @deernova/icons(图标);@deernova/page(页面布局)在搭建中,还没发布;以后加入动画。
@deernova/style 是 Deernova 的设计语言,写成一个给 AI agent 读的 skill。agent 在你的项目里写界面时参考它,用项目现有的技术栈实现 Deernova 的风格。它不是组件库:不会往项目里加任何依赖、样式文件或业务代码。
一句话:黑、白、灰为底,朱砂只表示 AI 正在做事,靛青只给链接和引用;内容放在不透明的纸面上,原生端的操作层用系统 Liquid Glass,Web 应用用不透明平面加 1px 线;界面和 AI 回答用系统无衬线,衬线只给大标题和长文;桌面端的骨架和密度参照 Claude 桌面端,iOS、iPadOS 和触屏给手指留足位置,官网和文档更舒展。
| 路径 | 内容 |
|---|---|
skills/deernova-style/ |
skill 本体,也是规范的唯一来源。 SKILL.md 是入口:先确定场景,再按路由表读文件;references/ 分成 foundations/(颜色、字体、间距、圆角、线条、阴影等原则)、components/(每个组件的尺寸表和 Web / SwiftUI 写法)、scenes/(Web 应用、官网、macOS、iOS、iPadOS)以及变量表和审查清单;assets/ 是 tokens.json 和由它生成的 tokens.css、tailwind.css、DeernovaTokens.swift,以及效果截图 |
skills/deernova-page/ |
页面布局 skill:一种页面有哪些区块、按什么顺序、哪些不放、窄屏怎么变。数值和组件都引用 style,不另外定义 |
apps/website/ |
官网。首页传达风格;guide.html 是规范页:色卡、字阶、活的组件样例和尺寸表都从 skill 生成,可以切换场景查看 |
art/milu/ |
首页麋鹿的原始插画和离线烘焙脚本,生成首页用的散步帧,不参与构建 |
packages/style/ |
npm 包 @deernova/style:把 skill 装进其他仓库的命令行工具 |
packages/page/ |
npm 包 @deernova/page:用同一个安装命令装 page skill,暂不发布 |
scripts/ |
生成 token 文件、构建网站和 npm 包、发布 |
tests/ |
skill 结构、token 同步、对比度、构建边界、开发热更新、安装器和动画 |
reviews/ |
当前验收结果、截图,以及单独保留的历史记录 |
archive/Paperlight/ |
最初的设计稿资料,只做留档,不参与构建;现行规范和它的异同见 ARCHITECTURE.md |
装进项目:在项目根目录运行。skill 跟着仓库走,团队共用,每个项目可以停在自己的版本上。
npx @deernova/style@latest install # 写入 .agents/skills/deernova-style/
npx @deernova/style@latest install --agent claude # Claude Code:写入 .claude/skills/deernova-style/
npx @deernova/style@latest update # 更新到最新版本(安装时加了 --agent 的,这里也加上)
npx @deernova/style@latest doctor # 检查是否安装、是否被改过、是否最新装到全局:装到用户目录,所有项目都能用。
npx @deernova/style@latest install --global --agent claude # Claude Code:写入 ~/.claude/skills/deernova-style/
npx @deernova/style@latest install --global # Codex:写入 $CODEX_HOME/skills/deernova-style/(默认 ~/.codex)
npx @deernova/style@latest update --global --agent claude # 更新全局安装,参数和安装时一致
npx @deernova/style@latest doctor --global --agent claude # 检查全局安装然后直接告诉 agent:「参考 deernova-style,给这个应用做一个设置页。」
--agent agents|codex|claude选择写入.agents/skills、.codex/skills或.claude/skills;--repo <path>指定其他仓库;--dir <skills-parent>写到自定义目录;--global装到用户目录(默认$CODEX_HOME/skills)。--repo、--dir、--global只能选一个。- 更新是手动执行的。安装后的文件被改过时,CLI 拒绝覆盖;加
--force会先备份再替换。 - 不想用 npm 时,也可以直接把
skills/deernova-style/整个文件夹复制到项目的 skill 目录里。
- 改规则:直接编辑
skills/deernova-style/里的 Markdown。SKILL.md只放每次都要用到的核心规则,细节放进references/。 - 改颜色、字号、间距、圆角、线条、组件尺寸:编辑
skills/deernova-style/assets/tokens.json,再运行npm run tokens,重新生成tokens.css、tailwind.css、DeernovaTokens.swift、references/tokens.md,以及 Markdown 里<!-- tokens:… -->标出的表格。生成内容不要手改,测试会检查它们和tokens.json是否一致。 - 按场景取值:尺寸 token 用
values给出三种密度(desktopWeb 应用和 macOS 内容区、touchiOS / iPadOS / 触屏、comfortable官网)的值,名字里不写平台。测试会拒绝带mac、ios、web这类平台名的 token。 - 截图:
assets/screens/里的图不会自动更新。源页面在art/screens/(Mac 窗口、iPhone 页面、iOS 按钮尺寸,共用的手机机身在phone.css),改了组件或规则后运行npm run screens重新渲染浅色和深色两张(文件名保持名字-light.png/名字-dark.png)。 - 网站:页面在
apps/website/。网站的改动不会改变 skill 的内容哈希,不需要发新版本。
需要 Node.js 22.12.0 以上。
npm install
npm run dev # Vite 开发服务,默认 http://localhost:4173
npm run preview # 构建网站并预览静态产物,不监听修改
npm run tokens # 从 tokens.json 重新生成 CSS、Tailwind、Swift、变量表和文档里的尺寸表
npm run screens # 用本机 Chrome 把 art/screens/ 的源页面渲染成 skill 里的截图(改了组件或源页面后手动运行)
npm run build # 构建网站(dist/)和 npm 包里的 skill(packages/style/skill/)
npm test # 构建并运行全部测试
npm run pack # 在 releases/ 生成 npm 包,不发布开发服务直接读取源码:CSS 保存后热更新,不重置首页动画;HTML、脚本和图片修改会自动刷新。规范 Markdown 修改后会刷新规范页;tokens.json 修改会即时更新样式和规范页,提交或构建前仍需运行 npm run tokens 同步生成文件。
开发端口被占用时会直接提示,避免误看旧服务;也可以用 npm run dev -- --port 4174 指定其他端口。从旧静态服务切换后,手动刷新一次页面以加载热更新连接。
dist/ 和 packages/style/skill/ 是构建产物,已加入 .gitignore。Vite 开发服务不写入这些目录,也不改写规范源文件。架构和改动边界见 ARCHITECTURE.md。
当前验证结果与未覆盖范围见 验收记录。首页动画可通过 ?t=24.5 固定时刻检查,通过 ?halftone=0 查看原始灰度画面。
官网支持 One CLI + Infisical + SSH/SCP 直接发布到现有阿里云 ECS。One 从共享凭据库读取部署密钥和主机配置,无需每台电脑手工复制私钥,也不需要 OSS 或阿里云 AccessKey。完整初始化、SSH 配置和排障见 SSH 部署说明;历史发布记录见 网站部署说明。
维护者登录 Infisical 并获得部署目录读取权限、通过服务器 IP 白名单后,可运行 one run website:deploy。以下初始化步骤用于其他电脑;拉取开源代码本身不会获得部署权限。
npm run setup:one # 固定版本 One,安装到本仓库 .cache/one/bin
export PATH="$PWD/.cache/one/bin:$PATH" # 当前终端使用本仓库的 One
one mise trust
one run website:install # npm ci
one login # 登录维护团队的 Infisical 组织
one run website:doctor # 检查 SSH 与服务器条件,不发布
one run website:deploy -- --dry-run # 只预览流程,不构建或连接服务器
one run website:deploy # 构建、上传、切换版本、验收
one run website:status # 当前与上一版本
one run website:rollback # 恢复上一版并验收One 任务复用 npm scripts;npm run deploy、npm run rollback 也会通过 One 获取 Infisical 凭据。npm run pack:site 仅生成公开静态文件发布包。服务器要求 Python 3.12+;运行本仓库完整测试还需要本机 Python 3.11.8+。
规范、skill 内容或安装器有变化时,发布新版本,使用者通过最新 CLI 安装或运行 update 才能拿到:
npm run release:version -- 0.3.0
npm install --package-lock-only
npm test
npm run release:publish发布由 npm 账号所有者执行,普通提交不会自动发包。只改网站不需要发布。