Getting Started

The common path is: install blackwork, import one stylesheet, configure the root theme, and render a first Button. The remaining guides build on this setup.

Blackwork provides layouts, theme controls, and interactive components for blogs and documentation sites. This site and the blog chengpeiquan.com use the same components and serve as working examples.

Start with installation and styles, then use the Next.js App Router example below to build a page with a theme toggle.

For a new documentation site, follow the Docs Starter guide for the template overview, creation command, and deployment steps.

Installation

pnpm add blackwork

For forms built with blackwork/form, also install TanStack Form:

pnpm add @tanstack/react-form

Import styles

Import Tailwind and Blackwork in the app stylesheet:

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

To replace the default sans-serif font, set --blackwork-font-sans:

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

For theme variables and global styles without Tailwind scanning Blackwork component classes, use these entries instead:

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

Set up Next.js

Import the styles in the root layout and use ThemeProvider to manage the theme. Place ThemeScript in head to apply the theme before the content appears, avoiding a flash between light and dark mode. This layout includes a header, main content, footer, and theme toggle.

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

import { Button } from 'blackwork'

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

export default Page

Verify the first page in both themes before adding more components. Then explore Layouts, Theme, and Widgets. The component overview lists the remaining components and the API differences to check when using shadcn/ui examples.