frontend-ui

name	frontend-ui
description	UI/UX guidelines for app development in this Turborepo (apps/web and future apps). Use when designing or implementing app pages, layouts, navigation, or interactions with Tailwind and @repo/ui components.

Frontend UI (Apps)

Overview

Design and implement app UI/UX with consistent patterns, accessibility, and performance. Reuse shared components from @repo/ui, keep the landing page lightweight, and follow App Router conventions.

Scope and Boundaries

• Apps may import packages; packages must not import apps.
• Prefer shared UI in packages/ui to avoid duplication across apps.
• App-specific UI belongs under the app (for web: apps/web/src/components).
• Import UI components via subpath exports (no barrel imports).

Workflow

1. Scan existing app layouts/components to preserve established patterns.
2. Decide whether the UI should be shared (packages/ui) or app-specific.
3. Build the UI using @repo/ui components and Tailwind utilities.
4. Add or update local app components using the ~/ path alias.
5. Validate UX details: hierarchy, spacing, responsive behavior, states, and a11y.
6. Keep changes minimal and avoid new dependencies unless required; ask first.

UI/UX Guidelines

• Layout: establish clear hierarchy with headings and section spacing; keep pages lightweight.
• Typography: use the existing Geist Sans/Mono setup unless explicitly asked to change.
• Color: rely on the UI theme tokens and CSS variables; avoid ad-hoc palettes.
• States: include hover/focus/active/disabled plus empty, loading, and error states.
• Responsiveness: design mobile-first and avoid horizontal scroll.
• Motion: use subtle, purposeful motion only when it improves clarity.

Implementation Rules

• App Router only: routes live in apps/web/src/app (use page.tsx and layout.tsx).
• Use ~/ for local imports (e.g., ~/components/...).
• Do not duplicate global CSS imports already defined in apps/web/src/app/globals.css.

Accessibility and Semantics

• Use semantic elements (header, nav, main, footer) and proper heading order.
• Ensure keyboard access and visible focus states.
• Use buttons for actions and links for navigation.
• Provide labels or ARIA attributes where needed.

Client Component Guidance

• Default to Server Components in apps.
• Add "use client" only when needed (hooks, browser APIs, event handlers).
• Isolate client components to the smallest subtree.

Output Format (PR-ready)

• Follow the repo response format: Plan, Edits, Review Notes, Validation.
• In Review Notes, include a PR summary (what/why), risks, and follow-ups.

Validation Commands

• pnpm --filter web lint
• pnpm --filter web typecheck
• pnpm --filter web build
• pnpm --filter web format
• Use repo-wide pnpm lint / pnpm typecheck when required.