Add harness workflow and Material showcase design system

DESIGN.md

@@ -0,0 +1,290 @@
+# 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.