@code-sherpas/pharos-tokens
Design tokens for Code Sherpas. Framework-agnostic. DTCG + Style Dictionary v4 + OKLCH.
Part of Pharos, Code Sherpas' design system: its visual direction and the
values of every token are decided in the
Pharos design system artifact,
published here as tokens and as components in pharos-react, and the program's documentation (decisions, roadmap,
quality standard)
lives in Notion → Programa Pharos.
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, easing, and layout widths and breakpoints. 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/styles.css';
or, from a JS/TS entry point:
import '@code-sherpas/pharos-tokens/styles.css';
Both entry points ship type declarations, so the side-effect import type-checks with noUncheckedSideEffectImports (on by default since TypeScript 6) without any declare module. @code-sherpas/pharos-tokens/css is the same stylesheet under its original name and keeps working.
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'];
Every token path is typed, so a renamed or removed token fails your compilation. The declarations need neither resolveJsonModule nor skipLibCheck, and compile with moduleResolution bundler, node16 and nodenext.
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 the rules for consumers in Notion (Programa Pharos), where Pharos keeps its documentation (decision D27).
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. |
| Width | width.panel | Widths by role. panel: Sheet and SidePanel (24rem). |
| Breakpoint | breakpoint.panel | Viewport breakpoints by role (D32); read them in JS. |
Contributing
pnpm install- Modify or add tokens in
src/*.tokens.json(DTCG format). pnpm build— verify that Style Dictionary compiles.pnpm test— WCAG + DTCG validations must pass.pnpm changeset— declare the type of change (patch / minor / major).- 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.