HexTrails/design/shared.md

# 五套设计的接入与维护约定

适用于主游戏的 01–05 五套设计。先读 [方案目录](README.md)，确定设计 ID，再读对应的 `design.md`。本文和各套 design.md 是人工维护的设计规则；数值以实现源及其生成的 tokens.json 为准。发现文档与实现不一致时核对用户已确认要求并同步修正，不能用旧说明撤回新要求。

## 选择一个设计与主题

三个参数分别控制不同的事：

| 参数 | 合法值 | 作用 |
| --- | --- | --- |
| `design` | `calm` / `vivid` / `toy` / `animals` / `paper` / `signpost` / `macaron` | 棋子造型、轨道画法、配色库和控件风格 |
| `theme` | `lagoon` / `apricot` / `lavender` / `rose` / `midnight` | 轻松、进阶、烧脑、挑战、每周挑战的视觉主题 |
| `colors` | 4 / 7 / 9 / 12 | 主游戏单关使用的棋子配色数量，默认 7 |

在根目录执行 `npm run dev`。打开 [paper 的轻松主题](../index.html?design=paper&theme=lagoon&colors=7)，或 [paper 的夜间审核](../design-showcase.html?design=paper&theme=midnight#phone)。审核页用控件切换色数；`colors` URL 参数由主游戏读取。设计总览的主题切换只用于视觉对照。

不传 design 时使用 calm。主游戏不传 theme 时按关卡评分选前四种主题；midnight 需显式指定。主题名与配色不改变难度或玩法。编辑模式和工坊试玩使用基础自由配色，不能拿它们判断设计参数是否生效。审核记录保存在 `hex-trails-art-review-v1`，与游戏存档分开。

## Agent 如何读取数据

1. 读取 [manifest.json](manifest.json)，确认 `schemaVersion === 1`。
2. 按 `designs[].id` 找方案，读取 `designDoc` 与 `tokens`。manifest 的所有路径字段均从仓库根目录解析，不从当前 JSON 目录拼接。
3. tokens 中的 `themes` 给出环境、文字和已展开的棋盘材质。`palettes["7"]` 是 7 色时的**有序色库索引**；索引指向本文件的 `pigments`，不能借用另一套设计的色库。
4. tokens 是当前实现的只读数值导出，不能单独描述完整造型或所有 CSS 控件。几何和组件规则仍需读取 design.md、共享渲染器及 CSS。`design/tokens.json` 是旧有基础语义 token 导出，不包含五套方案全集。

manifest 不存用户审核意见，也不表示最新方案已被选为默认。文档中的“最新”只表示新增顺序。

## 复用现有渲染器

浏览器页面已有 `<canvas id="board" width="600" height="600"></canvas>` 时，可在仓库根目录页面的 ES module 中运行以下代码；通过 HTTP 加载，不直接双击文件：

```js
import { artDirection, directionTheme } from './src/art-directions.js';
import { CanvasPainter, drawScene } from './src/renderer.js';
import { layout } from './src/geometry.js';
import { createStudyLevel } from './src/study-levels.js';
import { TILE_ATLAS } from './src/sprites.js';

const direction = artDirection('paper');
const theme = directionTheme(direction, 'lagoon', 7);
const level = createStudyLevel(3);
const canvas = document.querySelector('#board');
const painter = new CanvasPainter(canvas.getContext('2d'));
const atlas = new Image();
atlas.src = TILE_ATLAS;
await atlas.decode();
painter.atlas = atlas;
canvas.style.background = theme.background;
canvas.style.color = theme.ink;
painter.ctx.clearRect(0, 0, canvas.width, canvas.height);
drawScene(painter, level, level.tiles,
  layout(level.cells, canvas.width, canvas.height), { theme });
```

`drawScene` 只画棋盘、轨道与棋子，不画画布背景，也不自动清屏。响应式画布使用实际显示尺寸和 DPR，复用 [board-viewport.js](../src/board-viewport.js) / app.js 的适配逻辑。不要根据每枚棋子的位置另设显示比例。

整盘绘制时传入完整的 `level.tiles` 与当前剩余 tiles。`drawScene` 以棋子在初始 `level.tiles` 中的索引映射主题 palette，因此移除、撤销与运动不换色；不要按“剩余棋子第几个”重新编号。独立棋子样本才使用 `appearanceTile({color: pigmentIndex, dir}, theme)` 再调用 `drawTile`，这里的 color 已是该设计的色库索引。

所有方向以弧度 `-Math.PI / 2 + dir * Math.PI / 3` 绘制，dir 为 0–5。移动中的棋子经共享 `drawExit` / `drawTile` 保持同一造型。不要复制静态棋子绘制代码实现另一套移动画法。

## 接入完整游戏界面

| 接入点 | 实际来源 | 注意事项 |
| --- | --- | --- |
| 设计与主题定义 | [src/art-directions.js](../src/art-directions.js) | ID、12 色库、五主题、artStyle；calm 复用基础色库 |
| 基础语义色、字体、动效 | [src/design-tokens.js](../src/design-tokens.js) | 被各设计继承；不能用基础色覆盖新方案的独立色库 |
| 场景几何与运动绘制 | [src/renderer.js](../src/renderer.js)、[src/token-art.js](../src/token-art.js) | 使用同一套命令和曲线路径 |
| 主游戏选择逻辑 | [src/app.js](../src/app.js) | 设置 body.dataset.design / theme，应用场景背景与文字色 |
| 控件风格 | [art-directions.css](art-directions.css) | 用 body[data-design] 限定，避免影响其他方案 |
| 底部道具及布局 | [game-tools.css](game-tools.css) | 最后加载，保证扁平道具覆盖既有立体风格 |
| 通知与通用组件 | [notifications.css](notifications.css)、[components.css](components.css) | 通知位于剩余步数下方，奖励为金色发光星星 |
| 图集与裁切 | [src/sprites.js](../src/sprites.js)、[src/ui-skin.js](../src/ui-skin.js) | 棋子图集只在 calm 分支使用；UI 图标各套共享 |

主游戏 CSS 加载顺序参考 [index.html](../index.html)：style.css → tokens.css → components.css → notifications.css → campaign.css → art-directions.css → game-tools.css。只有设置 CSS 主题而没给 drawScene 传 theme，棋盘仍会使用基础画法。只有给画布传 theme 而没设置 body.dataset.design，控件不会切换。

## 所有方案共用的产品要求

- 棋盘在通知区与旋转区之间垂直居中。旋转与道具占真实布局行，不绝对定位压住棋盘。适配手机、Pad、折叠屏和桌面。
- 撤销、重来、提示是游戏道具，与顶部紧凑导航分开。常规底座 64px，宽度至少 600px 时为 68px，短屏高度不超过 600px 时为 56px；图标 32px、标签 13px。底座无阴影、立体底边或渐变高光，方案的棋子材质不覆盖这条要求。唯一例外：07 `macaron` 的道具是参考作品的白色圆钮带柔和投影，2026-09-14 用户确认只允许该方案使用，其他方案（含新增方案）继续保持扁平，不得引用这条例外。
- 次数和“▶ AD”角标只用于设计示例，当前不接入真实库存、广告或付费获取逻辑。
- 奖励星星为黄色／金色并带光感。通知固定在剩余步数下方，不能挪回棋盘下方。
- 路线以弯曲路径为主要观看内容。动画复用 [exit-animation.js](../src/exit-animation.js) 和 [collision-animation.js](../src/collision-animation.js)。离场时长按实际路径长度计算，不把旧文档中的固定时长或上下限当作当前速度公式。
- 设计切换不改规则、关卡布局、编号、关卡版本或存档。设计编号 01–05 与关卡 v0.1–v0.5 是两套不同的标识。

## 修改与验证

只改配色：编辑 art-directions.js 中指定设计；calm 的色库及基础主题在 design-tokens.js。改造型：编辑 token-art.js 的指定分支，必要时改 renderer.js 的相关绘制，并同步该套 design.md。改控件：编辑对应 CSS 的作用域规则；共用道具约束仍需保留。

文档整理不需要重新生成关卡。根目录执行：

```sh
npm run design
node --test tests/design-packages.test.js tests/art-directions.test.js tests/themes.test.js
node design/examples/render-design.mjs paper lagoon 7
node scripts/build.mjs
```

`npm run design` 会刷新 manifest、每套 tokens、HTML 和旧入口；**不覆盖人工维护的 design.md、shared.md、README.md**。文档测试检查目录与链接、数值导出与运行时一致性，并执行接入示例。视觉修改另检查五主题、长弯路离场、碰撞、旋转与撤销；至少查看 390×844 手机、短屏、平板和桌面。纯文档修改检查链接和预览能加载即可。原生验证单独报告。

## 跨引擎范围与已知限制

绘制抽象只要求 polygon、line、circle，calm 可额外使用 sprite 图集。路径单位是格半径；不能把示例画布尺寸当作固定像素规范。实际应用背景和 UI 布局由宿主引擎实现。

[cocos/HexTrailsBoard.ts](../cocos/HexTrailsBoard.ts) 是适配示例，当前没有传入这五套设计的 theme，且动画时序仍有旧值；[cocos/CandyUiSkin.ts](../cocos/CandyUiSkin.ts) 也不是五套设计的完整原生控件实现。移植时需显式接入主题、核对圆头线条与图层，并按浏览器参考画面验收；本目录不代表原生移植已完成。

paper 的浅色轨道是用户认可的特例，轨道与棋盘对比度低于基础 3:1 目标；不要为通过基础轨道指标自行加深。文字和方向需保持可读。各套 design.md 标明具体差异。

## 实现依据与旧文档

| 依据 | 确认的事实 | 修改／复现入口 |
| --- | --- | --- |
| art-directions.js 导出的五个 ID | 五套方案共存且都有五种主题 | manifest.json、每套 tokens.json |
| renderer.js 的 visualTile 与 paper 分支 | 固定初始索引配色，paper 使用更细轨道 | render-design.mjs、art-directions.test.js |
| game-tools.css 的最后加载覆盖 | 道具保持扁平且分行布局 | 各套 index.html、主游戏 |

[根目录 Design.md](../Design.md) / Design.html 保留基础组件规范与历史说明，[docs/art-direction.md](../docs/art-direction.md) 保留较早的制作简报。它们的“唯一色源”、轨道对比度和动画旧值不能无差别套用到五套设计。新增方案的接入从本目录开始。