feat(design): 明确设计知识并落实字体、轮廓与中性色彩

.changeset/better-trees-begin.md

@@ -0,0 +1,9 @@
+---
+'@inkcre/ui-web': patch
+---
+
+将 DESIGN.md 调整为共同设计总纲与按任务阅读的入口，分别维护设计立场、视觉语言、页面组合和判断依据，使设计选择与理由便于按任务查阅。
+
+明确局部等宽混排、中性灰与少量彩色重点、默认直角、平面层次和空间节奏，并补充内容取舍、按状态与层级呈现及中西文排印参考。
+
+设计正文和带有适用范围说明的实例图片随包交付，消费与维护入口同步更新；生成和安装包检查覆盖整组文件、内容及相对链接。

.changeset/clear-header-menu.md

@@ -0,0 +1,5 @@
+---
+"@inkcre/ui-web": patch
+---
+
+修复 Header 默认菜单图标被按钮透明背景覆盖而不可见的问题。按钮与装饰图标分别负责交互和绘制，保留菜单名称、键盘操作及 menu-click 事件。

.changeset/goofy-bears-brake.md

@@ -0,0 +1,7 @@
+---
+"@inkcre/ui-web": patch
+---
+
+浅深主题的主动作与 Switch 采用中性灰配对，深色基底与相邻表面缩小明暗跳变；危险按钮使用灰红底色，需要注意的反馈文字采用较纯的绿、金黄、蓝和红。同步普通、悬停、按下、等待及反色文字的配对，并缩小覆盖层阴影的偏移与模糊范围。
+
+保留公开角色与调用方式，品牌基础色映射到中性色阶；危险动作底色与错误前景分别维护。按用途区分语义文字与动作底色，修正默认成功着色的指南、Agent 配方和表单示例。

.changeset/neat-chicken-type.md

@@ -0,0 +1,7 @@
+---
+'@inkcre/ui-web': patch
+---
+
+Switch 普通状态文案采用系统 UI 字体，继续由两种文案共同维持切换与等待时的轨道宽度。AutoForm 根级错误容器采用默认直角轮廓。
+
+同步 AutoForm 和 Image 示例的字体、主题配色与轮廓，图片示例使用准确的替代文字、持续可见的查看提示和可实际下载的原图链接。

.gitignore

@@ -32,6 +32,10 @@ coverage/
 *.png
 *.jpg
 
+# Published design examples are maintained documentation assets.
+!/docs/design/examples/*
+!/packages/web/docs/design/examples/*
+
 # svc:begin local-config sha256=0cb2591848c4e5675766aa516f16dfb9981fc52e1dcbadd8cec89b6982db927d
 svc.local.json
 AGENTS.local.md

AGENTS.md

@@ -16,7 +16,7 @@ Reason in English. Communicate with humans in Chinese.
 
 ## Knowledge Owners
 
-UI 设计、组件、Token 或视觉审视工作先读取 [DESIGN.md](DESIGN.md)，再按任务读取具体实现与指南。纯构建和非 UI 工作不需要加载全部设计上下文。DESIGN.md 拥有共同设计判断，具体值与 API 仍由下面的源头负责。
+UI 设计、组件、Token 或视觉审视工作从 [DESIGN.md](DESIGN.md) 的总纲和阅读路径进入，只读取与任务有关的设计正文。`docs/design/` 分别维护设计立场、视觉语言、页面组合与判断依据；纯构建和非 UI 工作无需加载这些正文。具体值与 API 仍由下面的源头负责。
 
 - Repository and package entry points: `README.md` and `packages/web/README.md`.
 - Public package API: package exports, component manifest, TypeScript source,
@@ -29,6 +29,14 @@ UI 设计、组件、Token 或视觉审视工作先读取 [DESIGN.md](DESIGN.md)
   scripts, and `.github/workflows/`.
 - Repeated subtree hazards: the nearest local `AGENTS.md`.
 
+## 设计变更的维护责任
+
+先明确变化要保持的设计关系，再确定修改位置。已有角色是否可复用，取决于共同用途与共同变化理由；新增共享能力应说明实际情境、现有缺口、默认行为、允许变化和覆盖责任。可以在变更说明中自然表达，无须另建统一模板。
+
+设计正文拥有已确认的选择及其理由，Token 源拥有名称、类型、值与引用，组件源码和声明拥有 API 事实。实现观察、提炼过程、待确认方案与讨论状态记录在 task packet，确认后的结论才进入正式正文。当前表现与认可要求不一致时应明确指出差异，按任务授权修复或提出规则变更，不能只为解释代码而修改要求。
+
+改变公开名称、用途、默认表现或交互承诺时，同步相应实现、设计正文、示例和迁移说明。静态检查确认交付事实，真实场景确认设计关系与表现；视觉验收需要说明比较依据，不能只报告 Token 合法或构建成功。
+
 ## Coding Guidelines
 
 - [Coding for Human](.github/instructions/coding-for-human.instructions.md)

DESIGN.md

@@ -1,77 +1,16 @@
-# InKCre 设计决策指南
+# InKCre 设计
 
-这份指南面向使用和维护 InKCre 设计系统的人与 Agent。它说明界面应保持的关系、默认选择，以及变化应该由谁负责。消费者用它选择和组合能力，维护者用它判断现有实现和新增能力是否合适。具体 API、安装与调用从所在仓库或安装包的 [README](README.md) 继续查阅。
+InKCre 的界面应让内容的关系和可执行的操作容易理解，让阅读、判断与修改有连续的秩序。文字、颜色、边界和空间共同表达这种秩序；具体表现随内容与容器调整，同时保留各自承担的含义。
 
-仓库根级文件是人工维护的源，Web 包内文件是随版本交付的副本。消费时读取安装版本的指南；维护时读取当前 checkout 的指南。指南中的 Web 能力不表示 Flutter 或 uniapp 已有对应实现。
+这里是人、消费者 Agent 和维护 Agent 的共同入口。设计知识按责任分别维护，阅读与当前任务有关的部分即可。组件 API、Web 调用和工程流程从 [README](README.md) 进入，不在这里重复。
 
-## 从任务决定界面
+| 当前要作出的判断                                   | 阅读入口                                   |
+| -------------------------------------------------- | ------------------------------------------ |
+| 理解共同立场，或判断一项新需求值得保持什么         | [设计立场](docs/design/principles.md)      |
+| 选择文字、颜色、形状和层次，或审视整体视觉是否协调 | [视觉语言](docs/design/visual-language.md) |
+| 把内容和操作组织成页面、列表、表单或浮层           | [页面组合](docs/design/composition.md)     |
+| 比较方案、解释取舍，或用已有例子校准判断           | [判断依据](docs/design/reference.md)       |
 
-先明确用户要理解什么、改变什么，以及操作何时算完成。按这些关系组织信息、选择组件，再调整视觉。系统提供文字、颜色、空间和交互的共同约束；具体业务导航、权限、数据模型与流程由宿主产品决定。
+设计立场说明理由，视觉语言说明表达，页面组合说明关系如何落到场景，判断依据说明能从实例得出什么结论。它们共享设计方向，各自只拥有相应的知识；一个技术问题不要求加载整套正文。
 
-默认使用现有组件和语义角色。需要变化时，说明实际内容、容器或状态有什么不同，以及变化解决了什么问题。视觉边界与内容可读、功能可用冲突时，先保护内容与功能，再调整布局和策略。已有页面可以作为证据，但其中的偶然值或缺陷不能自动成为后续标准。
-
-## 文字与视觉层级
-
-按文字的职责选角色。正文需要支持连续阅读，标签需要标识控件或状态，说明需要表达补充信息或错误，标题需要帮助理解页面和区块结构。默认选择如下；名称对应当前系统角色，精确度量由 Token 源维护。
-
-| 内容                                   | 默认角色                         |
-| -------------------------------------- | -------------------------------- |
-| 普通正文／说明、错误、提示             | body-md／body-sm                 |
-| 控件值与字段标签／短元信息、小按钮状态 | label-lg／label-md               |
-| 页面标题／区块与弹层标题               | title-lg／title-sm               |
-| 强调正文或引言／醒目页面标题           | body-lg／headline-lg             |
-| 代码、标识符                           | 合适的文字角色，加 mono 字体选择 |
-
-label-lg 和 body-sm 当前度量相同，但承担不同职责。消费者按用途选择；维护者只有在用途和未来变化责任一致时才合并角色。不能因为说明放不下，就改成更小的标签角色。
-
-默认使用系统 UI 字体，代码可使用等宽字体。家族和装饰与尺寸角色分别选择。Web 不下载字体、不重设 html 字号；相对字体尺度与比例行高表达既定依赖，不能单凭使用了 rem 就宣称所有内容都能适应。
-
-## 配色表达用途和状态
-
-颜色按文字、表面和状态的关系选择，并在实际背景上检查可读性。普通表面的文字选 text.base 或 text.subtle；primary 与 danger 表面分别配 text.on-primary、text.on-danger。反色文字的适用性取决于配对表面，不能因它叫 primary 就用于普通正文。
-
-error、success、warning、info 是普通表面上的反馈前景用途，配合明确的文字表达状态。系统目前没有约定带色反馈容器，不能从前景角色自行推导一套容器角色。必要控件边界用 border.base，装饰分隔用 border.subtle，焦点轮廓用 border.strong。
-
-hover／pressed 表达可执行动作的交互反馈；focus 表达当前键盘位置；error 表达需要处理的问题。它们的责任可以同时存在，例如错误边框不能抹掉焦点提示。pending 保留动作文字与可读配色，显示进行状态并防止重复执行；普通 disabled 使用对应的弱化表现。
-
-覆盖主题颜色时，应连同前景、背景和相关状态一起核对。某个色值自身或一种派生公式不能证明所有配对都可读。图片文字需要稳定的承载表面，不能依赖图片恰好够暗。
-
-## 空间、内容和适应
-
-先用布局、间距和对齐表达分组。字段内部、字段之间、组件内部与页面留白有不同责任，即使此刻数值相同，也不意味着必须一起变化。
-
-长内容优先换行并扩展承载区域；宿主负责页面列数、容器和外部留白，组件负责内部文字与控件的布局。带框输入的默认最小高度允许随文字增长，不应被固定高度重新裁切。无法断开的标识符、长中英文与窄容器应作为相关变化的具体核对场景。
-
-固定值、离散尺度和局部 CSS 都可以表达合理决定。按钮内与文字相关的留白可以跟随文字尺度，页面空间可以依据容器调整；不要求所有间距遵循统一缩放曲线。引入响应规则时，应说清依据哪个上下文、允许怎样变化、边界是什么，以及相对现有方案改善了什么。
-
-例如，页面在宽容器中需要更大的留白，可以由页面布局表达。只有多个场景需要共享同一种空间政策时，才考虑公共角色；一张设计稿中的数值差异不足以支持新增全局密度参数。
-
-## 组件组合与用户状态
-
-普通表单从 InkForm 的纵向布局和内置控件的 label／error 开始。Input、Textarea、Dropdown、Picker 已承担标签关联；自定义字段再用 InkField，避免重复标签。页面负责字段分组、提交和持久化；字段组件负责输入与反馈表达。
-
-按后果区分普通动作、主要动作与危险动作。主提交明确使用相应按钮主题和原生提交类型。异步操作保留动作含义和用户输入，失败应有明确反馈和可恢复路径；不能把异常显示成成功，也不能让校验默认值覆盖已有草稿。
-
-确认场景按所需语义选择：InkDoubleCheck 提供确认弹层，InkDialog 支持更完整的确认、取消与等待过程，自定义弹层才使用 InkPopup。受控模型、确认提交和取消草稿是不同责任，消费时遵循各组件参考，不从外观推断模型提交时机。
-
-加载、空结果、操作失败与确认分别表达不同状态。根据真实可达状态提供界面，不把它们合并为一个含糊的提示，也不为应用不可能进入的状态添加配置。
-
-原始编辑数据与解析结果也要区分。InkJsonEditor 编辑包含不完整 JSON 在内的原始文字；消费者只在验证通过的边界解析和持久化。适合固定业务流程的普通表单和由 schema 驱动的表单，按数据责任选择，不能仅因为后者能自动生成控件就替换前者。
-
-## 主题与实现责任
-
-用户明确选择的主题优先于系统偏好。Web 以根级主题和公开 CSS 变量提供已约定的覆盖能力；哪些值在运行时传播、哪些需要重新构建，由样式指南说明。任意 ref 值的变化不保证自动带动所有 sys 或 comp 输出。
-
-Web 的 Popup／Scrim 会移动到 body，局部容器的主题或字体不能被当成弹层的继承保证。宿主需要统一主题时，应使用已支持的根级入口。跨平台可以共享颜色用途、文字职责和状态要求；CSS、DOM、原生控件与平台交互方式由对应实现负责。
-
-## 维护和扩展
-
-修改前先确定要保持的设计关系与预期变化，再选择改动位置。复用已有角色的依据是共同用途和共同变化责任；局部计算只有形成有意支持的公共能力后才需要成为 Token 或 API。
-
-新增共享能力应说明真实使用情境、现有能力的缺口、默认行为、允许变化和覆盖责任。设计决定、输入格式、求值机制和某次渲染结果分别判断；不要把它们都当成“改一个数字”。这些说明可以放在适当的自然段和例子中，无须为每次调整填写统一模板。
-
-Token 源拥有名称、叶节点用途、类型、值与引用；组件源码和公开声明拥有 API 事实；本指南拥有跨角色与场景的设计判断。发现实现与已认可要求不一致时，应指出差异，在当前授权范围内修复或提出规则变更。不能仅为解释现有代码而修改要求。
-
-变更验证应与其影响对应：静态检查确认类型、生成与包契约，真实页面确认内容、状态、视觉和交互。生成成功不能代替设计判断。只有稳定重复、能够可靠判定的问题才值得加入自动检查；新的品牌主张或尚无证据的通用规则先作为提案讨论。
-
-对公开名称、用途、默认表现或交互承诺的改变，连同实现、指南、示例及迁移说明一起交付。Agent 的操作授权、命令和提交规则由所在仓库的 AGENTS 负责。
+仓库根级 DESIGN.md 与 docs/design 是人工维护的源，Web 包内相同路径是随版本交付的副本。消费者读取安装版本，维护者读取当前 checkout；设计意图可以跨平台延续，具体宿主业务与平台实现由各自负责。

README.md

@@ -5,7 +5,7 @@ renderer is published as `@inkcre/ui-web`.
 
 ## Single Source of Truth
 
-设计判断由 [DESIGN.md](DESIGN.md) 维护。`tokens/inkcre.tokens.json` 是 Token 规范源，
+[DESIGN.md](DESIGN.md) 提供设计总纲和按任务阅读的路径；设计立场、视觉语言、页面组合和判断依据由 `docs/design/` 分别维护。`tokens/inkcre.tokens.json` 是 Token 规范源，
 Figma 仅提议已有路径的值更新；生成物通过生成器更新。
 当前输入格式与维护入口见 [Token 指南](tokens/tokens.md)，生成命令与输出见
 [Token 生成说明](scripts/build-tokens.md)。
@@ -87,6 +87,8 @@ coverage, and generated Agent Skills.
 
 ## Histoire delivery
 
+展示构建使用 lockfile 中的 Vue 和 Histoire 高亮实现，由 Vite 打包到站点。不要把 Vue 单独替换成 CDN 生产版本，也不要用空对象模拟 Shiki；Histoire 的状态同步和源码面板依赖这些库的实际运行时契约。
+
 `UI checks` validates Histoire as part of the repository contract. After a
 successful same-repository run, the trusted Preview workflow checks out that
 exact pull-request head, builds Histoire itself, and publishes it to the stable