Components

This document provides complete technical documentation and implementation details for @celestia-project/ui, including installation, color system tokens, import conventions, component module mappings, sub-component exports, underlying primitives, and prop APIs.

All components live in packages/ui/src/components and are imported via the @celestia-project/ui package alias. Every component is built on Base UI primitives, styled with Tailwind CSS, and supports the className prop for overrides. Icons come from @phosphor-icons/react.

Installation

The @celestia-project/ui package is already a workspace dependency. To add a new shadcn/ui component to the shared library:

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

Colors

The design system uses two layers of Celestia color tokens: landing tokens (forced dark theme) and semantic tokens (light/dark theme support).

Landing Tokens

These tokens are always dark and used exclusively on the landing page. They're defined in packages/ui/src/styles/globals.css.

Brand Accent

The brand accent is tokenized — consume it with utilities, never with hex literals:

Gradient: linear-gradient(90deg, hsl(var(--brand)) 0%, hsl(var(--brand-deep)) 100%) — defined as the .accent-gradient class in apps/web/app/landing.css (landing-scoped, not part of the package styles).

Semantic Tokens

These tokens power the app-shell components (dashboard, forms, dialogs) and support both light and dark themes via the .dark class.

Light Theme (:root)

Dark Theme (.dark)

Chart Colors

Charts use a dedicated palette defined by --chart-1 through --chart-5 tokens. These are grayscale values that work in both light and dark themes.

Import Conventions

The @celestia-project/ui library supports both barrel imports and deep imports.

1. Styles & CSS Variables

Choose the integration method based on whether the consuming project already configures Tailwind CSS v4:

Option A: Quickstart (Standalone or new apps)

Import the global stylesheet once in your top-level application file (app/layout.tsx or pages/_app.tsx / main.tsx):

import "@celestia-project/ui/globals.css"

This stylesheet injects Tailwind CSS v4, tw-animate-css, shadcn base styles, and oklch theme variables (light + dark mode).

Option B: Existing Tailwind v4 Apps (@source directive)

In existing Tailwind v4 applications that define their own CSS variables, color palettes, or @theme blocks, do not import @celestia-project/ui/globals.css directly. Doing so can cause duplicate utility injection or overwrite app-level theme variables.

Instead, add the @source directive in your project's main stylesheet (e.g. src/styles/globals.css):

@import "tailwindcss";
/* 1. Instruct Tailwind to scan the UI package for used class names */@source "../../node_modules/@celestia-project/ui";@source "../**";
@custom-variant dark (&:is(.dark *));
/* 2. Map shadcn & Celestia design tokens to Tailwind theme utilities */@theme inline {  --color-background: var(--background);  --color-foreground: var(--foreground);  --color-card: var(--card);  --color-card-foreground: var(--card-foreground);  --color-popover: var(--popover);  --color-popover-foreground: var(--popover-foreground);  --color-primary: var(--primary);  --color-primary-foreground: var(--primary-foreground);  --color-secondary: var(--secondary);  --color-secondary-foreground: var(--secondary-foreground);  --color-muted: var(--muted);  --color-muted-foreground: var(--muted-foreground);  --color-accent: var(--accent);  --color-accent-foreground: var(--accent-foreground);  --color-destructive: var(--destructive);  --color-destructive-foreground: var(--destructive-foreground);  --color-border: var(--border);  --color-input: var(--input);  --color-ring: var(--ring);
  --radius-sm: calc(var(--radius) - 4px);  --radius-md: calc(var(--radius) - 2px);  --radius-lg: var(--radius);  --radius-xl: calc(var(--radius) + 4px);  --radius-2xl: calc(var(--radius) * 1.8);  --radius-3xl: calc(var(--radius) * 2.2);  --radius-4xl: calc(var(--radius) * 2.6);
  /* Celestia UI tokens & motion */  --color-bg: hsl(var(--bg, 0 0% 4%));  --color-surface: hsl(var(--surface, 0 0% 8%));  --color-text-primary: hsl(var(--text, 0 0% 96%));  --color-fog: hsl(0 0% 53%);  --color-stroke: hsl(var(--stroke, 0 0% 15%));
  --ease-out: cubic-bezier(0.23, 1, 0.32, 1);  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);  --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
  --animate-scroll-down: scroll-down 1.5s ease-in-out infinite;  --animate-role-fade-in: role-fade-in 0.4s cubic-bezier(0.23, 1, 0.32, 1) both;  --animate-gradient-shift: gradient-shift 6s ease infinite;
  @keyframes scroll-down {    0% { transform: translateY(-100%); }    100% { transform: translateY(200%); }  }
  @keyframes role-fade-in {    from { opacity: 0; transform: translateY(8px) scale(0.98); }    to { opacity: 1; transform: translateY(0) scale(1); }  }
  @keyframes gradient-shift {    0% { background-position: 0% 50%; }    50% { background-position: 100% 50%; }    100% { background-position: 0% 50%; }  }}

2. Barrel Imports (Recommended)

Barrel imports pull from the package root. All components are tree-shakeable in modern bundlers (Next.js, Vite).

import {  Button,  Card,  CardHeader,  CardTitle,  CardContent,  Dialog,  DialogTrigger,  DialogContent,  cn} from "@celestia-project/ui"

Note on Toast Collisions: Both Base UI Toast and Sonner provide toaster components. In the root barrel export:

• Base UI Toast / Toaster is exported as Toast / Toaster.
• Sonner Toaster is exported as SonnerToaster.

3. Deep Imports

For strict bundle-size optimizations or non-bundler environments, import directly from the module paths:

import { Button } from "@celestia-project/ui/primitive/button"import { Card, CardHeader, CardTitle, CardContent } from "@celestia-project/ui/primitive/card"import { Dialog, DialogContent, DialogTrigger } from "@celestia-project/ui/primitive/dialog"import { useIsMobile } from "@celestia-project/ui/hooks/use-mobile"import { cn } from "@celestia-project/ui/lib/utils"

4. Utilities & Hooks

Component Mapping Reference

Below is the complete mapping of every component module — 153 files across primitive/, composite/ and ai/ in packages/ui/src/components/, plus the 32 page templates shipped as copy sources under apps/web/components/layout-templates/ — listing their deep import specifiers, exported sub-components, and underlying base primitives.

Layout & Structure

The layout family is the page-level layer — 36 members: four slot-only shells (package composites) and 32 page templates shipped as copy sources under apps/web/components/layout-templates/, grouped below. The shells own the frame (centred/split for auth, rail + header + content for the signed-in app, a full-viewport frame for status screens, and a nav + footer frame for public pages), and thin page components supply their own fields and defaults on top of a shell.

Two rules hold across the whole family. A page that sits inside a shell never draws its own chrome — LandingPage renders the hero and the content bands and expects MarketingShell around it, and every *Page on PageShell inherits the blurred sticky header rather than repeating it. A page that owns a document shape instead sets its own height: InvoicePage and ReportsPage are natural-height, because a document that flexes to fill the viewport pushes its totals block up under an overflowing table and the two paint on top of each other.

State is split deliberately. Anything that belongs in the URL — SearchPage's query and facets, BlogIndexPage's category, InboxPage's selected message — is controlled and passed in. Anything purely internal — PricingPage's billing toggle, OnboardingPage's step, IntegrationsPage's connection state — is uncontrolled and owned by the component. That way a consumer never has to mirror state they do not route on.

The page templates are documented as a family in Templates. Unlike the primitives, they ship as copy templates — plain source files under apps/web/components/layout-templates/ rather than package exports; the four slot-only shells they compose on (AuthShell, PageShell, DashboardShell, MarketingShell) are package composites. Preview any of them at /layout and copy the source straight into an app.

Shells vs. pages

DashboardShell is deliberately slot-based rather than opinionated about navigation — nav takes whatever list the consumer already has, so it can back an existing route group without rewriting its navigation. SettingsPage keeps every panel mounted and hides the inactive ones, so unsaved input survives a section switch.

ListPage owns layout and selection state but never filters, sorts or paginates rows — that stays with whoever owns the data, so there is only ever one source of truth for what a given page contains. BillingPage follows the same rule for money: it renders the figures you pass and never derives a prorated amount or a renewal date, because being subtly wrong about a charge is worse than not showing it.

Typography & Display

Forms & Inputs

Overlays & Popups

Navigation

Data & Media

Content & Block Editor

Two editors ship in the composite family: a Monaco-backed source editor and the block-based text editor used by the CMS features — a compound component whose sections, drag helpers, and formatter live in one module directory.

AI & Chat Development (@celestia-project/ui/ai & @celestia-project/ui)

Comprehensive suite of 54 AI development primitives, interactive elements, streaming displays, and agent tools.

Feedback & Utilities

Key Component Props Reference

1. Button (button.tsx)

import { Button } from "@celestia-project/ui/primitive/button"

2. Badge (badge.tsx)

import { Badge } from "@celestia-project/ui/primitive/badge"

3. Card (card.tsx)

import { Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter } from "@celestia-project/ui/primitive/card"

4. Dialog & Sheet (dialog.tsx, sheet.tsx)

import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription } from "@celestia-project/ui/primitive/dialog"import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle } from "@celestia-project/ui/primitive/sheet"

5. Sidebar (sidebar.tsx)

import { SidebarProvider, Sidebar, SidebarHeader, SidebarContent, SidebarGroup, SidebarMenu, SidebarMenuItem, SidebarMenuButton } from "@celestia-project/ui/composite/sidebar"

6. Select (select.tsx)

import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from "@celestia-project/ui/primitive/select"

7. Attachment & Chat (attachment.tsx, message.tsx, bubble.tsx)

import { Attachment, AttachmentMedia, AttachmentContent, AttachmentTitle, AttachmentDescription } from "@celestia-project/ui/composite/attachment"