Stack

Flexbox container. Composes vertical and horizontal layouts using Fibonacci spacing tokens.

Vertical (default)

Horizontal + justify between

Horizontal + align center

<Stack gap="4">
  <div>First</div>
  <div>Second</div>
  <div>Third</div>
</Stack>

<Stack direction="horizontal" justify="between">
  <Text>Left</Text>
  <Text>Right</Text>
</Stack>

{/* Flex wrap via style prop */}
<Stack direction="horizontal" gap="3" style={{ flexWrap: "wrap" }}>
  <Badge>one</Badge>
  <Badge>two</Badge>
  <Badge>three</Badge>
</Stack>

Grid

CSS grid container with Fibonacci gap tokens. Accepts a number of equal columns or a custom template string.

3-column equal grid

Golden ratio split (1fr 1.618fr)

<Grid columns={3} gap="3">
  <div>1</div>
  <div>2</div>
  <div>3</div>
</Grid>

{/* Custom template — e.g. golden ratio split */}
<Grid columns="1fr 1.618fr" gap="4">
  <div>Narrow</div>
  <div>Wide (φ)</div>
</Grid>

{/* Per-axis gaps */}
<Grid columns={2} gapX="5" gapY="3">
  ...
</Grid>

Section

Page section wrapper with max-width constraint and automatic horizontal centering.

Centered with md max-width

<Section maxWidth="lg" paddingY="8" paddingX="5">
  <Heading>Page content</Heading>
  <Text>Body copy sits inside the max-width container.</Text>
</Section>

{/* Full-bleed with internal constraint */}
<div style={{ background: "var(--renge-color-bg-subtle)" }}>
  <Section maxWidth="xl" paddingY="7">
    <Heading>Wide section</Heading>
  </Section>
</div>

Heading

Semantic heading using the PHI-derived type scale. Level maps to h1–h6 and sets a proportional default size.

Levels 1–4 with default sizing

Color variants

<Heading level={1}>The golden ratio.</Heading>
<Heading level={2} color="accent">Section title</Heading>

{/* Override the default size for a level */}
<Heading level={3} size="2xl">Larger h3</Heading>

{/* PHI-derived line heights apply automatically */}
{/* h1/h2 → display (1.236), h3/h4 → heading (1.382) */}

Text

Inline or block text element with full access to the PHI type scale, color tokens, and weight options.

Size scale

Colors + weights

<Text size="lg" color="fg-subtle">Natural proportion.</Text>
<Text as="p" weight="medium" size="base">
  Fibonacci spacing.
</Text>
<Text size="xs" color="accent" weight="semibold">
  PHI = 1.618033...
</Text>

{/* Block-level text */}
<Text as="p" size="base" color="fg-subtle">
  Paragraph text using the base size — 16px, line-height 1.618 (φ).
</Text>

Divider

Horizontal or vertical rule rendered as an <hr>. Uses border color tokens for consistent visual weight.

Horizontal variants

Vertical

<Divider />
<Divider color="border" spacing="2" />
<Divider orientation="vertical" spacing="4" />

Button

Action element. Every variant, size, and color combination resolves to a CSS variable — no hardcoded values.

Variants

Sizes

Color schemes

Full width + disabled

<Button variant="solid" size="md" colorScheme="accent">
  Continue
</Button>

<Button variant="outline" colorScheme="danger" size="sm">
  Delete
</Button>

<Button variant="ghost" colorScheme="success">
  Confirm
</Button>

{/* Disabled state — native HTML attribute */}
<Button disabled style={{ opacity: 0.4, cursor: "not-allowed" }}>
  Unavailable
</Button>

{/* Extends all native button props */}
<Button onClick={handleSubmit} type="submit" fullWidth>
  Submit form
</Button>

Input

Text input with Renge sizing and validation state styling. Focus ring is handled with inline event handlers to stay in-system.

States

Sizes

<Input placeholder="Enter value" size="md" />
<Input state="error" placeholder="Invalid input" fullWidth />
<Input state="success" defaultValue="Confirmed" fullWidth />

{/* Controlled */}
<Input
  value={value}
  onChange={(e) => setValue(e.target.value)}
  placeholder="Controlled input"
  fullWidth
/>

FormField

Wraps any input with a label, optional helper text, and error text. Error overrides helper when both are present.

States

<FormField
  label="Email"
  htmlFor="email"
  helperText="We'll never share this."
>
  <Input id="email" type="email" fullWidth />
</FormField>

<FormField
  label="Username"
  htmlFor="username"
  required
  errorText="Username already taken."
>
  <Input id="username" state="error" fullWidth />
</FormField>

Card

Surface container with three visual variants. Padding and radius are token-driven.

Variants

Padding scale

<Card variant="elevated" padding="5" radius="3">
  <Heading level={3}>Card title</Heading>
  <Text color="fg-subtle">Supporting copy goes here.</Text>
</Card>

<Card variant="outlined" padding="4">
  <Stack gap="3">
    <Badge variant="success">Active</Badge>
    <Heading level={3}>Status card</Heading>
  </Stack>
</Card>

Badge

Compact inline label for status, category, or count. Six semantic variants map directly to the color token system.

Variants

Sizes

<Badge variant="success">Published</Badge>
<Badge variant="warning" size="sm">Beta</Badge>
<Badge variant="danger">Deprecated</Badge>
<Badge variant="info">New</Badge>
<Badge variant="accent" size="lg">Featured</Badge>

Chip

Dismissible tag with the same semantic color variants as Badge. Provide onDismiss to render a close button.

Variants

Dismissible (live demo)

{/* Static */}
<Chip variant="accent">Design system</Chip>

{/* Dismissible */}
<Chip variant="neutral" onDismiss={() => removeTag(id)}>
  Removable
</Chip>

{/* Dynamic tag list */}
{tags.map(tag => (
  <Chip
    key={tag.id}
    variant="accent"
    onDismiss={() => removeTag(tag.id)}
  >
    {tag.label}
  </Chip>
))}

Avatar

User avatar with image or initials fallback. Sizes follow the Fibonacci sequence × 4px.

Sizes — Fibonacci × 4px

Shapes + image

PH

circle

FB

square

image

{/* Initials fallback */}
<Avatar initials="RG" size="3" />

{/* Image with initials fallback */}
<Avatar
  src="/user.jpg"
  alt="Profile photo"
  initials="RG"
  size="4"
/>

{/* Square shape */}
<Avatar initials="FB" shape="square" size="3" />

Stat

Key metric display. Trend badges are color-coded via success/danger tokens. Value renders at 3xl — designed to be read at a glance.

Metrics

<Stat value="φ" label="Golden ratio" />

<Stat
  value="89"
  label="Fibonacci step"
  trend="up"
  trendValue="+34"
  caption="from step 9"
/>

<Stat
  value="0ms"
  label="Build time delta"
  trend="neutral"
  trendValue="no change"
/>

Alert

Contextual banner with left-border accent and semantic status. Renders with role="alert" for screen reader compatibility.

All statuses

Without title

<Alert status="info" title="Note">
  Informational context.
</Alert>

<Alert status="success" title="Deployed">
  Production build complete.
</Alert>

<Alert status="danger" title="Error">
  Something went wrong.
</Alert>

{/* No title — body only */}
<Alert status="warning">
  Approaching rate limit.
</Alert>

Spinner

Animated loading indicator. The CSS keyframe (rengeSpinnerSpin) is injected once at module load — no runtime overhead per instance.

Sizes

Colors

<Spinner size="md" color="accent" label="Loading tokens" />
<Spinner size="sm" color="fg-muted" />

{/* In a button */}
<Button variant="outline" disabled>
  <Stack direction="horizontal" gap="2" align="center">
    <Spinner size="sm" color="accent" />
    <span>Saving...</span>
  </Stack>
</Button>

Progress

Linear progress bar. Value is clamped 0–100. Track and fill colors reference semantic tokens.

PHI-derived values

<Progress value={61.8} color="accent" />
<Progress value={100} color="success" size="lg" />
<Progress value={30} color="danger" radius="none" />

{/* Controlled */}
<Progress
  value={uploadProgress}
  color="accent"
  size="md"
  label="Upload progress"
/>

Navbar

Navigation container. Composes with Stack to build any nav layout. Pass sticky to get fixed-top positioning.

Basic navigation

With border off

{/* Basic */}
<Navbar>
  <Stack direction="horizontal" justify="between" style={{ width: "100%" }}>
    <Text weight="semibold">Brand</Text>
    <Stack direction="horizontal" gap="4">
      <a href="/docs">Docs</a>
      <a href="/github">GitHub</a>
    </Stack>
  </Stack>
</Navbar>

{/* Sticky top */}
<Navbar sticky>
  <Stack direction="horizontal" justify="between" style={{ width: "100%" }}>
    <Text weight="semibold">Brand</Text>
    <ProfileToggle />
  </Stack>
</Navbar>

Token API

@renge-ui/tokens exports two ways to consume tokens: createRengeTheme() for generating CSS, and rengeVars for typed CSS variable references.

createRengeTheme(config?)

Generates a complete token set from mathematical first principles. Returns CSS ready to inject and a JS vars map.

import { createRengeTheme } from "@renge-ui/tokens";

const theme = createRengeTheme({
  profile:    "ocean",   // 'ocean' | 'earth' | 'twilight' | 'fire' | 'void' | 'leaf'
  mode:       "light",   // 'light' | 'dark'
  baseUnit:   4,         // Spacing multiplier in px — try 6 for denser UIs
  typeBase:   16,        // Root font size in px
  scaleRatio: 1.618,     // Typography scale ratio (φ = golden ratio)
  variance:   0,         // 0–1 tolerance drift (0 = exact math, deterministic)
  selector:   ":root",   // CSS selector to wrap the variables in
});

// theme.css   — full :root { --renge-* ... } string, ready to inject
// theme.vars  — Record<string, string> of every --renge-* variable
// theme.config — resolved config with all defaults applied

rengeVars

A statically typed object of CSS variable references. No runtime dependency — use it anywhere you need a var(--renge-*) string with IDE autocomplete.

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

// Color (22 semantic tokens, profile-reactive)
rengeVars.color.bg            // "var(--renge-color-bg)"
rengeVars.color.bgSubtle      // "var(--renge-color-bg-subtle)"
rengeVars.color.fg            // "var(--renge-color-fg)"
rengeVars.color.accent        // "var(--renge-color-accent)"
rengeVars.color.danger        // "var(--renge-color-danger)"
rengeVars.color.borderFocus   // "var(--renge-color-border-focus)"

// Spacing (Fibonacci × baseUnit, steps 0–10)
rengeVars.space[0]   // "var(--renge-space-0)"  → 0px
rengeVars.space[3]   // "var(--renge-space-3)"  → 12px (Fib[3] × 4)
rengeVars.space[5]   // "var(--renge-space-5)"  → 32px

// Typography (PHI scale, 8 steps)
rengeVars.fontSize.base  // "var(--renge-font-size-base)"
rengeVars.fontSize.lg    // "var(--renge-font-size-lg)"
rengeVars.lineHeight.base // "var(--renge-line-height-base)"

// Motion (Fibonacci × 100ms, steps 0–9)
rengeVars.duration[2]    // "var(--renge-duration-2)"  → 200ms
rengeVars.duration[5]    // "var(--renge-duration-5)"  → 800ms
rengeVars.easing.out     // "var(--renge-easing-ease-out)"
rengeVars.easing.spring  // "var(--renge-easing-spring)"

// Radius (Fibonacci × baseUnit, steps none/1–5/full)
rengeVars.radius[2]      // "var(--renge-radius-2)"   → 8px
rengeVars.radius.full    // "var(--renge-radius-full)" → pill

Integrating with another system

Use rengeVars to map Renge tokens to your own CSS variable names. This is the recommended pattern for adopting Renge alongside an existing design system.

import { createRengeTheme, rengeVars } from "@renge-ui/tokens";

const theme = createRengeTheme({ profile: "earth", mode: "light" });

// Map semantic Renge tokens → your system's variable names
const aliases: [string, string][] = [
  // Backgrounds
  ["--color-bg-primary",   rengeVars.color.bg],
  ["--color-bg-secondary", rengeVars.color.bgSubtle],
  ["--color-surface",      rengeVars.color.bgMuted],
  // Foreground
  ["--color-text",         rengeVars.color.fg],
  ["--color-text-muted",   rengeVars.color.fgSubtle],
  // Interactive
  ["--color-primary",      rengeVars.color.accent],
  ["--color-primary-hover",rengeVars.color.accentHover],
  // Status
  ["--color-error",        rengeVars.color.danger],
  ["--color-success",      rengeVars.color.success],
  ["--color-warning",      rengeVars.color.warning],
  // Spacing bridge
  ["--space-sm",           rengeVars.space[2]],
  ["--space-md",           rengeVars.space[4]],
  ["--space-lg",           rengeVars.space[5]],
];

const aliasCSS = `:root {
${aliases.map(([k, v]) => `  ${k}: ${v};`).join("\n")}
}`;

// Inject Renge base vars first, then your aliases on top
document.head.insertAdjacentHTML("beforeend",
  `<style>${theme.css}\n${aliasCSS}</style>`
);

All 22 semantic color tokens

Animations

15 named animations derived from the token system. Apply via the animation prop on any component that accepts it.

Available tokens

Live examples

{/* On any component that accepts animation prop */}
<Heading level={2} animation="breathe">
  Living proportion.
</Heading>

<Badge variant="accent" animation="pulse">
  New
</Badge>

<Card animation="bloom">
  <Text>Enters with bloom effect</Text>
</Card>

{/* Via CSS variable directly */}
<div style={{ animation: "var(--renge-animation-float)" }}>
  Floats gently.
</div>

Patterns

Common composition patterns using @renge-ui/react components.

Status card

Form with validation

Metric grid

{/* Every component uses only CSS custom properties */}
{/* Switch profiles and all colors update instantly */}
import { createRengeTheme } from "@renge-ui/tokens";

const theme = createRengeTheme({ profile: "twilight" });
// Inject theme.css and all components adapt — no re-render.