Skip to main content

@renge-ui/tokens

The proportions made programmable.

15+ token categories derived from natural mathematics. CSS custom properties, JavaScript objects, Tailwind preset, and framework adapters. Zero dependencies. WCAG 2.1 AA certified.

pnpm add @renge-ui/tokens
v2.6.1WCAG 2.1 AA

Getting Started

Three ways to consume.

Tokens are available as CSS custom properties, JavaScript objects, or Tailwind utilities. Pick the interface that fits your workflow.

CSS Custom Properties

Import the stylesheet. Every token becomes a CSS variable ready to use.

import '@renge-ui/tokens/renge.css';

/* In your CSS */
.card {
  padding: var(--renge-space-4);
  border-radius: var(--renge-radius-2);
  background: var(--renge-color-bg-subtle);
  border: 1px solid var(--renge-color-border);
}

JavaScript / TypeScript

Fully typed token objects for programmatic access.

import { rengeVars } from '@renge-ui/tokens';

const cardStyles = {
  padding: rengeVars.space[4],
  borderRadius: rengeVars.radius[2],
  background: rengeVars.color.bgSubtle,
  border: `1px solid ${rengeVars.color.border}`,
};

Tailwind CSS

Plugin automatically registers all tokens as utilities.

/* globals.css */
@import "tailwindcss";
@plugin "@renge-ui/tailwind/plugin";

<!-- HTML -->
<div class="p-renge-4 rounded-renge-2 bg-renge-bg-subtle border border-renge-border">
  Fully proportional design, zero hardcoding.
</div>

Spacing

Fibonacci × 4px

Each spacing step is a Fibonacci number multiplied by 4px (the base unit). 11 values from 4px to 220px create a naturally proportional scale.

All spacing values

ClassValue / DerivationCSS output
--renge-space-14px1 × 4px
--renge-space-28px2 × 4px
--renge-space-312px3 × 4px
--renge-space-420px5 × 4px
--renge-space-532px8 × 4px
--renge-space-652px13 × 4px
--renge-space-784px21 × 4px
--renge-space-8136px34 × 4px
--renge-space-9220px55 × 4px

Usage example

/* Padding — all directions or individual sides */
.box {
  padding: var(--renge-space-4);           /* 20px all sides */
  padding-left: var(--renge-space-5);      /* 32px left only */
}

/* Margin */
.card {
  margin: var(--renge-space-3);
  margin-bottom: var(--renge-space-6);    /* Increased bottom gap */
}

/* Gap in flexbox/grid */
.grid {
  display: grid;
  gap: var(--renge-space-5);              /* 32px between all items */
  grid-template-columns: repeat(3, 1fr);
}

/* Tailwind: prefix token names with p-, m-, gap-, etc. */
<div class="p-renge-4 m-renge-3 gap-renge-5">...</div>

Tip: Use consistent spacing values to build visual rhythm. The Fibonacci scale naturally creates a sense of balance. If you need something between space-4 (20px) and space-5 (32px), consider the intended visual weight — often space-4 is sufficient.

Typography

PHI ratio scale

Eight font sizes derived from the golden ratio. Each size is exactly {PHI.toFixed(4)} times the previous, creating a proportionally harmonious hierarchy.

Font sizes (base 16px)

ClassValue / DerivationCSS output
--renge-font-size-xs10px16 × φ⁻⁰·⁵ ≈ 10px
--renge-font-size-sm13px16 × φ⁻⁰·²⁵ ≈ 13px
--renge-font-size-base16pxbase (1.0)
--renge-font-size-lg26px16 × φ ≈ 26px
--renge-font-size-xl42px16 × φ² ≈ 42px
--renge-font-size-2xl68px16 × φ³ ≈ 68px
--renge-font-size-3xl110px16 × φ⁴ ≈ 110px
--renge-font-size-4xl177px16 × φ⁵ ≈ 177px

Line height scale

ClassValue / DerivationCSS output
--renge-line-height-xs1.2Tight, for labels and captions
--renge-line-height-sm1.4Compact, for small text
--renge-line-height-base1.6Standard, for body text
--renge-line-height-lg1.8Generous, for long-form content
--renge-line-height-xl2.0Spacious, for visual comfort

Letter spacing

ClassValue / DerivationCSS output
--renge-letter-spacing-tight-0.02emHeadings, display text
--renge-letter-spacing-normal0emBody text (default)
--renge-letter-spacing-wide0.05emSmall caps, emphasis
--renge-letter-spacing-ultra0.2emLabels, all-caps UI text

Usage example

/* Display heading */
h1 {
  font-size: var(--renge-font-size-3xl);      /* 110px */
  line-height: var(--renge-line-height-xs);   /* 1.2 tight */
  letter-spacing: var(--renge-letter-spacing-tight);
}

/* Body text */
p {
  font-size: var(--renge-font-size-base);     /* 16px */
  line-height: var(--renge-line-height-base); /* 1.6 */
}

/* Label or caption */
.label {
  font-size: var(--renge-font-size-sm);       /* 13px */
  text-transform: uppercase;
  letter-spacing: var(--renge-letter-spacing-ultra);
}

/* Tailwind: text-renge-xs, text-renge-sm, leading-renge-base, tracking-renge-wide */
<h1 class="text-renge-3xl leading-renge-xs">Heading</h1>
<p class="text-renge-base leading-renge-base">Paragraph</p>

Pro tip: Combine font-size with matching line-height for visual harmony. The progression from xs to 4xl maintains consistent visual weight relative to line length. Never use line-height alone; always pair with appropriate font-size.

Color Profiles

Six complete worlds

Six color systems, each with light and dark variants, all WCAG 2.1 AA certified. Switch profiles at runtime with no rebuild required.

Available profiles

ClassValue / DerivationCSS output
oceanCool periwinkle to deep indigodata-profile="ocean"
earthWarm parchment to deep soildata-profile="earth"
twilightSoft periwinkle to inky indigodata-profile="twilight"
fireSoft cream to deep red-browndata-profile="fire"
voidCool near-black to deep navydata-profile="void"
leafLight sage to forest greendata-profile="leaf"

Semantic color tokens

All colors are semantic — they adapt to the active profile and dark mode automatically.

ClassValue / DerivationCSS output
--renge-color-bgDocument backgroundAdapts to profile + mode
--renge-color-bg-subtleSubtle background layerSlightly elevated from bg
--renge-color-bg-mutedMuted backgroundFurther elevated
--renge-color-fgForeground (text)Primary text color
--renge-color-fg-subtleSubtle foregroundSecondary text
--renge-color-fg-mutedMuted foregroundTertiary text
--renge-color-accentPrimary accentCTA, highlights
--renge-color-accent-hoverHover state accentDarkened accent
--renge-color-borderBorder colorDefault border
--renge-color-border-subtleSubtle borderMinimal emphasis
--renge-color-border-focusFocus ring colorKeyboard focus
--renge-color-successSuccess statusWCAG AA compliant
--renge-color-warningWarning statusWCAG AA compliant
--renge-color-dangerDanger/error statusWCAG AA compliant

Usage example

<!-- HTML: Set profile on root element -->
<html data-profile="ocean" data-mode="light">
  ...
</html>

/* All colors reference the active profile */
.card {
  background: var(--renge-color-bg-subtle);
  border: 1px solid var(--renge-color-border-subtle);
  color: var(--renge-color-fg);
}

.button {
  background: var(--renge-color-accent);
  color: var(--renge-color-fg-inverse);
}

.button:hover {
  background: var(--renge-color-accent-hover);
}

/* Switch profiles at runtime (no rebuild) */
<script>
  document.documentElement.dataset.profile = "twilight";
  document.documentElement.dataset.mode = "dark";
</script>

/* Tailwind: bg-renge-bg, text-renge-fg, border-renge-border, etc. */
<div class="bg-renge-bg-subtle border border-renge-border-subtle p-renge-4">
  <p class="text-renge-fg">Content</p>
  <button class="bg-renge-accent text-renge-fg-inverse">Action</button>
</div>

Border Radius

Fibonacci scale

Five radius values (plus full pill radius) derived from Fibonacci × base unit. Used for cards, buttons, inputs, and other rounded elements.

ClassValue / DerivationCSS output
--renge-radius-00pxSharp corners
--renge-radius-14pxSubtle rounding (1 × 4)
--renge-radius-28pxButtons, inputs (2 × 4)
--renge-radius-312pxCards, surfaces (3 × 4)
--renge-radius-420pxLarge surfaces (5 × 4)
--renge-radius-532pxXL surfaces (8 × 4)
--renge-radius-full9999pxPill shape, circles

Usage example

/* Button: subtle rounding */
button {
  border-radius: var(--renge-radius-2);  /* 8px */
}

/* Card: more prominent rounding */
.card {
  border-radius: var(--renge-radius-3);  /* 12px */
}

/* Badge or pill */
.badge {
  border-radius: var(--renge-radius-full);
}

/* Avatar circle */
img {
  border-radius: 50%;  /* or var(--renge-radius-full) for square images */
}

/* Tailwind: rounded-renge-1, rounded-renge-2, rounded-renge-full */
<button class="rounded-renge-2">Button</button>
<div class="rounded-renge-3">Card</div>
<div class="rounded-renge-full">Pill</div>

Z-Index

Stacking context

Semantic z-index values that prevent stacking conflicts. Each tier is for a specific UI layer.

ClassValue / DerivationCSS output
--renge-z-dropdown100Select, datalist, popover
--renge-z-sticky200Sticky headers, scroll-fix elements
--renge-z-fixed300Fixed nav, sidebars
--renge-z-modal400Modal backdrop + dialog
--renge-z-toast500Toast notifications (topmost)

Usage example

/* Dropdown menu */
.dropdown {
  position: absolute;
  z-index: var(--renge-z-dropdown);  /* 100 */
}

/* Sticky navbar */
nav {
  position: sticky;
  z-index: var(--renge-z-sticky);    /* 200 */
}

/* Fixed sidebar */
aside {
  position: fixed;
  z-index: var(--renge-z-fixed);     /* 300 */
}

/* Modal backdrop */
.modal-backdrop {
  z-index: var(--renge-z-modal);     /* 400 */
}

.modal-dialog {
  z-index: calc(var(--renge-z-modal) + 1);  /* 401 */
}

/* Toast notification */
.toast {
  position: fixed;
  z-index: var(--renge-z-toast);     /* 500 */
}

Motion

Duration and easing

Fibonacci-based durations (100–5500ms) and 10+ easing curves. Create consistent, natural-feeling animations.

Duration scale (Fibonacci × 100ms)

ClassValue / DerivationCSS output
--renge-duration-1100msSnappy microinteractions
--renge-duration-2100msQuick feedback
--renge-duration-3200msStandard transitions
--renge-duration-4300msDeliberate animations
--renge-duration-5500msSlower, layered effects
--renge-duration-6800msExtended motion
--renge-duration-71300msLong sequences
--renge-duration-82100msExtended sequences
--renge-duration-93400msVery long motion
--renge-duration-105500msLanguorous effects

Easing curves

ClassValue / DerivationCSS output
--renge-easing-linearlinearNo acceleration
--renge-easing-ease-incubic-bezier(0.618, 0, 1, 1)Slow start
--renge-easing-ease-outcubic-bezier(0, 0, 0.382, 1)Slow end
--renge-easing-ease-in-outcubic-bezier(0.618, 0, 0.382, 1)Both
--renge-easing-springcubic-bezier(0.34, 1.56, 0.64, 1)Springy overshoot
--renge-easing-bouncecubic-bezier(0.68, -0.55, 0.265, 1.55)Bouncy
--renge-easing-back-incubic-bezier(0.6, -0.28, 0.735, 0.045)Pull back entrance
--renge-easing-back-outcubic-bezier(0.175, 0.885, 0.32, 1.275)Pull back exit
--renge-easing-elastic-incubic-bezier(0.68, -0.55, 0.265, 1.55)Elastic entrance
--renge-easing-elastic-outcubic-bezier(0.68, -0.55, 0.265, 1.55)Elastic exit

Usage example

/* Button hover — quick and snappy */
button {
  transition: background-color var(--renge-duration-2) var(--renge-easing-ease-out);
}

/* Smooth color transition */
.card {
  transition: all var(--renge-duration-3) var(--renge-easing-ease-in-out);
}

/* Animated entrance */
.modal {
  animation: slideIn var(--renge-duration-4) var(--renge-easing-ease-out);
}

/* Springy, playful interaction */
.button:active {
  animation: bounce var(--renge-duration-3) var(--renge-easing-spring);
}

/* Tailwind: duration-renge-2, ease-renge-ease-out, etc. */
<button class="transition-colors duration-renge-2 ease-renge-ease-out hover:bg-renge-accent">
  Hover me
</button>

Other Categories

Complete reference

Additional token categories for shadows, dimensions, and layout constraints.

Shadows & Elevation

10 elevation levels with WCAG-compliant opacity. Higher values create stronger depth perception.

/* 10 shadow levels */
--renge-shadow-1: 0 1px 2px rgba(0,0,0,0.05);
--renge-shadow-2: 0 2px 4px rgba(0,0,0,0.08);
/* ... through ... */
--renge-shadow-10: 0 20px 25px rgba(0,0,0,0.2);

/* Usage */
.elevated {
  box-shadow: var(--renge-shadow-5);
}

.card {
  box-shadow: var(--renge-shadow-3);
}

.modal-backdrop {
  box-shadow: var(--renge-shadow-8);
}

Dimensions (Width & Height)

Fixed sizes for common UI elements. Fibonacci-based progression.

/* Avatar size */
--renge-size-avatar-sm: 24px;
--renge-size-avatar: 32px;
--renge-size-avatar-lg: 52px;

/* Icon sizes */
--renge-size-icon-sm: 16px;
--renge-size-icon: 20px;
--renge-size-icon-lg: 24px;

/* Usage */
.avatar {
  width: var(--renge-size-avatar);
  height: var(--renge-size-avatar);
}

img.icon {
  width: var(--renge-size-icon);
}

Container (Max-width breakpoints)

5 max-width values for responsive containers. Derived from φ⁴ progression.

ClassValue / DerivationCSS output
--renge-container-sm524pxφ² × 200
--renge-container-md847pxφ³ × 200
--renge-container-lg1371pxφ⁴ × 200
--renge-container-xl2218pxφ⁵ × 200

Integration

Works everywhere.

Tokens integrate with React, Vue, Svelte, or vanilla JavaScript.

React

Use useRengeTheme() hook or RengeProvider wrapper for dynamic theme switching.

import { RengeProvider, useRengeTheme } from '@renge-ui/react';

function App() {
  return (
    <RengeProvider config={{ profile: 'ocean' }}>
      <ThemeSwitcher />
    </RengeProvider>
  );
}

function ThemeSwitcher() {
  const { profile, switchProfile } = useRengeTheme();
  return (
    <button onClick={() => switchProfile('twilight')}>
      Switch to Twilight
    </button>
  );
}

Vue 3

Access profile/mode via useRengeTheme() composable.

import { useRengeTheme } from '@renge-ui/vue';

export default {
  setup() {
    const { profile, mode, switchProfile } = useRengeTheme();

    return { profile, mode, switchProfile };
  }
};

Svelte

Reactive stores for theme management.

import { profile, mode, switchProfile } from '@renge-ui/svelte';

<button on:click={() => switchProfile('earth')}>
  Switch to Earth (currently: {$profile})
</button>

✨ WCAG 2.1 Level AA Certified

All color tokens meet 4.5:1 contrast ratio on light backgrounds. All breakpoints and spacing values verified for touch target accessibility (44×44px minimum). See the Accessibility reference for full compliance details.
Scale6.0