# Hiui Design

> 在 React 项目中接入、生成、修改、联调或验收 HiUI 典型页与非典型页面时使用。适用于 数据统计表、普通表格、树形表格、左树右表、数据可视化、异常反馈页、抽屉表单/详情、 全页编辑/详情、不规范原型截图转规范页、老旧系统截图/URL/源码现代化转译，以及 host-integration、rules-only、legacy-host-compatible 等场景。

- Skill: `xiaomi/hiui-design` (Agent Skill, multi-file: 788 files)
- Install (CLI): `npx skillmds@latest add xiaomi/hiui-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiaomi/hiui-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: xiaomi (https://skillmd.com/u/xiaomi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiaomi/hiui-design

---


# HiUI 典型页 Skill

## Positioning

本 skill 是 HiUI React 页面工程的标准生成协议与交付治理控制面。`page-task-plan.v1` 继续是唯一顶层执行入口；`generationRecipe` 是其内部的正向生成子协议；交付完成态仍由 `preflight-report.v1`、`hiui-page-governance-report.v1`、`acceptanceProfile` 与 `finalReportContract` 决定。主叙事是“先按 recipe 正确生成，再由验收确认”，而不是“先生成一版，再靠验收纠偏”。

标准典型页命中 `page-component + slot-fill` 时，默认走 `minimal-doc fast path`：优先消费 planner、scaffold 与 slot contract，不再手工展开大段治理文档；复杂页、漂移页和正式验收场景才升级到完整规则链路。

`legacy-host-compatible` 的主路径统一为 `project-certified carrier first -> page-component semantics -> explicit fallback`。宿主承接事实成立时，应优先消费项目认证 carrier 或已认证页面组件，`managed-translation` 只保留为显式 fallback。`runtime-bridged-page-component` 只是 legacy 中对 `page-component` 的桥接语义命名，不引入平行 generation family；命中 `header` 时，只有 carrier certification、page contract 与 preflight 能共同证明 `PageHeader` stretch、`extra` right-docked 和 `60px` 节奏 owner 不漂移，主链路才成立。

对外沟通时要把两件事拆开说明：legacy 宿主主树不能被当成 generic `@hiui-design/typical-page-shells` 直挂运行时，不等于 legacy 项目不能走普通典型页组件主链。只要 planner 已给出 `page-component + runtime bridge + slot fill`，就必须沿该主链执行，不得把“不能 ad hoc direct shell import”误读成“只能 reference/fallback”。

## Core Object Model

- `page-task-plan.v1` 是唯一执行计划与事实出口；AI 不手工拼 `mode`、`pageType`、`pageUnits`、`startFrom`、`requiredDocs`、`requiredActions` 或关键命令链。
- `generationRecipe` 作为 `page-task-plan.v1` 的增量子对象引入，不单独创建平行顶层 contract。
- `generationRecipe` 只描述装配顺序、资产映射、槽位边界、禁止动作与轻量一致性检查；不重复存储可由 `pageComponent`、`baseMoldId`、registry 或既有 contract 派生出的事实。
- `targetDeliverySemantics` 与 `currentExecutionState` 必须分层输出：前者回答“计划成立后应沿哪条受管交付主链落地”，后者回答“当前这一步允许执行什么”。legacy blocked 时，前者仍可保留 `page-component + runtime bridge + slot fill` 目标语义，但后者必须只暴露 `ResolveBlockingFacts`。
- `editableSlots`、`lockedRegions`、`pageComponent`、`baseMoldId` 优先保持“引用或派生”，不复制进 planner。
- `runtimeBridgeProfile` 只作为 legacy `page-component` 路径的附加解析对象存在；它通过 `rules/runtime-bridged-component-matrix.json` 描述运行时桥接策略，不重定义 `pageComponent`、`baseMoldId`、`lockedRegions` 或业务槽位事实。
- project 级 `host pack`、project-scoped `page carrier` 与其认证结果属于运行时 / 资产事实，默认由计划通过 `facts`、`assetResolution`、`pageComponent` 等字段引用；不要把这些事实再平铺复制进每个页面合同。
- carrier-critical layout facts，尤其 `header` 的 stretch owner、actions docking 与 vertical rhythm owner，属于 contract + certification + preflight 共同消费的机器事实；不得退化成只存在于说明文档里的软建议。
- `acceptanceProfile`、`preflight-report.v1`、`hiui-page-governance-report.v1`、`finalReportContract` 继续保留，不降级、不移除。
- `requiredDocs` 是默认唯一补读来源；其最小结构固定为 `path`、`readMode`、`reason`。先读 `readMode=required`，`reference` / `conditional` 只在命中对应场景时补读。`requiredActions` 是默认唯一执行来源；没有结构化动作时，优先使用兼容命令字段，不自行扩展 gate。

对象模型与字段分级：`docs/generation/explainers/core-object-model.md`

## Standard Generation Protocol

`Standard Generation Protocol` 只回答 4 个问题：

- 从什么骨架起步。
- 关键 region 的装配顺序是什么。
- 哪些区域允许业务填充。
- 每完成一个关键步骤后做什么 `inlineChecks`。

`generationRecipe.required` 默认至少包含：

- `startingPoint`
- `assemblyOrder`
- `requiredAssets`
- `forbiddenMoves`

`generationRecipe.optional` 可按页型与复杂度逐步补齐：

- `slotFillPolicy`
- `regionOwnership`
- `inlineChecks`

第一批 recipe 只覆盖高频页型：

- `table-page`
- `analytics-page`
- `edit/detail-page`

标准生成协议补读：`docs/generation/explainers/standard-generation-protocol.md`

## Guardrails

- 本 skill 只处理 HiUI React 页面工程任务；需求细化、端到端流程编排、Figma 写入 / 设计稿生成、通用 React 重构必须交给对应 skill 或普通代码流程。
- 页面生成、重写、大改、页型迁移和旧系统 / 截图转译必须先取得 `page-task-plan.v1`；没有机器计划时不得手工拼结论、命令链或完成态。
- `blockingIssues` / `blockingReasons` 非空时必须 fail closed，只补事实；不得生成页面、写合同、跑 preflight 或输出完成态。
- 资产新增、补齐和更新只能走 shipped public contract；`add-asset` / `update-asset` 必须 dry-run，未 shipped 的 write / force / asset type 不得执行。
- 未经机器计划明确授权或维护者明确要求，不得执行 deploy、upload、publish、sync、global sync、Feishu / bitable 后台写入、release archive 生成或历史输出覆盖。
- 涉及外部服务、后台 agent、launch agent、守护进程或用户配置写入的动作，执行前必须同时验证目标范围、授权来源和 side effect 边界；缺任一条件时必须拒绝执行。
- `preflight` failed、hard profile governance failed、source snapshot 缺失 / 低置信度、`acceptance contract` 缺 provenance 时，最终回复必须是 blocked / failed。
- 开源版不得采集 usage data，必须按 `PRIVACY.md` 呈现 `not_applicable`、`skipped` 或 `unavailable`。

## Generation Gates

- 生成前门禁：项目根、机器计划、能力画像、mode lock、pre-plan facts。
- 生成协议门禁：page-component 可用性、route ownership、slot 边界、shell / adapter 证明、analytics contract、业务内容边界、受控扩展。
- `legacy-host-compatible` 普通典型页的硬门禁真相统一收口到 `rules/legacy-host-hard-gates.json`：baseline 固定为 4 个硬门禁，命中 `header` 时再追加 `header-layout-proof` 条件门禁，因此当前常见典型页通常会落到 5 个有效硬门禁。`styleBoundary`、`portalBoundary`、`runtimeSmoke` 仍按风险触发；但 `header` 的 stretch / right-dock / rhythm owner 不再只是样式建议，缺少结构化证明时必须阻断主链路。
- `legacy-host-compatible` 下若 planner 已证明 `page-component` ready 且 `runtimeAdapterProof.status=available`，默认执行语义就是 `page-component + runtime bridge + slot fill`。缺少 legacy 主树 direct shell import 前提，只能阻止 ad hoc standard-shell mount，不能作为擅自降级到兼容手拼页、reference 默认翻译页或自由 fallback 的理由。
- 前两层门禁属于“如何正确生成”的组成部分，不再和交付阻断口吻混写。
- `required` 级 `generationRecipe` 字段缺失时，不得假设或手工脑补；只能 blocked，
  或按计划明确给出的 fallback 执行。
- `startingPoint` 无法解析、`requiredAssets` 不可用、或 `assemblyOrder` 不完整时，
  不允许自由退回空白页手写。
- 只有当计划明确给出 `managed-fallback`、`host-archetype` 或
  `reference-or-scaffold` 为合法 fallback 时，才允许降级生成。
- `optional` 字段缺失不自动阻断，但不得伪造填充；缺失时按页型默认策略或现有规则执行。

生成门禁细节：`docs/generation/explainers/generation-gates.md`

## Delivery Gates

- `preflight-report.v1` 与 `hiui-page-governance-report.v1` 继续是交付确认层核心判断对象。
- `acceptanceProfile` 决定验收范围；`formal acceptance` 是验收等级，不是生成链路。
- `finalReportContract` 继续保留，用于完整报告与下游兼容。
- 交付门禁只负责“是否允许宣告完成”，不再主导生成叙事。
- 若某类问题连续多次在 `DeliveryConfirmation` 阶段暴露，必须优先回灌到
  `generationRecipe` 或 generation gates，而不是持续追加新的验收描述。

交付门禁细节：`docs/generation/explainers/delivery-gates.md`

## Runtime Protocol

- 运行时协议的唯一真相是 `rules/runtime-contract.md`；受管页面治理协议的唯一真相是
  `rules/page-governance.md`。
- `rules/runtime-bridged-component-matrix.json` 是 legacy `page-component` 桥接语义的唯一真相；它只声明 bridge profile、runtime shell 来源与薄桥层职责，不复制 mold / slot / ownership 事实。
- `rules/legacy-host-hard-gates.json` 是 legacy 普通典型页硬门禁编排的唯一机器真相；`SKILL.md`、生成门禁说明和 planner 只引用它，不再各自手写门禁数量。
- 基础项目事实（mode、capabilities、route ownership、i18n、governance availability）与基础资产事实（certified page component、mold、adapter catalog）应由计划内部消费并通过 `facts`、`assetResolution`、`projectMode`、`targetPage.routeOwnership` 等字段暴露。
- 对已接入项目，接入阶段写入的 `.local-context/hiui-design/outputs/project-integration-state.json`
  属于 project 级 runtime input fact。`PlanTask` 应优先复用它与 `project-mode.json`，
  直接进入页面规划；只有该状态缺失、损坏或与当前事实冲突时，才回退到 host profile /
  mode detection 诊断。
- `project-integration-state.json.integrationReady=true` 只有在接入阶段已经验证过
  project-certified carriers 的 `componentSource`、`componentShell` 与
  `componentSupportSources` 都能解析到真实项目源码时才成立；缺任一项时，接入必须保持
  `integrationReady=false`，页面生成阶段只允许暴露阻断原因，不得把缺失 carrier 问题延后到
  业务页实现期才发现。
- 对 `legacy-host-compatible`，`integrationReady=true` 的定义本身就包含项目级 required rollout 已完成：
  默认先覆盖 `table-basic`、`table-stat`、`tree-table`、`tree-split`、`drawer-form`、
  `drawer-detail`、`full-page-edit`、`full-page-detail` 这些 `carrier-first-required`
  页型；`feedback-status` 与 `data-visualization` 可作为 deferred batch 后补。缺少 required
  batch 的 project-certified carrier 时，integration state 必须显式输出
  `requiredLegacyPageTypes`、`deferredLegacyPageTypes`、`certifiedLegacyPageTypes`、
  `missingRequiredLegacyPageTypes` 与 `legacyRolloutCoverageStatus=blocked`，并把当前项目视为
  legacy 接入未完成，而不是“已接入但页面阶段再补 rollout”。
- `integrationReady` 默认只回答“项目是否已完成 hiui-design 接入”和“legacy 宿主桥接是否已具备项目级承接事实”。对 legacy，这个完成态已经内含 required carrier batch ready；`rules-only` / `host-integration` 下标准典型页组件是否可用，属于 planner 消费的资产事实与页型支持事实，不应被收口为通用项目接入失败。
- project-scoped host pack / carrier facts 也属于 runtime input facts。对 legacy 项目，应优先
  在项目接入 / capabilities 阶段一次认证，再由页面生成阶段复用，不要在每个页面重复解释宿主边界。
- Agent 只在 plan 缺失 / 冲突 / 排障 / 维护时显式读取 capabilities、mode lock、
  认证文件或 catalog。
- `host-qualification-facts.v1` 只是 runtime input facts contract，不是 execution plan；
  它只承载 legacy 宿主边界、bridge / adapter 事实与 provenance。
- `typical-page:runtime-smoke` 只记录“当前源码快照上的浏览器级证据”，不负责宣告页面完成；
  `preflight` / `doctor` 只把该证据与当前源码快照对齐并识别是否已过期；
  只有 `typical-page:finalize-page` 可以把交付状态翻转为 `finalized`。

## Task Lifecycle

文档叙事层统一为：

`LocateProjectRoot -> PlanTask -> ResolveBlockingFacts -> BuildGenerationRecipe -> GenerateByRecipe -> InlineConformanceChecks -> DeliveryConfirmation -> OutputDeliverySummary`

- `PlanTask`：默认先消费项目级 integration facts，再补 capabilities / route / asset-resolution；不要把“确认仓库结构 / 确认是否已接入 hiui-design”当成每次页面任务的可见前置步骤。planner 默认还要把生成期与交付期动作拆成 `generationInputs`、`inlineChecks`、`deliveryChecks`，避免把重验收口径前移成生成指导。
- `PlanTask` 输出层必须同时暴露 `targetDeliverySemantics` 与 `currentExecutionState`：前者描述目标交付主链，后者描述当前允许动作、阻断相位与 blocker 优先级。`requiredCommands`、`requiredActions` 与 `canStartImplementation` 必须跟 `currentExecutionState` 一致，不得再让 blocked 计划对外看起来像可以直接开始页面生成。
- `PlanTask` 对 legacy 普通典型页的首要职责之一，是把 “禁止 legacy 主树 ad hoc 直挂 standard shell” 与 “允许 page-component + runtime bridge + slot fill 主链” 同时暴露清楚；不得把 direct shell import 不成立，回退表达成通用 page-component 不可用。
- 若项目级 integration facts 已存在但 `integrationReady=false`，`PlanTask` 必须 fail closed，
  直接回显接入阻断原因；不要再尝试把页面生成、起手 scaffold 或页面级 preflight 当成接入 /
  legacy bridge 完整性的补救路径。页型级 `page-component` 资产是否 ready，继续由 planner 的
  `assetResolution` / `projectTypicalPageSupport` 独立判断，而不是反写成通用 integration debt。
- 当 `integrationReady=false` 的原因来自 legacy required rollout 未完成时，`PlanTask` 默认应把
  `bootstrap-target-project` 放在 `ResolveBlockingFacts` 队首；这表示当前项目的 legacy 接入 /
  bootstrap 还未完成，而不是“已接入项目在页面阶段追加一个 rollout 步骤”。若同时命中 route
  ownership blocker，再在其后追加 route 修复动作，不得跳过项目级 carrier rollout 直接进入页面实现。
- `BuildGenerationRecipe`：把 `generationStrategy` 转化为标准装配协议。
- `GenerateByRecipe`：生成行为必须遵循 `assemblyOrder`、`requiredAssets`、`forbiddenMoves`；不允许自由发明页壳、region owner、slot 顺序。
- `InlineConformanceChecks`：关键装配步骤后的轻量一致性检查，不把重验收前移。
- `DeliveryConfirmation`：末端确认层，内部继续承接 `WriteContract`、`Preflight`、`PreviewReady`、`FormalAcceptance`、`RuntimeGovernance`。开源版不承担 usage telemetry / stats closeout，最终回复只收口页面交付与质量验证状态。
- 这是叙事改名，不是立即的外部接口改名；公共脚本、报告对象和字段至少保留一个迁移周期 alias。

详细生命周期仍以 `rules/page-task-lifecycle.md` 为唯一真相。

## First Turn Output

页面任务首轮回复默认优先展示生成信息，而不是先铺验收字段。默认优先字段：

- `generationStrategy`
- `generationRecipe`
- `generationInputs`
- `inlineChecks`
- `primaryGenerationAsset`
- `assemblyOrder`
- `requiredAssets`
- `extensionPolicy`
- `requiredActions`

复杂或严格场景再展开：

- `deliveryChecks`
- `acceptanceLevel`
- `acceptanceProfile`
- `finalReportContract`

若命中 `non-typical-overlay` 或 `single-page-composite`，首轮还必须直接暴露 `layoutStrategy`、`layoutArchetype`、`nonTypicalScope`、`mandatoryComponents`、`compositionGuardrails`、`strategyEvidence` 与 `ownershipPlan`；这些属于生成输入事实，不是交付后才补的检查备注。

若命中不规范原型截图、旧系统截图 / URL / 源码，首轮按
`docs/generation/ai-kickoff-template.md` 输出 `kickoffType=pre-plan-facts`，只解释
`visual-translation-brief.v1` 与必要的 `host-qualification-facts.v1` 状态。

## Truth Index

- 机器计划入口、成功信号和失败信号：`scripts/README.md`
- 快路径执行入口与补读顺序：`rules/QUICK-START.md`
- 公开 CLI 契约：`scripts/public-cli-contracts.json`
- 运行时协议：`rules/runtime-contract.md`
- 页面任务生命周期：`rules/page-task-lifecycle.md`
- 失败恢复矩阵：`rules/failure-matrix.md`
- 生成约束：`rules/generation-rules.md`
- 数据可视化主次/样式机器策略：`rules/chart-semantic-policy.json`、`rules/data-visualization-layout-policy.json`
- 页面组件与模具注册表：`rules/page-component-registry.json`、`rules/page-mold-registry.json`
- runtime bridge profiles：`rules/runtime-bridged-component-matrix.json`
- legacy hard gates：`rules/legacy-host-hard-gates.json`
- runtime 交付策略：`rules/runtime-delivery-policy.json`
- adapter 注册表：`rules/adapter-registry.json`
- contract 约束与摘要：`rules/contract-regions.md`
- 页面治理与 source snapshot / acceptance contract：`rules/page-governance.md`
- 验收清单：`rules/validation-checklist.md`
- 前向验证与成功指标：`docs/validation/generation-recipe-forward-tests.md`
- 页面组件策略与认证：`docs/generation/page-level-components.md`、`docs/generation/component-certification.md`
- explainers（解释层，不是 source of truth）：`docs/generation/explainers/README.md`
- 页头几何与宿主 baseline：`docs/generation/figma-reference.md`
- 旧宿主转译：`docs/generation/legacy-host-compatibility.md`
- 视觉 / 旧系统 pre-plan facts：`docs/generation/visual-to-hiui-translation.md`
- 非典型页面：`docs/generation/non-typical-pages.md`
- 图表与数据可视化：`docs/generation/figma-page-rules.md`、`docs/generation/figma-pages/data-visualization.md`
- usage stats：`PRIVACY.md`

默认只读计划里的 `requiredDocs`；先消费 `readMode=required`，再按 `reason` 命中情况补读 `reference` / `conditional` 项。不要为选择模具或解释页型而整包遍历 `docs/`、`rules/`、`templates/`、`manifests/`。

## Final Report

- 最终回复默认基于 `deliverySummaryProfile` 输出轻量交付摘要。
- 复杂 / 高风险场景、严格验收、legacy 迁移、真非典型、复杂数据可视化、`preflight` / smoke 失败时，再进入 `finalReportContract` / `final-page-report.v1`。
- `final-page-report.v1` 应优先复用 managed page contract / workflow 已有事实来判断页面是否已生成、是否 stale、是否曾完成 formal finalize；不要再要求上层重复手填同一组状态。
- 最终报告默认阅读顺序是：页面如何生成 -> 使用了哪些主资产与槽位 -> 哪些区域继承 / 哪些区域业务填充 -> 当前交付确认状态。
- 状态字段必须完整保留，但不再占据主阅读中心。
- 若无法运行 `typical-page:render-final-report`，也必须呈现页面状态、preflight 状态、
  formal 验收状态、usage stats 状态、已执行动作、变更文件、验证命令与剩余风险。