UI Spec

UI Specification

Overview

Ground a candidate direction in current source truth, or turn an approved source into an implementation-ready UI contract for dev-frontend. It may serialize a candidate into a complete generation prompt, but never operates external AI, generates images, builds prototypes, or edits product source.

Consume urn:skills:ui-request:v1; the portable typed handoff is urn:skills:ui-contract:v1, with urn:frontend-visual-evidence:v1 retained as a typed attachment when applicable. Product behavior, shared DESIGN.md, and Feature UI Markdown keep separate native authority; the handoff references them and never copies shared token semantics.

Workflow

1. Read effective repository guidance and run git status --short before planning an authorized artifact write.
2. Before trusting a concept, inspect current product/source truth for real scope, data/actions/states, components, shared owners, and library mappings. Record conflicts and exclude every concept-only capability.
3. Choose one lifecycle stage:
   • Candidate direction: when the user has directed exploration but has not approved a visual result, load references/candidate-visual-direction.md. Keep its spec and complete synchronized prompt under verified ignored .codex/reviews/; leave formal docs unchanged and remain Not Ready.
   • Accepted contract: fix the selected visual source: a user-selected Product Design result, supplied screenshot/mockup/frame, accepted current surface, or accepted shared visual baseline. Record identity, revision/image ID, approval, rights status, use and ignore boundaries, target viewport/state, and source limitations. When a current runtime exists, load references/frontend-visual-evidence.md and request same-round, same-viewport/state source and runtime captures from ops-browser without operating the browser here. If neither a source-grounded candidate brief nor a selected/accepted source exists, stop as evidence-incomplete instead of fabricating one.
4. For an accepted contract, resolve DESIGN.md adoption from effective guidance, build ownership, and shared consumers. An adopted boundary uses its approved <design-root>/DESIGN.md as the sole shared visual-semantic authority; monorepo nesting implies neither inheritance nor one file per app. A local slice that preserves shared semantics may instead record DESIGN.md: Not adopted (not required for this slice). Require first adoption only when requested or when shared semantics change. Then load references/design-md-contract.md, use assets/DESIGN.md as the verified-source starter, and follow its completeness and trusted-approval gates. Format lint alone is insufficient; changed DESIGN.md content makes its approval stale and dependent slices Not Ready. Keep page-local changes in their Feature Spec; do not rewrite unchanged shared semantics merely to synchronize documents. Existing exact-content approval rules remain.
5. Define implementation slices: one Feature Spec per confirmed page/flow/domain; for multiple independent domains, create one shared index plus one independently loadable contract per slice and load references/multi-surface.md.
6. Select one profile:
   • Feature Spec (default): reuse current shared systems unless shared semantics truly change.
   • Design System Spec (conditional): only when shared tokens, reusable component meaning/variants, state vocabulary, or cross-surface visual rules must change.
7. In Design System Spec, keep <design-root>/DESIGN.md as the only durable shared visual output; Feature Specs reference it instead of copying shared semantics.
8. Translate the selected source into concrete layout, state, interaction, and accessibility specifications for each slice. Name reusable and page-defining components only after checking current source and the project map when one exists; keep props, slots, events, types, SVG path data, source paths, and copied token values out of the page contract. Use the exact evidence levels source-extracted, browser-computed, visually-inferred, proposed, and Not verified. Load the visual-direction, layout-governance, measurement-normalization, and viewport workflow references only when their named conditions apply. Load layout governance also for changed state transitions, competing inputs, focus, or hit testing; reuse its affected interaction matrix in the existing UI contract. When standardizing a scene layout archetype, load references/scene-archetypes.md. When icons must be SVG or shared iconography changes, load references/svg-icon-system.md, resolve the actual icon owner/library and rights, and specify semantic role, family, rendering, state, accessibility, and fallback without generating SVG source.
9. Add a traceable delta table for every material visual difference: acceptance ID, selected-source target, current runtime, target contract, priority, shared-or-local owner, evidence IDs, verification, and applicable asset owner/fallback.
10. For every slice and multi-slice task, add one Ready for dev-frontend <slice>, Partial, or Not Ready verdict. Do not issue Ready when the selected source is unavailable or unapproved, rights/use are insufficient, target viewport/state is uncertain, a P1 asset has no accepted owner/fallback, or an exact proposed value lacks owner approval. This verdict is the UI visual/interaction readiness axis only. It neither proves nor upgrades Product readiness. When Product behavior applies, dev-frontend may start the slice only after the matching Product and UI axes are both ready; a conflict stays with its semantic owner and no model may select a winner.
11. For a shared DESIGN.md change, follow references/design-md-contract.md for lint, diff, duplicate-heading, and explicit derived-export gates. Missing required evidence remains Not verified and keeps the affected slice Not Ready.
12. Keep the page UI contract and component guidance human-readable and authoritative for their own meanings. Markdown is the default durable UI artifact. A YAML/JSON 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. Never copy tokens, API/DTO schemas, props, slots, events, or source paths into a projection; otherwise omit it and let current source plus Markdown remain authoritative.
13. Hand the spec, delta rows, evidence limits, and a validated frontend-visual-evidence/v1 spec-ready artifact to dev-frontend. Store that task evidence under a verified ignored .codex/artifacts/ location by default; publish it with durable docs only when a named team consumer, accessible artifacts, schema/validator, drift policy, and revalidation owner justify it. Do not add implementation mapping, visual reviews, runtime coverage, final verdict, or claim runtime behavior in this Skill.
14. When a compatible Repository Asset Graph is available, resolve shared-design, feature-UI, route, component, and consumer refs and reject duplicate active authority claims. Never invent graph IDs or turn the graph into visual authority.
15. When Forgeway integration is active, bind the immutable Run input and PackageManifest/basis, fingerprint authorized outputs, and attach typed UI-contract and visual-evidence Observations to that exact result package. For adopted DESIGN authority, follow references/forgeway-handoff.md for package-relative artifacts, hashes, byte lengths, compatible consumer, and claim. Ready or a satisfied gate is not review, delivery, deployment, or production proof.

Profiles

• Feature Spec (default): one selected page or flow contract; a multi-surface request may use a shared index plus independently loadable Feature Spec contracts, each with its own layout, mapping, states, interaction, responsive/accessibility rules, assets, acceptance, and readiness verdict.
• Design System Spec (conditional): accepted shared tokens, semantic components, variants, state vocabulary, or visual rules; may create, extract, maintain, or evaluate the repository-owned contract.

Do Not Use For

• Generating images, inventing redesign alternatives, UX research/critique, or shareable prototypes; use the host's Product Design or image capability. Preparing a source-grounded candidate specification and complete prompt remains in scope.
• Sending prompts, assets, or follow-up instructions to a named external model; use ask-ai with the frozen local artifacts.
• Unresolved product behavior, permissions, failure semantics, or acceptance; use product-spec.
• Frontend source changes or refactors; use dev-frontend with the accepted specification.
• Read-only frontend implementation audits; use audit-frontend.
• Browser screenshots, console/network evidence, or desktop-window operation; use ops-browser or ops-client.
• Git staging, commits, pushes, or branch cleanup; use repo-delivery after review.

Hard Rules

• Require a selected visual source or accepted existing UI/design-system baseline before authoring a visual implementation contract.
• Treat the local candidate UI specification as the only candidate-direction source. Update it first, then rewrite the complete generation prompt from that revision. Never treat external-chat-only corrections as part of the candidate contract.
• Verify both candidate paths, ignore status, and hashes after edits and before handoff; any change makes the prior handoff stale.
• Do not generate or edit images, build prototype code, or edit product source.
• Do not generate or edit SVG source. Define its visual, ownership, safety, accessibility, and acceptance contract, then route implementation to dev-frontend.
• Do not invent metrics, features, routes, permissions, states, backend behavior, or runtime evidence.
• Do not treat pixels as proof of exact tokens, component ownership, behavior, accessibility, or implementation feasibility.
• Do not activate Design System Spec merely because a feature reuses existing tokens or components.
• Do not create a parallel component library or token system when the project already has an owner.
• Do not make page specs redefine reusable component interfaces. Record page composition and page-local state/interaction; route current component ownership through a validated project map when one exists, then recheck live source before implementation.
• Do not require a ui-page/v1 or ui-components/v1 Schema, project-local validator, or YAML/JSON companion for ordinary UI work. Admit a projection only when its named non-LLM consumer and complete lifecycle are already real and maintained.
• Treat <design-root>/DESIGN.md as the single human-readable visual-semantic authority for a proven boundary that has adopted it; do not force first adoption for a local slice that preserves shared semantics.
• Keep durable DESIGN.md, UI indexes, and Feature Specs current-only. Git retains formal history; task captures, comparison passes, superseded candidates, and validation timestamps belong in .codex/ unless durable-evidence gates are met.
• Require named non-implementer human approval bound to the exact content hash before treating a newly created or changed DESIGN.md as accepted; never let the executor self-approve extracted current CSS as the target design.
• Require applicable loading, empty, error, populated, permission, focus, responsive, overflow, localization, and reduced-motion rules; justify exclusions.
• Give every applicable slice its own viewport matrix and readiness verdict; keep independent incomplete slices visible as Partial without turning one surface's viewport requirements into a catalog default.
• Do not stage, commit, push, publish, or approve a shared baseline.
• Keep default and interaction states distinct. Overlays are closed and absent from default acceptance unless explicitly defined as default; specify open state, trigger, focus, close, and layout separately.

Output Contract

Report capability ui.contract.specify@1.1.0, typed result/attachment refs, Run and input/result PackageManifest refs when integration is active, the lifecycle stage and selected profile, source identity/approval and rights/use boundary, target viewport/state and slices, evidence levels, layout/state contract, delta table, component/token mappings, responsive/accessibility rules, assets/copy, shared-system changes or None, evaluation gates, per-slice and overall readiness, and every Not found or Not verified gap. Include at least:

• shared visual-authority disposition: adopted, first-adoption requested, or not adopted/not required for this slice
• resolved <design-root> and DESIGN.md revision or stable identity when adopted
• lint command and result when DESIGN.md is created or changed; otherwise Not applicable
• diff command and regression verdict, or Not applicable when a Feature Spec leaves DESIGN.md unchanged, the authority is created for the first time, or the boundary has not adopted it
• per-slice spec IDs and readiness
• for candidate direction: both paths/hashes, ignore status, generation owner, handoff status, and DESIGN.md unchanged
• raw selected-source measurement evidence and the normalization record for every applicable repeated spacing cluster
• per-slice viewport acceptance matrix or a justified Not applicable verdict, including required/optional/excluded entries, size, environment, state, and acceptance-evidence source; hand the same matrix to dev-frontend, audit-frontend, and ops-browser/ops-client without redefining its schema
• when SVG icons apply: shared-or-local disposition, semantic role-to-owner mapping, approved family/render/state and coloring rules, rights, accessibility, accepted isolated fallback or evidenced None, and focused gallery/runtime acceptance

References

• Core: usage, workflow, candidate direction, DESIGN.md, Forgeway handoff, visual source.
• Visual detail: direction, layout, SVG icons, measurement, evidence.
• Scope/output: multi-surface, documentation, rubric, evals.