cabinw
10cf93a324
Add the paper direction with thin tracks, outlined hexagons and line arrows, without exterior color markers or piece numbers. Add a unified catalog for five designs and their 25 themes, with direct review links. Organize each design into an authored design.md, generated tokens.json and preview. Add Agent routing, shared integration guidance, a machine-readable manifest and an executable rendering example. Preserve legacy preview and document links. Validation: 16 focused design, theme and package tests passed; npm run design and static build passed. Confirmed all eight authored documents survive generation unchanged. Browser checks covered mobile, tablet and desktop layouts, theme links and migrated previews. Native engine integration and visual verification remain pending.
HEX TRAILS · 设计系统入口
这是给设计审核者和 Agent 共用的主游戏设计入口。当前有 5 套并列方案，每套 5 个主题，共 25 种组合。默认方案是 01「柔和原色」，最新候选是 05「轻线纸境」；可同时保留多套。
人看 设计总览 与 可操作审核页。Agent 从本文、共用接入约定 和本次指定方案的 design.md 开始；可直接读 manifest.json 发现全部文件。根目录 AGENTS.md 与本目录 AGENTS.md 提供路由和维护要求。
按任务找到入口
| 你要做什么 | 先读 | 然后做什么 |
|---|---|---|
| 使用指定设计实现页面 | shared.md → 该套 design.md → tokens.json | 复用 directionTheme 和 drawScene，并接入对应 CSS |
| 调整某套造型或配色 | 该套 design.md → 文档列出的 JS/CSS 源 | 修改对应分支，同步文档，再生成配色与预览 |
| 比较与选择设计 | index.html | 同主题比较，再到审核页多选、记录意见 |
| 用其他引擎实现 | shared.md 跨引擎范围 → 该套 design.md | 复用绘制命令和几何，按浏览器参考验收 |
| 自动发现方案与颜色 | manifest.json → designs[].tokens | 路径从仓库根解析，schemaVersion 当前为 1 |
五套独立规范
| 编号 | ID | 方案 | Agent 规范 | 数据 | 预览 |
|---|---|---|---|---|---|
| 01 | calm | 柔和原色：哑光原版 | design.md | tokens.json | 查看 |
| 02 | vivid | 高彩游乐场：高饱和贴纸 | design.md | tokens.json | 查看 |
| 03 | toy | 积木轨道屋：塑胶积木 | design.md | tokens.json | 查看 |
| 04 | animals | 动物弯弯镇：动物角色 | design.md | tokens.json | 查看 |
| 05 | paper | 轻线纸境：细线纸面 | design.md | tokens.json | 查看 |
设计 ID、主题 ID 和关卡版本各自独立。每套都支持 lagoon（轻松）、apricot（进阶）、lavender（烧脑）、rose（挑战）、midnight（每周挑战）；显示名可以不同，ID 不变。各主题名称、色值与有序色板从 tokens.json 读取。
文件架构与来源
design/
├── AGENTS.md # Agent 工作入口，人工维护
├── README.md # 本索引，人工维护
├── shared.md # 共用规则、接入、验证与限制，人工维护
├── manifest.json # 全部方案与文件路径，生成
├── index.html # 人看的总览，生成
├── examples/
│ └── render-design.mjs # 可执行的无 DOM 接入示例
├── directions/
│ ├── calm/ # 其余 vivid / toy / animals / paper 结构相同
│ │ ├── design.md # 本套设计规范，人工维护，构建不覆盖
│ │ ├── tokens.json # 12 色库、5 主题与 4/7/9/12 色板，生成
│ │ └── index.html # 人看的完整设计稿，生成
│ ├── calm.html # 兼容旧 URL，跳转到 calm/index.html
│ └── calm.md # 兼容旧文档入口，指向 calm/design.md
├── art-directions.css # 五套控件的样式源
├── game-tools.css # 共用扁平道具与布局源
└── tokens.json # 基础语义色导出，不是五套方案全集
设计颜色定义仍在 src/art-directions.js / src/design-tokens.js，几何仍在 src/renderer.js / src/token-art.js。没有将运行时代码复制到每套目录。各 design.md 解释意图、精确画法、控件差异、不可丢失的特征和验收点；tokens.json 给 Agent 提供当前数值快照。
所有生成 JSON 中 pathBase 为 repository-root；文件路径从仓库根目录解析。它与 Markdown 内按当前文档位置解析的相对链接不同。manifest 的版本号描述数据格式，不代表第几套设计。新增字段可保持同一版本；改变字段含义或移除字段时升级版本并更新消费者。
快速验证一次接入
在仓库根目录执行，Node.js 20+，无需安装依赖：
node design/examples/render-design.mjs paper lagoon 7
它调用共享主题与渲染器，输出设计 ID、主题 ID、色数、棋盘格数、色板和绘制命令数。可更换为 animals midnight 12。未知 ID 或不支持的色数会报错，避免 Agent 拼错 ID 后默默使用默认设计。此例验证无 DOM 几何接入，不代替 PNG、CSS 或实机视觉验收。浏览器 Canvas 示例在 shared.md 中。
修改、生成与校验
npm run design
node --test tests/design-packages.test.js tests/art-directions.test.js tests/themes.test.js
node scripts/build.mjs
- 规范源：本目录 AGENTS.md、README.md、shared.md、各套 design.md，直接编辑且不会被生成脚本覆盖。
- 实现源：JS/CSS、已接受的图集；在本次指定的方案范围内修改。
- 生成物：manifest、各套 tokens.json、index.html 及旧入口；不要只改生成物，下一次构建会重建。
- 新增方案：在 ART_DIRECTIONS 注册稳定 ID，新增
directions/<id>/design.md，更新本索引与相关验证，再运行构建。缺少规范时构建会失败。 - 校验覆盖文件可发现性、链接、配色导出与运行时一致性，以及可执行示例。视觉与原生范围按 shared.md 验收。
旧的 design/directions/<id>.html 和 <id>.md 入口继续可用；新的代码和文档请引用独立目录。根目录 Design.md / Design.html 保留基础组件与历史设计说明，不作为五套独立方案的唯一规范。实验室中的其他玩法原型各有自己的文档，不在这五套主游戏设计的 manifest 中。