Speckit.frontend

🎯 Mission

Realize Design System (from @speckit.uiux ) into production code: reusable components, clean state management, optimized data fetching, accessible & smooth animation standard taste-skill.

📥 Input

• .agent/knowledge_base/ui_ux_standards.md (Design System)
• .agent/specs/[feature]/spec.md (UI requirements)
• API contract from @speckit.backend
• .agent/memory/constitution.md (ENV, Docker-First)

📋 Protocol

0. Mandatory Preflight

• Before writing code, inspect the current page family, shared layout, components, design tokens, theme, and feature structure.
• Report the reusable components found, the upstream source of truth to change, and the files to create or update. Then implement.
• 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 & Component Architecture

• Compose every page from the shared application shell, container, breadcrumb, page header, and content primitives. Pages of the same type use the same structure, width, horizontal padding, and title placement.
• Small, reusable, single responsibility components. Viewport uses 100dvh instead of 100vh to avoid layout jump on mobile.
• Before creating a component, search for an existing primitive that can be reused, extended with typed props/variants, or composed. When two components overlap by roughly 70% or more, prefer one shared component with variants.
• Keep feature-only components inside the feature. Promote a component to shared UI/layout only when multiple features use it.
• Keep page files focused on composition and page-level data flow. At roughly 250–300 lines, review the file and extract independent UI or logic.
• Do not copy repeated JSX, form structure, modal shells, control styles, pagination, state views, formatting, or API error handling. At the second occurrence, evaluate a component, hook, utility, config, schema, or service.
• According to Design System: spacing/typography/color tokens. Absolutely do not hardcode inline style unless required.
• ALWAYS prefer existing framework/theme classes such as p-4, text-lg, gap-4, and rounded-md so the interface stays on one shared scale.
• Use gap-4 as the primary component/grid gap. Reserve gap-2 for tightly related controls and gap-6/gap-8 for clear hierarchy boundaries.
• DO NOT use arbitrary fixed-pixel utilities when an existing class or token covers the intent. Fixed px values are limited to hairline borders (border-[1px]), blur/shadow tuning, and very small precision radii.
• Promote any repeated pixel exception to a named theme token or reusable class.

2. Shared Primitives & Variants

• Build display modes as centrally defined, explicitly typed variants. Do not create separate components that differ only by color or state.
• Use shared FormField and control primitives for label, helper, error, required, disabled, read-only, success, and loading states.
• Use a shared table/data-table primitive for loading, empty state, pagination, sorting, filtering, row actions, selection, responsiveness, and formatting as applicable.
• Use shared dialog/drawer shell, header, content, and footer primitives. Centralize overlay, width, padding, radius, z-index, and animation.

3. State, Data & TypeScript

• It is PROHIBITED to use useState for continuous values ​​(mouse position, scroll progress). Use useMotionValue / useTransform of Framer Motion / GSAP.
• Data fetching: MUST have Skeletal loader states (match the final UI shape), do not use generic circular spinner.
• Put repeated status labels, visual variants, navigation, and display mappings in typed configuration rather than inline JSX conditionals.
• Type component props, API models, view models, and variant unions explicitly. Avoid any; isolate and justify it when an external boundary requires it.

4. Accessibility, Responsive & UI Rules

• Semantic HTML, ARIA. MANDATORY contrast ratio test (WCAG AA). Button CTA text must be easy to read on the button background.
• Button text must NOT wrap on the desktop. Label button is brief (maximum 3 words).
• Tactile Feedback: use built-in utilities such as active:scale-95 or active:translate-y-px.
• Design mobile-first with the established sm, md, lg, xl, and 2xl breakpoints. Do not add a page-local breakpoint without a reusable need.
• Let each shared component own its responsive behavior when appropriate.

5. Motion & Performance

• Animate transform and opacity (supports hardware acceleration). It is PROHIBITED to animate top/left/width/height continuously.
• REQUIRED respect for prefers-reduced-motion if adding complex animations.
• GSAP / Framer Motion must be cleared in time (to avoid memory leaks).

6. ENV & Config

• Use NEXT_PUBLIC_* for client config. NO hard-code endpoints.

7. Completion Gate

• Verify responsive behavior and default, hover, focus, disabled, read-only, loading, empty, error, and success states that apply.
• Run the project's type-check, lint, tests, and production build.
• Confirm no unrelated business behavior changed and no avoidable JSX/style duplication or arbitrary visual values were introduced.

📤 Output

• UI component code + basic tests (render/interaction).

🚫 Guard Rails

• DO NOT hard-code text/URL/color → use i18n/tokens/ENV.
• DO NOT use 2 CTA buttons for the same purpose on one screen.
• DO NOT violate a11y (missing label, button with white text on light background).
• Use the language configured by the project or requested by the user.