@wealth-os/design-system

Standalone React component library and token package for WealthOS products. It provides typed, presentation-focused components, design tokens, and optional integrations for React applications.

Requirements

• React 19 and React DOM 19 or later
• TypeScript 5.8 or later for typed consumers
• Tailwind CSS 4 when using the package token and utility stylesheet

Installation

npm install @wealth-os/design-system

Import the host application's Tailwind stylesheet first, then the consumer-safe package stylesheet, then any host overrides. The package stylesheet contains its tokens, Tailwind theme mappings, component utilities, and type/layout utilities. It does not include Tailwind preflight or set document background, root sizing, global typography, or global focus rules.

/* app.css */
@import "tailwindcss";
@import "@wealth-os/design-system/styles.css";

/* Optional host-specific token overrides come after the package. */
:root { --primary: #0f766e; }

Import the package stylesheet once. Add @import "@wealth-os/design-system/reset.css"; only when you explicitly want WealthOS document defaults (canvas, text, font, and root minimum height). That optional file does not include preflight and does not set global focus styles. Do not import it when the host owns those values. @wealth-os/design-system/tokens.css exposes only canonical custom properties for non-Tailwind contexts; do not import it alongside styles.css because the package stylesheet already includes it.

Then import typed public components:

import "@wealth-os/design-system/styles.css";
import { Button, Field, TextInput, Surface, StatusBadge } from "@wealth-os/design-system";

export function ContactField() {
  return (
    <Surface className="p-5">
      <Field label="Contact email" help="Used for account updates.">
        <TextInput type="email" autoComplete="email" />
      </Field>
      <StatusBadge status="confirmed">Confirmed</StatusBadge>
      <Button className="mt-4">Save changes</Button>
    </Surface>
  );
}

The package exports compiled ESM, declaration files, the consumer-safe compiled stylesheet, optional document defaults, and the canonical token source. Do not import from src/ or from a private component file.

Public component families

• Actions: Button, IconButton, ButtonGroup, buttonVariants
• Fields: Field, TextInput, Textarea, NumberInput, MoneyInput, QuantityInput
• Choice and date controls: Select, SelectMenu, Combobox, Autocomplete, MultiSelect, SearchInput, Checkbox, RadioGroup, Switch, Slider, Toggle, ToggleGroup, SegmentedControl, DateInput, UsDateInput, DateRangePicker
• Form controls: Form, FormField, InputOTP, FileUpload
• Surfaces: Surface, Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter
• State: Badge, StatusBadge, Notice, ValidationMessage
• Tables and data display: Table anatomy, Avatar, AvatarGroup, DescriptionList, EmptyState, Skeleton, Progress, CircularProgress, Separator, ScrollArea, AspectRatio, Stat, MetricCard, Timeline, DataList, KeyValue
• Financial presentation (@wealth-os/design-system/financial): CurrencyValue, PercentageValue, ShareQuantity, FinancialMetric, EstimateIndicator, AllocationBar, FinancialDataTable, AssumptionNotice
• Utility: cn

Optional interaction families are available from @wealth-os/design-system/overlays (Radix-backed overlays), @wealth-os/design-system/navigation (tabs, breadcrumbs, pagination, navigation menu, and sidebar primitives), @wealth-os/design-system/command-menu (the cmdk command palette), and @wealth-os/design-system/forms (an optional React Hook Form register bridge). These subpaths keep optional integrations out of the core root entry.

The advanced table engine is isolated at @wealth-os/design-system/data-table. It uses TanStack Table v9 and is intentionally absent from the root JavaScript entry. See the data table guide for typed columns, controlled state, server-side modes, and accessibility behavior.

Charts are isolated at @wealth-os/design-system/charts and use Recharts 3.10.1. The root entry does not load the charting engine. See the charts guide for the typed API, data and accessibility contracts, compatibility notes, and examples.

The package keeps common components in the root entry and exposes heavier optional integrations through separate entry points. See components for the public API and charts and data tables for optional modules.

Documentation

• Layout composition recipes
• Token reference
• Component catalog and usage
• Accessibility contracts

Current limitations

• The package provides the light WealthOS theme. A dark palette has not been designed.
• The documentation examples use illustrative values and do not connect to accounts or financial engines.
• Examples in this package are illustrative; consuming applications remain responsible for data access, financial calculations, and product-specific rules.