@code-sherpas/pharos-tokens

Design tokens for Code Sherpas. Framework-agnostic. DTCG + Style Dictionary v4 + OKLCH.

What's in this package

This package defines the atomic values of Code Sherpas's visual system: colors, spacing, radius, typography, shadows, z-index, duration, and easing. They are consumable from any frontend (React, Vue, Svelte, React Native) and from backends (transactional emails, PDFs, reports).

It contains no components. React components live in @code-sherpas/pharos-react and consume this package as a peer dependency.

Installation

pnpm add @code-sherpas/pharos-tokens
# or npm / yarn

Usage

Option A — CSS custom properties (recommended)

Import the CSS tokens at your app's entry point:

@import '@code-sherpas/pharos-tokens/css';

This exposes --pharos-* on :root. Use them directly or via Tailwind arbitrary values:

.button-primary {
  background: var(--pharos-color-primary-600);
  color: white;
}

<div class="bg-[var(--pharos-color-neutral-900)] text-white p-[var(--pharos-spacing-4)]">…</div>

Option B — Typed object (JS/TS)

import { tokens } from '@code-sherpas/pharos-tokens';

const darkSurface = tokens.color.neutral['900'];
const cardRadius = tokens.radius['2xl'];

Full autocomplete thanks to typeof tokens.

Option C — Flat constants (selective imports)

import { PharosColorPrimary600, PharosRadius2xl } from '@code-sherpas/pharos-tokens/tokens.js';

Option D — DTCG source (custom pipelines)

For your own transforms (iOS, Android, Figma, etc.):

import colorDtcg from '@code-sherpas/pharos-tokens/dtcg/color';
// DTCG object with $value, $type, $description

Rules for consumers

See RULES.md — published with the package.

Token structure

Family	Example path	Description
Base	color.base.{white,black}	Pure white and black.
Neutrals	color.neutral.{50..950}	Grayscale, slightly navy-tinted in the darker steps.
Primary	color.primary.{50..900}	Sea blue, scale 50-900. 600 is the base hue.
Semantic	color.semantic.{success,error,warning,info}.{fg,bg,on}	Success/error/warning/info. fg + on pairs pass WCAG AA.
Spacing	spacing.{0..24}	Tailwind-compatible scale in rem.
Radius	radius.{none,sm,md,lg,xl,2xl,3xl,full}	Corner rounding.
Typography	font.{family,weight,size,lineHeight,letterSpacing}.*	Typography. Body default = size.sm (14px).
Shadow	shadow.{sm,md,lg,xl}	Elevation.
Z-index	z.{0,header,above-header,modal-overlay,modal,drawer-overlay,drawer,dropdown,tooltip}	Semantic, not literal.
Duration	duration.{fast,normal,slow}	Transitions.
Easing	easing.{in,out,in-out}	Cubic-bezier curves.

Contributing

1. pnpm install
2. Modify or add tokens in src/*.tokens.json (DTCG format).
3. pnpm build — verify that Style Dictionary compiles.
4. pnpm test — WCAG + DTCG validations must pass.
5. pnpm changeset — declare the type of change (patch / minor / major).
6. Open a PR.

CI validates WCAG 2.1 AA contrast on every color/on-color pair. A PR cannot be merged if it breaks contrast.

License

MIT. See LICENSE.