blackchalk

Hand-drawn, monochrome React components built on rough.js. Wireframe-style UI that looks deliberately unfinished, so people react to the idea instead of the pixels.

It is built to be used by AI coding agents as much as by people. The rules, a catalogue of every component and a Claude Code skill ship inside the npm package, and every value a component draws with is an exported token, so an agent building a screen composes it from the system instead of redrawing it on every prompt.

Docs · Storybook · Starter app · npm

Install

npm install blackchalk

import "blackchalk/styles.css";
import "blackchalk/fonts.css"; // optional: the bundled Caveat handwriting face
import { SketchPaper, SketchCard, SketchButton } from "blackchalk";

export default function Page() {
  return (
    <SketchPaper>
      <SketchCard>
        <SketchButton variant="primary">Get started</SketchButton>
      </SketchCard>
    </SketchPaper>
  );
}

Works in Next.js App Router Server Components as they are: the components are marked as client modules, and the interactive ones work without handlers passed in.

Building with an agent

The package carries its own instructions, at the version installed:

| File | What it holds | |---|---| | node_modules/blackchalk/AGENTS.md | Setup and the rules: monochrome only, tokens never raw values, components for the common 80% and draw the rest, build pages from the layout patterns | | node_modules/blackchalk/CATALOG.md | All 88 components by purpose, with what each is for, what it is not for and the neighbour to use instead | | node_modules/blackchalk/skills/blackchalk/ | A Claude Code skill that loads the above whenever a task builds UI with blackchalk |

Point a project at them with one line in its AGENTS.md or CLAUDE.md:

UI is built with blackchalk. Before writing any UI, read
node_modules/blackchalk/AGENTS.md and node_modules/blackchalk/CATALOG.md.

and, for Claude Code, copy the skill in:

mkdir -p .claude/skills && cp -r node_modules/blackchalk/skills/blackchalk .claude/skills/

The starter app has all of this set up.

What is in it

88 components across text, form controls, overlays, navigation, display, feedback, charts, page layout and commerce patterns. CATALOG.md lists them all; the docs show each one live.

The library covers the common 80% and stops there on purpose. For the rest (a hero, a pricing block, a browser window) SketchOutline draws the system's line around anything and SketchText sets it in the system's type, so a piece built by hand in the page looks like it belongs.

Tokens

Every visual decision lives once, in src/tokens.ts and the stylesheet it reads from, and is exported:

| Token | Decides | |---|---| | colors, fills | ink, muted text, borders, background, and five solid fill strengths | | strokes, roughness | how thick a drawn line is, and how far it wanders (a theme's roughness scales it all) | | space | padding, margin and gap on a 4px scale | | typography | the hand font and a running-text font, an eleven-step type scale in real sizes, line heights and letter spacing |

blackchalk/tokens exports the same values without React, for server code and build scripts.

Theming

Monochrome by design: a theme is a background, an ink colour, optional fonts and an optional wobble setting, and every other colour is derived from the ink. Dark mode is data-theme="dark" on any ancestor, or SketchThemeProvider with darkTheme. See Theming.

Accessibility

The drawing is paint over real semantics: buttons are <button>, inputs are <input>, custom widgets carry the right roles and keys, and overlays trap and restore focus. Keyboard focus is a hand-drawn halo rather than a browser outline. Every story is scanned with axe-core in light and dark mode, plus a keyboard sweep, before each release.

Other entry points

• blackchalk/static: the same components with no animation runtime, for static renders.
• blackchalk/styles.host.css: the stylesheet for mounting inside a shadow root. See docs/embedding.md.

Contributing

See CONTRIBUTING.md. Component requests are welcome when a piece keeps coming up: something you have built by hand from SketchOutline more than once is the best case for a new component.

Licence

MIT