Adding Components

Step-by-step workflows for extending the design system

MethodologyAdding ComponentsModifyingAdding TokensEjectingTroubleshooting

Core Methodology

Do Not Skip Steps

Creating a .tsx file is only 20% of the work. A component is not "done" until it is fully documented, exported, and showcased in the Studio. Incomplete components cause build failures and confusion.

  1. 1

    Create the Component

    Build the component in packages/ui/src/components/[category]/ where [category] is one of: actions, forms, navigation, overlays, feedback, data-display, or layout. Use the React 19 ref-as-prop pattern (no forwardRef needed) and properly type its props.

  2. 2

    Export the Component

    Add exports to both the category index packages/ui/src/components/[category]/index.ts and the main barrel packages/ui/src/index.ts.

    // 1. In packages/ui/src/components/[category]/index.ts:
export * from './ComponentName';

// 2. In packages/ui/src/index.ts:
export * from './components/[category]/ComponentName';
  3. 3

    Build the Design System

    You MUST rebuild the package for the Studio app to see the new component. The Studio consumes the built version of the library, not the raw source.

    pnpm --filter @thesage/ui build
  4. 4

    Update Navigation & Routing

    Ensure the component is accessible via the sidebar and has correct breadcrumbs:

    A. Add to Navigation: Update apps/web/app/components/studio/ComponentsSection/index.tsx in the appropriate functional category.

    // In COMPONENT_CATEGORIES object
[category]: {
  label: 'Category Label',
  description: 'Category description',
  components

    B. Choose Functional Category: Select based on primary purpose: actions, forms, navigation, overlays, feedback, data-display, or layout.

    // Examples of category selection:
// - Button → actions (triggers behavior)
// - Input → forms (collects data)
// - Dialog → overlays (contextual content)
  5. 5

    Register in Studio

    Add the component configuration to apps/web/app/components/lib/component-registry.tsx. This powers the documentation page.

    • Define props controls (select, boolean, text)
    • Add usage examples
    • Add "Preview" and "Customize" sections via the registry config