dev-rcfa-memory/fe-digitaltwin-v2/prompts/design-system.md

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.