Rialto Design System
Rialto is a 62-component React design system with warm-neutral aluminum surfaces, gold accent, spring-physics motion, and CSS token architecture. Import everything from the barrel:
import { Button, Input, Card, Stack, Text } from "rialto";
import "rialto/tokens";
Required Providers
<RialtoProvider vibe="default" theme="system">
<ToastProvider>
<App />
</ToastProvider>
</RialtoProvider>
RialtoProvider — device context, theming, vibe token overridesToastProvider — required before calling useToast()
6 Cardinal Rules
- Tokens only — Never hardcode colors, spacing, radii, or easing. Always
var(--rialto-*).
- Gold is surgical —
--rialto-accent only for focus rings, active/selected states, primary button fills. Never decorative.
- forwardRef always — Every component uses
React.forwardRef. New components must too.
- Respect reduced motion — Check
useReducedMotion() from Framer Motion. Skip animation when true.
- Logical properties — Use
margin-inline-start, padding-inline-end, inset-inline-start — never left/right.
- Barrel imports — Always
import { X } from "rialto". Never import X from "rialto/components/X".
Component Selection
Full details: decision-trees.md
| Need |
Start Here |
| Form input |
Decision tree → Input, TextArea, NumberInput, Select, Toggle, etc. |
| Overlay |
Dialog, ConfirmDialog, Drawer, Popover, Tooltip, HoverCard |
| Feedback |
Priority routing: P1 ConfirmDialog → P2 Dialog → P3 Banner → P4 Alert → P5 Toast → P6 Tooltip |
| Navigation |
Tabs, Breadcrumb, Steps, Pagination, Sidebar, Navbar |
| Data display |
Table, Card, Badge, Tag, Stat, DataList, Timeline, Tree |
| Layout |
Stack, Divider, Collapsible, Accordion, ScrollArea |
Composition
Full details: composition-patterns.md
| Pattern |
Components |
| Data table page |
Table + Pagination + Stack |
| Login form |
Card + Stack + Input + Button |
| Settings panel |
Drawer + Stack + Toggle + Select + Divider |
| Confirmation flow |
ConfirmDialog (variant="danger") |
| Toast notifications |
ToastProvider + useToast() hook |
Tokens
Full details: token-enforcement.md
| Category |
Prefix |
Example |
| Surfaces |
--rialto-surface-* |
--rialto-surface-elevated |
| Text |
--rialto-text-* |
--rialto-text-secondary |
| Borders |
--rialto-border* |
--rialto-border-strong |
| Accent |
--rialto-accent* |
--rialto-accent-muted |
| Semantic |
--rialto-error*, --rialto-success* |
--rialto-error-muted |
| Shadows |
--rialto-shadow-* |
--rialto-shadow-elevated |
| Radius |
--rialto-radius-* |
--rialto-radius-soft |
| Spacing |
--rialto-space-* |
--rialto-space-lg |
| Easing |
--rialto-ease-* |
--rialto-ease-precision |
Icons
Full details: icon-vocabulary.md
Use Lucide React icons. Import directly or use getIcon(concept) for data-driven UIs. Sizes: 14px (sm buttons), 16px (md buttons), 20px (standalone), 32-48px (hero/empty state).
Authoring New Components
Full details: authoring-guide.md
File structure: src/components/Name/Name.tsx + Name.module.css. Extend native HTML props, use forwardRef, CSS Modules with token variables, all states (hover/active/focus/disabled), WCAG AA contrast.
Common Mistakes
Full details: common-mistakes.md
- Hardcoding
#hex colors instead of tokens
- Importing from
"rialto/components/Button" instead of "rialto"
- Using gold accent for decorative backgrounds
- Calling
useToast() without <ToastProvider>
- Using CSS transitions for interactive animations (use Framer Motion)
- Skipping
useReducedMotion() check before animating
Auto-Generated Reference
For complete per-component props, slots, and character limits, see the generated reference:
component-reference.md
1---2name: rialto3description: Use when building UI with the Rialto design system, importing from "rialto" or "@mattbutlerengineering/rialto", choosing components, applying design tokens, composing layouts, or authoring new Rialto components. Triggers on mentions of "Rialto", "component library", "design system", "UI component", or imports from rialto.4---5
6# Rialto Design System
7
8Rialto is a 62-component React design system with warm-neutral aluminum surfaces, gold accent, spring-physics motion, and CSS token architecture. Import everything from the barrel:
9
10```tsx
11import { Button, Input, Card, Stack, Text } from "rialto";
12import "rialto/tokens";
13```
14
15## Required Providers
16
17```tsx
18<RialtoProvider vibe="default" theme="system">
19 <ToastProvider>
20 <App />
21 </ToastProvider>
22</RialtoProvider>
23```
24
25- `RialtoProvider` — device context, theming, vibe token overrides
26- `ToastProvider` — required before calling `useToast()`
27
28## 6 Cardinal Rules
29
301. **Tokens only** — Never hardcode colors, spacing, radii, or easing. Always `var(--rialto-*)`.
312. **Gold is surgical** — `--rialto-accent` only for focus rings, active/selected states, primary button fills. Never decorative.
323. **forwardRef always** — Every component uses `React.forwardRef`. New components must too.
334. **Respect reduced motion** — Check `useReducedMotion()` from Framer Motion. Skip animation when true.
345. **Logical properties** — Use `margin-inline-start`, `padding-inline-end`, `inset-inline-start` — never `left`/`right`.
356. **Barrel imports** — Always `import { X } from "rialto"`. Never `import X from "rialto/components/X"`.
36
37## Component Selection
38
39> Full details: [decision-trees.md](references/decision-trees.md)
40
41| Need | Start Here |
42|------|-----------|
43| Form input | Decision tree → Input, TextArea, NumberInput, Select, Toggle, etc. |
44| Overlay | Dialog, ConfirmDialog, Drawer, Popover, Tooltip, HoverCard |
45| Feedback | Priority routing: P1 ConfirmDialog → P2 Dialog → P3 Banner → P4 Alert → P5 Toast → P6 Tooltip |
46| Navigation | Tabs, Breadcrumb, Steps, Pagination, Sidebar, Navbar |
47| Data display | Table, Card, Badge, Tag, Stat, DataList, Timeline, Tree |
48| Layout | Stack, Divider, Collapsible, Accordion, ScrollArea |
49
50## Composition
51
52> Full details: [composition-patterns.md](references/composition-patterns.md)
53
54| Pattern | Components |
55|---------|-----------|
56| Data table page | Table + Pagination + Stack |
57| Login form | Card + Stack + Input + Button |
58| Settings panel | Drawer + Stack + Toggle + Select + Divider |
59| Confirmation flow | ConfirmDialog (variant="danger") |
60| Toast notifications | ToastProvider + useToast() hook |
61
62## Tokens
63
64> Full details: [token-enforcement.md](references/token-enforcement.md)
65
66| Category | Prefix | Example |
67|----------|--------|---------|
68| Surfaces | `--rialto-surface-*` | `--rialto-surface-elevated` |
69| Text | `--rialto-text-*` | `--rialto-text-secondary` |
70| Borders | `--rialto-border*` | `--rialto-border-strong` |
71| Accent | `--rialto-accent*` | `--rialto-accent-muted` |
72| Semantic | `--rialto-error*`, `--rialto-success*` | `--rialto-error-muted` |
73| Shadows | `--rialto-shadow-*` | `--rialto-shadow-elevated` |
74| Radius | `--rialto-radius-*` | `--rialto-radius-soft` |
75| Spacing | `--rialto-space-*` | `--rialto-space-lg` |
76| Easing | `--rialto-ease-*` | `--rialto-ease-precision` |
77
78## Icons
79
80> Full details: [icon-vocabulary.md](references/icon-vocabulary.md)
81
82Use Lucide React icons. Import directly or use `getIcon(concept)` for data-driven UIs. Sizes: 14px (sm buttons), 16px (md buttons), 20px (standalone), 32-48px (hero/empty state).
83
84## Authoring New Components
85
86> Full details: [authoring-guide.md](references/authoring-guide.md)
87
88File structure: `src/components/Name/Name.tsx` + `Name.module.css`. Extend native HTML props, use `forwardRef`, CSS Modules with token variables, all states (hover/active/focus/disabled), WCAG AA contrast.
89
90## Common Mistakes
91
92> Full details: [common-mistakes.md](references/common-mistakes.md)
93
94- Hardcoding `#hex` colors instead of tokens
95- Importing from `"rialto/components/Button"` instead of `"rialto"`
96- Using gold accent for decorative backgrounds
97- Calling `useToast()` without `<ToastProvider>`
98- Using CSS transitions for interactive animations (use Framer Motion)
99- Skipping `useReducedMotion()` check before animating
100
101## Auto-Generated Reference
102
103For complete per-component props, slots, and character limits, see the generated reference:
104[component-reference.md](../../generated/component-reference.md)
aibot88