Foundation
Khaeli's tokens and base layer: the Tailwind v4 @theme inline mapping, light and dark palettes (Underlay by default), the type scale, the 30px control height, the Kargul radius ladder, motion durations and eases, and the [data-slot] rules that restyle every registry primitive. A product swaps the brand through the --primary family, --tint-* and --chart-*.
The first item a product installs. It sets the colour tokens for light and dark, the type roles, the radius ladder, the shadows, the motion clock and the 30px control, and styles Registry components through their data-slot. The examples here use only the Tailwind utilities it defines, so each one pastes into a product that has nothing but foundation. Every value, with its token, is on the Colours, Radius, Shadows and Spacing and sizing pages under Foundations. A product changes the primary family, the tints, the chart series and the font families, and nothing else.
Palette
- Surfaces
--background--card--secondary--muted--border--input
- Text
--foreground--muted-foreground--subtle-foreground
- Primary
--primary--primary-hover--primary-subtle--link
- Status
--positive--warning--destructive--positive-subtle--info-subtle--warning-subtle--destructive-subtle
- Tints
--tint-mint--tint-peach--tint-sky--tint-blue--tint-pink--tint-lavender
// Each swatch is drawn with the utility foundation defines for the token beside it.
const groups = [
{
title: "Surfaces",
swatches: [
{ token: "--background", fill: "bg-background" },
{ token: "--card", fill: "bg-card" },
{ token: "--secondary", fill: "bg-secondary" },
{ token: "--muted", fill: "bg-muted" },
{ token: "--border", fill: "bg-border" },
{ token: "--input", fill: "bg-input" },
],
},
{
title: "Text",
swatches: [
{ token: "--foreground", fill: "bg-foreground" },
{ token: "--muted-foreground", fill: "bg-muted-foreground" },
{ token: "--subtle-foreground", fill: "bg-subtle-foreground" },
],
},
{
title: "Primary",
swatches: [
{ token: "--primary", fill: "bg-primary" },
{ token: "--primary-hover", fill: "bg-primary-hover" },
{ token: "--primary-subtle", fill: "bg-primary-subtle" },
{ token: "--link", fill: "bg-link" },
],
},
{
title: "Status",
swatches: [
{ token: "--positive", fill: "bg-positive" },
{ token: "--warning", fill: "bg-warning" },
{ token: "--destructive", fill: "bg-destructive" },
{ token: "--positive-subtle", fill: "bg-positive-subtle" },
{ token: "--info-subtle", fill: "bg-info-subtle" },
{ token: "--warning-subtle", fill: "bg-warning-subtle" },
{ token: "--destructive-subtle", fill: "bg-destructive-subtle" },
],
},
{
title: "Tints",
swatches: [
{ token: "--tint-mint", fill: "bg-tint-mint" },
{ token: "--tint-peach", fill: "bg-tint-peach" },
{ token: "--tint-sky", fill: "bg-tint-sky" },
{ token: "--tint-blue", fill: "bg-tint-blue" },
{ token: "--tint-pink", fill: "bg-tint-pink" },
{ token: "--tint-lavender", fill: "bg-tint-lavender" },
],
},
]
export default function FoundationPalette() {
return (
<dl className="flex w-full flex-col gap-6">
{groups.map(({ title, swatches }) => (
<div key={title} className="flex flex-col gap-2">
<dt className="text-sm text-muted-foreground">{title}</dt>
<dd>
<ul className="grid grid-cols-2 gap-x-4 gap-y-3 sm:grid-cols-3">
{swatches.map(({ token, fill }) => (
<li key={token} className="flex min-w-0 items-center gap-2">
<span aria-hidden="true" className={`size-8 shrink-0 rounded-md ring-1 ring-border ring-inset ${fill}`} />
<code className="min-w-0 font-mono text-xs break-words">{token}</code>
</li>
))}
</ul>
</dd>
</div>
))}
</dl>
)
}
Type roles
- Display
text-2xl - The notes go out on Wednesday
- Heading
text-xl - The notes go out on Wednesday
- Title
text-lg - The notes go out on Wednesday
- Body
text-base - The notes go out on Wednesday
- Footnote
text-sm - The notes go out on Wednesday
- Caption
text-xs - The notes go out on Wednesday
- Micro
text-2xs - The notes go out on Wednesday
// One scale of roles. Each class sets the size, the line height and, from the title up, the weight.
const roles = [
{ role: "Display", size: "text-2xl" },
{ role: "Heading", size: "text-xl" },
{ role: "Title", size: "text-lg" },
{ role: "Body", size: "text-base" },
{ role: "Footnote", size: "text-sm" },
{ role: "Caption", size: "text-xs" },
{ role: "Micro", size: "text-2xs" },
]
export default function FoundationTypeRoles() {
return (
<dl className="flex w-full flex-col divide-y divide-border border-y border-border">
{roles.map(({ role, size }) => (
<div key={size} className="flex flex-col gap-1 py-3 sm:flex-row sm:items-baseline sm:gap-6">
<dt className="flex shrink-0 items-baseline gap-2 sm:w-40">
<span className="text-sm text-muted-foreground">{role}</span>
<code className="font-mono text-xs">{size}</code>
</dt>
<dd className={`min-w-0 ${size}`}>The notes go out on Wednesday</dd>
</div>
))}
</dl>
)
}
Radius and controls
rounded-smallBadges, keycapsrounded-mdRowsrounded-controlControlsrounded-cardCards, menusrounded-trayTrays, dialogsrounded-fullChips, avatars
A control is 30px tall: h-7.5 with rounded-control, on shadow-cta when filled and shadow-control when not.
// The radius ladder, smallest to largest, then a 30px control row drawn with it.
const radii = [
{ use: "Badges, keycaps", corner: "rounded-small" },
{ use: "Rows", corner: "rounded-md" },
{ use: "Controls", corner: "rounded-control" },
{ use: "Cards, menus", corner: "rounded-card" },
{ use: "Trays, dialogs", corner: "rounded-tray" },
{ use: "Chips, avatars", corner: "rounded-full" },
]
export default function FoundationRadiusAndControls() {
return (
<div className="flex w-full flex-col gap-8">
<ul className="grid grid-cols-2 gap-4 sm:grid-cols-3">
{radii.map(({ use, corner }) => (
<li key={corner} className="flex flex-col gap-2">
<span aria-hidden="true" className={`h-14 bg-secondary ring-1 ring-border ring-inset ${corner}`} />
<span className="flex flex-col">
<code className="font-mono text-xs">{corner}</code>
<span className="text-sm text-muted-foreground">{use}</span>
</span>
</li>
))}
</ul>
<div className="flex flex-col gap-2">
{/* Marks, not controls: the height every single-line control has on a desktop. */}
<div aria-hidden="true" className="flex flex-wrap items-center gap-2">
<span className="flex h-7.5 items-center rounded-control bg-primary px-3 font-medium text-primary-foreground shadow-cta">
Save changes
</span>
<span className="flex h-7.5 items-center rounded-control bg-background px-3 font-medium shadow-control">
Cancel
</span>
<span className="flex h-7.5 min-w-40 items-center rounded-control bg-background px-3 text-subtle-foreground shadow-control">
Search tasks
</span>
</div>
<p className="text-sm text-muted-foreground">
A control is 30px tall: <code className="font-mono text-xs whitespace-nowrap text-foreground">h-7.5</code> with{" "}
<code className="font-mono text-xs whitespace-nowrap text-foreground">rounded-control</code>, on{" "}
<code className="font-mono text-xs whitespace-nowrap text-foreground">shadow-cta</code> when filled and{" "}
<code className="font-mono text-xs whitespace-nowrap text-foreground">shadow-control</code> when not.
</p>
</div>
</div>
)
}
Motion
--duration-fast--duration-standard--duration-considered
"use client"
import { useState } from "react"
// Three durations on one ease. Each class reads a foundation token.
const clocks = [
{ token: "--duration-fast", duration: "duration-(--duration-fast)" },
{ token: "--duration-standard", duration: "duration-(--duration-standard)" },
{ token: "--duration-considered", duration: "duration-(--duration-considered)" },
]
export default function FoundationMotion() {
const [moved, setMoved] = useState(false)
return (
<div className="flex w-full max-w-sm flex-col gap-4">
<ul className="flex flex-col gap-3">
{clocks.map(({ token, duration }) => (
<li key={token} className="flex flex-col gap-1">
<code className="font-mono text-xs text-muted-foreground">{token}</code>
<div className="rounded-control bg-muted p-1">
<div className="@container">
{/* Reduced motion: the mark is at its new place at once and only its opacity eases. */}
<div
className={`size-6 rounded-small bg-primary transition-[translate,opacity] ease-(--ease-standard) motion-reduce:transition-[opacity] ${duration} ${
moved ? "translate-x-[calc(100cqw-100%)] opacity-100" : "opacity-50"
}`}
/>
</div>
</div>
</li>
))}
</ul>
<button
type="button"
className="focus-ring flex h-7.5 items-center self-start rounded-control bg-background px-3 font-medium shadow-control"
onClick={() => setMoved(!moved)}
>
Play
</button>
</div>
)
}
Installation
npx shadcn@latest add @khaeli/foundationbunx --bun shadcn@latest add @khaeli/foundationInstall once per app before any component. Re-adding it resets the palette in your globals.css, so apply your Design Bundle's palette after it.
Installs with
- npm packages
- @fontsource-variable/geist-mono ^5.3.0
- @fontsource-variable/inter ^5.3.0
- tw-animate-css ^1.4.0
Registry JSON
The item as the shadcn CLI reads it, with every file it ships: https://ui.khaeli.com/r/foundation.json