Philosophy
Why every surface looks the way it does, the thinking the rest of this page applies.
The product should feel quiet. One brand accent does all the emphasizing; everything else comes from semantic foreground, background, and muted tokens. Whitespace is a material, pages are centered and given room to breathe. We reach for the inset edge hairline instead of a drop shadow or hard outline. Restraint is the point: when only one thing is colored, that one thing means something.
Adapted from Vercel's Design Engineer Principles for this registry: bias toward usefulness, own outcomes end-to-end (every state and edge case), find the binding constraint before you ship, design for the full audience, ship craft not volume, and raise the team's floor through registry patterns, lint, and examples.
- Bias toward usefulness
- Own outcomes end-to-end
- Find the binding constraint
- Design for the full audience
- Ship craft, not volume
- Raise the team's floor
Consistency comes from shared materials and constant chrome, never from a repeated page template. The thing to avoid is the uniform multi-column card grid. Every page earns a distinctive centerpiece, pick one signature hero and compose everything else around it. Secondary content may use cards, but cards are never a page's primary identity. The kit below exists precisely so each page can look unique without looking random.
The shell never moves. A light top bar (brand mark + org switcher, user avatar) and a dark floating dock, the primary nav, are identical on every surface; only the body changes. That fixed frame is what lets each page be a bespoke composition without the product feeling disjointed. There is exactly one deliberate exception to the calm-and-light rules: a dark, dense surface (e.g. an inbox/cockpit), a two-pane layout that trades the airy spacing for speed, still on our single green accent.
Principles
The rules behind every surface, read these before composing anything new.
One warm green (--brand) carries all emphasis, links, primary actions, the lone chart series. Chart series beyond the first step down a grayscale ramp (--chart-2…5), never a rainbow. The single multi-hue exception is identity avatars, where color encodes a person.
Status reads from a small colored dot, not colored text. Keep labels in foreground ink so the meaning is the dot, legible in either theme.
Radius base --radius: 0.75rem, scaled up for cards and down for chips.
Spacing scale
Foundations
Color, radius, elevation, and type, the raw material everything is built from.
app/globals.css--brand
The one accent
--success
Good · = brand
--warning
Needs work
--destructive
Poor / danger
--foreground
Text
--muted-foreground
Secondary text
--background
Page
--card
Surfaces
--muted
Fills
--primary
Solid buttons
--border
Hairlines
--dock
Floating dock
--accent
Hover fills
--sidebar
Sidebar surface
--chart-1
Chart · the green
--chart-2
Grayscale series
--chart-3
Grayscale series
--chart-4
Grayscale series
--chart-5
Grayscale series
--radius-*.edgeedge
cards
edge
dock · popovers
Geist · font-sans / font-monoThe quick brown fox
Section heading · xl semibold
Body copy · sm, calm, readable, generous line height for long-form settings and descriptions.
Muted · sm, captions, hints, and secondary metadata.
Mono · 12px, values, IDs, and code (e.g. usr_8f2a91c4).
app/globals.cssBuilt on one brand accent
.glow-brand
.bg-grid
.mask-fade-x
Primitives
The base controls, every one a pill, token-driven, light & dark safe.
@/components/ui/buttonDetails →@/components/ui/buttonDetails →@/components/ui/badgeDetails →@/components/ui/filter-pillDetails →@/components/ui/segmented-controlDetails →@/components/ui/status-dotDetails →@/components/status-pillDetails →@/components/ui/cardDetails →12,480
Forms
Inputs and controls, labeled fields, token-driven, light & dark safe.
@/components/ui/inputDetails →@/components/ui/textareaDetails →@/components/ui/selectDetails →@/components/ui/checkboxDetails →@/components/ui/switchDetails →@/components/ui/radio-groupDetails →@/components/ui/labelDetails →@/components/ui/toggleDetails →@/components/ui/toggle-groupDetails →@/components/ui/input-groupDetails →Overlays
Floating surfaces, triggers open content via the render prop. Dark over light by design.
@/components/ui/tooltipDetails →@/components/ui/popoverDetails →@/components/ui/dropdown-menuDetails →@/components/ui/dialogDetails →@/components/ui/sheetDetails →@/components/ui/commandDetails →@/components/ui/navigation-menuDetails →@/components/ui/hover-cardDetails →Feedback
Status, progress, and loading, how a surface tells you what's happening.
Data display
Reading surfaces, how records, structure, and identity are presented.
@/components/ui/tabsDetails →@/components/ui/accordionDetails →@/components/ui/avatarDetails →@/components/ui/separatorDetails →@/components/ui/breadcrumbDetails →@/components/ui/tableDetails →| Name | Status | Usage |
|---|---|---|
| Acme Inc. | Active | 1,284 |
| Globex | Pending | 0 |
@/components/ui/aspect-ratioDetails →@/components/ui/scroll-areaDetails →@/components/ui/collapsibleDetails →Patterns
Composed pieces, the recurring building blocks of a page.
@/components/page-headerDetails →People
8 people this week
Projects
3 active projects
@/components/metric-statDetails →@/components/stat-cardDetails →@/components/ui/activity-ringDetails →@/components/ui/activity-gridDetails →@/components/ui/gradient-avatarDetails →@/components/empty-stateDetails →No activity yet
Events for this project will show up here.
Charts
One green series, soft gradient fade, faint gridlines, endpoint labels only, never a rainbow.
House components
Composed dashboard pieces, detail headers, settings panels, and event timelines.
@/components/detail-headerDetails →Acme Inc.
Active@/components/sectionDetails →Display name
The name shown across your workspace.
Acme Inc.
Visible to teammates and on shared links.
@/components/event-timelineDetails →- Deployment live
Production build published.
Today · 9:42 AM - Changes pushed
Awaiting review.
Mar 14 · 4:18 PM - Action needed
Billing details could not be verified.
Mar 12 · 11:02 AM - Project createdMar 11 · 8:30 AM
@/components/verification-progressDetails →Layout archetypes
Composition shells, every page picks one signature hero, never a generic card grid.
See all six archetypes as full, live pages
Open the gallery to inspect each at any viewport, in either theme, and re-skin them live.
@/components/hero-sectionDetails →@/components/centered-focalDetails →Waiting for events
Nothing has come through yet. Send a test to get started.
@/components/split-with-railDetails →Curious Falcon
usr_8f2a91c4
- Signed in1m 8s
- Viewed dashboard12s
- Failed login0s
- Updated profile44s
Side by side
The same twelve components, ours on the left, a design system you know on the right. Toggle between Vercel, Linear, 0.email, Shopify, Stripe, GitHub, Atlassian, Radix, Mailchimp, and Apple, and flip our side light or dark.
Button. Ours pills every control, keeps borders to a hairline, reserves the single warm green for status (not buttons), and lets whitespace carry the layout. Vercel squares to 6px and stays monochrome, a flat black primary, a hairline secondary, no accent on the button.
Status. Vercel's badges are small, squared, and uppercase, tonal text on a faint fill, no leading dot.
12,480
Card. Vercel keeps the card flat, 8px, a single #eaeaea border, no shadow. Structure from the line.
Shown to teammates across your workspace.
Shown to teammates across your workspace.
Text field. Vercel's input is a crisp 6px box with a hairline border that darkens to black on focus, no ring.
Select. Vercel's trigger is a monochrome 6px box with a quiet chevron, it matches the input exactly.
Checkbox. Vercel's box fills solid black when checked, monochrome, no blue.
Switch. Vercel's track flips to solid black when on, a monochrome toggle.
Progress. Vercel draws a thin black bar on a grey track, monochrome throughout.
Avatar. Vercel keeps the avatar a circle with a neutral grey fill.
Banner. Vercel keeps callouts light, a faint tinted surface and a single accent icon.
| Name | Status | Usage |
|---|---|---|
| Acme Inc. | Active | 1,284 |
| Globex | Pending | 0 |
| Name | Status | Usage |
|---|---|---|
| Acme Inc. | Active | 1,284 |
| Globex | Pending | 0 |
Table. Vercel's table is clean and monochrome, a #fafafa header, hairline rows, plain.
Tabs. Vercel uses underline tabs, a black bottom-rule under the selected label, no track.