Vendure Design System

The design system powering every Vendure surface.

Design tokens and React components built on shadcn/ui, Base UI, and Tailwind CSS v4, consumed across Vendure applications and ecosystem surfaces.

Documentation | Website

What's in this repo

This monorepo contains the published packages and agent skills of the Vendure design system, plus a Storybook app for component documentation.

Package	Description
@vendure-io/design-tokens	Design tokens and Tailwind v4 CSS theme (@theme, CSS variables)
@vendure-io/ui	React components built on shadcn/ui (base-vega style), Base UI, and Tailwind v4
@vendure-io/design-lint	Equivalent ESLint and Biome rules for mechanical design-system constraints

App	Description
storybook	Component documentation and playground (Storybook 10)

Note that @vendure-io/ui ships raw .tsx source with no build step; consumers transpile the package themselves. The packages version independently.

Getting started

To consume the design system in your app, follow the getting started guide. Further guides:

• Design tokens: token pipeline, CSS theme, usage
• UI components: component catalog and usage
• Agent skills: global installation for Codex and Claude Code
• Testing: CI quality gates (a11y, visual regression) and baselines
• Releasing: how packages are versioned and published

Agent setup

Install the portable UI composition and token skills globally for Codex, Claude Code, or another supported agent:

npx skills add vendurehq/design --skill vendure-ui --skill vendure-tokens --global

The skills are model-invoked, so developers can describe the screen they want to build or review without selecting a skill manually. See Agent Skills for non-interactive installation and host-specific behavior.

Add the mechanical semantic-color checks to a consuming app:

bun add --dev @vendure-io/design-lint

Enable either the recommended ESLint config or the Biome GritQL plugin as shown in the @vendure-io/design-lint package guide.

Development

This repo uses Bun and Turborepo.

# Install dependencies
bun install

# Run Storybook
bun run storybook

# Type-check all packages
bun run check-types

# Lint
bun run lint

# Format
bun run format

# Run tests
bun run test

Releasing

Packages are released independently by creating a GitHub Release with a per-package tag. The CI workflow bumps the version in package.json, publishes to npm with provenance, and commits the bump back to main.

Package	Tag format	Example
@vendure-io/design-tokens	design-tokens/v{version}	design-tokens/v1.2.0
@vendure-io/ui	ui/v{version}	ui/v1.3.0
@vendure-io/design-lint	design-lint/v{version}	design-lint/v1.0.0

Prerelease tags such as ui/v1.4.0-beta.0 publish to the matching npm dist-tag (beta) instead of latest. See docs/releasing.md for the full workflow, including release ordering when both packages change.

License

See LICENSE.md.