README.md

USWDS + Tailwind

USWDS components for Tailwind CSS, available as React components or vanilla JS modules. Built on top of zag-js state machines for accessible, headless behavior.

Note

This project is currently in alpha. APIs may change between releases.

Documentation

Full guides, component API, and examples live at uswds-tailwind.com.

Packages

Package	Description
@uswds-tailwind/react	React component library
@uswds-tailwind/compat	Drop-in vanilla JS modules
@uswds-tailwind/theme	Tailwind v4 theme with USWDS design tokens
@uswds-tailwind/<name>-compat	Headless zag-js state machines (one per component)

Repository structure

• apps/docs/: Astro documentation site at uswds-tailwind.com
• packages/react/: React component library + Storybook
• packages/compat/: vanilla JS bundle
• packages/theme/: Tailwind v4 theme
• packages/machines/: per-component zag-js state machines
• examples/: minimal example projects

Local development

Requires Node.js (see .nvmrc) and pnpm.

git clone https://github.com/IHIutch/uswds-tailwind.git
cd uswds-tailwind
pnpm install
pnpm build:packages

Common scripts (run from the repo root):

Script	What it does
pnpm build:packages	Build all publishable packages
pnpm build:website	Build the docs site
pnpm lint	Run ESLint across the monorepo
pnpm lint:publish	Run publint on every package
pnpm typecheck	Run TypeScript across packages
pnpm test	Run package tests
pnpm --filter website dev	Start the docs dev server
pnpm --filter @uswds-tailwind/react storybook	Start Storybook

Contributing

Contributions are welcome. See CONTRIBUTING.md for branching, conventional commits, changesets, and PR conventions.

Community

• GitHub Issues for bug reports and feature requests
• GitHub Discussions for questions and ideas
• Code of Conduct
• Security policy

License

MIT