[protocol]works design system

Shared design foundations for [protocol]works products.

The repository publishes two layers:

• @protocol-works/design-tokens owns the brand palette, canonical light and dark theme values, typography, bundled fonts, motion, geometry, and Tailwind CSS v4 aliases.
• @protocol-works/ui owns portable React primitives established across [protocol]works products.

Products continue to own runtime theme persistence, framework adapters, product-specific semantic roles, and domain components.

Status

0.x foundation. @protocol-works/design-tokens and @protocol-works/ui are published publicly.

Install

npm install @protocol-works/design-tokens

Import Tailwind first, then the shared foundation:

@import "tailwindcss";
@import "@protocol-works/design-tokens";

The default export includes the self-hosted font CSS, namespaced tokens, light/dark theme bindings, and Tailwind aliases. More selective consumers may import:

@import "@protocol-works/design-tokens/fonts.css";
@import "@protocol-works/design-tokens/tokens.css";
@import "@protocol-works/design-tokens/tailwind.css";

Set data-theme="light" or data-theme="dark" on the document root. With no attribute, the shared CSS renders the light theme. Consumers decide how to detect, persist, and synchronize the preference.

Token layers

• --pw-palette-*: stable brand colors.
• --pw-color-*: active semantic theme values.
• --pw-font-*, --pw-text-*, --pw-leading-*: typography.
• --pw-duration-*, --pw-ease-*: motion.
• --pw-border-*, --pw-radius-*, --pw-shadow-*: geometry and elevation.
• --pw-focus-*, --pw-hit-target-min, --pw-control-*, --pw-icon-*: interaction and sizing.

tailwind.css exposes utilities such as bg-background, text-foreground-muted, border-rule, bg-accent-clay, font-sans, text-body, text-signal, rounded-tight, duration-quick, ease-edit, ease-reveal, and size-control-compact. text-signal is the compact typography role; use text-brand-signal when the semantic gold signal color is intended.

React UI

Install the token and UI packages together:

npm install @protocol-works/design-tokens @protocol-works/ui

Register the compiled component sources after importing Tailwind and the token foundation:

@import "tailwindcss";
@import "@protocol-works/design-tokens";
@import "@protocol-works/ui/tailwind.css";

Import components directly so consumers only load what they use:

import { Button } from "@protocol-works/ui/button";
import { IconButton } from "@protocol-works/ui/icon-button";
import { Stack } from "@protocol-works/ui/stack";
import { Heading } from "@protocol-works/ui/heading";

Form controls and buttons accept size="sm" for compact desktop toolbars and inspectors. Modal and popover primitives use Radix behavior for focus management, escape handling, portals, and collision-aware positioning.

See packages/ui/README.md for the complete component catalogue.

Fonts

DM Sans, DM Mono, and DM Serif Display are delivered through Fontsource packages and are bundled by consuming applications for offline runtime use. The font packages are licensed under the SIL Open Font License 1.1.

License

MIT. See LICENSE.

Development

npm install
npm run check
npm pack --dry-run
npm pack --dry-run --workspace @protocol-works/ui