Getting Started

Blackwork is a React design system for blogs, documentation sites, and other content-driven products. Install it as an npm package and you can use the same UI components as this site. My blog chengpeiquan.com uses it too.

If the app already has React and Tailwind, install this one package.

Requirements

Use React 19+ and Tailwind CSS v4.

Installation

Bash

pnpm add blackwork

Add this only when you use blackwork/form:

Bash

pnpm add @tanstack/react-form

Import styles

Import Tailwind and the Blackwork entry in your app stylesheet:

src/app/globals.css

CSS

@import 'tailwindcss';
@import 'blackwork/tailwind.css';

Set --blackwork-font-sans if you want to override the default sans font:

src/app/globals.css

CSS

:root {
  --blackwork-font-sans: 'Your Font', sans-serif;
}

If you only need theme tokens and globals without scanning Blackwork component classes:

CSS

@import 'blackwork/theme.css';
@import 'blackwork/ui-globals.css';

Set up Next.js

Import the styles in the root layout, use ThemeScript to prevent a flash during page load, and mount ThemeProvider once. This is a complete App Router skeleton.

src/app/layout.tsx

TSX

import { LayoutHeader, ThemeProvider, ThemeToggle } from 'blackwork'
import { LayoutFooter, LayoutMain, ThemeScript } from 'blackwork/rsc'
import './globals.css'

const RootLayout = ({ children }: React.PropsWithChildren) => {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body className="flex min-h-dvh flex-col">
        <ThemeProvider>
          <LayoutHeader themeToggle={<ThemeToggle />}>My site</LayoutHeader>
          <LayoutMain>{children}</LayoutMain>
          <LayoutFooter>© My site</LayoutFooter>
        </ThemeProvider>
      </body>
    </html>
  )
}

export default RootLayout

First component

src/app/page.tsx

TSX

import { Button } from 'blackwork'

const Page = () => {
  return <Button>Get started</Button>
}

export default Page

Server components

Button, overlays, and most interactive components come from blackwork. Server-renderable layouts and primitives come from blackwork/rsc.

Next, compose Layouts for the page chrome, then Theme and Widgets. Most other primitives follow shadcn/ui. See Components for the split.