Getting Started

Which one are you?

Solo product builder

Building a product alone — no dedicated designer. You want consistent UI without maintaining a sprawling CSS file. → Your path

UX designer at a product team

You have an existing Pencil design system. You need DTCG tokens, component specs, clickable prototypes, and WCAG reports for dev handoff. → Your path

Using an AI coding agent

You're using Claude Code, Cursor, or another MCP-compatible agent to generate UI. nib's MCP server gives it brand context, component specs, and validation tools. → Your path

Prerequisites

• Node.js 20+ or Bun 1.0+
• Pencil.app — only needed for commands that read or write .pen files (capture, brand push, brand import). Token generation and prototype building from a snapshot are fully offline.

Installation

npm

npm install -g usenib

bun

bun install -g usenib

pnpm

pnpm add -g usenib

Two Workflows

nib has two main workflows. You can use them independently or together.

1. Brand System — from guidelines to design tokens

Generate a complete design token system from your brand guidelines:

# Interactive — guided prompts for colors, fonts, personality
nib brand init

# From a file — extract brand values from a markdown document
nib brand init --from brand-guidelines.md

# From a website — pull colors and fonts from a live URL
nib brand init --from https://your-company.com

No AI key? Use --no-ai

By default, nib brand init uses Anthropic (ANTHROPIC_API_KEY). nib also supports OpenAI and local Ollama — see the AI Enhancement section for all providers. Or skip AI entirely and still get 77+ tokens from pure algorithmic derivation:

nib brand init --from brand.md --no-ai

This generates:

• Design tokens (W3C DTCG format) — color primitives, semantic light/dark themes, typography, spacing, elevation, motion
• CSS custom properties + Tailwind preset — ready to drop into any project
• brand.md — a structured context file that AI coding agents read to generate on-brand UI
• WCAG audit — every color pair checked for AA contrast compliance

See the Brand System guide for details.

2. Prototypes — from design to interactive HTML

Export Pencil.dev .pen files to clickable HTML prototypes:

nib prototype my-design.pen

This runs the full pipeline: captures the design via the Pencil MCP server, then builds the HTML output into ./prototype/.

Pencil open required

nib prototype (and nib capture, nib dev) need Pencil.app running with the file open. nib build works fully offline from a .design.json snapshot.

Choose a Template

nib ships with two prototype templates:

# Minimal — great for handoff and review
nib prototype my-design.pen --template clean

# Slide-style — keyboard navigation and transitions
nib prototype my-design.pen --template presentation

See the Templates guide for a visual comparison.

Add a Device Frame

Wrap your prototype in a realistic device frame:

nib prototype my-design.pen --device "iPhone 16 Pro"

Run nib devices to see all available frames.

Dev Mode

Start a local dev server that watches for .pen file changes and hot-reloads:

nib dev my-design.pen

The server starts at http://localhost:3142 and opens your browser automatically.

Connect the Pipelines

The brand system and prototype pipeline work together. After generating tokens, push them into your .pen file:

# Generate brand system
nib brand init --from brand.md

# Push tokens into your Pencil.dev file
nib brand push my-design.pen

# Export the prototype with brand-consistent variables
nib prototype my-design.pen