rialto

name	rialto
description	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.

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 overrides
• ToastProvider — required before calling useToast()

6 Cardinal Rules

1. Tokens only — Never hardcode colors, spacing, radii, or easing. Always var(--rialto-*).
2. Gold is surgical — --rialto-accent only for focus rings, active/selected states, primary button fills. Never decorative.
3. forwardRef always — Every component uses React.forwardRef. New components must too.
4. Respect reduced motion — Check useReducedMotion() from Framer Motion. Skip animation when true.
5. Logical properties — Use margin-inline-start, padding-inline-end, inset-inline-start — never left/right.
6. 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