/ui-first-principles

name: ui-first-principles
description: "First-principles UI/IA reasoning: turns a `<scenario>` + API field set into JTBD analysis, principle-anchored field-priority decisions, anti-pattern findings, and a bidirectional UI↔API gap report. Trigger: UI、UX、資訊架構、IA、scenario-driven UI、欄位優先級、information hierarchy. Not for: visual/CSS work (use `/frontend-design`), post-build critique (use `/critique`), or simplifying existing layouts (use `/distill`)."
allowed-tools: Read, Grep, Glob, Write, Bash(bash:*), Bash(node:*), Bash(mktemp:*), Bash(rm:*)

UI First-Principles

Reasoning chain: `<scenario>` → JTBD → 5 IA/cognitive principles → field decisions → anti-patterns → gap report → validated handoff doc.

> **Output**: `handoff-ui-first-principles.md` (default `<cwd>/handoff-ui-first-principles.md`, override with `--output`). Downstream `/frontend-design` reads §5 Information Hierarchy directly.

Non-Negotiable Rules

> SKILL.md is the normative source. Files under the `references/` directory elaborate but do not override.

| # | Rule | Violation = | |---|------|-------------| | 1 | Phase 1 (`redact.js`) **must** run before any LLM phase. Raw input never enters Phases 3–6. | Skill invalid (PII risk) | | 2 | Phase 7 critical violation (`pii_leak_fingerprint` / `pii_leak_regex` / `missing_decision`) → **1 retry** with violation context → still critical → emit `⚠️ Need Human` (no warn-only fallback). | Retry policy breach | | 3 | Principle Anchor column **must** hold one ID from `JTBD \| CognitiveLoadTheory \| HicksLaw \| MillersLaw \| ProgressiveDisclosure`. Multi-principle prose is fine in rationale. | `invalid_anchor` soft violation | | 4 | Priority column **must** hold one of `primary \| secondary \| on_demand \| hidden`. | `invalid_priority` soft violation | | 5 | Anti-Pattern `Pattern` column IDs **must** belong to the v1 whitelist in `references/anti-patterns.md`. Use literal `(none detected)` when no anti-patterns apply. | `invalid_anti_pattern_id` soft violation | | 6 | Output **must** end with `✅ Ready` (clean) or `⚠️ Soft warnings` (soft only) or `⚠️ Need Human` (post-retry critical). Hook + behavior layer parses these. | Auto-loop cannot parse |

Trigger

• Keywords: UI first principles, IA design, 資訊架構, 欄位優先級, scenario-driven UI, JTBD UI, anti-pattern audit, ui-first-principles
• Slash form: `/ui-first-principles <scenario>`

When NOT to Use

| Intent | Use instead | |--------|-------------| | Visual layout / colour / Tailwind work | `/frontend-design` | | Post-build evaluation of existing UI | `/critique` | | Simplifying an already-shipped flow | `/distill` | | Pure feasibility on a design idea | `/feasibility-study` | | Tech-spec for an IA decision | `/tech-spec` (use this skill's output as input) |

Arguments

| Arg | Required | Default | Purpose | |-----|----------|---------|---------| | `<scenario>` | Yes | — | Free-text scenario name (e.g. `transaction confirmation`, `NFT detail page`). Drives JTBD. | | `--api <path>` | No | — | JSON sample file (single object literal). Phase 2 uses top-level keys as field set. | | `--manual <path>` | **Deferred to v2** | — | Manual field-list file (`fieldName: type (description)` per line). **Not supported in v1.** Reason: `redact.js` masks via the KV-pair fallback parser, which treats `field: type` as `field=type` and masks the type literal — `address: string` becomes `address: <redacted:address>`. The masked line then fails `normalize-input.js`'s `MANUAL_LINE_RE` (the type token must start with a letter or quote, not `<`), so the field is silently dropped from `bundle.fields` and Phase 7 Rule 2 cannot require a decision for it. Always use `--api` in v1. Manual-list support requires a redactor change tracked in the v2 backlog. | | `--domain crypto` | No | none | Phase 1 + 7 desensitization for `0x...` addresses/hashes. | | `--output <path>` | No | `<cwd>/handoff-ui-first-principles.md` | Override report path. |

> v1 invocation contract: `--api` is required in v1 (`--manual` is deferred to v2 — see Arguments table for why). Phase 0 rejects missing input or any combination that supplies `--manual`. The tech-spec §3.3 LLM-fallback path (running Phases 3–6 with no real input) is also **deferred to v2** — `redact.js` cannot mask what does not exist, so a no-input run would publish an empty bundle and skip Rule 1 fingerprint coverage and Rule 2 field coverage. Rule 1b (regex rescan over the report) would still execute, but it cannot compensate for missing input — it only catches new PII the LLM hallucinates, not values that should have been redacted upstream.

Workflow

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
                                                                           ↑__________________________ retry-on-critical (×1) ____________________________|

Phase 0 — Preflight (Bash)

1. Verify `--api <path>` was provided. v1 only accepts `--api`; reject `--manual` (deferred to v2 — see Arguments table). Reject and exit non-zero with the canonical usage banner:

   ⚠️ Need Human: ui-first-principles preflight error
   Reason: <missing_input | unsupported_input_v1 | input_unreadable>
   Usage: /ui-first-principles "<scenario>" --api <path> [--domain crypto] [--output <path>]
   Detail: <one-line context — e.g. "--manual is deferred to v2; only --api is supported">

2. Verify the file at `--api` exists and is readable; on failure use `Reason: input_unreadable` with the offending path in `Detail:`. 3. `TMPDIR=$(mktemp -d /tmp/ui-fp.XXXXXX)`. Pass to all later phases. Install the cleanup trap **before** any later phase runs:

   set -Eeuo pipefail
   cleanup() { rm -rf "${TMPDIR:-}" 2>/dev/null || true; }
   trap cleanup EXIT
   trap 'cleanup; trap - INT;  kill -INT  $$' INT
   trap 'cleanup; trap - TERM; kill -TERM $$' TERM

This purges `$TMP