@code-sherpas/pharos-tokens
v1.3.1
Published
Design tokens de Code Sherpas — agnóstico de framework. DTCG + Style Dictionary + OKLCH.
Readme
@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 / yarnUsage
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 — 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, $descriptionRules 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.{compact,panel} | By role (D32), read in JS. compact: a phone, < 40rem. |
color.semantic.warning.border is the warning amber for borders and bars, such as the side bar of a warning Alert: it clears WCAG 3:1 non-text contrast on surface.card and surface.canvas, where the amber warning.fg is a fill and does not. It is not for text.
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, and 3:1 non-text contrast for the border tokens on the surfaces they sit on. A PR cannot be merged if it breaks contrast.
License
MIT. See LICENSE.
