Reference · shadcn/ui Maia + GSAP

Build consistent.
Move with purpose.
Stay on brand.

A living reference for brand colors, GSAP motion presets, and component customizations. shadcn/ui (Maia style, Gray theme) is the design system — this repo documents everything we add on top.

shadcn/ui · Maia style Gray base color System UI + Lora + Poppins Hugeicons Tailwind v4 · OKLCH GSAP v3 Large radius (0.875rem)

Section 01

Typography

Lora (serif) for h0–h1, Poppins for h2–h4 (and light-weight alternates h0-alt / h1-alt), system UI for body text and UI, Geist Mono for code.

h0The quick brown

The quick brown fox

h0-altThe quick brown

h1-altThe quick brown fox

The quick brown fox

The quick brown fox jumps

The quick brown fox jumps over

body

The quick brown fox jumps over the lazy dog. Body text uses the system font stack.

codeconst theme = "gray-maia";

Display & H1 Font

Lora (serif) · 400–700
h0 (400) and h1 (700) only

Headline Font

Poppins · 300, 600–800
h2–h4 + h0-alt / h1-alt (300)

Body Font

System UI · 400–700
All body, buttons, inputs

Code Font

Geist Mono · 400
Code blocks, inline code

Icons

Hugeicons
npm i hugeicons-react

Section 02

Logo

Two logo variants: the way*ID pill badge and the Lineage*Labs text wordmark. Both have distinct light and dark mode treatments and animated GSAP reveals.

way*ID Badge

Plain text wordmark — no border, no background. Navy text on light, near-white on dark. The * uses brand offset blue.

Light Mode default

way*ID way*ID way*ID

Dark Mode inverted

way*ID way*ID way*ID

Animated Reveal back.out(1.7) center stagger

Light

way*ID

Dark

way*ID

Lineage*Labs Wordmark

Text wordmark in Lora. Weight 400 on both modes. Light: --brand-highlight-navy text + asterisk. Dark: --brand-surface text, --brand-offset-green asterisk.

Light Mode Lora 400 --brand-highlight-navy

Lineage*Labs Lineage*Labs Lineage*Labs

Dark Mode Lora 400 --brand-surface

Lineage*Labs Lineage*Labs Lineage*Labs

Animated Reveal left stagger asterisk pop

Light

Lineage*Labs

Dark

Lineage*Labs

Usage Rules

Clear Space

Maintain at least 1x the badge height as clear space on all sides of the logo.

Minimum Size

Badge text must never be smaller than 12px. Below that, use the badge-only variant.

No Modifications

Never rotate, stretch, recolor, add shadows, or apply effects to the logo. Use it exactly as specified.

Mode Matching

Always use the light logo on light backgrounds and the dark logo on dark backgrounds. Never mix.

Spec Reference — way*ID Badge

Property	Light Mode	Dark Mode
Background	transparent	transparent
Text color	`--brand-highlight-navy`	`--brand-highlight-light`
Border	`--brand-highlight-navy` (1.5px solid)	`--brand-highlight-light` (1px solid)
Radius	`9999px` (pill)
Font	Poppins, 600 weight, `-0.08em` letter-spacing
Animation	Reveal: `scale 0.94→1, opacity 0→1, back.out(1.7), 300ms` Post-reveal: `* cycles lavender → green → yellow → coral every 1.4s (power2.inOut crossfade)`

Spec Reference — Lineage*Labs Wordmark

Property	Light Mode	Dark Mode
Text color	`--brand-highlight-navy`	`--brand-highlight-light`
Asterisk color	`--brand-offset-green`	`--brand-offset-green`
Font	Lora, 400 weight, `-0.03em` letter-spacing	Lora, 400 weight, `-0.03em` letter-spacing
Default size	`64px` / line-height `82px`
Animation	Phase 1: `chars stagger 0.04s from left, blur 6→0 + x -16→0 + y 8→0, power2.out, 400ms` Phase 2: `asterisk scale pop 1→1.28→1, sine.out + power2.inOut, 700ms (keyframes)`

Section 03

Brand Colors

These are additive — they never replace shadcn semantic tokens. Apply via --brand-* only when a design explicitly calls for brand treatment.

Highlights

Navy

#0E1233

--brand-highlight-navy

Light

#FAFAFA

--brand-highlight-light

Surfaces

Surface Light

#E8E5DE

--brand-surface-light

Surface Dark

#0E1233

--brand-surface-dark

Offset Accents — Light surface

Lavender

#7267E2

--brand-offset-lavender-light

Green

#A0D246

--brand-offset-green-light

Yellow

#F8BC4D

--brand-offset-yellow

Coral

#FF7236

--brand-offset-coral-light

Blue

#006CDB

--brand-offset-blue-light

Highlights + Offsets — Dark / Blue surface

Light

#FAFAFA

--brand-highlight-light

Lavender

#B4AFE7

--brand-offset-lavender-dark

Green

#D5FD8D

--brand-offset-green-dark

Yellow

#F8BC4D

--brand-offset-yellow

Coral

#FF814C

--brand-offset-coral-dark

Blue

#2886E6

--brand-offset-blue-dark

When to use

Hero sections, marketing headings, CTAs, status badges, illustrations, gradient accents — any element the design explicitly marks as brand colored.

When NOT to use

Buttons, inputs, cards, body text, borders, error states, focus rings — use shadcn semantic tokens for all standard UI.

Sidebar Tokens

Eight --sidebar-* tokens power the shadcn Sidebar component. Do not use them as general color tokens outside of sidebar contexts.

Token	Purpose
`--sidebar`	Sidebar panel background
`--sidebar-foreground`	Sidebar text
`--sidebar-primary`	Active nav item background
`--sidebar-primary-foreground`	Active nav item text
`--sidebar-accent`	Hover state background
`--sidebar-accent-foreground`	Hover state text
`--sidebar-border`	Sidebar border / divider
`--sidebar-ring`	Focus ring inside sidebar

Tailwind v4 @theme block

tokens/colors.css includes a commented-out @theme inline block (Section 3). Copy it into your project's root CSS when using Tailwind v4 — it maps all CSS variables to Tailwind utilities (bg-primary, text-muted-foreground, etc.).

Sidebar vs. standard tokens

For page layouts that include a sidebar, use standard --background, --border, etc. tokens. Only use --sidebar-* tokens when styling the shadcn Sidebar component itself.

Section 04

Spacing

4px grid — every value is a multiple of 4px (0.25rem). Maia style means generous spacing: when in doubt, size up.

Base Scale

Token	rem	px	Tailwind
`0.5`	0.125	2	0.5
`1`	0.25	4	1
`2`	0.5	8	2
`3`	0.75	12	3
`4`	1	16	4
`5`	1.25	20	5
`6`	1.5	24	6
`8`	2	32	8
`10`	2.5	40	10
`12`	3	48	12
`16`	4	64	16
`20`	5	80	20
`24`	6	96	24

Semantic Tokens

Inline

inline-xs · 4px · Icon-to-label gap inline-sm · 8px · Button icon gap inline-md · 12px · Nav link gap

Component Padding

component-xs · 6px · Badge, dropdown chrome component-sm · 10px · Button / input padding component-md · 16px · Compact card component-lg · 24px · Maia card default component-xl · 32px · Dialog / sheet

Gap (between siblings)

gap-xs · 8px · Tight list items gap-sm · 12px · Form fields gap-md · 16px · Card grid gap gap-lg · 24px · Section content gap-xl · 32px · Major blocks

Section & Page

section-sm · 48px · Compact section section-md · 64px · Default section section-lg · 96px · Major page section section-xl · 128px · Hero / footer page-gutter · 24px → 32px page-max-width · 1100px

Component Spacing

Component	Padding	Gap / Notes
Button	`0.625rem 1.25rem`	Icon gap: 0.5rem
Button sm	`0.375rem 1rem`	—
Button lg	`0.875rem 2rem`	—
Input	`0.625rem 1.25rem`	Label gap: 0.5rem
Card	`1.5rem` (p-6)	Internal: 1rem
Dialog	`2rem` (p-8)	Actions: 0.75rem
Sheet	`1.5rem` (p-6)	—
Dropdown	`0.375rem` chrome	Item: 0.5rem 0.75rem
Toast	`1rem 1.25rem`	—
Accordion	`1rem 0.75rem`	Content: 1rem
Badge	`0.2rem 0.625rem`	—
Tabs	`0.5rem 0.875rem`	List gap: 0.25rem

Guidelines

4px grid

All spacing is a multiple of 4px (0.25rem). No arbitrary values like 0.3rem or 7px.

Generous by default

Maia style. Cards get p-6 not p-4. Sections get mb-20 not mb-12. When in doubt, size up.

Gap over margin

Use flexbox/grid gap for layout spacing. Avoid margin for sibling separation.

44px touch targets

Interactive elements must be ≥44×44px. Use padding or min-height to reach this.

Section 05

Responsive Design

Mobile-first. Default CSS targets mobile. Override upward with Tailwind md: and lg: prefixes. The primary layout breakpoint is 768px (md:).

Breakpoint Scale

Token	Min-width	Tailwind	Use
`mobile`	0px	(default)	Base styles — all CSS starts here
`sm`	640px	`sm:`	Large phones landscape — rarely needed
`md`	768px	`md:`	Primary breakpoint — layout shifts here
`lg`	1024px	`lg:`	Desktop — full multi-column layouts
`xl`	1280px	`xl:`	Wide desktop — optional refinement

Live Grid Demo — resize your browser to see columns change

📱 Mobile — 1 column

Card 1

Single column on mobile, 2 at md:, 3 at lg:

Card 2

Component padding stays the same at every breakpoint

Card 3

Only layout and page-level spacing adapt

Card 4

Typography scales fluidly with clamp()

Card 5

Page gutter: 1.5rem mobile → 2rem desktop

Card 6

Touch targets stay ≥44px on all screens

Container Behavior

Content area max-width: 1100px · centered · auto margins

◀ Gutter: 1.5rem mobile / 2rem desktop ▶

What Changes vs. What Stays Fixed

Element	Mobile → Desktop	Changes?
Component padding	Same everywhere	No
Page gutter	1.5rem → 2rem	Yes — at md:
Section spacing	May compress one step	Yes — below md:
Grid columns	1 → 2 → 3	Yes — at md: and lg:
Headlines	Fluid via clamp()	Fluid
Body text	1rem fixed	No
Touch targets	44px minimum	No

Fluid Typography

Element	Value	Min → Max	Notes
`h0`	`clamp(3.5rem, 8vw, 6rem)`	56px → 96px	Display / hero text
`h1`	`clamp(2rem, 4vw, 2.75rem)`	32px → 44px	Page titles
`h2`	`clamp(1.5rem, 3vw, 1.75rem)`	24px → 28px	Section titles
body	`1rem` (fixed)	16px	No scaling

Mobile Compaction — below 768px

Layout-level spacing compresses on mobile. Component-level spacing never changes.

Token	Desktop	Mobile (<768px)	Tailwind
`section-xl`	128px	96px	`py-24 md:py-32`
`section-lg`	96px	64px	`py-16 md:py-24`
`section-md`	64px	48px	`py-12 md:py-16`
`section-sm`	48px	32px	`py-8 md:py-12`
`gap-xl`	32px	24px	`gap-6 md:gap-8`
`gap-lg`	24px	16px	`gap-4 md:gap-6`
`gap-md`	16px	16px (fixed)	`gap-4`

Compresses on mobile

• Section spacing (one step down) • Layout gaps (gap-lg, gap-xl) • Page gutter (24px → 32px at md:) • Grid columns (1 → 2 → 3) • Headlines (fluid via clamp())

Fixed at every size

• Component padding (cards p-6, buttons, inputs) • Small/medium gaps (gap-xs–gap-md) • Border radius • Touch targets (44px min) • Animation durations & easings

Guidelines

Mobile-first CSS

Default styles target mobile. Override upward with md: and lg:. Never write desktop-first CSS.

Layout shifts at md:

768px is where single-column becomes multi-column. Sidebars appear. Navigation expands.

Fluid typography

Use clamp() for h0–h2. No breakpoint-based font-size changes. Body stays at 1rem.

Fixed component padding

Buttons, cards, inputs keep the same padding at every screen size. Only page-level spacing adapts.

Section spacing compresses

Section margins and large gaps (gap-lg, gap-xl) each drop one step below md:.

Restructure, don't hide

If content matters on desktop, show it on mobile. Change layout (stack, reorder), not visibility.

Grid: 1 → 2 → 3 columns

grid-cols-1 → md:grid-cols-2 → lg:grid-cols-3. Standard pattern for card grids.

Mobile Overflow Prevention — minimum viewport: 320px

Prevent content cutoff on narrow screens. All layouts must work at 320px wide (iPhone SE / split-screen).

#	Rule	Implementation
1	Minimum viewport	All layouts must be usable at 320px wide
2	Table scroll wrappers	`<div class="table-scroll">` around every `<table>`
3	Code block overflow	`pre { overflow-x: auto; }`
4	Break long words	`body { overflow-wrap: break-word; }`
5	Safe grid minimums	`minmax(min(Xpx, 100%), 1fr)` — max safe: 272px at 320px
6	Contain media	`img, video, svg { max-width: 100%; height: auto; }`
7	Clamp overlay widths	Tooltips, toasts, popovers: `max-width: calc(100vw - 3rem)`
8	Collapse inline grids	Multi-column → single-column below `sm` (640px)
9	Block page scroll	`html { overflow-x: clip; }` — use `clip` not `hidden`

Global CSS Resets

Add to every project's global stylesheet:

/* Mobile overflow prevention */
html { overflow-x: clip; }
body { overflow-wrap: break-word; }
img, video, svg, canvas, iframe { max-width: 100%; height: auto; }
pre { overflow-x: auto; }
.table-scroll { overflow-x: auto; -webkit-overflow-scrolling: touch; }
      

Safe Grid Pattern

/* ✅ Safe — collapses to 100% on narrow screens */
grid-template-columns: repeat(auto-fill, minmax(min(220px, 100%), 1fr));

/* ❌ Unsafe — overflows at 320px when min > 272px */
grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
      

Vertical Content & Fixed Heights

Fixed-height containers (height: 100vh + overflow: hidden) are the most common cause of vertical content clipping on mobile. Content that fits on desktop often doesn't fit on a phone.

#	Rule	Implementation
1	`min-height` not `height`	Use `min-height: 100dvh` — content can grow beyond viewport
2	Slides scroll on mobile	Slide/carousel containers: `overflow-y: auto` below `md:`
3	No `overflow: hidden` on content	Only for decorative wrappers (border-radius, image crops)
4	`dvh` not `vh`	`100vh` includes browser chrome on mobile. Use `100dvh`.
5	Reduce density or scroll	If 3 cards don't fit, scroll within slide or show fewer per slide

/* ✅ Section grows with content */
.hero { min-height: 100dvh; }

/* ❌ Section clips content that doesn't fit */
.hero { height: 100vh; overflow: hidden; }

/* ✅ Slide scrolls internally on mobile */
.slide { height: 100dvh; overflow-y: auto; }
@media (min-width: 768px) {
  .slide { overflow-y: visible; }
}

/* ✅ dvh with vh fallback */
.full-screen {
  min-height: 100vh;   /* fallback */
  min-height: 100dvh;  /* dynamic */
}
      

min-height not height

min-height: 100dvh lets content grow. height: 100vh clips it.

Slides scroll on mobile

Carousel/slide containers need overflow-y: auto below md:. Content that fits on desktop rarely fits on a phone.

dvh not vh

100vh includes browser chrome on mobile. 100dvh adjusts dynamically. Always provide vh fallback.

Sidebar Layout

Breakpoint	Behavior
Mobile (default)	Sidebar hidden — use `Sheet` (mobile nav drawer) to reveal
`md:` (768px)	Side-by-side — sidebar 280px fixed, content fills remaining width

Mobile sidebar pattern

Use a shadcn Sheet component (entrance: slideInLeft, exit: slideOutLeft) triggered by a hamburger button. Sheet width: min(280px, calc(100vw - 3rem)). Do not stack the sidebar below content — it pushes critical content below the fold.

Section 06

Motion Tokens

All animations use GSAP v3. Every animation must check prefers-reduced-motion.

Durations

Token	Value	Use
`instant`	100ms	Active/pressed
`fast`	150ms	Hover, toggles
`normal`	300ms	Modals, fades
`slow`	500ms	Page sections
`slower`	700ms	Staggered
`slowest`	1000ms	Hero/cinematic

Note on 400ms

The slideIn* entrance presets use 400ms and slideOut* exit presets use 300ms. These are intentional intermediate values hardcoded in animations/presets.js — they do not map to a named duration token. When referencing these presets' timing, write 400ms explicitly.

Easings

Name	GSAP	Use
out (default)	`power2.out`	Entrances, general UI
in	`power2.in`	Exits
in_out	`power2.inOut`	Layout shifts
overshoot	`back.out(1.7)`	Modals, bounces
spring	`elastic.out(1, 0.3)`	Springy — GSAP only
bounce	`bounce.out`	Bounce — GSAP only

Reduced Motion

Mandatory accessibility requirement

Every animation must respect prefers-reduced-motion: reduce. The design system handles this automatically in most cases — read the rules below.

GSAP — use applyPreset()

The recommended path. applyPreset(gsap, target, "scaleIn") handles reduced motion automatically. For raw gsap.fromTo() calls, check manually: window.matchMedia("(prefers-reduced-motion: reduce)").matches and set duration: 0.

Scroll triggers — self-managed

All factory functions in scroll-triggers.js check reduced motion internally. revealUp/Left/Right and staggerReveal call gsap.set() (instant). parallax() and pinSection() return null. No extra guard needed.

CSS — already handled

All classes in animations/transitions.css include a @media (prefers-reduced-motion: reduce) block that sets all durations to 0ms and removes all transforms. No extra work needed.

Rule	Detail
Never use raw `gsap.to/from` without a duration guard	Use `applyPreset()` or check `window.matchMedia()` directly
Never hand-roll scrubbing without a reduced-motion guard	Use the `parallax()` factory — it returns `null` automatically
Opacity-only fades ≤ 150ms are permissible	Even under reduced motion, pure fades under 150ms are acceptable
Translate and scale transforms → duration: 0	All movement must be instant when reduced motion is active

Section 07

Animation Presets

Click any card to replay. Presets live in animations/presets.js.

Entrance

fadeIn

opacity 0→1 · 300ms

Click to replay

slideInUp

y:24→0 · 400ms

Click to replay

slideInDown

y:-24→0 · 400ms

Click to replay

slideInLeft

x:-24→0 · 400ms

Click to replay

slideInRight

x:24→0 · 400ms

Click to replay

scaleIn

scale:0.95→1 · 300ms

Click to replay

expandIn

scaleY:0→1 · 300ms

Click to replay

Exit

fadeOut

opacity 1→0 · 200ms

Click to play

slideOutUp

y:0→-24 · 300ms

Click to play

slideOutDown

y:0→24 · 300ms

Click to play

scaleOut

scale:1→0.95 · 200ms

Click to play

Hover Interactions

Glow on hover (brand grass green)

CSS Transitions vs. GSAP

Use CSS Transitions for

Simple hover/focus/active states. Effects limited to transform, opacity, box-shadow. Anything reversible by removing a CSS class.

Use GSAP for

Component mount/unmount (Dialog, Sheet, Toast). Multi-step sequences or timelines. Scroll-triggered animations. Anything needing JS callbacks or ScrollTrigger.

CSS Class	Effect	Duration
`.transition-instant`	Sets transition-duration	100ms
`.transition-fast`	Sets transition-duration	150ms
`.transition-normal`	Sets transition-duration	300ms
`.transition-slow`	Sets transition-duration	500ms
`.hover-lift`	`translateY(-4px)` + shadow on `:hover`	200ms
`.hover-press`	`scale(0.97)` on `:active`	100ms
`.hover-fade`	`opacity: 0.8` on `:hover`	150ms
`.focus-ring`	`box-shadow` ring via `var(--ring)` on `:focus-visible`	150ms

Scroll-Triggered Presets

Preset	Trigger	Effect	Scrub
`revealUp`	`top 85%`	y: 40 → 0, fade in	No
`revealLeft`	`top 85%`	x: −40 → 0, fade in	No
`revealRight`	`top 85%`	x: 40 → 0, fade in	No
`parallax`	top bottom → bottom top	yPercent: −15	Yes
`staggerReveal`	`top 85%`	Stagger 0.08s, y: 30, fade in	No

pinSection(gsap, trigger, pinTarget, options)

Pins pinTarget in place while the user scrolls through trigger. Returns null under reduced motion — no pin applied. Use for sticky image / sticky sidebar layouts. Import from animations/scroll-triggers.js.

Logo Reveal

way*ID Lineage HQ

Icon: back.out(1.7), wordmark: power2.out.

Section 08

Live Components

Interactive Maia-styled components with their assigned GSAP animations. Maia = soft, rounded, generous spacing. Pill-shaped buttons & inputs, ring-1 cards, and smooth motion.

Button rounded-4xl (pill) press: scale(0.97)

Input rounded-4xl (pill) bg-input/30

Badge rounded-4xl (pill)

Default Outline Featured Active Pro

Icons Hugeicons currentColor 20px default

Icons use currentColor so they adapt to light/dark mode automatically. Never hardcode a stroke or fill color — let the icon inherit from its parent.

Inline / Toolbar

Hover: --muted bg · Focus: --ring outline · Tab to test

Quick Action Tile

Add

Schedule

Focus

Reports

Hover: 18% muted · Focus: --ring outline · Tab to test

Navigation

Hover: subtle bg · Focus: --ring outline · Tab to test

Dark Mode

Because icons use currentColor, they flip automatically when --foreground changes from dark to light. Never set explicit colors like stroke="#333" or fill="black" — these break in dark mode. Icon container backgrounds use color-mix() with semantic tokens, so they adapt too.

Stroke Weight by Context

Context	stroke-width	Notes
Inline / toolbar (standard)	`1.5`	Default fallback for uncategorized contexts
Inline / toolbar (emphasized)	`1.75`	When extra visual weight is needed
Quick-action tile	`2`	Larger tap target, needs more presence
FAB (floating action button)	`2.5`	Prominent primary action
Navigation bar	`1.5`	Consistent with inline standard

Do not mix stroke weights within a single context. The 1.5 default is the fallback for contexts not listed above.

Card rounded-2xl ring-1 ring-foreground/10 hover-lift

Interactive Card

Hover to lift. Uses shadow-md + translateY(-4px).

Maia Borders

Uses ring-1 instead of border for the Maia aesthetic.

Static Card

Non-interactive cards don't need hover effects.

Card with Image rounded-2xl aspect-ratio: 16/9 overflow: hidden

Project Alpha

Image area uses aspect-ratio: 16/9 with muted background.

Active

Media Upload

Interactive cards use hover-lift and shadow escalation.

Static Variant

Custom ratio (4:3). No hover effect on non-interactive cards.

Chart --chart-1..5 rounded-2xl Recharts

Weekly Activity

Tasks completed per day

Mon

Tue

Wed

Thu

Fri

Sat

Sun

Weekday

Weekend

Color Reference

All five chart tokens

chart-1

chart-2

chart-3

chart-4

chart-5

chart-1

chart-2

chart-3

chart-4

chart-5

Chart Color Token Reference

Token	Light	Dark	Data Series Role
`--chart-1`	Warm orange	Blue	Primary / first series
`--chart-2`	Teal	Green	Secondary series
`--chart-3`	Navy	Amber	Tertiary series
`--chart-4`	Yellow	Purple	Quaternary series
`--chart-5`	Amber	Red	Quinary series

Assignment rule

Assign tokens by series order — --chart-1 for the first data series, --chart-2 for the second, and so on. Never skip a token or assign by color preference. Exact OKLCH values are in tokens/colors.css.

Field label + input + description error state

Email address We'll never share your email.

Password Password must be at least 8 characters.

Role Choose your primary role.

Bio Max 280 characters.

Dialog scaleIn / scaleOut back.out(1.7)

Sheet (right) slideInRight / slideOutRight

Dropdown Menu slideInDown / fadeOut

Tooltip fadeIn / fadeOut (150ms)

Toast slideInRight / slideOutUp

Accordion expandIn (scaleY) rounded-2xl

Maia is one of shadcn/ui's built-in styles — "soft and rounded, with generous spacing." It uses pill-shaped buttons and inputs (rounded-4xl), rounded cards (rounded-2xl), and ring borders instead of traditional borders.

GSAP offers physics-based easings (spring, bounce), fine-grained timeline control, ScrollTrigger integration, and a consistent API across all browsers. It also makes it easy to respect prefers-reduced-motion by setting duration to 0.

No. Never edit files inside components/ui/ directly so the shadcn CLI remains updatable. Customise via CSS variable overrides, Tailwind utility composition, or thin wrapper components.

Tabs fadeIn (150ms)

The Maia style brings a consumer-friendly, warm, approachable aesthetic to shadcn/ui. Key features include pill-shaped buttons (rounded-4xl), generous spacing (gap-6), and blue-tinted gray neutrals (OKLCH hue ~262).

Design tokens are defined in tokens/colors.css (Gray theme OKLCH values), tokens/motion.yaml (duration & easing), and tokens/brand-colors.yaml (additive brand palette). The --radius is set to 0.875rem (large).

Install shadcn/ui via their CLI, choose Maia style and Gray base color. Copy tokens/colors.css into your global stylesheet. Import GSAP presets from animations/presets.js. Use Lora for h0/h1, Poppins for h2–h4, and the system font stack for everything else.

Animation Assignment Reference

Component	Entrance	Exit	Hover	Notes
Dialog / AlertDialog	scaleIn	scaleOut	—	Scale + overshoot
Sheet (left)	slideInLeft	slideOutLeft	—	Mobile nav drawer
Sheet (right)	slideInRight	slideOutRight	—	Matches open side
DropdownMenu	slideInDown	fadeOut	—	Drops down, fades out
Popover	scaleIn	fadeOut	—	Scale from trigger
Tooltip	fadeIn 150ms	fadeOut 150ms	—	Fast & subtle
Toast	slideInRight	slideOutUp	—	Slides in, dismisses up
Accordion	expandIn	reverse expandIn	—	Height from top
Tabs	fadeIn 150ms	—	—	Quick crossfade
NavigationMenu	fadeIn	—	—	Dropdown submenu
Card (interactive)	—	—	hover-lift CSS	Shadow escalation
Button	—	—	hover-press CSS	scale(0.97) on :active

Are you sure?

This action cannot be undone. This will permanently delete your account and remove your data from our servers.

Sheet Panel

This is a sheet that slides in from the right using the slideInRight GSAP preset.

Your name Email

Section 09

Images

Patterns, CSS utilities, aspect ratios, focal points, loading attributes, overlay recipes, and shadcn AspectRatio / Card / Avatar mappings. All demos use hero-market.jpg.

Hero / Full-bleed height: 60dvh object-fit: cover border-radius: 0 loading="eager"

Two people selecting produce at a farmers market

/* .img-hero — standalone <img>, no container needed */
.img-hero {
  display: block;
  width: 100%;
  height: 60dvh;
  min-height: 280px;
  object-fit: cover;
  object-position: 28% center; /* focal point left-of-centre */
}
@media (max-width: 767px) {
  .img-hero { height: 40dvh; }
}
        

<img class="img-hero"
     src="hero-market.jpg"
     alt="Descriptive alt text"
     loading="eager"
     decoding="sync" />
        

Hero — Text Overlay img-hero-wrap img-hero-scrim img-hero-content Lora headline + CTAs

Fresh & Local

The market, at your doorstep.

Seasonal produce from regional growers, delivered every Thursday.

/* .img-hero-wrap owns the height; .img-fill fills it */
/* Use .img-fill — NOT .img-hero — inside the wrap */
<div class="img-hero-wrap">
  <img class="img-fill" src="photo.jpg" alt="…"
       loading="eager" decoding="sync"
       style="object-position:28% center;" />
  <div class="img-hero-scrim"></div>   <!-- dark gradient, bottom-up -->
  <div class="img-hero-content">
    <span>Eyebrow label</span>
    <h2 class="img-hero-headline">Headline copy.</h2>
    <p class="img-hero-sub">Supporting sub-copy.</p>
    <div class="img-hero-actions">
      <button class="maia-btn maia-btn-primary">Primary CTA</button>
      <!-- Outline on dark bg: override color + box-shadow -->
      <button class="maia-btn maia-btn-outline"
              style="color:#fff;box-shadow:inset 0 0 0 1.5px rgba(255,255,255,0.55);">
        Secondary CTA
      </button>
    </div>
  </div>
</div>
        

Hero — Split Panel img-hero-split grid 1fr + min(46%, 460px) card panel stacks ≤600px

Local · Seasonal

Start shopping local today.

Connect with farmers in your area and get the freshest produce, harvested the same morning.

/* Split: CSS grid — panel reflows below image on narrow screens */
<div class="img-hero-split">
  <div class="img-hero-split-image">
    <img src="photo.jpg" alt="…"
         loading="eager" decoding="sync" />
  </div>
  <div class="img-hero-split-panel">
    <!-- badge, h3, p, then CTA buttons -->
    <h3>Headline.</h3>
    <p>Supporting copy.</p>
    <button class="maia-btn maia-btn-primary" style="width:100%;">Primary</button>
    <button class="maia-btn maia-btn-outline" style="width:100%;">Secondary</button>
  </div>
</div>
        

Section Image — Editorial aspect-ratio: 21/9 border-radius: var(--radius) loading="lazy"

/* .img-ar — aspect-ratio wrapper. Set --ar inline. */
.img-ar {
  position: relative;
  width: 100%;
  aspect-ratio: var(--ar, 16/9);
  overflow: hidden;
  background: var(--muted); /* placeholder while loading */
}
.img-ar img {
  display: block;
  width: 100%; height: 100%;
  object-fit: cover;
}
        

<div class="img-ar" style="--ar:21/9; border-radius:var(--radius);">
  <img src="hero-market.jpg" alt="…"
       loading="lazy" decoding="async" />
</div>
        

Section Image — Side-by-side img-text-grid grid 1:1 badge + headline + body + CTAs stacks on mobile

Seasonal

Grown within 50 miles.

Every item is sourced from farms within a 50-mile radius. We verify provenance at intake and publish full supply-chain transparency reports monthly.

/* Image left, text right */
<div class="img-text-grid">
  <div class="img-ar" style="--ar:4/3; border-radius:var(--radius);">
    <img src="photo.jpg" alt="…" loading="lazy" />
  </div>
  <div class="img-text-grid-body">
    <h3>Headline</h3>
    <p>Body copy.</p>
  </div>
</div>

/* Text left, image right — swap DOM order */
<div class="img-text-grid">
  <div class="img-text-grid-body">…</div>  <!-- text first = left col -->
  <div class="img-ar">…</div>           <!-- img second = right col -->
</div>
        

Section Image — Figure + Caption <figure> img-figure img-caption credit line

Vendors at the Riverside Farmers Market — **Riverside Farmers Market** — Weekly outdoor market featuring 40+ local vendors. Open every Saturday, 8am–2pm. Photo: Jane Doe / Maia Studio

<figure class="img-figure">
  <div class="img-ar" style="--ar:21/9; border-radius:var(--radius);">
    <img src="photo.jpg" alt="…" loading="lazy" />
  </div>
  <figcaption class="img-caption">
    <strong>Location name</strong> — Description copy.
    <span style="display:block;margin-top:0.25rem;opacity:0.65;">
      Photo: Photographer / Studio
    </span>
  </figcaption>
</figure>
        

Card Cover — 3-up Grid aspect-ratio: 16/9 shadcn: AspectRatio + Card object-position variants

Left Focal Point

object-position: 28% center — subject left of centre.

Right Focal Point

object-position: 60% center — space left for overlay text.

Top Focal Point

object-position: center top — upper portion. Suits faces.

/* Card cover — real <img> replaces SVG placeholder */
<div class="maia-card-image">
  <div class="maia-card-image-area" style="padding:0;">
    <img src="photo.jpg" alt="…"
         style="width:100%;height:100%;object-fit:cover;object-position:28% center;"
         loading="lazy" decoding="async" />
  </div>
  <div class="maia-card-image-body">…</div>
</div>
        

Aspect Ratio Reference 21/9 16/9 4/3 1/1 3/4

21 / 9

16 / 9

4 / 3

1 / 1

3 / 4

/* All ratios — one class, one property */
<div class="img-ar" style="--ar: 21/9;"><img … /></div>
<div class="img-ar" style="--ar: 16/9;"><img … /></div>
<div class="img-ar" style="--ar:  4/3;"><img … /></div>
<div class="img-ar" style="--ar:  1/1;"><img … /></div>
<div class="img-ar" style="--ar:  3/4;"><img … /></div>
        

Background with Text Overlay linear-gradient to-top --brand-highlight-navy color-mix

Fresh from the Farm

Seasonal produce sourced directly from local growers. Updated weekly.

/* Overlay structure */
<div class="img-overlay-wrap img-ar" style="--ar:16/9; border-radius:var(--radius);">
  <img src="photo.jpg" alt="…" loading="lazy" decoding="async" />
  <div class="img-overlay"></div>
  <div class="img-overlay-content">
    <h4>Heading</h4>
    <p>Supporting copy</p>
  </div>
</div>
        

/* Gradient recipe — navy to transparent, bottom-up */
.img-overlay {
  background: linear-gradient(
    to top,
    var(--brand-highlight-navy) 0%,
    color-mix(in srgb, var(--brand-highlight-navy) 60%, transparent) 40%,
    transparent 75%
  );
}
        

Avatar / Thumbnail border-radius: 50% 5 sizes initials fallback shadcn: Avatar

xl · 64px

lg · 48px

md · 36px

sm · 28px

xs · 20px

initials fallback

/* Image avatar */
<div class="img-avatar img-avatar-lg">
  <img src="user.jpg" alt="Jane Doe"
       loading="lazy" decoding="async" />
</div>

/* Initials fallback — no <img> */
<div class="img-avatar img-avatar-lg" style="background:var(--brand-surface-grey);">
  <span class="img-avatar-initials">JD</span>
</div>
        

Image Composition Patterns

Pattern	CSS	When to use	Mobile
Image only	`.img-hero` / `.img-ar`	Image communicates standalone; no text needed	Height compresses; ratio holds
Text overlay — bottom	`.img-hero-wrap` + `.img-hero-scrim` + `.img-hero-content`	Marketing heroes, event banners, editorial covers with atmospheric photography	Wrap shrinks to 40dvh; content stays bottom-anchored
Split panel	`.img-hero-split`	Sign-up/auth heroes, landing page primary CTAs, feature intros requiring a form or bullet list	Stacks: image top (35dvh) + panel below at ≤600px
Image + text grid	`.img-text-grid` + `.img-text-grid-body`	Feature rows, "about" sections, editorial articles — when copy needs equal visual weight to image	Single column; image first by DOM order
Figure + caption	`<figure>` + `.img-figure` + `.img-caption`	Articles, press releases, documentation — anywhere attribution or context is needed below the image	Full width; caption wraps naturally

Aspect Ratios by Image Type

Type	Ratio	CSS	Notes
Hero / Full-bleed	Variable height	`.img-hero` · `height: 60dvh`	Height in dvh units, not a fixed ratio
Section / editorial	21 : 9	`.img-ar` · `--ar: 21/9`	Wide editorial break between sections
Card cover (default)	16 : 9	`.maia-card-image-area`	Override inline for 4:3 or 1:1
Blog thumbnail	4 : 3	`.img-ar` · `--ar: 4/3`	Compact, good for sidebars
Square / product	1 : 1	`.img-ar` · `--ar: 1/1`	Product shots, avatar grids
Portrait / profile	3 : 4	`.img-ar` · `--ar: 3/4`	Team cards, author bios
Avatar	1:1 circular	`.img-avatar.img-avatar-{size}`	50% border-radius on container

`object-position` Focal Point System

Value	Effect	When to use
`center center`	Default · geometric centre	Symmetric subjects, products
`28% center`	Left-of-centre	`hero-market.jpg` default — subject occupies left third
`60% center`	Right-of-centre	Subject right, space left for text overlay
`center top`	Upper portion visible	Faces, sky-dominant landscapes
`center bottom`	Lower portion visible	Ground-level subjects, food dishes
`50% 20%`	Custom fine-tune	When keyword values are insufficient

Border-radius by Image Type

Type	Container radius	`<img>` radius	Rule
Hero / full-bleed	`0`	`0`	Bleeds edge-to-edge, no radius
Section / editorial	`var(--radius)`	`0`	Radius on `.img-ar` container only
Card cover	`1rem` via `.maia-card-image`	`0`	`overflow:hidden` on card clips the image
Avatar	`50%` via `.img-avatar`	`0`	Container is circular; image fills it

Cardinal rule: never put border-radius on <img>. Apply it to the container with overflow: hidden. This prevents pixel gaps in scaled states and avoids double-radius artefacts.

`loading` and `decoding` Attributes

Image type	`loading`	`decoding`	Reason
Hero (above fold)	`eager`	`sync`	LCP element — must load immediately, no deferral
Section / card	`lazy`	`async`	Below fold — async avoids main-thread jank
Avatar in header	`eager`	`async`	In viewport but small — async decode is safe
Avatar in content	`lazy`	`async`	Below fold; defer both

Responsive Behaviour

Pattern	Desktop (≥768px)	Mobile (<768px)
Hero height	`60dvh`	`40dvh` (via media query)
`aspect-ratio` containers	Ratio maintained	Ratio maintained — inherently responsive
3-up card grid	3 columns	1 column via `.img-card-grid`
Avatar sizes	Fixed px	Fixed px — never scale with `vw`
Section image	Full container width	Full container width, ratio intact

Overlay Gradient Recipes

Recipe	CSS value	Use
Navy to-top (default)	`linear-gradient(to top, var(--brand-highlight-navy) 0%, color-mix(in srgb, var(--brand-highlight-navy) 60%, transparent) 40%, transparent 75%)`	Card overlays, editorial callouts
Navy full scrim	`linear-gradient(to top, var(--brand-highlight-navy) 0%, color-mix(…80%) 60%, transparent 100%)`	Busy hero images needing heavy scrim
Subtle vignette	`radial-gradient(ellipse at center, transparent 50%, color-mix(…40%, transparent) 100%)`	Edge-darkening decorative backgrounds

`overflow: hidden` Containment

Where	`overflow: hidden`?	Reason
`.img-ar`, `.img-avatar`, `.img-overlay-wrap`, `.maia-card-image`	Yes — always	Clips image to container, enforces border-radius
`<img>` element itself	Never	No meaningful overflow; apply to wrapper
Layout / content containers	No	Would clip shadows, focus rings, tooltips
Scrollable regions	Use `overflow-y: auto`	Never hide content in scrollable areas

shadcn Component Mapping

shadcn

AspectRatio

Radix UI wrapper that applies aspect-ratio + overflow: hidden.

This system →

.img-ar with --ar custom property

shadcn

Card (image variant)

Card with top image area at 16:9, body below. Interactive with hover elevation.

This system →

.maia-card-image + .maia-card-image-area

shadcn

Avatar

Circular container with image, 50% radius, overflow: hidden, initials fallback.

This system →

.img-avatar.img-avatar-{size} + .img-avatar-initials

CSS Class Reference

Class	Applied to	Key properties	Notes
`.img-hero`	`<img>` directly	`height:60dvh` · `object-fit:cover` · `object-position:28% center`	No container needed; 40dvh on mobile
`.img-fill`	`<img>` inside sized container	`width:100%` · `height:100%` · `object-fit:cover`	Container must have explicit dimensions
`.img-ar`	Container `<div>`	`aspect-ratio:var(--ar,16/9)` · `overflow:hidden`	Set ratio via `style="--ar:4/3"`
`.img-avatar`	Container `<div>`	`border-radius:50%` · `overflow:hidden` · `display:flex`	Always pair with a size modifier
`.img-avatar-{xl\|lg\|md\|sm\|xs}`	Same container as `.img-avatar`	`width/height`: 64/48/36/28/20px	Fixed px — never scale with viewport
`.img-avatar-initials`	`<span>` inside `.img-avatar`	Poppins 600 · `0.75em` · `var(--muted-foreground)`	Fallback when image unavailable
`.img-overlay-wrap`	Container `<div>`	`position:relative` · `overflow:hidden`	Parent of image + overlay + content layers
`.img-overlay`	`<div>` inside `.img-overlay-wrap`	`position:absolute;inset:0` · gradient background	`pointer-events:none` — passes clicks through
`.img-overlay-content`	`<div>` inside `.img-overlay-wrap`	`position:absolute;bottom:0` · `padding:1.5rem` · `color:#fff`	Text layer above gradient

Section 10

Get Started

Set up a new project with shadcn/ui Maia + Gray theme.

Scaffold your framework

# Next.js
npx create-next-app@latest my-app --typescript --tailwind --eslint

Install shadcn/ui (Maia style, Gray base)

npx shadcn@latest init
# Choose: Gray base color, Maia style, Large radius

Install GSAP + Hugeicons

npm install gsap hugeicons-react

Add Lora + Poppins for headlines

/* Google Fonts */
/* Lora: ital,wght@0,400;0,700;1,400 | Poppins: wght@600;700;800 */
h1, .h0 { font-family: "Lora", Georgia, serif; }
h2, h3, h4 { font-family: "Poppins", sans-serif; }

Copy brand tokens

:root {
  --brand-surface: #E8E5DE;
  --brand-highlight-navy: #0E1233;
  --brand-highlight-light: #FAFAFA;
  --brand-offset-lavender: #7267E2;
  --brand-offset-green: #A0D246;
  --brand-offset-yellow: #F8BC4D;
  --brand-offset-coral: #FF7236;
  --brand-offset-blue: #006CDB;
}

Import animation presets

import { ENTRANCE, EXIT, HOVER } from "@/design-system/animations/presets";

Key files

DESIGN-SYSTEM.md · Full spec
tokens/colors.css · CSS variables (Gray theme)
tokens/motion.yaml · Duration & easing tokens
animations/presets.js · GSAP presets
components/shadcn-customizations.yaml · Overrides

Section 11

Mobile Example

A realistic mobile app — "Focus" — built entirely from design system components. Buttons, inputs, badges, cards, tabs, accordion, bottom sheet, toasts, FAB, and bottom nav all working together in a phone-frame layout.

Fully interactive — click, scroll, check tasks, fire toasts.

Components used

• App bar + status bar mock • Maia pill search input • Stat cards (maia-card) • Featured project card + progress bar • Quick actions grid (4-up) • Task list with checkboxes • Tabs (Today / Upcoming / Completed) • Accordion (Project Notes) • Bottom sheet (add task) • FAB • Bottom navigation bar • Toast notifications • Badges (lavender / blue / navy / default)

Animation patterns

• Staggered entrance sequence on load • Progress bar animated fill (0→62%) • Button micro-lift + back.out(2) spring • FAB scale bounce on hover • Task check — back.out(2.2) pop • Bottom sheet — slide up from 100% • Toast — back.out(1.5) slide-up entry • Accordion chevron nudge on hover • Tab panel y:8→0 fade-slide • Scroll reveal for lower sections

Fonts in use on this screen

Lora · Serif · 400 / 700 Good morning h1 · greeting heading only

System UI · Sans · 400–700 Everything else buttons · labels · stats · nav · badges

2 families · Poppins not loaded

Open standalone

View at full size or inspect source in a separate tab.

Open example-mobile.html

Section 12

Pitch Deck Slide

A Series A pitch slide for "Aria" — a fictional AI payments startup. Dark navy background, Lora headline for emotional impact, System UI for all data and labels. 16:9 desktop format.

SvelteKit + shadcn-svelte — static export

Slide components

• Series badge pill (offset-green border) • Lora 700 headline (3.1rem) • Body subtitle (System UI, muted) • Stats row: $2.4M ARR / 18% MoM / 340 customers • Wordmark badge (bottom-left) • Radial glow + decorative ring (right column) • Dot grid overlay (decorative)

Design decisions

• Dark navy bg — authority + brand depth • Lora for the headline only — max emotional pull • System UI for all data — stays crisp at small sizes • Right column abstract visual avoids literal imagery • Stats use weight + size hierarchy, not color

Fonts in use on this screen

Lora · Serif · 700 The AI layer h1 · slide headline only

System UI · Sans · 400–700 $2.4M ARR stats · labels · subtitle · wordmark

2 families · Poppins not loaded

SvelteKit

Open standalone

View at full 800×450 resolution or inspect source.

Open example-pitchdeck.html

Section 13

Startup Landing Page

Above-the-fold hero for "Aria" — light mode. Full nav + eyebrow badge, Lora headline, CTA pair, and social proof strip. Desktop 800×500.

SvelteKit + shadcn-svelte — static export

Page components

• Flat nav bar (logo + links + CTA) • Full-bleed photo — extends behind entire hero area • Solid white card (45%) overlaid right — no fade • Eyebrow badge "Now in private beta" • Lora 700 headline (2rem) • Subtitle paragraph (System UI) • CTA pair: filled primary + ghost • Social proof strip (4 company names)

Design decisions

• Hero photo anchors human context; copy stays minimal • Hard card edge — white panel sits over photo, border-left divider • Lora upright — authority without decoration • Ghost CTA lowers barrier vs. single primary • Social proof muted — present but not competing

Fonts in use on this screen

Lora · Serif · 700 Payments that feel human. h1 · page headline only

System UI · Sans · 400–700 Everything else nav · buttons · badge · subtitle · proof

2 families · Poppins not loaded

SvelteKit

Open standalone

View at full 800×500 resolution or inspect source.

Open example-landing.html

Section 14

Customer Review Platform

A mobile review screen for "Trustflow" — showing the Aria product page with a rating summary, star breakdown bars, filter chips, and review cards. System UI only — no web font needed.

SvelteKit + shadcn-svelte — fully interactive

Screen components

• App bar (back + title + kebab) • Rating summary: 4.7 ★, 2,341 reviews • 5-row star breakdown (CSS-only width bars) • Filter chips: All / 5★ / 4★ / Verified / Recent • Review cards (name, stars, date, text, helpful) • Verified badge (green pill) • Write review input bar (pinned bottom)

Design decisions

• 1 font family — no headings warrant Lora/Poppins • Star bars via CSS width — zero JS needed • Active chip uses --foreground fill, not brand blue • Verified badge mirrors eyebrow pill (offset-green, subtle) • Helpful CTA low-prominence — secondary action

Fonts in use on this screen

System UI · Sans · 400–700 4.7 ★★★★★ entire screen — app bar · ratings · reviews

1 family · Poppins not loaded · Lora not loaded

SvelteKit

Open standalone

View at 390×780 or inspect source in a separate tab.

Open example-reviews.html

Build consistent. Move with purpose. Stay on brand.

Typography

The quick brown fox

The quick brown fox

The quick brown fox jumps

The quick brown fox jumps over

Logo

way*ID Badge

Lineage*Labs Wordmark

Brand Colors

Highlights

Surfaces

Offset Accents — Light surface

Highlights + Offsets — Dark / Blue surface

Sidebar Tokens

Spacing

Base Scale

Semantic Tokens

Component Spacing

Guidelines

Responsive Design

Breakpoint Scale

Live Grid Demo — resize your browser to see columns change

Container Behavior

What Changes vs. What Stays Fixed

Fluid Typography

Mobile Compaction — below 768px

Guidelines

Mobile Overflow Prevention — minimum viewport: 320px

Global CSS Resets

Safe Grid Pattern

Vertical Content & Fixed Heights

Sidebar Layout

Motion Tokens

Durations

Easings

Reduced Motion

Animation Presets

Entrance

Exit

Hover Interactions

CSS Transitions vs. GSAP

Scroll-Triggered Presets

Logo Reveal

Live Components

Stroke Weight by Context

Interactive Card

Maia Borders

Static Card

Project Alpha

Media Upload

Static Variant

Chart Color Token Reference

Animation Assignment Reference

Are you sure?

Sheet Panel

Images

The market, at your doorstep.

Start shopping local today.

Grown within 50 miles.

Left Focal Point

Right Focal Point

Top Focal Point

Fresh from the Farm

Image Composition Patterns

Aspect Ratios by Image Type

object-position Focal Point System

Border-radius by Image Type

loading and decoding Attributes

Responsive Behaviour

Overlay Gradient Recipes

overflow: hidden Containment

shadcn Component Mapping

CSS Class Reference

Get Started

Mobile Example

Pitch Deck Slide

Startup Landing Page

Customer Review Platform

Build consistent.
Move with purpose.
Stay on brand.

`object-position` Focal Point System

`loading` and `decoding` Attributes

`overflow: hidden` Containment