Design Tokens

This package exports design tokens as TypeScript constants and metadata objects, enabling type-safe styling and theming in your applications.

Figma Integration

For a visual representation of the design tokens and their usage, you can access the Figma file where these tokens are implemented.

• Figma Design Tokens File

Installation / Setup

Install the package in your project using npm, pnpm, or your preferred package manager:

npm install @ogcio/design-system-tokens

or

pnpm install @ogcio/design-system-tokens

or

yarn add @ogcio/design-system-tokens

Explanation / Usage

The token system supports both light and dark themes. Each theme exports:

• Resolved tokens: Fully computed values ready for direct use
• Unresolved tokens: Reference chains for debugging and tooling
• CSS variables: Browser-compatible variable object with the gieds prefix

Tokens are exported from this package as TypeScript objects and can be imported directly into your application code. Use:

• tokens — resolved token values exposed as JS/TS constants. For example, in the light theme, colors are hex values like #rrggbb, sizes are numbers/strings, etc. These constants are convenient for compile-time usage (static values), such as building styles or performing calculations during bundling.

• variables — references to CSS Custom Properties (var(--...)) for the same tokens. Use these for runtime theming: you reference var(--gieds-...) in CSS, and the actual value is applied in the browser depending on the active theme.

• meta — a token tree enriched with metadata (at least $type and $value) available in two variants:

  • meta.light.resolved / meta.dark.resolved — values are fully resolved to primitives (e.g., a color like #004d44).
  • meta.light.unresolved / meta.dark.unresolved — values remain as references (aliases) to other tokens, for example $value: "{primitive.color.emerald.800}". This is useful in pipelines and tooling where you want to preserve semantic relationships and avoid flattening aliases too early.

Example

• Importing from the package:

  import { tokens, variables, meta } from "@ogcio/design-system-tokens";

• CSS‑in‑JS with runtime theming (variables):

  const Button = styled.button({
    backgroundColor: variables.brand.color.primary[500], // → var(--gieds-color-primary-500)
    color: variables.brand.color.neutral.white, // → var(--gieds-color-neutral-white)
  });

• Static value composition at build time (tokens):

  const border = `1px solid ${tokens.light.giedsColorNeutral300}`; // → 1px solid #babec4

• Tooling/Docs generation (meta):

  const treeUnresolved = meta.light.unresolved; // has $type and alias references in $value
  const treeResolved = meta.light.resolved; // has final primitive values

Token Categories

Colors

The color system includes primitive color scales (gray, blue, red, yellow, green, emerald, purple, and gold) with 50–950 shades for granular control. Brand colors define primary (emerald), secondary (gold), and neutral (gray) palettes. Semantic color tokens provide contextual meaning through:

• System colors: Neutral defaults and interactive states for general UI elements
• Tone colors: Variations for fills, outlines, and flat styles (primary, dark, light, convention)
• Intent colors: Feedback colors for info, success, error, warning, and focus states
• Surface colors: Background layers and interactive surface states

Typography

Typography tokens define text styles through a type scale system with heading and body text variants. Headings range from 2xs to xl with bold weights, supporting responsive scaling across breakpoints (default, xs, md, xl). Each scale references primitive font families, sizes, weights, and line heights for consistent vertical rhythm.

Spacing

Spacing tokens provide a comprehensive scale from 0px to 960px using a 4px base unit. The scale includes fractional values (e.g., 0-5, 1-5) for fine-grained control and larger increments for layout composition. Use these tokens for margins, padding, gaps, and positioning.

Borders

Border tokens include width scales (100–800, from 1px to 16px) and radius scales (100–600 plus full for pill shapes). These values maintain visual consistency across buttons, cards, inputs, and other bordered elements.

Shadows

Shadow tokens define elevation layers for depth and hierarchy in the interface. Values include box-shadow configurations for different z-index levels and semantic focus shadows.

Sizing

Sizing tokens standardize component dimensions including heights, widths, icon sizes, and container constraints. The scale ensures proportional relationships between UI elements.

Opacity

Opacity tokens provide transparency levels for overlays, disabled states, and visual hierarchy. Values range from fully transparent to fully opaque in semantic increments.

Z-Index

Z-index tokens establish consistent stacking contexts for modals, dropdowns, tooltips, and other layered UI components, preventing z-index conflicts.

Screens (Breakpoints)

Screen tokens define responsive breakpoints (xs, sm, md, lg, xl) for consistent media queries and adaptive layouts across device sizes.

Build Process

The build script (scripts/build.ts) transforms JSON token definitions into multiple output formats using @ogcio/design-system-tokens-builder. It generates TypeScript files for both resolved and unresolved token trees, camelCase constant exports, and CSS variable objects. The package uses a two-stage build: first tokens are generated, then source files are compiled with tsup. Run the build with:

pnpm build

File Structure

├── dist/                  # Generated output file of variables (consumed by tailwind later)
├── scripts/
│   └── build.ts           # Token builder configuration
├── src/
│   ├── dist/              # Generated output files for tokens (tokens light/dark, meta light/dark resolved/unresolved and variables)
│   └── index.ts           # Main export file
└── tokens/
    └── light/             # Light theme source tokens
        ├── brand/         # Brand identity tokens
        ├── primitive/     # Base value tokens
        └── semantic/      # Contextual usage tokens

Token Naming Convention

Tokens follow a hierarchical dot-notation structure:

{tier}.{category}.{subcategory}.{variant}.{state}

For example: semantic.color.surface.tone.primary-fill.hover

This naming provides clear semantic meaning and enables predictable token discovery across the system.