# components/

Component layers in this project.

```
ui/          shadcn primitives — token-driven, reskinnable per design system
forms/       composed form widgets
data/        data display (tables, filters, empty states)
layout/      app shell, page chrome, navigation wrappers
marketing/   landing and marketing blocks
[system]/    design-system-specific components (e.g. m3/, apple/)
```

## The one rule

**Custom components import *from* `ui/`, never the reverse.**

`ui/` is the primitive layer. It must stay reskinnable by swapping tokens in
`app/themes/*.css` alone. If a component can't be expressed that way (M3
ripple, Apple segmented control, etc.), it belongs in a system-specific
folder — not `ui/` and not the shared folders above.

## Tokens, not values

Every custom component should reference semantic tokens:

- Colors: `bg-primary`, `text-muted-foreground`, `border-border`
- Radius: `rounded-md`, `rounded-lg`
- Fonts: `font-sans`, `font-heading`

Hardcoded hex, oklch, or px values are a bug — they break theming.