Ui spec

UI Specification

Overview

Turn a selected visual source and verified product facts into an implementation-ready UI contract, then hand it to dev-frontend. This Skill specifies an accepted direction; it does not explore visual directions, generate images, build prototypes, or edit product source.

Workflow

1. Read effective repository guidance and run git status --short before planning an authorized artifact write.
2. 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, approval, rights status, use, and ignore boundaries.
3. Require the repository-root DESIGN.md as the single source of truth for shared visual semantics. If it does not exist, copy assets/DESIGN.md as the structural starter, replace every placeholder from verified sources, omit unverified token groups, obtain named human approval, and validate it before authoring Feature Specs or shared-system changes.
4. 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.
5. 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.
6. In Design System Spec, make the repository-root DESIGN.md the only durable shared output.
   • DESIGN.md is the only accepted shared product visual output.
   • Feature Spec never copies token values or component semantics from shared systems into its own artifacts.
7. Translate the selected source into concrete layout, state, interaction, and accessibility specifications for each slice. Mark each decision verified, extracted, proposed, or Not verified. Do not infer exact values from pixels.
8. For every slice and multi-slice task, add one Ready for dev-frontend <slice> verdict or one blocker verdict; mark partial multi-surface tasks clearly.
9. Before finalizing:
   • run official lint with npx -p @google/[email protected] designmd lint --format json DESIGN.md;
   • treat duplicate H2 headings as hard blockers for repository contracts: do not accept any output if the contract contains duplicate H2 (even if @google/[email protected] only emits warnings and exits 0);
   • for a Design System Spec update only, compare with the previous accepted source using npx -p @google/[email protected] designmd diff <before-DESIGN.md> DESIGN.md --format json; record diff as Not applicable for a Feature Spec that leaves DESIGN.md unchanged or for the first accepted creation, with no fabricated baseline;
   • only export machine assets when explicitly required, and always as explicit derived outputs (--format ...) after acceptance of the updated DESIGN.md.
10. Do not claim lint, diff, or export success without evidence output. If required tooling or network is blocked, report those checks Not verified and mark the affected slice Blocked.
11. Hand the spec and checks to dev-frontend; do not claim runtime implementation or runtime behavior evidence in this Skill.

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

• Visual exploration, image generation, redesign alternatives, UX research/critique, or shareable prototypes; use the host's Product Design capability when available.
• 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.
• Do not generate or edit images, build prototype code, or edit product source.
• 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 author or rely on another structured UI package as shared visual authority.
• Treat the repository-root DESIGN.md as the single human-readable visual-semantic authority.
• Require named human approval before treating a newly created or changed DESIGN.md as accepted.
• Treat duplicate H2 headings as hard blockers in Design System Spec contracts, regardless of CLI warning wording or exit code.
• Require applicable loading, empty, error, populated, permission, focus, responsive, overflow, localization, and reduced-motion rules; justify exclusions.
• Do not merge independent business domains into one omnibus contract. Author only confirmed slice contracts, keep unconfirmed slices visible in the shared index, and mark the overall multi-surface result Partial until every requested slice has its own complete state, interaction, responsive/accessibility, mapping, and acceptance contract.
• Do not stage, commit, push, publish, or approve a shared baseline.

Output Contract

Report the selected profile, source identity and approval, evidence basis, target surfaces and slice boundaries, verified/extracted/proposed decisions, layout and state contract, component/token mappings, responsive/accessibility rules, assets and copy, shared-system changes or None, evaluation gates, one Ready for dev-frontend <slice> or blocker verdict per slice, overall Complete or Partial, and every Not found or Not verified gap. Include at least:

• root DESIGN.md revision
• lint command and result
• diff command and regression verdict, or Not applicable when a Feature Spec leaves DESIGN.md unchanged or the authority is created for the first time
• per-slice spec IDs and readiness

Never present a source image or specification as implemented or runtime-verified UI.

References

• See references/usage.md for routing and artifact examples.
• See references/workflow.md for profile-specific specification and handoff details.
• See references/visual-source.md when qualifying and translating the selected visual source.
• See references/multi-surface.md when a request covers more than one page, flow, or business domain.
• See references/documentation-boundaries.md for durable UI locations, PRD links, and consumer reads.
• See references/design-md-contract.md for the official DESIGN.md format, validation gates, and derived exports.
• See references/evaluation-rubric.md for blockers and scoring.
• See references/eval-cases.md for trigger and quality evals.