Guidelines for maintainable, accessible, and system-compliant frontend development.

Core Principles

• Component Reuse: Use shadcn/ui components first. Extend via cva variants or composition. Avoid custom CSS.

• Design Fidelity: Code must map 1:1 to Design Tokens. Resolve discrepancies before implementation.

• Rendering Strategy: Default to Server Components for performance. Use Client Components only for interactivity and API integration.

• Accessibility: Semantic HTML and screen reader compatibility are mandatory.

• Tool First: Check for existing solutions and tools before coding.

1. Tooling & Performance

• Reference: Consult react-best-practices skill for deep dives.

• Metrics: Target First Contentful Paint (FCP) < 1s.

• Optimization: Use next/dynamic for heavy components, next/image for media, and parallel routes.

• Shadcn Workflow:

• Search: shadcn_search_items_in_registries

• Review: shadcn_get_item_examples_from_registries

• Install: shadcn_get_add_command_for_items

2. Architecture (FSD-lite)

• Root (src/ ): Shared logic (components, lib, types). Hoist common code here.

• Feature (src/features/*/ ): Feature-specific logic. No cross-feature imports. Unidirectional flow only.

• Libraries:

• Date: luxon

• Styling: TailwindCSS v4

• shadcn/ui

• Hooks: ahooks (Pre-made hooks preferred)

• Utils: es-toolkit (First choice)

3. Standards

• Utilities: Check es-toolkit first. If implementing custom logic, >90% Unit Test Coverage is MANDATORY.

• Design Tokens: Source of Truth is packages/design-tokens (OKLCH). Never hardcode colors. Run mise tokens:build after updates.

• i18n: Source of Truth is packages/i18n . Never hardcode strings. Run mise i18n:build after updates.

4. Component Strategy

• Server Components: Use for Layouts, Marketing pages, and SEO metadata (generateMetadata , sitemap ).

• Client Components: Use for interactive features and useQuery (Orval) hooks.

• Structure: One Component Per File.

• Naming:

• Files: kebab-case.tsx (Name MUST clearly indicate purpose/functionality).

• Components/Types/Interfaces: PascalCase

• Functions/Vars/Hooks: camelCase

• Constants: SCREAMING_SNAKE_CASE

• Skeletons: Must be placed in src/features/[feature]/components/skeleton/ .

• Imports: Standard > 3rd Party > Local (Absolute @/ is MANDATORY; No relative paths like ../../ ). MUST use import type for interfaces/types.

• State Management:

• URL: jotai-location

• Server: TanStack Query

• Client Global: Jotai (Minimize use)

• Forms: @tanstack/react-form

• zod (Refer to v4 docs; NO deprecated APIs)

5. UI Implementation (Shadcn/UI)

• Patterns: Review .agent/skills/frontend-engineer/examples/ for mandated implementation patterns.

• Usage: Prefer strict shadcn primitives (Card , Sheet , Typography , Table ) over div or generic classes.

• Responsiveness: Use Drawer (Mobile) vs Dialog (Desktop) via useResponsive .

• Customization Rule: Treat components/ui/* as read-only. Do not modify directly.

• Correct: create a wrapper (e.g., components/common/ProductButton.tsx ) or use cva composition.

• Incorrect: Editing components/ui/button.tsx .

6. Designer Collaboration

• Sync: Map code variables to Figma layer names.

• UX: Ensure key actions are visible "Above the Fold". Verify clarity of usage.

7. Review Checklist

• A11y: Interactive elements have aria-label . Semantic headings (h1 -h6 ).

• Mobile: functionality verified on mobile viewports.

• Performance: No CLS, fast load.

• Resilience: Error Boundaries and Loading Skeletons implemented.

• Tests: Logic covered by Vitest where complex.

• Quality: Refactor until Typecheck and Lint (bun lint ) pass.