@tlouverse/ui

Shared UI primitives and shared interaction patterns for Tlouverse apps.

Foundation

This package standardizes on shadcn-style primitives built on top of Radix UI, then applies the Tlouverse design tokens and rules on top. It does not use Base UI. If an app currently uses Base UI wrappers, treat that as migration work, not as the reference implementation for this package.

Scope

This package exports reusable primitives and domain-agnostic composed interaction patterns:

• Button
• Badge
• Breadcrumb
• Calendar
• Card
• Chart
• ContextMenu
• DataTable
• DatePicker
• Drawer
• DropdownMenu
• Form
• Input
• Label
• LaunchCard
• Pagination
• Popover
• Progress
• ProgressBar
• Select
• Separator
• Switch
• Toaster
• Table
• Textarea
• Tooltip
• Tabs
• Typography

It should not contain app chrome or feature components such as headers, nav bars, dashboards, cards tied to a specific product domain, or page-level shells. It can contain shared semantic components when they represent the same interaction pattern across multiple apps.

Install

npm install @tlouverse/ui

Usage

Import the package stylesheet once from your app entry CSS:

@import "@tlouverse/ui/styles";

Then consume primitives from TypeScript:

import { Button, Card, LaunchCard, Toaster, Typography, toast } from "@tlouverse/ui";

Mount Toaster once near the app root, then call toast(...) from anywhere in client code.

LaunchCard

LaunchCard is the shared semantic pattern for app and tool launch grids. It composes the package Card and Typography primitives so hover, disabled, title, description, and status-label behavior stay consistent across apps.

Use Card when you only need a neutral container. Use LaunchCard when the UI represents a navigable or disabled launch surface in a grid or directory.

Example:

<LaunchCard
  icon={<Key className="size-4" />}
  title="Auth"
  description="Identity and access management"
/>

<LaunchCard
  icon={<Bot className="size-4" />}
  title="Automation"
  description="Background workflows and agent jobs"
  statusLabel="Soon"
  disabled
/>

Styles

The main stylesheet export includes:

• the Inter Variable font import
• Tailwind v4 theme tokens
• baseline global styles
• typography defaults for the document body

Additional style entrypoints are also exported when an app needs finer control:

• @tlouverse/ui/styles/fonts.css
• @tlouverse/ui/styles/theme.css
• @tlouverse/ui/styles/typography.css

@tlouverse/ui/styles/tokens.css is kept as a compatibility alias for the theme layer.

Typography

Typography is organized around design roles rather than HTML tag names. Available variants:

• display
• lead
• pageTitle
• sectionTitle
• cardTitle
• body
• muted
• description
• eyebrow
• subLabel
• small

Example:

<Typography variant="eyebrow">Kana</Typography>
<Typography variant="pageTitle">Quiz setup</Typography>
<Typography variant="muted">Choose the character set to practice.</Typography>

Development

npm run typecheck
npm run build

For package maintenance rules and the update workflow, see MAINTAINING.md.