Frontend UI (Apps)

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.