# Shared Component Design System

Every component prompt may have a distinct visual theme, but it must build from
the same project tokens. This keeps reusable components consistent across apps
and automatically supports light and dark modes.

Visual reference: open `/design-system` in the running application. The route is
public so developers and agents can inspect it without authentication. The page
also contains a searchable inventory of local shadcn-style, MapCN, project, and
AI Elements components plus an AI workbench that generates repository-aware
implementation prompts.

## Foundations

- **Font:** Sora for interface text; JetBrains Mono for code or dense technical
  values when the surrounding feature already uses it.
- **Primary:** `bg-primary`, `text-primary`, `text-primary-foreground`.
- **Surfaces:** `bg-background`, `bg-card`, and `bg-popover`.
- **Text:** `text-foreground` and `text-muted-foreground`.
- **Structure:** `border-border`, `border-input`, and `ring-ring`.
- **Secondary emphasis:** `bg-secondary`, `text-secondary-foreground`.
- **Errors/destructive actions:** `bg-destructive`,
  `text-destructive-foreground`.
- **Radius:** `rounded-sm`, `rounded-md`, or `rounded-lg`, derived from
  `--radius`.

Prefer semantic Tailwind classes over raw hex values. A component theme should
describe hierarchy, density, shape, and interaction—not invent an isolated
palette.

## Required interaction states

Reusable interactive components must define:

- default, hover, active, focus-visible, disabled, and loading states;
- a visible keyboard focus ring;
- sufficient light/dark contrast;
- reduced-motion-friendly transitions;
- touch targets that remain usable on small screens.

## React design rules

- Reusable components receive data and actions through typed props.
- Pages and feature containers own routing, API calls, authorization, and
  server-state orchestration unless the component explicitly models one of them.
- Use composition (`children`, slots, or subcomponents) instead of adding many
  boolean props.
- Extend the relevant native HTML attributes and forward refs when useful.
- Reuse primitives from `src/shared/components/ui` before introducing another
  implementation.