blackwork

Blackwork Tattoo style React UI layout for blogs, documentation sites, and other content-driven websites.

Install

With pnpm (or npm or yarn):

pnpm add blackwork @bassist/utils clsx react tailwindcss tailwind-merge tailwindcss-animate

If you use the Tailwind example below, install the typography plugin as well:

pnpm add -D @tailwindcss/typography

These are optional and only need to be installed if the corresponding subpath is used:

# For `blackwork/form`
pnpm add @hookform/resolvers react-hook-form

Usage

Tailwind CSS v3

In your tailwind.config.ts:

import { createBlackworkTailwindConfig } from 'blackwork/tailwind-config'
import typography from '@tailwindcss/typography'
import animate from 'tailwindcss-animate'

export default createBlackworkTailwindConfig({
  rootDir: import.meta.url,
  content: [
    'src/app/**/*.{js,mjs,cjs,ts,jsx,tsx,mdx}',
    'src/components/**/*.{js,mjs,cjs,ts,jsx,tsx,mdx}',
    'content/**/*.{js,mjs,cjs,ts,jsx,tsx,mdx}',
  ],
  plugins: [typography, animate],
})

If you only need the shared theme tokens and want to assemble the rest yourself, theme is also exported from blackwork/tailwind-config.

In your root layout:

// e.g. `src/app/layout.tsx`
import 'blackwork/ui-globals.css'

Tailwind CSS v4

Tailwind CSS v4 users do not need blackwork/tailwind-config. Import Tailwind and the Blackwork v4 CSS entry from your app stylesheet:

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

Set --blackwork-font-sans in your app stylesheet if you want to override Tailwind v4's font-sans token.

If you only need the shared theme tokens and globals without scanning Blackwork components, import the lower-level CSS entries directly:

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

In your layout or other components:

// e.g. `src/app/page.tsx` or an MDX component
import {
  Alert,
  AlertDescription,
  AlertTitle,
  LayoutFooter,
  LayoutMain,
} from 'blackwork/rsc'

export default function Page() {
  return (
    <LayoutMain>
      <Alert>
        <AlertTitle>Blackwork</AlertTitle>
        <AlertDescription>
          Use the `blackwork/rsc` entry in server components when you only need
          server-renderable primitives.
        </AlertDescription>
      </Alert>

      <LayoutFooter />
    </LayoutMain>
  )
}

In client components:

'use client'

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
  ScrollToTop,
  ThemeToggle,
  useKeyword,
} from 'blackwork'

// Icons
import { Moon, Sun } from 'blackwork/icons'

// Form
import { Form } from 'blackwork/form'

Documentation

There is no dedicated documentation site yet. Most primitive component usage follows shadcn/ui patterns.

For the package-specific APIs, refer to the props and examples in the source code.