@lexydesign/designsystem

The Lexy Design System — 37 React components built on Tailwind CSS v4, generated from Figma. Works in Vite, CRA, and Next.js App Router (all interactive components ship with "use client").

Install

npm install @lexydesign/designsystem
# peer deps (if not already in your app):
npm install react react-dom

Setup — pick ONE of two paths

Path A · Zero-config standalone CSS (recommended)

Works without Tailwind and is the safest for AI-assisted setups: there is no build-tool wiring to get wrong, so components can never silently render unstyled. Import one file, anywhere CSS is loaded (app entry, layout.tsx, main.tsx, …):

import "@lexydesign/designsystem/styles.css";

styles.css is fully compiled and self-contained. It ships every design token (as CSS variables) and a utility class for every token — not just the ones the components happen to use — plus the reset, base body, and .type-* typography helpers. So you can also use any token directly in your own markup, e.g. className="bg-subbrand-deudor text-accent-strong rounded-hero p-stack-md".

Path B · Tailwind v4 source (smallest CSS, requires Tailwind v4)

If your app already runs Tailwind v4 and you want the leanest possible output (only the utilities actually rendered), import the token layers and point Tailwind at our compiled JS instead of shipping the full styles.css:

@import "tailwindcss";
@import "@lexydesign/designsystem/tokens.css";   /* design tokens → @theme */
@import "@lexydesign/designsystem/globals.css";  /* optional: reset, base body, .type-* */

/* let Tailwind generate the utilities the components use */
@source "../node_modules/@lexydesign/designsystem/dist";

The @source line points Tailwind at our compiled JS so it can scan the class names we use and emit exactly those utilities. Adjust the relative path to your CSS file's location, and note that with pnpm or a monorepo the package may live in a hoisted/nested node_modules — point @source at wherever @lexydesign/designsystem/dist actually resolves. If components look unstyled, this path is almost always wrong; prefer Path A.

Fonts (both paths)

The CSS does not load remote webfonts. Load Geist in the consuming app with a <link> tag, next/font, or @fontsource/geist; otherwise --font-base falls back to system-ui, sans-serif. This avoids shipping a remote @import url() inside a distributed stylesheet, which can become invalid once your app concatenates CSS after Tailwind.

Usage

import { Button, Modal, Badge } from '@lexydesign/designsystem';

export function Example() {
  return (
    <div className="flex gap-2">
      <Button variant="primary">Save</Button>
      <Button variant="destructive" hierarchy="outline">Delete</Button>
      <Badge tone="green" variant="subtle">Active</Badge>
    </div>
  );
}

Compound components expose their parts as properties:

import { Modal } from '@lexydesign/designsystem';

<Modal open={open} onClose={close}>
  <Modal.Header title="Invite members" />
  <Modal.Body>…</Modal.Body>
  <Modal.Footer>
    <Button onClick={close}>Done</Button>
  </Modal.Footer>
</Modal>

Also exported: cn (class merge helper) and useFloating (anchored-popover positioning hook).

Components

Accordion · Avatar · Badge · Breadcrumb · Button · Checkbox · Combobox · CounterBadge · Divider · Dropdown · FeatureCard · HeaderBar · InfoLabel · Input · Logo · Menu · Modal · Nav · ProfileCard · ProgressBar · Radio · Searchbox · Skeleton · Slider · Snippet · StatusDot · Switch · Tabs · Tag · Textarea · Toast · Tooltip · Tree

Layout

Use the layout primitives instead of hand-rolling page chrome with raw Tailwind. They consume the grid tokens (--grid-*) defined in tokens.css and enforce the layout contract from Prompts/lexy-layout.md.

import { PageShell, Container, Grid, GridItem, Region } from '@lexydesign/designsystem';

<PageShell header={<AppHeader />} aside={<AppNav />}>
  <Container>
    <Grid columns={12}>
      <GridItem span={{ mobile: 'full', tablet: 'full', desktop: 8 }}>
        <Region role="content">
          <CaseSummary />
        </Region>
      </GridItem>
      <GridItem span={{ mobile: 'full', tablet: 'full', desktop: 4 }}>
        <Region as="aside" role="sidebar">
          <StatusPanel />
        </Region>
      </GridItem>
    </Grid>
  </Container>
</PageShell>

Components: Container (widths: container | content | readable | full), PageShell (header/aside/footer slots + page padding tokens), Grid (columns/columnsTablet/columnsMobile, gap, align), GridItem (span as number or { mobile, tablet, desktop }), Region (as + role: content | sidebar | toc | shell; toc auto-hides under 1440px).

For non-React markup, globals.css also ships .lexy-container, .lexy-grid (+ --dense/--loose), and .lexy-region-toc as a minimal CSS fallback.

What’s new in 0.5.0

• AI contract: ai/manifest.json, scenarios, and synced skills updated for all components; per-component GUIDELINES.md in Storybook.
• Forms: Radio.Group (controlled, label/error, orientation); Searchbox without double focus ring; Slider layout/showValue fixes and keyboard-only focus styling.
• Overlays & nav: Modal (portal, focus trap, sizes, header icons without circular bg); Nav compound API (Item, Group, Label, Separator).
• Polish: Tabs segmented control; Switch/StatusDot a11y; shared iconSize helpers.

If you are on npm 0.3.x, read the breaking migration below (tokens renamed in 0.4.0, still required in 0.5.0).

Migrating 0.3.x → 0.4.0+ (breaking: token rename)

Token and .type-* class names are now native Tailwind/shadcn. There are no legacy aliases — update class names when upgrading. Main mappings:

Colors (utility prefix unchanged, only the token segment changes):

• bg-surface-background → bg-background
• bg-surface → bg-card (overlays: bg-popover)
• bg-surface-background-muted → bg-muted; bg-surface-background-inverse → bg-background-inverse
• text-text-foreground → text-foreground; text-text-foreground-secondary → text-secondary-foreground
• text-text-foreground-muted → text-muted-foreground; text-text-foreground-subtle → text-foreground-subtle
• bg-surface-disabled → bg-disabled; text-text-foreground-disabled → text-disabled-foreground
• text-text-ink → text-ink; text-text-link → text-link
• bg-neutral-surface-muted → bg-secondary; bg-neutral-surface-subtle → bg-neutral-subtle
• *-status-danger* → *-destructive* (on-fill text: text-destructive-foreground = white; same-hue text on light: text-destructive-strong)
• *-status-success* / *-status-warning* / *-status-info* → *-success* / *-warning* / *-info* (drop status-); *-foreground-strong → *-foreground
• *-alpha-{primary,success,warning,danger,neutral}-alpha-{hover,pressed} → *-alpha-$1-$2 (drop the repeated -alpha-)
• New shadcn-parity tokens: card/popover(+-foreground), secondary-foreground, accent-foreground, destructive-foreground, ring, input.

Typography:

• type-baseline-{display,headline,title,body,label}-{large,medium,small} → type-{display,heading,title,body,label}-{lg,md,sm}
• type-emphasized-… → same name with a -strong suffix (e.g. type-heading-md-strong)
• Convenience: type-body = type-body-md

AI / agents

The package ships a compact, machine-consumable context surface under ai/ so AI agents can use the library reliably without reverse-engineering the source. Treat it like an OpenAPI contract for the package: load the contract first, resolve the API from the manifest, and pull deeper docs on demand.

Load order:

1. ai/AGENTS.md — concise contract: CSS setup, import, hard invariants, and a load-on-demand map. Always load this first.
2. ai/manifest.json — curated machine-readable API: components, props/variants, layout primitives, helpers, tokens, invariants and canonical flows.
3. On demand: ai/scenarios/*.md (canonical flows + edge cases) and ai/skills/*.md (full design rules; see ai/skills/index.md). For how to build good UI — general guidelines, best practices, component usage, states, motion, a11y, patterns, content, and an audit checklist (distilled from Material 3 + Fluent 2, adapted to Lexy) — start at ai/skills/guidelines/SKILL.md (hub + references/).

Consume the files from the installed package, e.g. node_modules/@lexydesign/designsystem/ai/AGENTS.md, or programmatically via the exports (@lexydesign/designsystem/ai/manifest.json, @lexydesign/designsystem/ai/scenarios/forms.md, …).

The large design context stays in the repo at /Prompts; npm run ai:sync (also part of npm run build) projects those skills verbatim into ai/skills/. When components, props or tokens change, update ai/manifest.json, ai/AGENTS.md and ai/scenarios/* (curated by hand) alongside the code.

Development

npm run storybook   # explore components
npm run css         # regenerate tokens.css/globals.css from figma-export.json
npm run css:full    # rebuild the standalone dist/styles.css (needs a prior build for dist/)
npm run ai:sync     # project /Prompts skills into ai/skills/ + regenerate index
npm run build       # full distributable build to dist/ (JS + types + all CSS) + ai/skills

npm run build runs, in order: token generation → vite build (per-component ESM

• .d.ts) → prepare-css (token layers for Path B) → build-full-css (the standalone styles.css for Path A, with a utility for every token) → ai:sync (refresh ai/skills/ from /Prompts).