Adding New UI Components

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• packages/ui/components.json
• packages/ui/package.json
• apps/dashboard/components.json
• packages/ui/src/components/tabs.tsx
• packages/ui/src/styles/globals.css

Introduction

The Subito project utilizes a monorepo architecture where UI components are centralized within a shared @subito/ui package. This design ensures visual consistency across different applications, such as the dashboard, by providing a single source of truth for design tokens, styles, and reusable React components. Sources: packages/ui/package.json, apps/dashboard/package.json

Components are primarily built using shadcn/ui, leveraging Tailwind CSS for styling and Radix-based primitives (via @base-ui/react) for accessibility and behavior. This wiki page outlines the workflow for adding, configuring, and consuming these components within the workspace. Sources: README.md:1-12, packages/ui/package.json:15-25

Component Architecture

The UI system is structured to separate global styles, utility functions, and individual component logic. Components are stored in the packages/ui/src/components directory and exported through the package's entry points. Sources: packages/ui/package.json:34-38

Dependency Stack

The UI package relies on several core libraries to manage component state and styling:

Dependency	Purpose
shadcn	CLI and base templates for UI components.
@base-ui/react	Headless primitives for complex components (e.g., Tabs).
tailwindcss	Utility-first CSS framework for styling.
class-variance-authority (CVA)	Managing component variants and class compositions.
tailwind-merge	Safely merging Tailwind classes without conflicts.

Sources: packages/ui/package.json:15-28

Styling System

Styling is driven by packages/ui/src/styles/globals.css, which defines the project's design tokens using CSS variables. It supports both light and dark modes through the .dark class and includes a custom @theme block for Tailwind configuration. Sources: packages/ui/src/styles/globals.css:1-120

The diagram shows how styles flow from global CSS definitions to specific application instances. Sources: packages/ui/src/styles/globals.css, apps/dashboard/app/layout.tsx:4-6

Workflow: Adding a Component

To add a new component from the shadcn registry, developers use the pnpm dlx command directed at the specific application context.

Command Execution

Run the following command from the root directory to add a component (e.g., a button):

pnpm dlx shadcn@latest add button -c apps/dashboard

Sources: README.md:7-11

Configuration (components.json)

The components.json file in packages/ui defines where the CLI should place and find files. Key aliases include:

• components: @subito/ui/components
• utils: @subito/ui/lib/utils
• ui: @subito/ui/components

Sources: packages/ui/components.json:10-18

Path Mapping and Integration

Components added to the shared package are automatically available to applications via TypeScript path mappings. Applications like dashboard map @subito/ui/* to ../../packages/ui/src/*. Sources: apps/dashboard/tsconfig.json:5-8

Component Implementation Pattern

New components should follow the existing implementation pattern seen in packages/ui/src/components/tabs.tsx. This includes:

1. Pruning Primitives: Importing from @base-ui/react or Radix.
2. Defining Variants: Using cva to define visual states (e.g., default vs line variants).
3. Utility Usage: Using cn() (tailwind-merge + clsx) for dynamic class names.
4. Client Directives: Using "use client" for components requiring interactivity.

Example: Tabs Implementation

The implementation uses class-variance-authority to handle the different visual styles of the Tabs component. Sources: packages/ui/src/components/tabs.tsx:23-44

Usage in Applications

Once added to packages/ui/src/components, a component can be imported into any application within the monorepo using its workspace alias. Sources: README.md:15-19

Code Snippet: Consuming a Component

import { Button } from "@subito/ui/components/button"

export default function Page() {
  return (
    <div>
      <Button>Subito Action</Button>
    </div>
  )
}

Sources: apps/dashboard/app/page.tsx:1-15

Conclusion

Adding new UI components to the Subito project involves utilizing the shadcn CLI to populate the shared @subito/ui package. By maintaining a centralized component library with standardized styling through globals.css and consistent implementation patterns (CVA + Base UI), the project ensures scalability and design integrity across the entire workspace.