https://github.com/MikeNotThePope/a8f3k2x9q7
A neobrutalist React component library built on Radix UI primitives, CSS custom properties, and Tailwind CSS v4.
https://github.com/MikeNotThePope/a8f3k2x9q7
component-library css-custom-properties design-system neobrutalism nextjs radix-ui react tailwindcss typescript ui
Last synced: 27 days ago
JSON representation
A neobrutalist React component library built on Radix UI primitives, CSS custom properties, and Tailwind CSS v4.
- Host: GitHub
- URL: https://github.com/MikeNotThePope/a8f3k2x9q7
- Owner: MikeNotThePope
- License: mit
- Created: 2026-03-23T11:04:22.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-05T08:47:50.000Z (about 2 months ago)
- Last Synced: 2026-04-13T22:41:26.667Z (about 2 months ago)
- Topics: component-library, css-custom-properties, design-system, neobrutalism, nextjs, radix-ui, react, tailwindcss, typescript, ui
- Language: TypeScript
- Homepage: https://www.substrateui.dev
- Size: 1.03 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-github-repos - MikeNotThePope/a8f3k2x9q7 - A neobrutalist React component library built on Radix UI primitives, CSS custom properties, and Tailwind CSS v4. (TypeScript)
README
# Substrate UI
A neobrutalist React component library with bold borders, hard shadows, and high contrast design. Built on [Radix UI](https://www.radix-ui.com/) primitives and [Tailwind CSS v4](https://tailwindcss.com/).
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://react.dev/)
**[Documentation & Demos](https://substrate-ui.vercel.app/)** | **[Storybook](https://substrate-ui.vercel.app/)** | **[npm](https://www.npmjs.com/package/@mikenotthepope/substrateui)**
---
## Why Substrate UI?
Most component libraries optimize for invisibility — neutral colors, subtle shadows, rounded everything. Substrate UI goes the other direction: **hard pixel-offset shadows, bold borders, and sharp corners by default.** It's opinionated about aesthetics but flexible about theming, built on Radix UI so accessibility comes free.
- **57 UI primitives** — Button, Dialog, Tabs, Select, DataTable, and more
- **12 landing page components** — Hero, Pricing, FAQ, Testimonials, and more
- **5 composite layouts** — NavBar, CardGrid, SectionNav, SimplePage, TwoColumnLayout
- **Light & dark themes** with CSS custom properties
- **Tree-shakeable** ESM + CJS builds
- **Full TypeScript** support with exported types
## Quick Start
### Install
```bash
npm install @mikenotthepope/substrateui
```
Requires `react` and `react-dom` v19+ as peer dependencies.
### Import the stylesheet
Add the base stylesheet once in your app root. This provides all design tokens and component styles.
```tsx
// app/layout.tsx (Next.js) or src/main.tsx (Vite)
import "@mikenotthepope/substrateui/styles";
```
### Use components
```tsx
import { Button, Card, Text } from "@mikenotthepope/substrateui";
export function Example() {
return (
Hello
Neobrutalist components, ready to go.
Get Started
);
}
```
## Fonts
Substrate UI uses three font families via CSS custom properties:
| Token | Default Font | Purpose |
| -------------- | --------------- | ---------- |
| `--font-head` | Bricolage Grotesque | Headings |
| `--font-sans` | Space Grotesk | Body text |
| `--font-mono` | Space Mono | Code |
**Next.js:**
```tsx
import { Space_Grotesk, Bricolage_Grotesque, Space_Mono } from "next/font/google";
const sans = Space_Grotesk({ variable: "--font-sans", subsets: ["latin"], weight: "400" });
const head = Bricolage_Grotesque({ variable: "--font-head", subsets: ["latin"], weight: ["400", "700", "800"] });
const mono = Space_Mono({ variable: "--font-mono", subsets: ["latin"], weight: "400" });
export default function RootLayout({ children }) {
return (
{children}
);
}
```
**Plain HTML / Vite:**
```html
:root {
--font-head: 'Bricolage Grotesque', sans-serif;
--font-sans: 'Space Grotesk', sans-serif;
--font-mono: 'Space Mono', monospace;
}
```
If fonts aren't loaded, the library falls back to `Space Grotesk -> system-ui -> sans-serif`.
## Theming
### Light / Dark Mode
Use the built-in `ThemeProvider` to manage theme switching:
```tsx
import { ThemeProvider } from "@mikenotthepope/substrateui";
function App({ children }) {
return (
{children}
);
}
```
Access and toggle the theme anywhere:
```tsx
import { useTheme } from "@mikenotthepope/substrateui";
function ThemeToggle() {
const { theme, setTheme } = useTheme();
return (
setTheme(theme === "dark" ? "light" : "dark")}>
Toggle theme
);
}
```
Accepts `"light"`, `"dark"`, or `"system"` (default). Persists to `localStorage` and respects `prefers-color-scheme`.
### Rounded Corners
Components have sharp corners by default. Add `with-radius` to opt in to rounded corners:
```html
```
### Custom Tokens
Override any CSS custom property to customize the theme:
```css
:root {
--primary: #6366f1;
--primary-foreground: #fff;
--primary-hover: #4f46e5;
}
```
See the full token reference in `base/substrate.css`.
## Components
### Primitives
Accordion, Alert, AlertDialog, Avatar, Badge, Breadcrumb, Button, Calendar, Card, Carousel, Chart, Checkbox, Collapsible, Combobox, Command, Container, ContextMenu, DataTable, Dialog, Divider, Drawer, DropdownMenu, Flex, Form, FormLayout, Grid, HoverCard, IconButton, ImageCard, Input, InputOTP, Label, Link, Loader, Marquee, Menu, Menubar, NavigationMenu, Pagination, Popover, Progress, RadioGroup, Resizable, ScrollArea, Select, Sheet, Sidebar, Skeleton, Slider, Sonner, Stack, Switch, Table, Tabs, Text, Textarea, Tooltip
### Landing
AnnouncementBanner, CTABanner, FAQ, FeatureSection, Footer, Hero, LogoCloud, NewsletterSignup, PricingTable, Section, StatsBar, Testimonial
### Composite
CardGrid, NavBar, SectionNav, SimplePage, TwoColumnLayout
## Framework Compatibility
Works in any React 19 environment — Next.js, Vite, Remix, etc.
The `NavBar` component accepts an optional `linkComponent` prop for framework-specific routing:
```tsx
import Link from "next/link";
import { NavBar } from "@mikenotthepope/substrateui";
```
When omitted, it defaults to a plain `` tag.
## Development
```bash
bun install # Install dependencies
bun dev # Start the demo app (Next.js)
bun storybook # Start Storybook
bun test # Run tests
bun run build # Build the library (tsup)
```
### Project Structure
```
substrateui/
├── src/index.ts # Barrel export for the published package
├── components/ui/ # 57 primitive components
├── components/landing/ # 12 landing page components
├── components/ # Composite components + ThemeProvider
├── base/substrate.css # Design tokens & base styles
├── app/ # Next.js demo/docs site
├── AGENTS.md # Shared AI agent instructions
├── CLAUDE.md # Claude Code config (imports AGENTS.md)
└── tsup.config.ts # Library build config
```
## Acknowledgements
Substrate UI draws inspiration from these projects:
- [neobrutalism-components](https://github.com/ekmas/neobrutalism-components) by ekmas
- [RetroUI](https://github.com/logging-studio/retroui) by Logging Studio
## License
[MIT](LICENSE)