HexTrails/design/shared.md

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

适用于主游戏的 01–05 五套设计。先读 方案目录，确定设计 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 的轻松主题，或 paper 的夜间审核。审核页用控件切换色数；colors URL 参数由主游戏读取。设计总览的主题切换只用于视觉对照。

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

Agent 如何读取数据

1. 读取 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 加载，不直接双击文件：

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

主游戏 CSS 加载顺序参考 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 和 collision-animation.js。离场时长按实际路径长度计算，不把旧文档中的固定时长或上下限当作当前速度公式。
• 设计切换不改规则、关卡布局、编号、关卡版本或存档。设计编号 01–05 与关卡 v0.1–v0.5 是两套不同的标识。

修改与验证

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

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

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 是适配示例，当前没有传入这五套设计的 theme，且动画时序仍有旧值；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.html 保留基础组件规范与历史说明，docs/art-direction.md 保留较早的制作简报。它们的“唯一色源”、轨道对比度和动画旧值不能无差别套用到五套设计。新增方案的接入从本目录开始。