Foundations
Colors, typography, spacing, surfaces, and animations — the building blocks of the Work Forward design system.
Start here
Check the foundation rules before composing chat shells, inline cards, or artifact surfaces.
Use when
You need token intent, typography hierarchy, or a source-of-truth read on surface depth.
Do not use when
You only need a finished recipe. Go to App Surfaces or Navigation & Shells for composed guidance.
Surface Stack
4-level surface hierarchy: Ground → Card → Raised → Elevated. Each level gains ~4% lightness.
What it is for
Define depth and contrast before any component-level styling decisions are made.
Use when
You are choosing shell layers, card depth, or whether a context rail should visually step above the main body.
Do not use when
You are trying to solve a hierarchy problem with raw color changes instead of depth and spacing.
Related patterns
Navigation & Shells · App Surfaces
Escalation path
Ground for page canvas, card for main work, raised or elevated only when the surface truly needs separation.
Developer details
Start from these files when you need to trace the live implementation.
src/shared/styles/globals.css — :root block
Ground (S0)
--surface-ground
Card (S1)
--surface-card
Raised (S2)
--surface-raised
Elevated (S3)
--surface-elevated
Accent Colors
Amber accent system — universal trades recognition (DeWalt, CAT, Klein).
Primary (Amber)
--accent-primary
Primary Hover
--accent-primary-hover
Primary Muted
--accent-primary-muted
Secondary (Teal)
--accent-secondary
Text Hierarchy
Primary
--text-primary
Secondary
--text-secondary
Tertiary
--text-tertiary
On Accent
--text-on-accent
Semantic Colors
Success
--status-success
Warning
--status-warning
Error
--status-error
Destructive
--destructive
Borders
Default
--border-default
Hover
--border-hover
Focus
--border-focus
Ring
--ring
shadcn/ui Mappings
Core color tokens mapped via @theme inline in globals.css.
Background
--background
Foreground
--foreground
Card
--card
Card Foreground
--card-foreground
Popover
--popover
Primary
--primary
Primary Foreground
--primary-foreground
Secondary
--secondary
Muted
--muted
Muted Foreground
--muted-foreground
Accent
--accent
Input
--input
Chart Colors
Chart 1
--chart-1
Chart 2
--chart-2
Chart 3
--chart-3
Chart 4
--chart-4
Chart 5
--chart-5
Sidebar Colors
Sidebar
--sidebar
Sidebar Foreground
--sidebar-foreground
Sidebar Primary
--sidebar-primary
Sidebar Accent
--sidebar-accent
Sidebar Border
--sidebar-border
Typography
Host-fit inline surfaces should inherit the system stack. The brand pair stays available for fullscreen or public KnearMe surfaces that need more identity.
Developer details
Start from these files when you need to trace the live implementation.
src/shared/styles/globals.css — @theme inline fonts
Platform surfaces — system stack
Thread and panel titles should feel native in the host.
Page titles, rails, and inline cards now default to the system stack.
Reserve heavier display personality for product-owned fullscreen moments.
Brand pair — fullscreen or public KnearMe moments
Red Hat Display for marketing and high-identity hero treatments.
IBM Plex Sans remains the KnearMe body face when the product owns the full canvas and does not need to visually disappear into a host thread.
Body rhythm
Body Large (18px) — Used for premium/spacious layouts with generous line height.
Body Base (16px) — The default text size with comfortable line height for reading.
Body Small (14px) — Compact text for information-dense displays like dashboards.
Caption / Label (12px) — Metadata, labels, and supplementary text.
Monospace
font-mono — Used for code, technical values, CSS variables.
Heading Styles (Token Dimension)
4 heading styles from HeadingStyleSchema — AI selects based on business personality.
Developer details
Start from these files when you need to trace the live implementation.
src/shared/lib/design/tokens.ts — HEADING_CLASSES
| Token | Tailwind Classes |
|---|---|
| bold | font-display font-bold tracking-tight |
| elegant | font-display font-bold tracking-tight |
| industrial | font-mono uppercase tracking-widest text-sm |
| warm | font-display font-bold tracking-normal |
bold
Professional Masonry Work
elegant
Professional Masonry Work
industrial
Professional Masonry Work
warm
Professional Masonry Work
Spacing Density
3 spacing levels from SpacingSchema — controls vertical rhythm between sections.
Developer details
Start from these files when you need to trace the live implementation.
src/shared/lib/design/tokens.ts — SPACING_CLASSES
| Token | Classes (container / section / gap) |
|---|---|
| compact | space-y-4 / py-4 / gap-3 |
| comfortable | space-y-8 / py-8 / gap-6 |
| spacious | space-y-12 / py-12 / gap-8 |
compact
comfortable
spacious
Surface Levels
4-level surface stack. Hover each card to see the border-hover progression.
Developer details
Start from these files when you need to trace the live implementation.
src/shared/styles/globals.css — surface-ground through surface-elevated
Ground (S0)
Page background
Card (S1)
Content cards
Raised (S2)
Interactive/hover
Elevated (S3)
Popovers, menus
Shadow System
Depth and elevated shadows for cards and interactive elements.
Developer details
Start from these files when you need to trace the live implementation.
src/shared/styles/globals.css — @layer utilities
shadow-xs
Subtle default
shadow-depth
Card depth
shadow-elevated
Interactive elements
Animations
10 animation keyframes. Click each button to trigger the demo.
Developer details
Start from these files when you need to trace the live implementation.
src/shared/styles/globals.css — @keyframes
Fade Up
animate-fade-up
Fade In
animate-fade-in
Scale In
animate-scale-in
Slide In Right
animate-slide-in-right
Message In
animate-message-in
Canvas Item In
animate-canvas-item-in
Chip Slide In
animate-chip-slide-in
Typing Fade
animate-typing-fade
Wave Bar
animate-wave-bar
Status Breathe
animate-status-breathe
Border Radius
Theme-driven radius tokens from --radius CSS variable (default 0.5rem).
sm
md
lg
xl
full