Distributed Poimandres design-system

The shared pmndrs visual language: colours, typography, spacing, radius, shadows and motion, with brand guidelines and reusable assets. Use its documented values and exported files across design tools and implementations.

Design resources

Start with the guidelines and tokens. The SVG assets and design tokens are available directly. Light and dark colours and foundations use DTCG; text and shadow styles use Tokens Studio.

Registry items

The registry distributes code and files. Items can target vanilla JavaScript, Vue, React or other environments; each item carries its own files and dependencies. Choose items according to your project and their setup requirements.

The official shadcn registry directory lets the CLI resolve @pmndrs automatically, without manual registration.

Read the JSON index or use the shadcn CLI to browse and install individual items:

npx shadcn@latest add @pmndrs/logo @pmndrs/figma-tokens
npx shadcn@latest search @pmndrs

See the registry catalog for this repo's items and blocks from other pmndrs repos.

The hosted registry follows main. To pin an installation, use a GitHub address with a tag: pmndrs/design-system/logo#v0.9.0. Hosted previews serve their own items, but their GitHub dependencies still resolve at the tags they declare. The versioning section explains how item versions resolve.

Integrations

• Vanilla HTML and CSS: shared palette, fonts and native elements.
• Vue: preset, theme and components with shadcn-vue, or standard CSS.
• React and Tailwind: preset, theme and components.

Prototype in v0

To prototype with the theme, logo and guidelines in v0: Open in v0.

Or generate the brand guidelines as slides:

Open the brand guidelines as slides. The starter includes the theme, logo and guidelines/Guidelines.md.

Custom palettes

The md3-base item provides the colour plumbing without a baked palette. Follow its docs to generate a palette from your own seed with Material Theme Builder.

Publish an item

Publish code or files from the repo that owns them, then add the registry to the catalog. Each item declares its files and dependencies; pin every dependency to its own ref.

Claude Design

The design system is published to Claude as the Poimandres Design System artifact, so that the designs Claude generates stay on brand: its tokens, its brand book (README.md), its fonts, and a card per pmndrs block of the registry catalog. The artifact draws the foundations, colours to shadows, from the tokens itself.

Every file of it comes from this repo. pnpm run artifact writes them into out/artifact/project/ (gitignored), laid out as the artifact's own project/:

• tokens.json, from the theme palette, the shadcn remap and the docs tables, with the usage lines and provenance of scripts/artifact.notes.json;
• README.md, assets/Logos/README.md and components/<Block>/*, copied from artifact/ with their {{placeholders}} filled: every version and sha in them comes from git, package.json, node_modules or registry/external.json. README.md is the brand book, which pnpm run build also turns into the docs site's Guidelines page and the guidelines item's Guidelines.md: passages that only make sense in the artifact sit between <!-- artifact-only --> and <!-- /artifact-only -->, and stay out of those two;
• fonts/*, the latin subsets of Inter and Inconsolata.

components/ mirrors the catalog's blocks (registry:block items of registry.json and registry/external.json): each has a hand-written preview.html, a static rendition styled with the artifact's token variables, and a README.md. A block listed without its card fails the run, and so does a card whose block left the catalog.

The artifact generates the rest itself (tokens.css, manifest.json, api/), and its index, design-system.json, which names the logo uploads, is edited in place.

A maintainer publishes after each release, from Claude Code, signed in to claude.ai, which is why CI cannot do it:

1. Check out main at the release and run pnpm run artifact.
2. Diff out/artifact/project/ against the artifact's files, and publish only the files that changed to https://claude.ai/artifact/FF46zANDT1mt2kdF9D9QAf with Claude Code's Artifact tool.
3. Last, update design-system.json's lastChange (by, at, via naming the commit, note).

Nothing of it is committed but its sources: scripts/artifact.mjs, scripts/artifact.notes.json and artifact/.

Storybook

Browse the supported registry components and links to the design system documentation:

pnpm run storybook        # http://localhost:6006
pnpm run build-storybook  # static output in out/storybook/

The documentation deployment includes Storybook at storybook/. Each Vercel PR preview serves the same build under /design-system/storybook/; its link is in the deployment job summary and the PR description.

Storybook composition is configured through refs in .storybook/main.ts. The pmndrs/docs reference loads the remote catalog; the sidebar filter in .storybook/manager.ts only displays components listed for that repository in registry/external.json (Color and Keypoints). Remote stories keep their own theme, and some addons have composition limitations. This filters sidebar navigation; remote search results and direct links can still reach other entries in the source Storybook.

registry/external.json records each published Storybook's release ref, source commit and immutable build URL. The pmndrs/docs preview matches v4.22.0. Updating a registry ref without updating its Storybook mapping fails the build. refresh-catalog preserves this metadata. Verify the published build's commit against the new release when updating the mapping; no external build or component code is imported by the DS.

dev

Use Node.js 24 and pnpm 10.33.4 (pinned in package.json).

pnpm install
pnpm run build   # regenerate registry.json, figma/*.tokens.json, the docs catalog
pnpm run artifact  # generate the Claude Design artifact files into out/artifact/
pnpm run lgtm    # outputs are current and valid, preset code round-trips
pnpm run refresh-catalog  # re-fetch the other repos' items listed in the docs catalog

Docs live in docs/ (pmndrs/docs), deployed to GitHub Pages on push to main, and to Vercel as well (a preview per pull request, which the sidebar's version switcher links to). Preview them on http://localhost:3000:

curl -sL https://raw.githubusercontent.com/pmndrs/docs/refs/heads/main/preview.sh | MDX=docs NEXT_PUBLIC_LIBNAME=design-system sh