CLI Commands

brand init New

Generate a brand system from brand guidelines.

nib brand init [OPTIONS]

Flag	Type	Default	Description
--from	string		Source: path to .md/.txt/.pdf/.json file, or a URL
--ai	string	anthropic	AI provider: anthropic, openai, ollama
--output	string	docs/design/system	Output directory
--no-ai	boolean	false	Skip AI enhancement

Outputs: DTCG token files, CSS variables, Tailwind preset, brand.md (AI context file), WCAG audit. Also injects a ## nib Brand System section into every AI agent config file found in the project (CLAUDE.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md, .cursor/rules/nib.md) and always writes AI_CONTEXT.md — so every agent session builds on-brand by default.

Examples:

# Interactive guided flow
nib brand init

# From a markdown file
nib brand init --from brand-guidelines.md

# From a website
nib brand init --from https://acme.com

# From a PDF, no AI
nib brand init --from brand.pdf --no-ai

# From a Tokens Studio JSON export
nib brand init --from tokens.json --no-ai

# Custom output directory
nib brand init --from brand.md -o src/design-system

brand build New

Build platform outputs (CSS, Tailwind, Pencil) from DTCG token files.

nib brand build [OPTIONS]

Flag	Type	Default	Description
--config	string	.nib/brand.config.json	Path to brand config

Examples:

# Rebuild all platform outputs
nib brand build

# Use a custom config
nib brand build --config path/to/brand.config.json

brand push New

Sync design tokens into a Pencil .pen file. Also includes Pencil $-- standard variable mappings ($--background, $--primary, $--foreground, etc.) so Pencil style guides work with your brand out of the box.

If the target file doesn't exist yet, nib creates it and opens it in Pencil automatically — this is the recommended first-time setup path.

nib brand push [file] [OPTIONS]

Flag	Type	Default	Description
--config	string	.nib/brand.config.json	Path to brand config

Pencil open required

Pencil.app must be running. The file path is read from brand.config.json → platforms.penFile (default: docs/design/system/design-system.pen).

First-time setup:

nib brand push
# → Creates docs/design/system/design-system.pen
# → Opens it in Pencil with tokens loaded
# → Save it in Pencil (Cmd+S) to persist

Subsequent pushes:

nib brand push               # uses penFile from brand.config.json
nib brand push my-design.pen # explicit path

brand style New

Fetch a Pencil style guide and push it (with $-- standard variable mappings) to a .pen file.

nib brand style [OPTIONS]

Flag	Type	Default	Description
--tags	string		Comma-separated style guide tags (e.g., minimal,webapp)
--name	string		Fetch a specific style guide by name
--file	string	from config	Path to .pen file
--config	string	.nib/brand.config.json	Path to brand config

When called with no flags, lists the available style guide tags. When --tags or --name is provided, fetches the matching style guide and pushes all variables (including $-- standard mappings) to the .pen file.

MCP Required

This command needs a running Pencil.dev instance with its MCP server accessible.

Examples:

# List available style guide tags
nib brand style

# Fetch a style guide by tags
nib brand style --tags minimal,webapp,developer

# Fetch a specific style guide by name
nib brand style --name "Modern Dashboard"

# Target a specific .pen file
nib brand style --tags minimal --file my-design.pen

brand audit New

Check WCAG contrast compliance of all semantic color token pairs.

nib brand audit [OPTIONS]

Flag	Type	Default	Description
--config	string	.nib/brand.config.json	Path to brand config
--level	string	AA	Minimum level: AA or AAA

Exits with code 1 if any pair fails — suitable for CI pipelines.

Examples:

# Run audit
nib brand audit

# Require AAA compliance
nib brand audit --level AAA

brand validate New

Run 11 automated checks against your token files and component contracts. See the full guide for check details, CI integration, and fixing common issues.

nib brand validate [OPTIONS]

Flag	Type	Default	Description
--config	string	.nib/brand.config.json	Path to brand config
--tokens-dir	string	from config	Override tokens directory
--fail-on	string	all	Which checks block CI: schema, required, a11y, components, all

Exits with code 1 when any errors are present (warnings do not fail).

Examples:

# Run all 11 checks
nib brand validate

# Only fail on schema errors (strictest CI gate)
nib brand validate --fail-on schema

# Validate a custom tokens directory
nib brand validate --tokens-dir ./custom/tokens

brand import New

Import variables from an existing Pencil .pen file into DTCG token files and brand.config.json. Use this when your design system already lives in Pencil and you want to bring it under nib control.

nib brand import <file> [OPTIONS]

Flag	Type	Default	Description
--output	string	docs/design/system/tokens	Tokens output directory
--config	string	.nib/brand.config.json	Path to write brand config

If brand.config.json already exists, nib shows a diff and asks before overwriting.

Pencil open required

Pencil.app must be running with the target .pen file open.

Examples:

# Import from an existing design file
nib brand import docs/design/system/design-system.pen

# Custom output locations
nib brand import design.pen --output src/tokens --config src/.brand.json

---

kit New

Bootstrap a complete design system (tokens + base component kit + Pencil-ready outputs), or return a scaffolding recipe for Claude to draw component frames in Pencil.

# Full bootstrap (interactive)
nib kit

# Bootstrap from a brand brief file
nib kit --from brand.md --no-ai

# Get a Pencil scaffolding recipe
nib kit --recipe [--component Button,Dialog] [--json]

Flag	Type	Default	Description
--from	string		Brand brief: .md/.txt/.pdf file or URL
--no-ai	boolean	false	Skip AI enhancement
--skip-init	boolean	false	Use existing brand.config.json
--recipe	boolean	false	Return a Pencil scaffolding recipe instead of bootstrapping
--component	string	all	With --recipe: comma-separated component names
--json	boolean	false	With --recipe: output as JSON envelope

---

component init New

Scaffold a component contract with WAI-ARIA keyboard patterns pre-filled. Writes the contract JSON, generates component docs, and registers the component in brand.config.json. See the full guide for the complete workflow.

nib component init <name> [OPTIONS]

Flag	Type	Default	Description
--widget-type	string	auto-detected	Force widget type: button, textinput, checkbox, radio, switch, tabs, dialog, combobox, tooltip, generic
--variants	string		Comma-separated variant names (e.g., primary,secondary,ghost)
--sizes	string		Comma-separated size names (e.g., sm,md,lg)
--config	string	.nib/brand.config.json	Path to brand config

Examples:

# Scaffold a Button with auto-detected widget type
nib component init Button

# Specify variants and sizes upfront
nib component init Button --variants primary,secondary,ghost --sizes sm,md,lg

# Force a widget type
nib component init SearchBox --widget-type textinput

# Overwrite an existing contract
nib component init Button --overwrite

---

component list New

List all registered component contracts.

nib component list [OPTIONS]

Flag	Type	Default	Description
--config	string	.nib/brand.config.json	Path to brand config

Example output:

  Button        button      draft     2026-03-04
  TextInput     textinput   draft     2026-03-04
  Dialog        dialog      draft     2026-03-04

---

component story New

Generate a .stories.ts scaffold from a component contract — variant controls, size controls, state stories, and a11y metadata wired automatically. See the full guide.

nib component story <name> [OPTIONS]

Flag	Type	Default	Description
--output, -o	string	src/stories/<Name>.stories.ts	Output path
--framework	string	auto-detected	Override framework: react, vue3, svelte, web-components
--overwrite	boolean	false	Replace an existing story file

Examples:

# Generate a story for the Button component
nib component story Button

# Overwrite after updating the contract
nib component story Button --overwrite

# Target a specific framework
nib component story Button --framework vue3

# Write to a custom path
nib component story Button --output src/ui/Button.stories.ts

---

storybook init New

Wire your nib brand tokens into Storybook — design token panel, light/dark theme switcher, and [data-theme] decorator. Creates or patches .storybook/main.ts, .storybook/preview.ts, nib-theme-decorator.ts, and src/stories/DesignTokens.mdx. Safe to re-run. See the full guide.

nib storybook init [cwd]

Requires:

• brand.config.json must exist (run nib brand init first)
• variables.css must be built (run nib brand build first)

Example:

# Wire Storybook in the current directory
nib storybook init

# Wire Storybook in a subdirectory
nib storybook init ./packages/ui

After running, install the addons nib recommends (the exact command is printed):

npm install @storybook/addon-themes storybook-design-token

Then enable the token panel — set "storybook": { "annotations": true } in .nib/brand.config.json and run nib brand build.

---

pencil open New

Open a .pen file in Pencil from the terminal. Pass new to create a blank canvas.

nib pencil open <file|new>

Pencil must already be running

This command tells the running Pencil.app to open a file — it does not launch Pencil. Open Pencil.app first, then run this command.

Examples:

# Open an existing file
nib pencil open docs/design/system/design-system.pen

# Create a blank canvas
nib pencil open new

After nib pencil open new, save the file in Pencil (Cmd+S) to a path of your choice, then run nib brand push --file <that-path> to push your tokens into it.

pencil status New

Check whether Pencil.app is running and the MCP server is responding.

nib pencil status

Returns one of three states:

• Pencil running — binary found, get_editor_state responded
• Pencil found but not running — binary exists, no response (open Pencil.app)
• Pencil not installed — binary not found at any known path

---

prototype Prototypes

Full pipeline: .pen → HTML prototype (MCP → capture → build).

nib prototype <files...>

Flag	Alias	Type	Default	Description
--output	-o	string	./prototype	Output directory
--template	-t	string	clean	Template: clean, presentation
--standalone		boolean	false	Embed all assets for offline use
--device	-d	string		Device frame name
--config		string		Path to nib.config.json

MCP Required

This command needs a running Pencil.dev instance with its MCP server accessible.

Examples:

# Build a prototype from a single file
nib prototype my-design.pen

# Build with a device frame and presentation template
nib prototype app.pen -t presentation -d "iPhone 16 Pro"

# Standalone single-file output
nib prototype app.pen --standalone -o dist/

capture Prototypes

Extract a .pen file into intermediate JSON.

nib capture <file>

Flag	Alias	Type	Default	Description
--output	-o	string	<filename>.design.json	Output path for the JSON file
--canvases	-c	string	all	Comma-separated canvas names to capture

MCP Required

This command needs a running Pencil.dev instance with its MCP server accessible.

Examples:

# Capture all canvases
nib capture my-design.pen

# Capture specific canvases
nib capture my-design.pen -c "Home,Settings"

# Custom output path
nib capture my-design.pen -o snapshots/design.json

build Prototypes

Build an HTML prototype from a .design.json snapshot. Fully offline — no Pencil, no MCP, no network required.

nib build <input>

Flag	Alias	Type	Default	Description
--output	-o	string	./prototype	Output directory
--template	-t	string	clean	Template: clean, presentation
--standalone		boolean	false	Embed all assets for a single self-contained HTML file
--device	-d	string		Device frame name (see nib devices)
--config		string		Path to nib.config.json for hotspot navigation links

Offline-first

nib build only reads the .design.json file and writes HTML. It never connects to Pencil or any external service. Run it in CI, on a plane, or anywhere.

Hotspot links via nib.config.json:

{
  "links": [
    { "from": "Home", "nodeId": "btn-login", "to": "Login", "transition": "slide-left" },
    { "from": "Login", "nodeId": "btn-back",  "to": "Home",  "transition": "slide-right" }
  ]
}

Transition values: slide-left, slide-right, fade, none (default).

Examples:

# Build from captured JSON
nib build my-design.design.json

# Build with presentation template
nib build my-design.design.json -t presentation

# Build standalone for sharing
nib build my-design.design.json --standalone

dev Prototypes

Start a local dev server with hot-reload on .pen changes.

nib dev <file>

Pencil open required

Pencil.app must be running with the file open. nib dev re-captures the .pen file on every save — it needs the MCP server to read the live node tree.

Flag	Alias	Type	Default	Description
--port	-p	string	3142	Port for the dev server
--template	-t	string	clean	Template: clean, presentation
--open		boolean	true	Open browser automatically

Examples:

# Start dev server
nib dev my-design.pen

# Use a custom port
nib dev my-design.pen -p 8080

# Start without opening the browser
nib dev my-design.pen --no-open

devices

List all available device frames.

nib devices

Available devices:

Name	Width	Height	Category
iPhone 16 Pro	393	852	phone
iPhone 16 Pro Max	430	932	phone
iPhone SE	375	667	phone
Pixel 9	412	924	phone
Samsung Galaxy S24	360	780	phone
iPad Pro 13"	1032	1376	tablet
iPad Pro 11"	834	1194	tablet
iPad Mini	744	1133	tablet
MacBook Pro 16"	1728	1117	desktop
MacBook Pro 14"	1512	982	desktop
MacBook Air 13"	1470	956	desktop
Desktop 1920	1920	1080	desktop
Desktop 1440	1440	900	desktop
Desktop 1280	1280	800	desktop

templates

List available prototype templates.

nib templates

Name	Description
clean	Minimal prototype viewer — ideal for handoff and review
presentation	Slide-style prototype with keyboard navigation and transitions