Shared monorepoSemantic tokensSanity CMSProduction-deployed

A design system that renders itself

Roaming Studios UI — shared components, semantic tokens, Sanity-driven pages.

Nothing here is documentation pasted over a mockup. This hero is _type: hero. Every section below is a live instance from packages/ui. Toggle component labels to read each block's _type, variant, and layoutId.

Case study · Design systems · Frontend architecture

Context

Several products, one engineering surface.

Roaming Studios, Maas Yoga, Frecuencia Humana, portfolio sites, and course landings needed distinct visual identities but repeated the same page patterns: hero, split narrative, card grids, bento blocks, pricing, FAQ. Rebuilding those patterns per project duplicated React markup, drifted spacing and color usage, and slowed every new landing.

Process

Constraints first, then structure.

Each decision came from a production requirement — not from a component library spec in isolation.

Core in packages/ui, thin apps

Components, resolvers, and Sanity schemas live in the monorepo package. Each deployment wires routing, globals.css, and env config. A fix to Card or splitSection propagates on the next deploy — no copy-paste between codebases.

Shared-first monorepo

Two-level color model

Level 1: palette tokens (accent-light, main-dark) backed by --color-* CSS vars in globals.css. Level 2: role props (surfaceColor, mainColor, textColor) that pick a palette token for a job — background, accent, or text ink. Rebrand = edit level-1 hex. Reskin a section = change level-2 assignment in the CMS document.

One palette · three roles

Variants, not page-specific components

Composition over inheritance. One Card covers plain, media-top, media-left, and media-background. One cardSection drives grid, bento, or slider via gridVariant. New page layouts are new Sanity documents — not new React components for every client.

CVA variants · DRY

Sanity as the page model

A page document holds an ordered sections[] array referencing section documents by _id. Each section type — hero, splitSection, cardSection, inlineHeading — exposes a fixed prop contract. ComponentGenerator routes _type to the correct renderer; resolvers map CMS fields to React props.

Schema-driven pages

TextBlock as the copy contract

Every section uses the same textBlock fields: eyebrow, heading, subheading, body, caption. Resolvers always produce the same molecule. CMS entries and this page share identical field names.

textBlock · TextBlock molecule

Headless sections

Hero, CardGrid, and CardBento deliberately omit internal headings. An inlineHeading precedes them when needed. That split keeps band dividers and section copy independent from layout orchestration.

Section types · no nested headings

Token architecture

Palette tokens anchor the system. Role props assign them.

Colors exist at two levels. Palette tokens — accent-light, main-dark, white-light — are named swatches. Each maps to a CSS custom property (--color-accent-light) with the hex for that site. Role props — surfaceColor, mainColor, textColor — do not define new colors. They pick a palette token for a job: background, accent, or text ink.

Same swatch · different role depending on context

Two levels

Anchors first. Roles second.

The token board edits level 1 — the --color-* values this page resolves. Section documents edit level 2 — which palette token fills each role. Enable component labels: surfaceColor: main, mainColor: highlight-1, textColor: highlight-1 is how this band's color is expressed as data.

Role change = composition · palette change = brand

Level 1

Palette tokens

The anchor layer. Every swatch is a ColorToken: main, accent-light, highlight-2-dark, white-light, … Each name maps 1:1 to a CSS var (--color-accent-light) in the site's globals.css. Components never hold hex — they hold names. colorMappings in theme.ts turns accent-light into bg-accent-light, text-accent-light, border-accent-light.

ColorToken · --color-{name} · Sanity ColorPicker

Level 2

Role props

Contextual assignment. surfaceColor selects which palette token paints the background — getSurfaceClasses('accent-light') → bg-accent-light. mainColor drives eyebrows, icon tint, CTA fill. textColor sets default ink for headings and body. The same token plays different roles: accent-light as surfaceColor on one card, mainColor on a bordered card with inverted: true.

surfaceColor · mainColor · textColor

Derived

Chained anchors

Some vars carry no hex. They reference palette tokens: --color-canvas: var(--color-white-dark), --shadow-card via color-mix with --color-black-default. Declared after the base palette to avoid circular references. Morphology tokens (--ui-radius-card, --ui-shadow-sm) default in roaming-studio.css, override per site in globals.css.

var() chains · no new colors

On this page

Three roles, three picks

This section's document sets surfaceColor: main for the background, mainColor: highlight-1 for accents, textColor: highlight-1 for copy. Edit a role in Sanity and the section re-composes. Edit --color-highlight-1-default in the token board and every element that picked highlight-1 updates together.

Visible in component labels

Component hierarchy

The stack that built this page.

Four layers with strict boundaries. Color logic, copy composition, and layout orchestration do not leak across them.

Sanity → ComponentGenerator → resolvers → React

Layer 1

Primitives

Atoms with CVA variants: Button, Text, Icon, Badge, Image, Input, Link. No layout logic. No CMS awareness. The CTAs, headings, and icons on this page.

packages/ui/primitives

Layer 2

Molecules

Composed units: TextBlock renders the copy being read. Card renders every tile in the grids. Media, Form. Accept role props and resolve surfaces through getSurfaceClasses.

packages/ui/molecules

Layer 3

Sections

Page blocks wired to Sanity schema: hero, splitSection, cardSection, inlineHeading, accordion, formSection. Each exposes layout props (paddingY, gridVariant, layoutId, orientation) and defers copy to textBlock.

packages/ui/sections

One schema field set, many surfaces.

The same cardSection _type drives bento, grid, or slider — controlled by gridVariant and layoutId, not by separate components. This page's decision grid and hierarchy bento are the same section type with different documents.

_type: cardSection · two layoutId values on this page

Layout system

Rhythm from data, not from page-level CSS.

Band alternation and bento placement are fields on section documents — not hand-written per route.

cardSection selects a layout engine via gridVariant and layoutId. Bento presets (bento-4-items-featured, bento-7-items-2-3-2, bento-4-items-3-top-featured-bottom) encode asymmetric spans once; any page reuses them by setting layoutId on the document. Card documents hold content and their own role props; the section document controls placement.

layoutId on sections 3 and 5 · role props on every band

Bento presets

layoutId selects a fixed grid template. Cards keep independent variant, media, and color props; the section only controls placement.

bento-4-items-3-top-featured-bottom · active in section 5

Page composition

A page document references section documents in order via sections[]. A cardSection references card documents via items[]. Structure is CMS data — components render whatever the documents specify.

page.sections[] → section docs → card refs

Grid · slider · bento

gridVariant: grid sets column count. slider adds slides, dots, autoplay. bento delegates to layoutId. Same section type, different layout engine — chosen per document.

One _type · three engines

Layout primitives

Section applies paddingY, max width, and surface classes. InlineHeading acts as a band divider between major blocks. Neither contains business copy — that lives in textBlock on the section or card document.

packages/ui/layout

Brand system

Same page. Different :root.

Brand differentiation is a CSS concern — not a fork of components.

Each deployment overrides the same semantic variable names in globals.css with different hex values. Components read bg-main, text-accent; they never hardcode palette values. Maas Yoga's purple-orange palette and Roaming Studios' violet-indigo palette share identical JSX. Frecuencia Humana adds scoped cycle palettes by aliasing semantic vars to --color-{cycle}-*. Brand swap operates at level 1 only: role assignments on each section document stay intact — the switcher replaces --color-* values, not document structure. Use the switcher to observe semantic stability with palette change.

No component forks per brand

Delivery process

How the system ships to production.

The pipeline that renders this page is the same pipeline that renders client landings.

Define palette tokens in the site's globals.css. Extend components in packages/ui when a pattern repeats across projects — not for a single page. Register section types in Sanity schema and wire resolvers. Compose pages in Studio: section documents, role props, layoutId, copy in textBlock. Validate in the UI showcase against the active token set. Publish via Sanity; Next.js renders through ComponentGenerator.

Tokens → components → schema → Studio → showcase → publish

Extend on repetition

A one-off layout stays a CMS composition. A pattern that appears across multiple landings becomes a layoutId, a section prop, or a new variant on an existing molecule.

System grows from reuse

No per-site component copies

Brand differences never justify duplicating Button, Card, or Hero. If the visual gap cannot close with tokens and props, the gap belongs in globals.css or a new variant — not a second component file.

Variants · not forks

Showcase before publish

PackageUIShowcase renders every primitive and section type against the active palette. Token and variant changes are verified there before they reach CMS-authored pages.

Dev validation · outside runtime

Self-demonstrating deliverable

A case study about a design system should not rely on static screenshots. Brand switcher, token board, and component labels expose what Studio fields control: live _type, live CSS vars, live role props, live remapping.

The page is the proof

Roaming Studios

A system that documents itself by being itself.

Tokens in CSS. Components in packages/ui. Pages in Sanity. Proof on this page.

React · Next.js · Sanity · TypeScript · CSS custom properties · Figma

Back to portfolio