ui-spec

UI Specification

Purpose

Produce an implementation-ready UI contract without replacing Product, shared design, component/source, runtime-evidence, or delivery authority. This file is a routing map: after selecting a branch, read only its referenced modules.

Entry Gate

• Require either a source-grounded candidate brief or a selected/accepted visual source; otherwise stop as evidence-incomplete.
• Read effective repository guidance and current Worktree status before an authorized artifact write.
• Keep Product behavior, Feature UI Markdown, adopted DESIGN.md, component source, runtime evidence, and Git delivery as separate authorities.

Route Map

Request state	Load	Result
Applicability or source selection is unclear	usage and visual source	Resolve scope/source or stop
Direction is exploratory and unapproved	candidate direction	Ignored local candidate spec plus synchronized complete generation prompt; DESIGN.md unchanged; Not Ready
A page, flow, or accepted surface is selected	workflow and documentation boundaries	Feature Spec and per-slice readiness
Shared visual semantics are being adopted or changed	DESIGN.md contract	Approved, linted <design-root>/DESIGN.md; Feature Specs reference it
Several independent surfaces are in scope	multi-surface	Shared index plus independently loadable slices/verdicts

Invariants

• Candidate handoffs bind candidate spec/prompt revisions and hashes. Accepted-contract handoffs and evidence bind the accepted comparison-basis revision.
• Do not invent product behavior, exact values, assets, component ownership, rights, runtime facts, or shared semantics. Tag unknowns with the defined evidence level.
• Do not duplicate shared tokens or component interfaces in a Feature Spec, introduce a parallel Registry/schema, or force DESIGN.md adoption for an unchanged local slice.
• A structured projection is conditional: use it only when a named owner, producer, non-LLM consumer, semantic version, executable validator, drift policy, and retirement rule already exist.
• Do not operate external AI, generate/edit images or SVG source, edit product source, operate browser/client state, or mutate Git. Route those actions to their owners.
• Ready covers only UI visual/interaction readiness. It is not Product approval, implementation, review, runtime, delivery, deployment, or production proof.

Output Map

Return [email protected] with lifecycle/profile, source identity and rights, authority disposition, slice IDs, applicable layout/state/interaction/accessibility and asset contracts, delta/evidence references, comparison basis, per-slice readiness, and named gaps. Candidate output additionally returns both ignored paths/hashes and handoff status. Store task-local evidence under verified ignored .codex/artifacts/. Include DESIGN, viewport, SVG, or runtime-evidence fields only when the corresponding module was activated.

Reference Map

Load a module only when its condition applies:

Condition	Module
Visual direction, theme, color, Preserve/Overhaul choice	visual direction
An accepted/candidate source names a scene archetype	scene archetypes
Layout ownership, inset, overlay, focus, hit order, or transition changes	layout and interaction
Repeated source measurements need normalization	measurement normalization
SVG/icon roles or fallback are part of acceptance	SVG icon contract
Current runtime is compared with a selected source	visual evidence
Final readiness is being decided	evaluation rubric

Maintainers use eval cases for regression work; do not load them during ordinary UI specification.