Getting started with GRAIN
GRAIN is the AI-interaction design system: a UI where registered surfaces can be addressed and operated by both a human and an AI through one shared vocabulary, with the AI's presence shown as a visible signal (grain = AI). It runs on a substrate (BATCH is the reference one) but imports nothing from it. The full reasoning is GRAIN.md; the contract is AI-INTERFACE.md.
Install
GRAIN is published on npm as @tjakoen/grain. Add it to a Bun app with:
bun add @tjakoen/grainWith npm, use npm install @tjakoen/grain. The package resolves from the public npm registry, so a fresh project needs no .npmrc or registry token. The GRAIN monorepo uses Bun workspaces for its internal packages; a separate app installs the published package.
Two layers — start with just the design system
GRAIN is two things, one-directional, so you can adopt only what you need:
- The design system (always usable, no AI required) — the
b-*atoms, the default theme (styles/variables.css→styles/global.css→styles/grain.css), and grade-as-signal (useful on its own: draft vs. saved, focus/editing, in-transit vs. committed). - The AI-interaction layer (opt-in) —
ai/*(the door, the contract, the manifest), the dispatcher island (scripts/ai-dispatch.js), andai/ai.css(the "AI is acting" spotlight).
To use just the design system in a plain BATCH app, link the three stylesheets and the b-* atoms, then skip ai/. Add the AI layer later by following the setup in the GRAIN package README.
The markup conventions in one table
| Attribute | On | Means | ||
|---|---|---|---|---|
data-surface="kind:id" | any region | its address — what render ops target | ||
data-action="verb" | a control | a click sends that verb as an Intent through the configured server or client door | ||
data-kind + data-accepts="v1 v2" | a component root | harvested into the AI manifest | ||
| `data-grade="grain\ | smooth\ | accent"` | any ancestor | provenance: grain = AI, smooth = human |
The verbs themselves live in the closed registry, ai/contract.ts (ActionName / SurfaceKind / ACTIONS) — the single source of truth; never hardcode a verb as a magic string.
Next steps
- Read
GRAIN.mdfor the full design (surfaces, one vocabulary, render ops, manifest). - Read
AI-INTERFACE.mdfor the wire contract (the intent envelope, render-op kinds, the SSE push channel, the AI-acts protocol). - Browse every component live at
/catalog— it's self-documenting. - See it running end to end on the
/grainshowcase — its "watch the AI act" demo drives a real surface through the one door. - Follow
TUTORIAL.mdto build one operable surface end to end, with a real captured request/response.