Design Tokens Reference¶

NON-NORMATIVE.

Package: @morphism-systems/design-tokens v0.1.0 License: BUSL-1.1 Format: ESM-only, TypeScript-first, tree-shakeable Color format: HSL "H S% L%" (shadcn/ui compatible)

Overview¶

@morphism-systems/design-tokens provides a structured, typed token system for all Morphism-ecosystem UI surfaces. It ships 10 canonical themes organized into two groups:

Project themes — extracted from live satellite products (morphism.systems, meshal-web, repz, gainboy, rounaq-atelier, llmworks). Each carries an origin field naming the source product.
Field themes — canonical UI/UX design movement references (Brutalism, Swiss Minimalism, Glassmorphism, Editorial Dark). These have origin: null.

All themes are fully typed via TypeScript interfaces, consumable as CSS custom properties, or as Tailwind CSS preset objects.

Token Schema¶

`HSLValue`¶

type HSLValue = string;

A color expressed as HSL channel values without the hsl() wrapper and without commas: "H S% L%". Example: "265 50% 4%". This format is compatible with Tailwind's hsl(var(--token) / alpha) pattern.

`ColorScale`¶

A semantic color scale covering all UI states for a single theme.

Field	Role
`bg`	Page background
`surface`	Card / elevated surface
`surfaceMuted`	Subtle surface (sidebar, code blocks)
`border`	Primary border color
`input`	Input / form element border
`accent`	Primary brand accent
`accentBright`	Accent hover / bright state
`accentDim`	Accent muted / dim state
`accentForeground`	Foreground color on accent backgrounds
`text`	Primary text
`textMuted`	Secondary / muted text
`destructive`	Error / destructive state
`success`	Positive / success state
`warning`	Caution / warning state
`info`	Neutral informational highlight

All values are HSLValue strings.

`Typography`¶

Field	Type	Description
`sans`	`string`	Primary sans-serif font stack
`serif`	`string \\| null`	Serif font stack (`null` if unused)
`mono`	`string`	Monospace font stack
`display`	`string \\| null`	Display / hero font (`null` if same as sans)
`baseFontSize`	`string`	Base font size in rem (e.g. `"1rem"`)
`baseLineHeight`	`string`	Base line height (e.g. `"1.6"`)
`weights.normal`	`number`	Normal weight (typically `400`)
`weights.medium`	`number`	Medium weight (typically `500`)
`weights.semibold`	`number`	Semibold weight (typically `600`)
`weights.bold`	`number`	Bold weight (typically `700`)

`Spacing`¶

Field	Type	Description
`radii.sm`	`string`	Small border radius
`radii.md`	`string`	Medium border radius
`radii.lg`	`string`	Large border radius
`radii.xl`	`string`	Extra-large border radius
`radii.full`	`string`	Fully rounded (pill / circle)
`maxWidth`	`string`	Content max-width (e.g. `"1200px"`)

`Effects`¶

Field	Type	Description
`shadows.sm`	`string`	Small box shadow
`shadows.md`	`string`	Medium box shadow
`shadows.lg`	`string`	Large box shadow
`blur.sm`	`string`	Small backdrop blur
`blur.md`	`string`	Medium backdrop blur
`blur.lg`	`string`	Large backdrop blur
`transition.fast`	`string`	Fast transition duration
`transition.normal`	`string`	Normal transition duration
`transition.slow`	`string`	Slow transition duration
`transition.easing`	`string`	CSS cubic-bezier easing curve

`ThemeTokens`¶

The complete token set for a theme. Combines the four token categories:

interface ThemeTokens {
  colors: ColorScale;
  typography: Typography;
  spacing: Spacing;
  effects: Effects;
}

`ThemeMeta`¶

Theme identity and classification metadata:

Field	Type	Description
`id`	`string`	Machine-readable slug (kebab-case)
`name`	`string`	Human-readable display name
`description`	`string`	Short design philosophy summary
`category`	`"project" \\| "field"`	Theme group
`mode`	`"dark" \\| "light"`	Default color mode
`tags`	`string[]`	Searchability tags
`origin`	`string \\| null`	Source product or design movement

`Theme`¶

The top-level theme definition, combining metadata and tokens:

interface Theme {
  meta: ThemeMeta;
  tokens: ThemeTokens;
}

API Reference¶

All functions are exported from @morphism-systems/design-tokens.

`getTheme(id: string): Theme`¶

Returns a theme object by ID. Throws Error if the ID is not registered.

import { getTheme } from "@morphism-systems/design-tokens";

const theme = getTheme("violet-theorem");
// theme.meta.name === "Violet Theorem"
// theme.tokens.colors.accent === "270 100% 74%"

Throws: Error: Unknown theme "foo". Available: violet-theorem, neon-cyber, ...

`getThemeNames(): string[]`¶

Returns all 10 registered theme IDs in registry order.

import { getThemeNames } from "@morphism-systems/design-tokens";

const ids = getThemeNames();
// ["violet-theorem", "neon-cyber", "command-center", ...]

`getThemeCSS(theme: Theme | string, selector?: string): string`¶

Generates a CSS custom properties block from a theme's tokens. Accepts a theme object or ID string. The selector parameter defaults to :root.

Color values are emitted as raw HSL channel strings (e.g. 265 50% 4%). At the call site, wrap with hsl():

background-color: hsl(var(--bg));
background-color: hsl(var(--bg) / 0.5); /* with alpha */

This matches Tailwind's convention and enables per-use alpha composition.

Generated variables include:

Color tokens: --bg, --surface, --surface-muted, --border, --input, --accent, --accent-bright, --accent-dim, --accent-foreground, --text, --text-muted, --destructive, --success, --warning, --info
Typography: --font-sans, --font-mono, --font-serif (if set), --font-display (if set), --font-size-base, --line-height-base, --font-weight-normal, --font-weight-medium, --font-weight-semibold, --font-weight-bold
Spacing: --radius-sm, --radius-md, --radius-lg, --radius-xl, --radius-full, --max-width
Effects: --shadow-sm, --shadow-md, --shadow-lg, --blur-sm, --blur-md, --blur-lg, --transition-fast, --transition-normal, --transition-slow, --easing

import { getThemeCSS } from "@morphism-systems/design-tokens";

const css = getThemeCSS("violet-theorem");
// :root {
//   --bg: 265 50% 4%;
//   --surface: 265 40% 8%;
//   --accent: 270 100% 74%;
//   ...
// }

// Scope to a specific selector
const darkCSS = getThemeCSS("violet-theorem", "[data-theme='dark']");

`getThemeTailwind(theme: Theme | string): Record<string, unknown>`¶

Generates a Tailwind CSS preset configuration object from a theme. Returns a plain JS object suitable for use in tailwind.config.ts as a preset.

Color values in the returned object are pre-wrapped in hsl() (e.g. "hsl(270 100% 74%)") — no further wrapping needed in Tailwind config.

import { getThemeTailwind } from "@morphism-systems/design-tokens";
import type { Config } from "tailwindcss";

export default {
  presets: [getThemeTailwind("violet-theorem")],
  content: ["./src/**/*.tsx"],
} satisfies Config;

The returned object extends theme.extend with:

colors: background, surface, surface-muted, border, input, accent (with DEFAULT, bright, dim, foreground variants), text (with DEFAULT, muted), destructive, success, warning, info
fontFamily: sans, mono, and optionally serif, display
fontSize: base with matching lineHeight
fontWeight: normal, medium, semibold, bold
borderRadius: sm, DEFAULT (md), md, lg, xl, full
maxWidth: content
boxShadow: sm, DEFAULT (md), md, lg
backdropBlur: sm, DEFAULT (md), md, lg
transitionDuration: fast, DEFAULT (normal), normal, slow
transitionTimingFunction: theme

`hslToHex(hsl: string): string`¶

Converts an HSL channel string (the raw "H S% L%" format used in token definitions) to a CSS hex color string.

import { hslToHex } from "@morphism-systems/design-tokens";

hslToHex("270 100% 74%");  // "#c084fc"
hslToHex("265 50% 4%");    // "#0b0612"

Returns "#000000" for malformed input.

`getThemeHex(theme: Theme | string): Record<string, string>`¶

Returns all color tokens for a theme as hex values. Useful for JavaScript contexts (canvas rendering, inline styles) where CSS custom properties are unavailable.

import { getThemeHex } from "@morphism-systems/design-tokens";

const hex = getThemeHex("violet-theorem");
// {
//   bg: "#0b0612",
//   surface: "#130e1f",
//   accent: "#c084fc",
//   ...
// }

All 10 Themes¶

ID	Name	Mode	Category	Description
`violet-theorem`	Violet Theorem	Dark	Project	Dark purple, glassmorphism, mathematical precision with ambient violet glow. Canonical Morphism Systems theme.
`neon-cyber`	Neon Cyber	Dark	Project	Full neon spectrum on navy void with glitch effects and scanline overlays. From meshal-web.
`command-center`	Command Center	Dark	Project	Intelligence dashboard aesthetic. Navy-charcoal base with tactical blue data accents. From llmworks/attributa.
`cyberpunk-sport`	Cyberpunk Sport	Dark	Project	High-energy fitness gamification. Dark base with orange CTA energy and cyan complement. From repz.
`retro-pixel`	Retro Pixel	Dark	Project	CRT-era pixel grid nostalgia. Zero border-radius, monospace-only typography, phosphor green accent. From gainboy.
`desert-luxury`	Desert Luxury	Light	Project	Warm minimalist editorial luxury. Cream parchment, gold accent, RTL-friendly. From rounaq-atelier.
`brutalist`	Brutalist	Light	Field	Raw exposed structure. System colors, monospace only, zero radius, zero blur, zero transitions.
`swiss-minimal`	Swiss Minimal	Light	Field	International Typographic Style. Helvetica, strict grid, Swiss red accent, golden-ratio line height.
`neo-glass`	Neo Glass	Dark	Field	Glassmorphism with heavy backdrop blur, gradient accents spanning blue → purple → pink.
`midnight-editorial`	Midnight Editorial	Dark	Field	Dark editorial print. Serif display headlines, warm amber accent, 680px reading measure.

Usage Examples¶

As a Tailwind preset¶

// tailwind.config.ts
import { getThemeTailwind } from "@morphism-systems/design-tokens";
import type { Config } from "tailwindcss";

export default {
  presets: [getThemeTailwind("violet-theorem")],
  content: ["./src/**/*.tsx"],
} satisfies Config;

After this, Tailwind classes like bg-background, text-accent, border-border, and shadow-md use the theme's values.

CSS custom properties via prebuild script¶

// scripts/generate-tokens-css.mjs
import { writeFileSync } from "fs";
import { getThemeCSS } from "@morphism-systems/design-tokens";

const css = getThemeCSS("violet-theorem");
writeFileSync("src/styles/tokens.css", css, "utf8");

Import tokens.css in your global stylesheet. Reference tokens in CSS:

body {
  background-color: hsl(var(--bg));
  color: hsl(var(--text));
}

.card {
  background-color: hsl(var(--surface));
  border: 1px solid hsl(var(--border));
  border-radius: var(--radius-md);
}

Dynamic theme switching¶

Inject CSS custom properties at runtime by writing to a <style> element:

import { getThemeCSS } from "@morphism-systems/design-tokens";

function applyTheme(themeId: string) {
  let styleEl = document.getElementById("morphism-theme");
  if (!styleEl) {
    styleEl = document.createElement("style");
    styleEl.id = "morphism-theme";
    document.head.appendChild(styleEl);
  }
  styleEl.textContent = getThemeCSS(themeId, ":root");
}

applyTheme("neon-cyber");

Direct theme import (tree-shaking)¶

Individual themes can be imported without loading the full registry:

import { violetTheorem } from "@morphism-systems/design-tokens/themes/violet-theorem";

// Use the theme object directly
const css = getThemeCSS(violetTheorem);

Adding a New Theme¶

Create packages/design-tokens/src/themes/my-theme.ts implementing the Theme interface:

import type { Theme } from "../types.js";

export const myTheme: Theme = {
  meta: {
    id: "my-theme",
    name: "My Theme",
    description: "...",
    category: "field",
    mode: "dark",
    tags: ["tag1"],
    origin: null,
  },
  tokens: {
    colors: { /* all 15 ColorScale fields */ },
    typography: { /* all Typography fields */ },
    spacing: { /* all Spacing fields */ },
    effects: { /* all Effects fields */ },
  },
};

Register it in packages/design-tokens/src/registry.ts:

import { myTheme } from "./themes/my-theme.js";

export const themes: ReadonlyMap<string, Theme> = new Map([
  // existing themes...
  ["my-theme", myTheme],
]);

Export from packages/design-tokens/src/index.ts:

export { myTheme } from "./themes/my-theme.js";

Regenerate the default CSS by running the prebuild script:

node apps/morphism/scripts/generate-tokens-css.mjs

Run npx turbo typecheck to verify the new theme satisfies all interfaces.

Design Tokens Reference¶

Overview¶

Token Schema¶

HSLValue¶

ColorScale¶

Typography¶

Spacing¶

Effects¶

ThemeTokens¶

ThemeMeta¶

Theme¶