cadence-ui/DESIGN.md

# Design System: Cadence UI Material Runtime
**Repository:** cadence-ui  
**Status:** Active direction as of 2026-03-23

## 1. Visual Theme & Atmosphere

Cadence UI should feel like a **softly lit Material You showcase**, not a generic dashboard kit
and not a rotating gallery of unrelated skins. The visual language is **pastel-tonal, ambient,
rounded, and slightly theatrical**, borrowing the warmth and optimism of Google's Material You
presentations while staying usable as a real product UI system.

The overall mood is **luminous and calm**. Surfaces should feel like layered slabs of tinted light:
cream canvas, lilac containers, sage accents, and soft violet action tones. The system should feel
**premium without becoming severe**, **expressive without becoming noisy**, and **mobile-informed
without becoming toy-like**.

The experience should evoke the feeling of a polished launch demo:
- soft environmental glow instead of hard contrast
- large rounded geometry instead of sharp technical edges
- tonal surfaces instead of flat white cards
- gentle spatial motion instead of bouncy micro-interaction clutter
- one coherent design language instead of multiple competing visual personalities

**Key characteristics:**
- Warm cream backgrounds with subtle tinted atmospheric light
- Rounded "slab" components with generous radii
- Tonal color relationships derived from a single seed color
- Pastel purple and sage-green emphasis by default
- Mobile-product elegance scaled to desktop docs and app surfaces
- Motion that feels staged, floaty, and spatial rather than mechanical

## 2. Color Palette & Roles

Cadence UI is **dynamic-color first**. New screens should be described in terms of **roles**, not
hardcoded one-off fills. The seed color may change, but the role structure should stay stable.

### Default Seed Presets

- **Violet Seed** (`#6750A4`) - the default Material baseline. Use when no stronger palette
  choice exists.
- **Jade Seed** (`#0B8F83`) - cooler, calmer, more aquatic. Good for operational or wellness-like
  product surfaces.
- **Sunset Seed** (`#B75A46`) - warmer and more human. Good for editorial, consumer, or
  lifestyle-heavy screens.

### Default Tonal Foundation

These are the current default fallback values when the active palette is not overridden:

- **Warm Cream Canvas** (`hsl(22 18% 96%)`) - primary page background
- **Soft Surface Cream** (`hsl(22 12% 94%)`) - general surface background
- **Lilac Mist Surface** (`hsl(274 18% 92%)`) - default tonal container
- **Lilac Lifted Surface** (`hsl(274 22% 89%)`) - elevated tonal container
- **Sage Mist Surface** (`hsl(117 18% 86%)`) - strongest supporting container / accent slab
- **Ink Violet Text** (`hsl(259 6% 15%)`) - primary text and icon color
- **Muted Violet Text** (`hsl(259 10% 38%)`) - secondary text
- **Primary Violet** (`hsl(264 38% 45%)`) - active emphasis and focus color
- **Primary Violet Container** (`hsl(270 34% 87%)`) - filled action and highlighted slab
- **Tertiary Sage** (`hsl(128 18% 40%)`) - supporting accent color
- **Tertiary Sage Container** (`hsl(112 20% 86%)`) - soft secondary accent background
- **Outline Violet Gray** (`hsl(259 10% 56%)`) - structural outline color
- **Outline Variant** (`hsl(259 10% 84%)`) - low-emphasis borders and separators

### Role Rules

- **Backgrounds** should read as tinted light, never as flat white.
- **Containers** should come from surface-container roles, not arbitrary translucent cards.
- **Primary actions** should usually use `primary-container` rather than a fully saturated fill.
- **Secondary emphasis** should prefer sage/tertiary-container instead of introducing a new accent.
- **Borders** should be whisper-soft or transparent. Hard dividers are the exception, not the default.
- **Errors** should use the error container family rather than loud red fills.

### Dynamic Color Principle

When generating new screens, treat color like this:

1. Pick a seed color.
2. Generate a full tonal family from that seed.
3. Map the resulting tones to stable semantic roles.
4. Keep the component geometry and motion language unchanged.

Do **not** solve personalization by introducing a new skin. Personalization comes from **seed-driven
tonal shifts**, not from changing the entire design language.

## 3. Typography Rules

**Primary Font Family:** Google Sans Text / Google Sans / Roboto Flex / Roboto  
**Display Font Family:** Google Sans Display / Google Sans / Roboto Flex / Roboto

The typography should feel **friendly, modern, and softly engineered**. It should not feel
editorial-serif, brutalist, developer-minimal, or luxury-fashion. The character is **rounded,
high-legibility, and quietly optimistic**.

### Hierarchy & Weights

- **Display Headlines:** Semibold weight, `clamp(2.75rem, 4vw, 4.75rem)`, tight tracking
  (`-0.02em`), line-height `1.1`
- **Primary Section Headlines:** Semibold weight, `2.25rem` or `1.75rem`, line-height `1.1-1.3`
- **Card / Panel Titles:** Semibold weight, `1.375rem`, line-height `1.3`
- **Body Text:** Regular weight, `1rem`, line-height `1.5`
- **Supporting Text:** Regular weight, `0.875rem`, line-height `1.5`
- **Eyebrow / Small Label Text:** `0.75rem` or `0.875rem`, uppercase only when used sparingly,
  tracking around `0.12em`
- **Buttons:** Medium to semibold presence through weight and shape, never all-caps shouting

### Typography Principles

- Headline scale should feel **heroic but rounded**, not sharp or corporate.
- Body copy should feel **quiet and readable**, letting color and space carry the emotional load.
- Eyebrow text is allowed, but only as a small framing device.
- Avoid serif display typography, condensed newspaper styling, and overly technical monospace accents.
- Large headlines should often be **left-aligned** and allowed to breathe.

## 4. Component Stylings

### Buttons

- **Shape:** fully pill or near-pill; default radius should feel almost capsule-like
- **Primary Button:** use `primary-container` with darker on-primary-container text
- **Secondary Button:** use the sage / tertiary container family
- **Ghost Button:** no visible container at rest; reveal a tonal hover plate on interaction
- **Subtle Button:** pale lifted slab, close to the surrounding tonal field
- **Hover Behavior:** gentle lift (`translateY(-1px)`), slight scale, soft shadow bloom
- **Press Behavior:** subtle compression, never dramatic squash
- **Tone:** polished and tactile, not loud, glossy, metallic, or game-like

### Cards & Surfaces

- **Corner Radius:** large and soft; standard cards should feel more like 28px slabs than desktop cards
- **Borders:** usually transparent
- **Depth:** use soft diffused shadow and tonal contrast before introducing visible strokes
- **Accent Card:** use primary-container tinting, never a neon or glass effect
- **Interactive Cards:** lift gently and scale microscopically; feel buoyant, not jumpy

### Inputs

- **Shape:** rounded but not full-pill in most cases
- **Background:** lifted tonal field rather than pure white
- **Border:** often transparent by default
- **Focus State:** soft violet glow ring plus tonal shadow bloom
- **Placeholder:** muted violet-gray
- **Overall Feel:** touch-friendly, calm, and integrated into the tonal field

### Panels, Dialogs, Popovers

- **Background:** elevated tonal container with slightly brighter internal light
- **Border:** transparent by default
- **Shadow:** deeper than cards, but still diffused and soft
- **Overlay:** blurred and dimmed, never harsh black
- **Motion:** smooth rise/fade with restrained speed; should feel spatial and deliberate

### Switches & Toggles

- **Track:** soft tonal channel
- **Checked Track:** primary-container, not fully saturated primary
- **Thumb:** bright neutral at rest, richer violet when active
- **Behavior:** smooth slide with calm easing; no spring snap

### Skeletons & Loaders

- **Skeleton Color:** muted tonal slab
- **Shimmer:** soft highlight pass that feels like light moving over frosted material
- **Spinners:** clean and minimal; motion should feel controlled and premium

## 5. Motion Language

Cadence UI should use **one motion language** plus a **static accessibility fallback**. Motion is
not a style pack. It is part of how the system communicates state and hierarchy.

### Motion Personality

- Calm, floaty, and spatial
- Slightly cinematic in hero/showcase moments
- Never bouncy, elastic, or playful-for-its-own-sake
- Built on ease-out curves that feel like soft deceleration

### Timing Guidance

- **Instant feedback:** ~120ms
- **Core state change:** ~180ms
- **Larger surface movement:** ~280ms
- **Deliberate ambient choreography:** ~360ms and above

### Approved Motion Patterns

- Soft rise / fade for surface entry
- Hover lift with small shadow bloom
- Press compression with minimal scale-down
- Slow floating or drifting ambient motion for showcase-only compositions
- Breathing accent glows or tonal pulses for decorative context

### Motion Rules

- Animate **transform**, **opacity**, and **shadow**; avoid layout-heavy animation
- Ambient motion belongs in showcase or hero surfaces, not on every control
- Exit motion should be faster than enter motion
- Respect reduced/static motion at all times
- Never use bounce, elastic easing, jitter, or constant busy loops across core UI

## 6. Layout Principles

### Structural Direction

Cadence UI layouts should feel like a **mobile-first visual language expanded to desktop**. Even on
large canvases, interfaces should maintain the rounded, stacked, tonal quality of contemporary
mobile surfaces.

### Spacing & Rhythm

- Use generous spacing to create a sense of premium calm
- Tighten within components, relax between sections
- Default spacing should feel deliberate, not grid-default or generic Tailwind spacing everywhere
- Prefer larger top-level section gaps than dense dashboard compression

### Alignment

- Headlines and body content should generally be left-aligned
- Centering is reserved for hero/showcase moments and empty states
- Use layered blocks and offset compositions when you need drama, not arbitrary asymmetry

### Showcase / Marketing-like Surfaces

For high-visibility demo pages:

- Use environmental light pools and blurred radial tints
- Layer device-like slabs or floating cards with overlap
- Let one hero composition dominate rather than filling the canvas with equal-weight content
- Create a clear front plane, middle plane, and background glow plane

### Product / Application Surfaces

For practical product screens:

- Use tonal grouping instead of borders to define regions
- Keep hierarchy obvious in under two seconds
- Maintain touch-friendly control sizes and generous internal padding
- Avoid the generic "card grid + icon + heading + paragraph" AI layout pattern

## 7. Design System Notes for Stitch / AI Generation

When using Stitch or any other AI design generator, this file should be treated as the
**source of truth for design direction**.

### Language to Use

Use phrases like:

- "softly lit Material You showcase"
- "pastel-tonal slabs with large rounded geometry"
- "warm cream canvas with lilac and sage tonal containers"
- "dynamic color derived from a single seed"
- "ambient spatial motion with restrained hover lift"

Avoid phrases like:

- "multiple skins"
- "glassmorphism"
- "neon"
- "cyber"
- "dark dashboard"
- "minimal monochrome admin panel"
- "brutalist"

### Component Prompt Examples

- "Create a dashboard hero using large rounded tonal slabs, warm cream background, lilac and sage containers, and softly staged Material motion."
- "Design a primary action button using a primary-container fill, dark violet text, pill geometry, and a gentle hover lift."
- "Build a settings card with a large 28px slab radius, transparent border, soft diffused shadow, and a tonal input field embedded into the same color family."
- "Generate a dialog that feels like an elevated Material container, with blurred overlay, soft entry rise, and large rounded corners."

### Iteration Rules

When refining screens:

1. Change one layer at a time: color, spacing, geometry, or motion.
2. Preserve the single Material language.
3. Prefer changing tonal roles before changing component structure.
4. Prefer changing seed color before inventing a new theme family.
5. If a screen starts to look like a different design system, pull it back.

### Non-Negotiables

- One visual language
- Dynamic color from a seed
- Tonal surfaces over flat white cards
- Large radii
- Calm spatial motion
- Reduced/static fallback

This repository should feel like **one memorable system**, not a catalog of styling experiments.