You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
51 lines
2.2 KiB
Markdown
51 lines
2.2 KiB
Markdown
# 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.
|