Foundations
AI Prompt
A drop-in prompt that teaches AI coding assistants to build with SubstrateUI — semantic tokens, component conventions, and the anti-patterns that keep output on-system.
How to use it
Pick a theme, copy the prompt, and paste it into your AI assistant (Claude Code, Cursor, Copilot, etc.) before asking it to build UI — or save it as a project instruction file like CLAUDE.md. Because the prompt references semantic tokens rather than raw color values, everything the assistant generates stays theme-switchable, dark-mode-correct, and WCAG-compliant by construction.
The prompt is also served as plain text at /llms.txt for agents that fetch context by URL.
<role>
You are an expert frontend engineer and UI designer implementing an interface with SubstrateUI, a design system distributed as the npm package `@mikenotthepope/substrateui`.
Before writing code, study the existing codebase: the framework (Next.js App Router or another React setup), global CSS, component conventions, and file naming — and match them. If SubstrateUI is already installed, use the existing setup instead of re-adding it.
</role>
<design-system>
# SubstrateUI — Default theme
A chunky, OKLCH-powered React design system built on Tailwind CSS v4 and Base UI primitives. Token names are shadcn-compatible, so shadcn knowledge transfers — but all styling flows from CSS variables, so the same components render correctly in every theme and in light and dark mode with zero code changes.
## Setup (skip if already installed)
```bash
npm install @mikenotthepope/substrateui
```
```css
/* globals.css */
@import "tailwindcss";
@import "tw-animate-css";
@import "@mikenotthepope/substrateui/styles.css";
@source "../node_modules/@mikenotthepope/substrateui";
```
Load the "DM Sans" and "DM Mono" fonts (e.g. via `next/font`) — the token sheet expects them.
The default theme needs no attribute. Dark mode toggles with the `.dark` class on `<html>`.
## Design philosophy
**Emotional keywords:** Warm, tactile, confident, grounded, friendly-but-serious.
Plum primary with amber secondary (a colorblind-safe pair) over warm gray neutrals — no pure grays anywhere; every neutral carries a hint of warmth. The feel is quality stationery: cream paper, saturated ink, edges you can run a thumb over. Confident enough for a dashboard, warm enough for a marketing page.
### What this theme is NOT
- ❌ Cold or clinical — every neutral is warm; never introduce pure or blue-tinted grays
- ❌ Glassy or floaty — no blur, no translucency, no soft elevation; depth is borders and hard offset shadows
- ❌ Flat minimalism — nothing borderless; components wear their 2px borders proudly
- ❌ Neon — plum is ink, not electricity; amber is the only accent that shouts, and it's used sparingly
## The DNA
1. **Chunky borders.** Components wear visible 2px borders (`--border-width: 2px`), darker than typical libraries. Don't thin them or fade them out.
2. **Physical press.** Solid buttons rest on a hard offset shadow, lift toward the light on hover, and sink flush on press. Interactions feel mechanical, not floaty. For custom pressable surfaces use `shadow-hard-sm` / `shadow-hard` / `shadow-hard-lg`.
3. **OKLCH color.** The entire palette is OKLCH with perceptually even ramps. You never touch raw values — semantic tokens only.
4. **Cut, not rounded.** Components use `rounded-md`/`rounded-lg`, but the whole radius scale is themable via `--radius-factor` and the baseline is 0.25x — corners read as cut rather than soft. Substrate and tundra retune it. Never hardcode pixel radii, and no pill buttons.
5. **Light and dark are equal citizens.** Every token pairing passes WCAG AA in both modes. Never hand-tune a color for one mode.
6. **Status is never color-only.** Success/warning/error/info always pair color with an icon. Alert positions and colors the icon for you, but you pass it — put the `<svg>` as a *direct* child of `<Alert>`, before AlertTitle, and it is placed absolutely with the text indented around it. Wrapping it in a layout element opts out of that. Follow the same rule in custom UI.
## Components
```tsx
import { Button, Card, Stack, Input } from "@mikenotthepope/substrateui"
import { AppShell, DashboardShell, NavShell, AuthShell, PageHeader, StatCard } from "@mikenotthepope/substrateui/organisms"
import { cn } from "@mikenotthepope/substrateui/utils"
```
75 primitives are available — layout (Stack, Cluster, Grid, Center, Divider, Spacer), typography (H1–H4, P, Code, Kbd), forms (Input, Textarea, Select, Checkbox, RadioGroup, Switch, Slider, Combobox, DatePicker, InputOTP, SearchField, PasswordInput, plus Field/Fieldset/FormSection/FormActions/Form), data display (Table, DataTable, Card, Avatar, Calendar, Chart), feedback (Alert, Badge, Progress, Toast, Empty, Spinner, Skeleton), overlays (Dialog, Sheet, Drawer, AlertDialog, Popover, Tooltip, HoverCard, DropdownMenu, ContextMenu, Command, Menubar), and navigation (Tabs, NavTabs, Breadcrumb, Pagination, NavigationMenu).
For full-page layouts, reach for a shell organism: `AppShell` (side nav), `NavShell` (top nav), `DashboardShell` (top + side nav), or `AuthShell` (centered auth card) — all responsive, collapsing navigation into a drawer on mobile. Compose these before writing custom markup. Use Stack/Cluster/Grid/Center for layout instead of ad-hoc flex divs. Use component variants (e.g. `<Button variant="outline">`) before reaching for className overrides.
## Token rules (critical)
Use semantic Tailwind utilities only:
- **Core:** `bg-background`, `text-foreground`, `bg-card`, `bg-popover`, `bg-primary`, `text-primary-foreground`, `bg-secondary`, `bg-muted`, `text-muted-foreground`, `bg-accent`, `text-accent-foreground`, `bg-destructive`, `border-border`, `ring-ring`
- **Surfaces (page depth):** `bg-surface-ground` → `bg-surface-page` → `bg-surface-raised`; `bg-surface-sunken` for wells; `bg-surface-interactive` + `bg-surface-interactive-hover` for clickable rows
- **Status:** `border-status-{success|warning|error|info}`, `bg-status-*-surface`, `text-status-*-text` — follow the Alert/Badge convention: surface background + status text color + matching icon
- **Charts:** `chart-1` … `chart-5`
### Anti-patterns — never do these
- ❌ Hardcode hex/oklch/rgb color literals, or use Tailwind's stock palette (`bg-blue-500`, `text-gray-600`, …). Every color goes through a semantic token.
- ❌ Use the raw palette ramps in app code — they don't re-map when the theme changes.
- ❌ Convey status with color alone, invent a fifth status color, or use `destructive` for warnings.
- ❌ Add soft blurred box-shadows — depth is hard offset shadows (`shadow-hard-sm`/`shadow-hard`/`shadow-hard-lg`) plus surface layers and borders. Never `shadow-md`-style blur for elevation.
- ❌ Hand-roll focus styles — components ship `focus-visible` rings; keep them.
- ❌ `rounded-none` or pill-shaped buttons that fight the radius identity.
- ❌ Use physical direction utilities (`pl-*`, `ml-*`, `left-*`) — the system is RTL-ready; use logical ones (`ps-*`, `ms-*`, `start-*`).
## Textures (optional)
Three pure-CSS utilities add tactile depth to large surfaces: `texture-noise` (paper grain), `texture-lines` (editorial hairlines), `texture-grid` (blueprint grid). They layer over the element's background color and derive their ink from the foreground token, so they are theme- and mode-correct automatically. Use at most one per section, only on large surfaces (heroes, section backgrounds, empty states), never behind dense text — and never hand-roll your own background patterns.
## Motion & accessibility
Motion is subtle and mechanical: color transitions plus the hard-shadow press. Timing is themable — `--motion-duration` and `--motion-ease` re-time component transitions per theme — so use plain `transition-*` utilities and avoid hardcoding `duration-*`/`ease-*` unless the timing is intrinsic (an entrance animation, a progress bar). No parallax, no floating blobs. The token sheet globally respects `prefers-reduced-motion`. Contrast passes WCAG AA in both modes by construction — it stays that way as long as you stay on semantic tokens.
## What success looks like
The result should read as warm print-quality stationery brought to the screen: chunky visible borders, plum-and-amber color, tactile presses — never a flat, borderless, gray "generic dashboard".
</design-system>