快速开始

Blackwork 是一套面向博客、文档站和其他内容型产品的 React 设计系统。以 npm 包的方式安装，即可使用和本站相同的 UI 组件。我自己的博客 chengpeiquan.com 也在用。

项目里已经有 React 和 Tailwind 时，装这一个包即可。

环境要求

需要 React 19+ 和 Tailwind CSS v4。

安装

Bash

pnpm add blackwork

只有使用 blackwork/form 时才需要再装：

Bash

pnpm add @tanstack/react-form

引入样式

在应用样式表里引入 Tailwind 和 Blackwork：

src/app/globals.css

CSS

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

如果要覆盖默认无衬线字体，设置 --blackwork-font-sans：

src/app/globals.css

CSS

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

如果只需要主题变量和全局样式、不需要扫描 Blackwork 组件 class：

CSS

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

接入 Next.js

先在根布局引入样式，再用 ThemeScript 防止页面载入时闪烁，用 ThemeProvider 管理主题。下面是可直接运行的 App Router 骨架。

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="zh-CN" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body className="flex min-h-dvh flex-col">
        <ThemeProvider>
          <LayoutHeader themeToggle={<ThemeToggle />}>我的网站</LayoutHeader>
          <LayoutMain>{children}</LayoutMain>
          <LayoutFooter>© 我的网站</LayoutFooter>
        </ThemeProvider>
      </body>
    </html>
  )
}

export default RootLayout

第一个组件

src/app/page.tsx

TSX

import { Button } from 'blackwork'

const Page = () => {
  return <Button>开始使用</Button>
}

export default Page

服务端组件

Button、浮层和大部分交互组件从 blackwork 引入。可以在服务端渲染的布局和基础组件从 blackwork/rsc 引入。

接下来用布局搭页面框架，再加上主题和小工具。其余组件跟 shadcn/ui。分层见组件。