@insidefi-ui/design-system

A from-scratch React + TypeScript component library built on Tailwind CSS v4, driven entirely by the design tokens in src/tokens/tokens.json and the structure of the Insidefi Design System Figma export. No pre-built UI kit (Radix, MUI, shadcn, Headless UI, etc.) is used — every component is hand-built on Tailwind utilities generated from the tokens.

Installation

Published as a private package under the @insidefi scope — authenticate to the org's npm registry first, then:

npm install @insidefi-ui/design-system

react and react-dom (>= 18) are peer dependencies; install them alongside.

Usage

Import the stylesheet once at your app's entry point:

// e.g. app/layout.tsx or main.tsx
import "@insidefi-ui/design-system/styles.css";

Then use components anywhere:

import { Button, Card, CardTitle } from "@insidefi-ui/design-system";

export function Example() {
  return (
    <Card>
      <CardTitle>Billing</CardTitle>
      <Button variant="primary" size="md">
        Save changes
      </Button>
    </Card>
  );
}

The stylesheet is pre-built — consumers do not need Tailwind installed. It ships every design token (--bg-base, --text-primary, …) plus the utility classes the components use, and sets color-scheme: dark on :root.

Typed tokens, the cn() class-merge helper, and the icon set are exported too:

import { tokens, cn, icons } from "@insidefi-ui/design-system";

The package is ESM-only ("type": "module"). Consumers on CommonJS need a bundler or a dynamic import().

Stack

• Vite (library build + Storybook builder)
• React 19 + TypeScript (strict)
• Tailwind CSS v4 (CSS-first @theme, no tailwind.config.js)
• Storybook 8 (@storybook/react-vite) for docs + interactive playgrounds

The token pipeline (single source of truth)

scripts/generate-theme.mjs parses src/tokens/tokens.json and emits two files (re-run automatically before dev, build, and storybook):

| Output | Purpose | | --- | --- | | src/styles/theme.generated.css | Tailwind v4 @theme block + @utility layer + component/layout CSS vars | | src/tokens/tokens.ts | Typed, tree-shakeable token objects for programmatic use |

How tokens map to utilities

| Token group (in tokens.json) | Emitted as | Example utility | | --- | --- | --- | | primitives color-* | --color-* | bg-navy-950, text-blue-500 | | primitives space-s-* / size-* | --spacing-* | p-s-4, h-control-h-md, w-modal-md | | primitives radius-r-* | --radius-* | rounded-md, rounded-pill | | primitives typography-size-fs-* | --text-* | text-fs-14 | | primitives typography-line-height-* | --leading-* | leading-lh-tight-fs-14 | | primitives typography-letter-spacing-* | --tracking-* | tracking-ls-normal-fs-14 | | primitives typography-weight-fw-* | --font-weight-* | font-bold | | primitives typography-family-f-* | --font-* | font-sans, font-mono | | primitives layout-breakpoint-* | --breakpoint-* | tablet:, wide: | | primitives z-* / border-width-bw-* | @utility | z-modal, border-bw-1 | | semantic.mode-1 bg-* / text-* / border-* | @utility (role-scoped) | bg-surface, text-brand, border-success | | semantic.mode-1 radius-* | --radius-* | rounded-card | | semantic.mode-1 heat-* / role-* / source-* | --color-* | bg-source-google, text-role-admin | | component.{desktop,tablet,wide} | --c-* CSS vars (responsive via @media) | var(--c-button-primary-button-bg) | | layout.{...} | --layout-<bp>-* CSS vars | var(--layout-desktop-padding-page-x) |

Why @utility for semantic colors? In Tailwind v4 the bg-/text-/border- prefixes all draw from a single --color-* namespace, but the semantic tokens are role-scoped (bg-brand = #3d8fff while text-brand = #5bb3ff), so they can't collapse into one color. Custom @utility rules preserve the exact bg-surface / text-brand API the design system expects.

Scripts

npm run tokens          # regenerate theme.generated.css + tokens.ts
npm run storybook       # regenerate tokens, then Storybook on :6006
npm run build-storybook # static Storybook build
npm run build           # library build (dist/) + .d.ts types
npm run typecheck       # tsc --noEmit

Components (~80 exported, full pass)

• Actions — Button, FAB, FabBar
• Forms — Input, Field, Textarea, Select, Checkbox, Radio/RadioGroup, Switch, NumberInput, Slider, TokenInput, Combobox, Dropzone/FileRow, OTPInput, PhoneInput, Calendar, DatePicker, DateRangePicker, TimePicker, ToggleGroup, Rating, ColorPicker, InlineEdit, FormSection/FormRow, SaveBar, Wizard
• Feedback — Spinner, LoadingOverlay, InlineAlert, Tag, Chip, StatusPill, PlanPill, HealthDot, Progress, UsageQuota, TrialBanner, LockCard/LockInline, UpgradeCard, Skeleton (+ Table/Card/Chart presets)
• Data display — CountBadge/LabelBadge/BadgeAnchor, Avatar/AvatarGroup, Tooltip, Menu/MenuItem/Kbd, KPITile, DataTable/TableEntity, DescriptionList, Pagination, CodeInline/CodeBlock, Sparkline, VarToken, SourceDot, Divider
• App shell — NavRail/NavApp/NavItem, Topbar, PageHeader, SubNav, SectionHeader, Toolbar, PageFooter, Card, Tabs
• Overlays — Modal, ConfirmDialog, AlertDialog, Drawer, Toast/ToastProvider/useToast, Banner, EmptyState, Popover, HoverCard, ContextMenu, CommandPalette, BottomSheet
• Domain — ActivityItem/Feed, Breadcrumb, ListRow/RowStat/ComplianceIcon, IntegrationCard, PlanCard, SeatStrip, AIInsightCard, DrillRow, ProjectMark/PageThumbnail, UTMChip, QuizStep/QuizAnswer, FilterBar
• Charts (pure SVG) — ChartCard, BarChart, LineChart, StackedBarChart, DonutChart, FunnelChart, Heatmap, CalendarChart, FunnelStage(s)
• Edge states — EdgePage (404 / 500 / empty / denied / session / offline / maintenance)
• Docs — Foundations/Tokens (live token swatches) and Foundations/Guidelines (number formatting, empty-cell, usage rules, a11y, motion, iconography)

Reference tooling: node scripts/extract-section.mjs <id|--list> prints any showcase section's markup + CSS from the original Figma export for 1:1 comparison.