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.