@mikenotthepope/substrateui

v0.4.0

Published

13 days ago

A chunky, OKLCH-powered design system for Next.js — built on Tailwind CSS v4, Radix UI, and Atomic Design principles.

0High
0Medium
0Low

mikenotthepope

design-system react nextjs tailwindcss radix-ui components ui

SubstrateUI

A chunky, opinionated design system for Next.js — OKLCH tokens, Tailwind CSS v4, Radix UI primitives.

Status

Docs:
Storybook: https://substrateui.dev/storybook/ — run locally with bun run storybook
npm: @substrateui/core (not yet published)

Features

75 components from atomic Button to organism App Shell
3-layer OKLCH color system: raw palette → semantic tokens → Tailwind utilities
Dark mode as a token swap — zero component changes
Chunky 2px borders and press-down animations
CVD-safe plum + amber color pairing
WCAG AA contrast verified on every token pairing — see contrast report
Built for Tailwind CSS v4 (@theme inline, CSS-first config)
Full TypeScript support with exported types
Tree-shakeable ESM exports

Quick Start

npm install substrateui

CSS Setup

/* globals.css */
@import "tailwindcss";
@import "tw-animate-css";
@import "substrateui/styles.css";
@source "../node_modules/substrateui";

Font Setup (recommended)

// layout.tsx
import { DM_Sans, DM_Mono } from "next/font/google"

const sans = DM_Sans({ subsets: ["latin"], variable: "--font-sans" })
const mono = DM_Mono({ weight: ["400", "500"], subsets: ["latin"], variable: "--font-mono" })

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html className={`${sans.variable} ${mono.variable}`}>
      <body>{children}</body>
    </html>
  )
}

Dark Mode

import { ThemeProvider } from "next-themes"

// Wrap your app:
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
  {children}
</ThemeProvider>

Use Components

import { Button, Stack, Card, CardHeader, CardTitle, CardContent } from "substrateui"
import { AppShell, AppShellSidebar, AppShellMain } from "substrateui/organisms"
import { cn } from "substrateui/utils"

Exports

| Import path | Contents | |---|---| | substrateui | All 75 UI primitives (Button, Card, Input, Table, etc.) | | substrateui/organisms | App-level patterns (AppShell, PageHeader, PageBody, PageTabs, StatCard) | | substrateui/utils | cn() utility (clsx + tailwind-merge) | | substrateui/styles.css | OKLCH token system + Tailwind theme + base styles |

Requirements

React 18+
Tailwind CSS 4+
tw-animate-css (for animations)
next-themes (optional, for dark mode toggle)
next 15+ (optional, only for substrateui/organisms which use next/link)

Token Architecture

SubstrateUI uses a 3-layer OKLCH color system:

Raw palette — OKLCH values (--raw-plum-600, --raw-amber-500, etc.)
Semantic tokens — Purpose-based mappings (--primary, --surface-raised, --status-error, etc.) with automatic dark mode via .dark class
Tailwind utilities — @theme inline maps tokens to bg-primary, text-foreground, border-border, etc.

Component Categories

General — Button, ButtonGroup, Badge, Kbd, Spinner, Empty
Typography — H1-H4, P, Lead, Large, Small, Muted, Code, Mono
Layout — Stack, Cluster, Grid, Center, Divider, Spacer, Separator, AspectRatio, ResizablePanels
Forms — Input, Textarea, Select, NativeSelect, Checkbox, RadioGroup, Switch, Slider, DatePicker, Combobox, InputGroup, InputOTP, SearchField, Field, Fieldset, FormSection, FormActions
Data Display — Card, Table, DataTable, Avatar, Calendar, Carousel, Chart, HoverCard, Item
Feedback — Alert, AlertDialog, Dialog, Progress, Skeleton, Sonner (toast)
Overlays — Sheet, Drawer, Popover, Tooltip, ContextMenu, DropdownMenu, Command
Navigation — Tabs, Breadcrumb, NavigationMenu, Menubar, Pagination, ScrollArea, Sidebar, Collapsible, Accordion
Patterns — AppShell, PageHeader, PageBody, PageTabs, StatCard

Customization

Override tokens after importing the stylesheet:

/* After importing substrateui/styles.css */
:root {
  --primary: oklch(0.55 0.15 250);  /* Change primary to blue */
}

Accessibility

SubstrateUI meets WCAG AA contrast requirements (verified by automated audit) and is built on Radix UI primitives for robust keyboard and screen reader support.

Every component ships with accessible defaults. For guidance on specific components, see the "Accessibility" section on each component's documentation page.

Storybook

Contributors can browse components in isolation, flip between light/dark themes, swap ltr/rtl direction, and switch the semantic palette from the toolbar.

bun run storybook        # dev server on http://localhost:6006
bun run build-storybook  # static bundle in ./storybook-static

Hosted build: https://substrateui.dev/storybook/

License

MIT