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
Process
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
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
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
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
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
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
Same swatch · different role depending on context
Two levels
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
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
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
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
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
Sanity → ComponentGenerator → resolvers → React
Layer 1
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
React · Next.js · Sanity · TypeScript · CSS custom properties · Figma