Pattern UI

Pattern UI (@patterninc/pattern-ui) is the Pattern component library: React 19 components, semantic color tokens, and icons built with Tailwind CSS v4. It is the UI foundation for Pattern EXP apps (Pi, Oly, Toggle, and apps moving off @patterninc/react-ui).

Source lives in lib/pattern-ui. Component docs and interaction tests run in Storybook.

Install

The package is public on npm as @patterninc/pattern-ui.

In this monorepo, keep the workspace protocol so apps always use the local package:

"@patterninc/pattern-ui": "workspace:*"

In any other repository, depend on the latest dist-tag. CI publishes a prerelease on every merge to main that touches lib/pattern-ui (0.0.0-main.<YYYYMMDDHHMM>.<sha>) and moves latest. Git stays at 0.0.1. We're not doing semver, so there's no API backwards-compatibility promises between versions.

Use "latest" specifically. * and ^0.0.0 skip prereleases, so they will not pick up new publishes.

pnpm add @patterninc/pattern-ui@latest

"@patterninc/pattern-ui": "latest"

Use

Import styles once, as early as the app entry allows:

import '@patterninc/pattern-ui/styles.css'

Each component is its own export. There is no barrel index.

import { Button } from '@patterninc/pattern-ui/button'
import CheckIcon from '@patterninc/pattern-ui/icons/CheckIcon'
import { ListItem } from '@patterninc/pattern-ui/list-item'

The import path is the kebab-case key in package.json "exports". Stories under src/components/<Name>/ show props and variants.

Most interactive components accept asChild, which merges their props onto a single child (Link, a, and so on) instead of wrapping it.

Dark mode follows a dark class on document.documentElement. Animated theme changes use startThemeTransition from @patterninc/pattern-ui/theme-transition.

Color tokens

Use semantic tokens from src/pattern-themed-tailwind.css. They adapt to light and dark mode. The theme resets Tailwind's default palette, so stock utilities such as bg-blue-500 are not available.

| Role | Examples | | ---------- | --------------------------------------------------------------- | | Text | text-text-strong, text-text-sub, text-text-disabled | | Background | bg-primary-base, bg-base-weak, bg-depth-black-4 | | Border | border-border-sub | | Status | text-positive-base, text-negative-base, text-caution-base |

Interactive variants use -base (default), -light (hover), -dark (active), and -lighter (disabled). Comment every arbitrary value (w-[103px]). Do not hardcode hex, rgb, or oklch in class names.

Browser artifacts

A single HTML file can render Pattern UI with no install and no build. Use that when an artifact or doc needs the real components and styles. The steps are in examples/README.md. examples/static-artifact.html is the artifact page. examples/playground-artifact.html is that page with an editor. Claude artifacts need play-cdn-claude.js instead of play-cdn.js; see Claude artifacts.

Develop

Run commands from the monorepo root.

| Command | What it does | | ----------------------------------------------- | ------------------------------------------ | | pnpm --filter pattern-ui storybook | Storybook on port 7007 | | pnpm exec vp run @patterninc/pattern-ui#build | Cached library build (vp pack → dist/) | | pnpm --filter pattern-ui watch | Rebuild on change | | pnpm --filter pattern-ui check | Lint, format, and type-check | | pnpm --filter pattern-ui check:fix | Same, with autofix | | pnpm --filter pattern-ui test | Unit tests and Storybook play tests | | pnpm --filter pattern-ui test:unit | *.test.ts only (Node) | | pnpm --filter pattern-ui test:storybook | Play-function tests (Chromium) | | pnpm --filter pattern-ui chromatic | Visual regression against Storybook |

On a fresh clone, install the test browser once before test or test:storybook:

pnpm --filter pattern-ui exec playwright install chromium

Chromatic uses a shared snapshot quota. Run it once per pull request, right before review, and paste the link into the PR template.

Contribute

Component, export, Storybook, and token rules for this package are in AGENTS.md. Story shape is defined in docs/pattern-ui-storybook-standards.md.

When adding a public component, export it inline with export function, add a matching "exports" entry in package.json, and add stories next to the component.