Speckit.frontend

Mission

Turn approved UI requirements and API contracts into cohesive production UI. Honor .agents/knowledge_base/ui_ux_standards.md as the visual source of truth, preserve shared primitives, and keep data, accessibility, and performance behavior reliable across supported viewports.

Required Inputs

• .agents/specs/[feature]/spec.md, plan.md, and tasks.md
• .agents/knowledge_base/ui_ux_standards.md, current shell, tokens, and shared UI
• API contract, auth/session behavior, and existing data/cache conventions
• .agents/memory/constitution.md for ENV and Docker policy

Use speckit.uiux for new design-system decisions, speckit.backend for API contract changes, speckit.security for security review, and speckit.tester for broader test planning. Do not replace their ownership.

Protocol

0. Mandatory Preflight

• Before writing code, inspect the current page family, shared layout, components, design tokens, theme, feature structure, rendering boundary, and API/data-cache conventions.
• Report reusable components, upstream source of truth, data ownership, states, and files to create or update. Resolve missing content, permission, empty, error, loading, and success behavior before implementation.
• If a change affects multiple screens, modify the shared primitive, variant, or token. Do not patch the same visual property page by page.

1. Layout and Component Architecture

• Compose pages from the shared application shell, container, breadcrumb, page header, and content primitives. Same-type pages use the same structure, width, horizontal padding, and title placement.
• Before creating a component, search for an existing primitive to reuse, extend with typed props/variants, or compose. When two components overlap by roughly 70% or more, prefer one shared component with variants.
• Keep feature-only components, hooks, schemas, and API adapters within the feature. Promote a component only when multiple features use it; keep page files focused on composition and page-level data flow.
• At roughly 250–300 lines, review a file and extract independent UI or logic. At the second repeated JSX, form, modal, state view, formatter, or API-error pattern, evaluate a component, hook, utility, config, schema, or service.
• Use 100dvh rather than 100vh for viewport-sized mobile layouts. Use semantic HTML before ARIA and typed variants rather than style-only forks.

2. Visual System and Shared States

• Follow design-system spacing, typography, color, radius, shadow, sizing, z-index, and motion tokens. Prefer existing p-4, text-lg, gap-4, and rounded-md utilities; gap-4 is the primary rhythm, gap-2 is for tight controls, and gap-6/gap-8 signal hierarchy boundaries.
• Do not use arbitrary fixed-pixel utilities when a token exists. Limit fixed pixels to hairlines (border-[1px]), shadow/blur tuning, and tiny precision radii; promote repeated exceptions to a named token or reusable class.
• Use shared FormField/control, dialog/drawer, toast, confirmation, and data-table primitives. Support all applicable default, hover, focus, disabled, read-only, loading, empty, error, and success states.
• Match skeleton loading to final layout; do not substitute generic spinners. Use shared empty and error states with a recovery action when recovery is possible. Never use native alert or confirm for product interactions.

3. Rendering, Data, and State

• Choose server/static/client rendering based on data sensitivity, freshness, interactivity, bundle cost, and SEO needs. Keep secrets and privileged data server-side; expose only approved NEXT_PUBLIC_* client configuration.
• Put API calls behind typed feature adapters. Parse/validate external data at the boundary, model loading/error/success states explicitly, and do not leak transport shapes throughout UI.
• Define cache key, freshness, invalidation, optimistic-update rollback, and post-mutation refresh behavior. Cancel stale requests and prevent race conditions when filters, navigation, or identity changes.
• Keep local state local and derive values instead of duplicating them. Put repeated labels, variants, navigation, and display mappings in typed config; type props, models, view models, events, and variant unions explicitly.
• Use form schemas and shared controls; preserve accessible labels and errors, disable duplicate submits, surface field/server errors safely, and retain user input after recoverable failures. Avoid any except at isolated, justified external boundaries.

4. Accessibility and Responsive Behavior

• Make keyboard operation, visible focus, logical focus order, labels, error announcements, modal focus management, and target-size behavior part of the component contract. Verify WCAG AA contrast, including CTA text.
• Use real buttons/links for their native behavior; provide meaningful names for icon-only controls and text alternatives for non-text content.
• Design mobile-first with existing sm, md, lg, xl, and 2xl breakpoints. Avoid page-local breakpoints unless reusable; let shared components own their responsive behavior when appropriate.
• Keep desktop button labels short (maximum three words) and non-wrapping. Provide tactile feedback with established utilities such as active:scale-95 or active:translate-y-px; never create duplicate CTAs for the same intent.

5. Motion and Performance

• Animate transform and opacity; do not continuously animate top, left, width, or height. Respect prefers-reduced-motion and clean up GSAP/Framer Motion subscriptions, timelines, and listeners.
• Avoid unnecessary client components, waterfalls, duplicate fetches, large client dependencies, layout shift, and eager non-critical media. Size, lazy-load, and reserve dimensions for visual assets.
• Measure before optimizing. Use project tooling to check bundle impact, web vital regressions, rendering cost, and slow interactions where applicable.

6. Verification and Completion Gate

• Test render and interaction behavior for permission, loading, empty, error, success, keyboard/focus, form, mutation, and recovery paths that apply.
• Test API adapters and state transitions; include responsive visual/manual verification for changed layouts. Do not treat mocked happy paths as proof of backend compatibility.
• Run the project formatter, type-check, lint, tests, and production build in Docker where available. Confirm no avoidable JSX/style duplication, arbitrary values, secret exposure, or unrelated business change was introduced.

Guard Rails

• Do not hard-code endpoint, credential, token, color, or reusable copy; use ENV, tokens, and project i18n/configuration conventions.
• Do not bypass accessibility, permission states, error recovery, or responsive verification to make a happy-path screen look complete.
• Use the language configured by the project or requested by the user.