Architecture Overview

Understanding the structure and decision-making framework

Functional Organization

Components Organized by Purpose, Not Hierarchy

This system organizes components by what they do, not by abstract hierarchy. This eliminates classification ambiguity and improves developer discoverability.

Actions (3)

Interactive elements that trigger behaviors

Button, Toggle, ToggleGroup

Forms (11)

Input controls for data collection with validation

Input, Select, Checkbox, Switch, Slider, Label...

Navigation (6)

Moving through content hierarchy and app structure

Breadcrumb, Tabs, Pagination, Command...

Overlays (9)

Contextual content that appears above main UI

Dialog, Sheet, Popover, Tooltip, Drawer...

Feedback (5)

Communicating system state and user action results

Alert, Toast, Progress, Skeleton, Sonner

Data Display (6)

Presenting information in structured formats

Table, DataTable, Card, Avatar, Badge, Calendar

Layout (8)

Spatial organization and structural elements

Accordion, Carousel, ScrollArea, Separator...

Why functional organization? Modern design systems (shadcn/ui, Material UI, Radix, Chakra) have moved away from atomic design. Developers think "I need a form input" not "I need an atom." This approach eliminates classification ambiguity and maps to real development workflows.

Choosing the Right Category

Actions, Forms & Navigation

Actions:

Use when the component's primary purpose is to trigger a behavior or state change. Examples: Button (triggers action), Toggle (binary state), ToggleGroup (multiple toggles).

Forms:

Use for any data input or collection component. Includes validation and form integration. Examples: Input, Select, Checkbox, RadioGroup, Slider, Form wrapper.

Navigation:

Use when helping users understand location or move through content hierarchy. Examples: Breadcrumb, Tabs, Pagination, Command palette.

Overlays, Feedback & Display

Overlays:

Use for contextual content that appears above the main UI without interrupting flow. Examples: Dialog, Popover, Tooltip, Sheet, Drawer.

Feedback:

Use to communicate system state or results of user actions. Examples: Alert, Toast, Progress, Skeleton loaders.

Data Display & Layout:

Data Display: presenting information (Table, Card, Avatar). Layout: organizing content spatially (Accordion, Carousel, ScrollArea).

Gray areas? Some components could fit multiple categories. Use the primary purpose rule: SearchBar is in Forms(primary purpose: collect input) not Navigation, even though it aids navigation.

Naming Conventions

Component Names

  • PascalCase for component names
  • kebab-case for file names
  • Descriptive, action-oriented names

File Organization

  • One component per file
  • Co-locate types with components
  • Group related components in folders

Tech Stack

Core Framework

React 19— UI library with hooks and concurrent features
TypeScript— Type safety and developer experience

Styling & Animation

Tailwind CSS— Utility-first styling
Framer Motion— Declarative animations with accessibility

State Management

Zustand— Lightweight global state management

Build & Bundle

tsup— Fast TypeScript bundler
Turborepo— Monorepo build system

Design Token System

Design tokens are the single source of truth for all visual values. They cascade through themes to ensure consistency.

Token Categories

  • Colors: Brand, semantic, surface, and text colors
  • Typography: Font families, sizes, weights, line heights
  • Spacing: Margin, padding, and gap scales
  • Motion: Animation durations and easing functions

How Tokens Cascade

1. Define in TypeScript
   tokens/studio/colors.ts

2. Export as CSS variables
   themes/studio.css

3. Consume in components
   var(--color-primary)

4. Switch themes at runtime
   setTheme('terra')