ptech-tokens
v0.8.11
Published
Design tokens + foundation utilities for ptech design system
Readme
ptech-tokens
Design tokens and foundation utilities for the Peterson/ptech design system. The package is published independently from ptechlibraryv3 so design primitives, theme overrides, and framework-agnostic recipes can be consumed by downstream hosts without importing React components.
The public CSS contract is:
| Import | Contents |
| --- | --- |
| ptech-tokens/index.css | Re-exports tokens.css and foundation.css |
| ptech-tokens/tokens.css | Unlayered :root token primitives, [data-theme="light"], and brand blocks |
| ptech-tokens/foundation.css | Token-backed utility/component recipes in CSS layers |
The TypeScript helper ptech-tokens exports token, cssVar(), TokenGroup, and Tokens. It mirrors token names only; importing CSS is still required for runtime values.
Install
pnpm add ptech-tokensInside this monorepo, ptechlibraryv3 consumes it through "ptech-tokens": "workspace:*".
Theme Model
Default :root is Peterson dark mode and follows Desgin/Demo/Theme Lab option Brand True. Light mode is explicit:
<html data-theme="light">Control Union is a brand axis and combines with light/dark:
<html data-brand="cu">
<html data-brand="cu" data-theme="light">The default Peterson and Control Union product UI values are:
| Axis | Source |
| --- | --- |
| Peterson dark | Theme Lab Brand True, navy surface, aqua definition, yellow CTA |
| Peterson light | Theme Lab Brand True, warm paper/wheat surface |
| CU dark | Theme Lab Brand True, CU cyan/blue adaptation |
| CU light | Theme Lab Brand True, light CU blue surfaces |
prefers-color-scheme is not used. Host apps own theme selection through attributes.
Peterson Design System Coverage
0.7.x expands tokens to cover the Peterson Solutions Design System source files under Desgin/Peterson Solutions Design System/ and the product UI demo under Desgin/Demo/. 0.8.0 adds the missing Peterson/CU pill and fixed editorial eyebrow badge roles used by preview/components-pills.html.
| Design-system area | Token coverage |
| --- | --- |
| Brand palette | --color-peterson-*, source aliases --ps-*, product roles --color-ps-* |
| Control Union palette | --color-cu-cyan, --color-cu-sky, --color-cu-teal, --color-cu-green, --color-cu-dark-blue, --color-cu-dark-grey, gradient tokens |
| Ink/line/paper neutrals | --ink-1..6, --line-1..3, --paper, --paper-warm |
| Semantic foreground/background | --fg-on-*, --bg-*, --rule-on-* |
| Typography | --font-display, --font-body, --font-doc, --fs-*, --lh-*, --tracking-* |
| Product type scale | --font-size-xs..2xl, --line-height-xs..2xl |
| Spacing | --space-1..9 plus compact aliases --space-3xs..2xl |
| Structural affordances | --font-weight-*, --stroke-*, --scrollbar-size, --surface-pattern-dot, --surface-lift-y |
| Radii | compact --radius-*, brand radii --radius-brand-*, semantic --radius-control, --radius-button, --radius-content-card |
| Shadows | --shadow-sm/md/lg, --shadow-deck, --shadow-aqua-glow, --shadow-cta-shelf, --shadow-print-shape, --shadow-ps-card |
| Components | badge, CU pills, tonal tags, fixed editorial eyebrow badges, messagebar, toast, hero, switch, progress, control shell, popover/surface, card accent, button/card/table/rule aliases, TokenDash card/button/table motif recipes |
| Brand motifs | aqua blob, photo tint, protection gradient, footer rule tokens |
| Demo compatibility | --shadow-card, --r-card, --r-ctl |
The package intentionally does not bundle font binaries, logos, photography, illustrations, icon PNGs, or copy guidance. Those assets stay with the host/app/artifact. ptech-tokens only provides the CSS variables and typed names needed to apply the system.
Token Naming
Use the existing public names for product UI:
--color-ps-*for product brand, surface, text, status, and interaction roles.--font-*,--font-size-*,--line-height-*,--space-*,--radius-*,--shadow-*, and--z-*for shared foundations.--color-badge-*,--color-messagebar-*,--color-toast-*,--switch-*, and--progress-*for component semantics. Use--color-badge-eyebrow-*for the fixed Peterson editorial labels (CASE STUDY,NEW,FEATURED) rather than theme-dependent status colours.
Use source-palette names when translating design-system artifacts:
--color-peterson-*and--ps-*mirror the Peterson design-system source palette.--ink-*,--line-*,--paper, and--paper-warmmirror neutral/source document tokens.--color-cu-*mirrors Control Union sub-brand tokens.
Do not remove or rename shipped tokens without a major version bump. New tokens are additive and should be mirrored in src/index.ts when useful to TypeScript consumers.
Fonts And Assets
Typography tokens declare stacks only:
| Token | Default stack |
| --- | --- |
| --font-display | "Sansa Pro", "Source Sans 3", "Segoe UI", ui-sans-serif, system-ui, sans-serif |
| --font-sans | Alias of --font-display |
| --font-brand | Alias of --font-display |
| --font-body | Alias of --font-display |
| --font-doc | "Calibri", "Sansa Pro", "Source Sans 3", "Segoe UI", sans-serif |
| --font-mono | "JetBrains Mono", ui-monospace, monospace |
Hosts must load licensed fonts with @font-face or another asset pipeline:
@font-face {
font-family: "Sansa Pro";
src: url("/fonts/SansaPro-Normal.woff2") format("woff2");
font-weight: 400;
font-display: swap;
}Consumption And Overrides
For non-Module-Federation hosts, a typical order is:
import "ptech-tokens/index.css";
import "ptechlibraryv3/dist/styles.css";
import "./host-overrides.css";For Module Federation hosts, the library injects its CSS at remote-load time. If the host overrides tokens, use a selector more specific than :root so source order cannot beat the override:
html[data-theme="light"] {
--color-ps-aqua: #0090a0;
}
html.my-host-brand {
--color-ps-cta: #eed74d;
}Override primitives for broad re-theming and semantic/component tokens for surgical changes:
html.my-host-brand {
--color-ps-aqua: #00b8c7;
}
html.my-host-brand {
--color-badge-info-soft: color-mix(in srgb, #00b8c7 18%, transparent);
}Foundation Utilities
foundation.css ships token-backed recipes:
| Class | Purpose |
| --- | --- |
| .scroll-slim | Thin tokenized scrollbar |
| .line-clamp-2 | Two-line text clamp |
| .divider-hairline | Tokenized divider |
| .ps-backdrop | Modal/overlay backdrop |
| .focus-ring | Tokenized focus ring |
| .ps-card-solid | Canonical single-layer card |
| .ps-section-wrap | Section/container grouping surface |
| .ps-row | Borderless list/settings row |
| .ps-list-item | Dense Peterson dashboard/list item surface |
| .ps-menu-surface | Floating menu/popover/dropdown surface |
| .ps-menu-item | Tokenized menu/listbox option row |
| .ps-nav-shell | Compact navigation container |
| .ps-nav-pill | Navigation tab/pill item |
| .ps-field-label | Compact uppercase field label |
| .ps-badge-eyebrow | Tokenized Peterson editorial eyebrow badge anatomy |
| .ps-tag-* | Tokenized Tag size, tone, icon, text, and remove affordance recipes |
| .ps-chip-* | Tokenized Chip selected/default/hover, icon, text, and remove affordance recipes |
| .ps-sidebar-*, .ps-sidenav-*, .ps-page-header-* | Tokenized Sidebar rail, SideNav item, and sidebar-aligned PageHeader recipes |
| .ps-control-shell | Shared input/select/search shell |
| .ps-control-input | Inner transparent input reset |
| .ps-control-icon | Accent icon helper |
| .ps-control-action | Compact icon action button |
| .ps-control-inset, .ps-shadow-sm | Tokenized inset and small elevation shadows for compact tracks and controls |
| .ps-icon-well | Token-tinted icon container |
| .ps-eyebrow | Compact metadata label |
| .ps-card-foot | Card footer divider recipe |
| .ps-hero-band, .ps-hero-shape | Hero band and decoration |
| .ps-button-primary, .ps-button-primary-shelf, .ps-button-cta, .ps-button-hero-outline, .ps-button-outline-accent, .ps-button-secondary, .ps-button-pill, .ps-button-ghost, .ps-button-subtle, .ps-button-danger, .ps-button-link | Button variant recipes |
| .ps-fab-*, .ps-speed-dial-action | FAB size, icon, label, tone, and SpeedDial floating action recipes |
| .ps-blade-* | Blade layout, header, scrollable body, footer, and tokenized entrance motion recipes |
| .ps-table-header-brand, .ps-table-row-accent | Branded table affordances |
| .ps-progress-track, .ps-progress-fill | Progress recipes |
| .ps-progress-sm | Compact token-derived progress height |
| .ps-switch-track, .ps-switch-knob | Switch recipes |
| .ps-drawer-surface | Drawer surface recipe |
| .ps-modal-size-full, .ps-drawer-size-*, .ps-command-palette-surface, .ps-toast-viewport, .ps-pdf-viewer-scroll | Token-derived overlay, viewer, and drawer dimensions |
| .ps-picker-chip-label, .ps-picker-input | Picker text measure and input sizing recipes |
| .ps-upload-surface, .ps-dropzone, .ps-upload-inlineBtn | Upload/dropzone recipes |
| .ps-surface-* | Generic surface variants, loading, border, glow, and dotted motif recipes |
| .ps-card-density-dashboard, .ps-card-content-dashboard, .ps-stat-*, .ps-table-*-dashboard | Peterson dashboard card, stat, and table recipes |
| .card-surface-*, .card-tone-*, .card-accent-*, .card-pattern-brand, .card-interactive, .card-selected | Card composition recipes |
foundation.css should only contain recipes that depend on tokens. Pure layout helpers belong in consuming apps.
Versioning
- Additive token surface: minor.
- Value retuning that preserves intent: patch.
- Removing or renaming shipped tokens: major.
When adding a token:
- Add the CSS variable to
src/tokens.css. - Add a light-mode and brand override when the value is theme-specific.
- Mirror it in
src/index.tsif TypeScript consumers should reference it. - Add a Tailwind
@theme inlinemapping inpackages/library/src/index.cssonly when utility classes are needed. - Update this README and
CHANGELOG.md.
Do / Don't
- Do use
ptech-tokens/tokens.cssas the source of token values. - Do use
[data-theme="light"]and[data-brand="cu"]for supported axes. - Do override tokens in host CSS instead of editing package files.
- Do keep assets and font binaries outside this package.
- Don't add token variables directly to
packages/library/src/index.css. - Don't hardcode hex or rgb values in runtime library components when a token exists.
- Don't add another runtime theme for Theme Lab
Premium ContrastorWheat Editorialunless that is explicitly requested.