diff --git a/README.md b/README.md index b488fc8..14c4109 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Agent 编程（Claude Code / Codex）的个人基准仓库：统一个人偏好 | better-* 等 11 个 skill | [jakubkrehel/skills](https://github.com/jakubkrehel/skills)（MIT） | 用户级 `~/.claude/skills/` | | web-design-guidelines | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)（MIT） | 用户级 `~/.claude/skills/` | | impeccable skill + agents + hook | [pbakaus/impeccable](https://github.com/pbakaus/impeccable)（Apache 2.0） | 项目级 `<项目>/.claude/` | +| 组件尺寸图约定（摘要，不含上游源码） | [enesozturk/dimensional-drawing](https://github.com/enesozturk/dimensional-drawing)（MIT） | 不安装；见 [`docs/references/design/dimensional-drawing.md`](docs/references/design/dimensional-drawing.md) | ## 结构 @@ -21,6 +22,11 @@ Agent 编程（Claude Code / Codex）的个人基准仓库：统一个人偏好 agent-coding-baseline/ ├── user/ # 个人级配置（自己维护） ├── project/ # 新项目模板：AGENTS.md、CLAUDE.md、.claude/、docs/、编辑器与 git 配置 +├── docs/ # 基准仓库文档，不进项目模板 +│ ├── README.md # 子目录索引：各目录放什么、新资料登记在哪 +│ └── references/ # 外部资料的约定摘要，按主题分目录 +│ └── design/ # 界面与图纸 +│ └── dimensional-drawing.md ├── vendor/ # 上游 skill 原样同步，不手改 ├── skills.json # 上游清单：仓库、许可证、同步路径、安装范围 ├── skills.lock.json # 当前同步到的上游提交 @@ -65,5 +71,6 @@ scripts/sync-upstream.py --check - 个人语言、工作偏好、模型参数只放 `user/`；`project/` 只放能随项目共享的约定。 - `vendor/` 只由同步脚本写入；新增上游时同时更新 `skills.json` 和 `THIRD_PARTY_NOTICES.md`。 +- `docs/` 是基准仓库自己的文档，不进项目模板。外部资料的约定摘要放 `docs/references/<主题>/`，一篇来源一份文件，写清来源和许可证，不复制上游源码；新增时登记到 `docs/README.md` 和 `THIRD_PARTY_NOTICES.md`。要安装的 skill 仍走 `vendor/`。 - 项目里的 `.claude/skills/`、`.claude/agents/` 不入库（模板 `.gitignore` 已忽略），需要时从本仓库重装。 - 提交前跑 `scripts/check.sh`。 diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 087e1ed..9b2b3a0 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -22,3 +22,12 @@ - 来源：https://github.com/vercel-labs/agent-skills，仅同步 `skills/web-design-guidelines` - 许可证：MIT。上游仓库没有单独的 LICENSE 文件，许可证声明见其 README 的 License 小节，同步保存在 `vendor/vercel-agent-skills/README.md` - 用途：按 Vercel Web Interface Guidelines 评审 UI 代码，安装为用户级 skill。该 skill 运行时会从 https://github.com/vercel-labs/web-interface-guidelines （MIT）拉取最新规则，规则本身不入库。 + +## 参考整理（未同步进 vendor/） + +### enesozturk/dimensional-drawing + +- 作者：Enes Ozturk，Copyright (c) 2026 Enes Ozturk +- 来源：https://github.com/enesozturk/dimensional-drawing +- 许可证：MIT，全文见上游仓库 LICENSE。本仓库未复制其源码、示例或媒体文件。 +- 用途：`docs/references/design/dimensional-drawing.md` 整理组件尺寸图的可复用约定。需要原技能出图时从上游安装，不经过 `scripts/sync-upstream.py`。 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..61dc34e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,17 @@ +# 文档索引 + +基准仓库自己的文档。这里的内容不进 `project/` 模板，也不会被 `new-project.sh` 拷进新项目。 + +| 目录 | 内容 | +| --- | --- | +| `references/` | 外部资料的约定摘要。按主题再分一层，一篇来源一份文件。写清来源和许可证，不复制上游源码。要安装的 skill 仍走 `vendor/`。 | + +| 主题 | 放什么 | +| --- | --- | +| `references/design/` | 界面、图纸、视觉说明方法 | + +| 文档 | 内容 | +| --- | --- | +| [references/design/dimensional-drawing.md](references/design/dimensional-drawing.md) | 组件尺寸图：只画结构、代号与公式、不发明数值 | + +新增一份资料时：放到对应主题目录（没有合适主题就新建目录），在上表登记，并在根目录 `THIRD_PARTY_NOTICES.md` 记下许可证。 diff --git a/docs/references/design/dimensional-drawing.md b/docs/references/design/dimensional-drawing.md new file mode 100644 index 0000000..b901ebe --- /dev/null +++ b/docs/references/design/dimensional-drawing.md @@ -0,0 +1,98 @@ +# 组件尺寸图 + +来源：[enesozturk/dimensional-drawing](https://github.com/enesozturk/dimensional-drawing)（MIT，Copyright (c) 2026 Enes Ozturk）。上游把苹果配件尺寸图的做法做成两个 agent skill：给一个 UI 组件（或一件实物），得到一页技术图纸；另一个 skill 再把画完的图做成约 10 秒的短片。参照物是苹果的 [Dimensional Drawings](https://developer.apple.com/accessories/dimensional-drawings/)。 + +本文只整理 agent 可以照做的约定。上游的 HTML 示例、SVG 绘图工具、动效场景和渲染器留在原仓库。要按原技能出图，安装上游 skill，用它自带的示例，不根据本文重写那套工具。 + +## 放在这里的原因 + +图纸约定对做界面的 agent 有用，和本仓库已有的间距层级、视觉体系接得上。收录方式按仓库现有边界： + +- `vendor/` 由同步脚本原样写入，给的是可以直接安装的 skill。这份材料要连同示例 HTML、动效场景、渲染器和媒体文件才完整，同步进来等于收下一套绘图程序。约定用这篇摘要就够。 +- `project/docs/design/` 是新产品要遵守的界面风格，会被 `new-project.sh` 拷进每个项目。尺寸图是按需产出的说明文件，放在 `docs/references/design/`。同一类外部资料继续放这个目录，别的主题另开 `docs/references/<主题>/`。 + +## 和现有规范的关系 + +产品界面仍按 [视觉体系](../../../project/docs/design/visual.md) 选定的 Quiet 或 Terminal，间距仍按 [间距层级](../../../project/docs/design/spacing.md)。图上的 `S#`、`R#` 只是代号：数值来自组件源码、计算样式，或上述 token。能对应上就同时写 token 名和实测值；源里没有的写 `[TBD]`。 + +Quiet 的嵌套圆角是外 = 内 + 内距。尺寸图把边框也算进去：内圆角 = 外圆角 − 边框 − 内距。边框为 0 时两条相同。公式写在图上，并给出算完的数。 + +## 何时画 + +别人要组件的 anatomy、spec sheet、redline 或尺寸图时再画。改界面、调间距、做视觉评审，走设计文档和 `scripts/check-design.mjs`。 + +## 图面规则 + +每条都能被指出违反。 + +1. **只画结构。** 槽位代替真实文案，例如标题槽、操作、内容槽。尺寸词只用三种：HUG（随内容）、FLEX（吃掉剩余空间）、FILL（撑满父级）。不标某段文字的宽度。 +2. **图上写代号，表里写值。** 每条尺寸是代号；变量表给出代号、名字、值。派生量先写公式再写结果，例如头部最小高度 = 上下内边距 + 操作区高度。图上每个代号都能在表里找到，公式的各项加总要闭合。 +3. **不发明数值。** 源码、计算样式或已发布规格里没有的量（视口边距、溢出行为、未公开的实物尺寸）标 `[TBD]`，按比例示意。同一尺寸的已发布来源互相矛盾时标 `CONFLICT`，并写上来源。 +4. **图面单色、不出现品牌。** 用线宽、虚线、点划线和剖面线区分对象。标题栏、图框和页脚用中性图名（如 `UI-CARD-001`）。产品界面的强调色不进这张图；这条只约束图纸。 +5. **一页为主。** 一张图能看清就不要第二张。加页时结构与第一张相同，注释写明见另一张。 +6. **测量走真实盒子。** 读仓库文件、Storybook、设计稿或页面，去掉缩放和模板占位后渲染，再读 padding、gap、radius、border、min-height 和 flex。同一变量在库里出现多次时，以这套系统为准，不以单个例子为准。 + +代号按度量分组，编号按这张图自己从 1 编，不照抄别的组件： + +| 前缀 | 指什么 | +| --- | --- | +| `S` | 间距：容器内边距、内部内边距、堆叠间距、弹性区与内容区之间的最小间隙 | +| `H` / `Z` / `I` | 区域高度、方形控件边长、图标边长 | +| `B` / `W` | 边框宽度、组件宽度（固定值或范围） | +| `R` | 圆角。药丸形取高度的一半；内圆角由外圆角、边框和内距推出 | +| `Y` / `BL` / `SP` / `E` | 阴影的偏移、模糊、扩展，以及包络的上、侧、下 | +| `T` / `V` / `MH` | 最小触控尺寸、视口边距、最大高度（视口高度减去两侧边距） | + +和本仓库 token 的对应示例：容器内边距优先用 `--space-inset`，同组间距用 `--space-group`，控件高度用选定风格里已有的控件尺寸。图上写 `S1 · --space-inset · 12`，而不是另起一个 12。 + +## 一张图上有什么 + +标题栏放在图纸上方：图号、版本、张数、单位、比例、来源，一段「除非另有说明」的总注，再加一行这张图的关键变量。图纸内不再重复标题栏，身份放在图下方的页脚一行。 + +| 区域 | 内容 | +| --- | --- | +| 左上注释 | 带编号的条目，同一编号标在图上对应特征旁 | +| 平面图 | 槽位线框；上下两条尺寸链，左右两条分区链；圆角引出；中心线；指向局部放大的虚线圆 | +| 注释下方 | 阴影包络：本体、阴影足迹、包络线 | +| 左下 | 图层爆炸图，自底向上：画布、遮罩（若有）、阴影、容器、内凹面、槽位与控件 | +| 底排 | 嵌套圆角、各个圆角的放大、内容区局部，以及该组件特有的局部 | +| 右侧 | 变量表：间距、尺寸、圆角、阴影。涉及视口时加视口与禁区 | + +按组件取舍，不把每种视图都画上： + +- 卡片、列表行：内容区内边距、堆叠间距、页脚是 FLEX 还是 HUG、触控热区。 +- 对话框、弹出层：在视口中的位置、全屏遮罩、最大高度与边距、头部控件、表单项、页脚动作的对齐和间距。 +- 按钮、芯片、输入框：放大后状态并排，触控热区高度和绘制高度分开标。 +- 导航、页面：按断点各一张平面，标栏和安全区。 +- 实物：第三角投影的顶视、前视、右视和剖面。只用已发布规格，单位毫米。 + +UI 图的单位跟源码（通常是 px）。总注里写明单位、槽位是占位、代号与公式的读法，以及 `[TBD]` 的含义。 + +## 交付前核对 + +- 图上每个代号都在表里，公式左右能对上（头部高度、分区之和、内圆角）。 +- 没有品牌文字，没有随文案变化的宽度，没有产品界面的强调色。 +- 宽视口渲染看一遍：标注不重叠，图元不越出图框。 +- 回复用一两句说明画了什么，以及哪些值仍是 `[TBD]`。 + +## 短片 + +上游的 `dimensional-drawing-motion` 把画完的图做成 8–15 秒的影片：先特写一处特征并让线自己画出来，再拉远到平面，图层从平面抬成爆炸图，最后拉到整页。场景是时间的纯函数，任意一帧只由时刻决定。笔画先出现，填充随后出现。镜头和笔画缓入缓出，淡入淡出只缓出。 + +这条影片的场景、样式和渲染器（Claude 的 Motion artifact，或 Playwright 逐帧加 ffmpeg）都留在上游。换别的动画库时先看那个库的许可证。 + +## 上游里看哪里 + +| 路径 | 作用 | +| --- | --- | +| `skills/dimensional-drawing/SKILL.md` | 图纸规则、测量步骤、绘图工具的用法 | +| `skills/dimensional-drawing/examples/` | 卡片和对话框两张完整的图 | +| `skills/dimensional-drawing-motion/` | 短片的时间安排、场景模板和两种导出方式 | + +安装（不经过本仓库的 `vendor/`）： + +```bash +npx skills add enesozturk/dimensional-drawing +``` + +Claude Code 也可以把上游 `skills/` 拷到 `~/.claude/skills/`。许可证全文在上游 [LICENSE](https://github.com/enesozturk/dimensional-drawing/blob/main/LICENSE)。