用途
UI First-Principles 是一个以第一性原理进行 UI / 信息架构（IA）推理的技能。它的推理链条为：<scenario> → JTBD → 5 个 IA/认知原则 → 字段决策 → 反模式 → 缺口报告 → 已验证的交接文档。它把一段场景描述加上一组 API 字段，转化为结构化的信息架构决策，并将结果作为交接文档输出。
主要能力
- 通过对场景进行 JTBD（Jobs To Be Done）分析，明确功能、情感、社交层面的任务。
- 以 5 个信息架构 / 认知原则（JTBD、CognitiveLoadTheory、HicksLaw、MillersLaw、ProgressiveDisclosure）为锚点，对每个字段做出优先级决策（primary / secondary / on_demand / hidden）。
- 进行反模式发现（如 too_many_primary、scenario_field_mismatch、pure_aesthetic_over_utility、hidden_critical_info、redundant_fields）。
- 生成双向缺口报告：UI 需要但 API 缺失的字段，以及 API 提供但 UI 忽略的字段。
- 输出交接文档 handoff-ui-first-principles.md，默认位于
<cwd>/handoff-ui-first-principles.md，可通过--output覆盖。下游的 /frontend-design 会直接读取其中的 §5 Information Hierarchy。
使用方式
触发方式：
- 关键词：UI first principles、IA design、資訊架構、欄位優先級、scenario-driven UI、JTBD UI、anti-pattern audit、ui-first-principles。
- 斜杠形式：
/ui-first-principles <scenario>。
主要参数：
<scenario>（必填）：自由文本场景名称（如 transaction confirmation、NFT detail page），用于驱动 JTBD。--api <path>（v1 中必需）：JSON 样本文件（单个对象字面量）。Phase 2 使用其顶层键作为字段集。--domain crypto（可选，默认 none）：Phase 1 与 Phase 7 对 0x... 地址/哈希做脱敏。--output <path>（可选）：覆盖报告路径，默认<cwd>/handoff-ui-first-principles.md。--manual <path>：推迟到 v2，v1 不支持。原因：redact.js 通过 KV-pair 回退解析器进行掩码，会把field: type当作field=type并掩码类型字面量（如address: string变成address: <redacted:address>），该被掩码行随后无法通过 normalize-input.js 的 MANUAL_LINE_RE（类型 token 必须以字母或引号开头，而非<），字段会被静默地从 bundle.fields 中丢弃，Phase 7 Rule 2 便无法要求对其做出决策。v1 中请始终使用--api。
工作流程（Phase 0 preflight → Phase 1 redact → Phase 2 normalize → Phase 3 JTBD → Phase 4 principles → Phase 5 field table → Phase 5b anti-patterns → Phase 6 gap → Phase 7 validate → Emit）：
- Phase 0 — Preflight：校验是否提供了
--api <path>，v1 仅接受--api，拒绝--manual。校验文件存在且可读，失败时以非零退出并输出规范化用法横幅。后续所有阶段传入同一 TMPDIR，并在任何后续阶段运行前安装清理 trap。 - Phase 1 — Redact：运行
node scripts/skills/ui-first-principles/redact.js（参数--input、--inputFormat、--domain、--output）。v1 中INPUT_FORMAT必须为json_sample。输出 schema 包含 maskedText、forbiddenFingerprints、fieldDecisions、redactionSummary。PII 类别包括 email、phone、address、account_id、national_id、credential；另有 scripts/security-redact.js 作为基础层，高置信度匹配（PEM 私钥、AWS AKIA…、OpenAI sk-…、GitHub ghp_… / github_pat_…、Slack xox*、Google AIza… 等）会以 high_confidence_secret 中止，中置信度匹配被掩码为 [REDACTED]。 - Phase 2 — Normalize：运行
node scripts/skills/ui-first-principles/normalize-input.js，输出 ScenarioBundle JSON，LLM（Phase 3–6）消费其中的 scenario、fields、inputFormat、redactionSummary；验证器（Phase 7）消费 fields[].name、forbiddenFingerprints 以及三个白名单。 - Phase 3 — JTBD 分析（LLM）：读取 references/jtbd-framework.md 与 bundle.json，产出 ### 1. JTBD Analysis（含 3 个子节，空维度需明确写明 none in this scenario）。
- Phase 4 — Principles Briefing（LLM）：读取 references/principle-anchors.md，内化封闭枚举 JTBD | CognitiveLoadTheory | HicksLaw | MillersLaw | ProgressiveDisclosure，Phase 5 每行只能引用其一。
- Phase 5 — 字段决策表（LLM）：对 bundle.fields 中每个字段决定 Field（使用原名，不重命名）、Priority、Principle Anchor、Rationale。
- Phase 5b — 反模式发现（LLM）：读取 references/anti-patterns.md，以 markdown 表输出 ## 3. Anti-Pattern Findings；无可适用时输出单行表
(none detected)。 - Phase 6 — 缺口报告（LLM）：双向分析，输出 ## 4. Gap Report，含 UI needs but API missing 与 API provides but UI ignores 两部分，无则填
none。 - Phase 7 — Validate：运行
node scripts/skills/ui-first-principles/validate-report.js，根据结果决定写出、添加警告前缀或重试。
适用场景
- 需要从场景出发做信息架构与字段优先级决策的 UI 前期设计。
- 希望用 JTBD 与认知原则为依据，而非纯审美来做字段取舍。
- 需要产出可供下游前端设计（/frontend-design）直接消费的交接文档。
- 需要做双向 gap 分析，识别 UI 与 API 之间的字段不匹配。
限制
- 不适用于视觉布局 / 配色 / Tailwind 工作（改用 /frontend-design）；不适用于对已有 UI 的构建后评估（改用 /critique）；不适用于简化已上线流程（改用 /distill）；不适用于纯设计想法可行性（改用 /feasibility-study）；不适用于信息架构决策的技术规格（改用 /tech-spec，并将本技能输出作为输入）。
- v1 中
--api为必需，--manual推迟至 v2。 - 无输入运行（带 no real input 运行 Phases 3–6 的 LLM-fallback 路径）也推迟至 v2，因为 redact.js 无法掩码不存在的内容。
- 部分 PII 类型（IBAN、SWIFT、BIC、助记词/种子/恢复短语、通用 sk_… 风格 API 密钥等）不被覆盖，需在调用前从输入中移除，或先扩展 redact.js。
--domain crypto仅抑制 Rule 1b 的 eth_address / eth_hash 检查，不验证 LLM 文本中的 0x... token 是否源自输入；origin-aware crypto 强制校验在 v2 待办中。- 关于具体的执行步骤、脚本细节与校验规则，上述内容以资料为准；未提及的功能、收费、价格、平台或效果暂未提供。