Design Tokens

PaperStack uses CSS custom properties as the single source of truth for all visual decisions. Tokens are defined in @paperstack/tokens as SCSS variables that compile to :root custom properties, making them available globally and overridable by any theme.

All tokens follow the prefix --ps- internally and are exposed via friendly SCSS variables in the tokens/ package.

Colors

The palette is built around three semantic families that reflect the paper metaphor:

Family	Custom Property Prefix	Description
Parchment	--color-parchment-*	Warm paper tones from cream to aged brown
G2 (ink)	--color-g2-*	Blue, black, red, green — classic pen ink colors
Stabilo	--color-stabilo-*	Highlighter-inspired accent colors

Each shade is available in steps 50 → 950. Semantic aliases like --color-surface, --color-text, --color-border remap to the appropriate shade at theme level.

/* Direct palette token */
background: var(--color-parchment-100);

/* Semantic alias */
color: var(--color-text);
border-color: var(--color-border);

Typography

Five font stacks power the typographic system:

Token	Stack	Use case
--font-ui	Inter, system-ui	UI controls, labels, navigation
--font-reading	EB Garamond, Georgia	Long-form prose, article text
--font-heading	Lora, Georgia	Section headings
--font-display	Playfair Display, Georgia	Hero headings, display text
--font-mono	JetBrains Mono, Fira Code	Code, terminal output

The type scale uses a modular ratio. Steps range from --text-xs through --text-4xl.

font-size: var(--text-base);    /* 1rem */
font-size: var(--text-lg);     /* ~1.25rem */
font-size: var(--text-2xl);    /* ~1.563rem */

Spacing

Spacing follows a 4-point base grid. The scale runs from --space-px (1px) through --space-24 (96px) with named steps for density-aware layouts.

padding: var(--space-4);      /* 16px at default density */
gap: var(--space-2);          /* 8px */
margin-block: var(--space-8); /* 32px */

Content density (compact, default, comfortable) scales spacing tokens automatically via the density system.

Border Radius

Token	Value	Use case
--radius-none	0	Flat / newspaper style
--radius-xs	2px	Badges, tags
--radius-sm	4px	Inputs, buttons
--radius-md	6px	Cards, panels
--radius-lg	8px	Modals, drawers
--radius-paper	1px 2px	Paper-edge corners
--radius-full	9999px	Pills, avatars

Shadows

Shadow tokens convey the physical paper layering metaphor. Each level corresponds to how far "off the desk" an element floats.

Token	Use case
--shadow-0	Flat, no elevation
--shadow-1	Subtle lift (cards)
--shadow-paper	Paper sheet resting on surface
--shadow-stack	Stack of papers
--shadow-float	Floating menus, popovers
--shadow-drawer	Drawers, modals

Motion

Motion tokens balance expressiveness with the prefers-reduced-motion media query. All durations automatically collapse to near-zero when reduced motion is preferred.

Token	Value	Use case
--duration-instant	50ms	State toggles
--duration-fast	100ms	Hover transitions
--duration-normal	200ms	Most UI transitions
--duration-slow	400ms	Panel opens, page transitions
--ease-standard	cubic-bezier(0.4, 0, 0.2, 1)	General purpose
--ease-enter	cubic-bezier(0, 0, 0.2, 1)	Elements entering
--ease-exit	cubic-bezier(0.4, 0, 1, 1)	Elements leaving

Z-Index

Token	Value	Layer
--z-base	0	Default flow
--z-raised	10	Sticky headers, raised cards
--z-dropdown	100	Dropdowns, popovers
--z-overlay	200	Modals, drawers
--z-toast	300	Toast notifications
--z-tooltip	400	Tooltips

Breakpoints

Name	Min-width	Target
xs	320px	Small phones
sm	480px	Large phones
md	768px	Tablets
lg	1024px	Laptops
xl	1280px	Desktops
2xl	1440px	Wide monitors
4xl	1728px	Ultra-wide

Usage in JS / TypeScript

Import token constants from the JS/TS entry point:

import {
  THEMES,
  FONT_FAMILIES,
  BREAKPOINTS,
  CONTENT_WIDTHS,
} from "@paperstack/tokens";

These are typed, readonly tuples and objects — useful for theme switchers, responsive utilities, and programmatic style generation.