Project Structure

nib uses an opinionated folder layout. Some of it is generated and managed for you — the rest is yours to own and version.

Annotated Directory Tree

my-project/
│
├── brand.md                              # Your brand brief — fill this in first
├── nib.config.json                       # Prototype navigation links (optional)
│
├── .nib/                                 # nib tool config — auto-generated
│   ├── brand.config.json                 # Brand preferences, paths, AI provider
│   └── components/                       # Component contracts (JSON)
│       ├── Button.contract.json
│       └── ...
│
├── docs/design/
│   │
│   ├── system/                           # Design system — nib manages this
│   │   ├── design-system.pen             # Pencil file: variables + component kit
│   │   │                                 # (auto-created by `nib brand push`)
│   │   ├── brand.md                      # AI context file (generated)
│   │   ├── components.md                 # Component registry (generated)
│   │   ├── tokens/                       # DTCG token files (generated — commit these)
│   │   │   ├── color/
│   │   │   │   ├── primitives.tokens.json
│   │   │   │   ├── semantic-light.tokens.json
│   │   │   │   └── semantic-dark.tokens.json
│   │   │   ├── typography.tokens.json
│   │   │   ├── spacing.tokens.json
│   │   │   └── ...
│   │   ├── build/                        # Platform outputs (generated — can gitignore)
│   │   │   ├── css/variables.css
│   │   │   ├── tailwind/preset.js
│   │   │   └── pencil/variables.json
│   │   └── components/                   # Per-component specs (generated)
│   │       ├── Button.md
│   │       └── ...
│   │
│   └── screens/                          # UX flows — you own these
│       ├── 01-onboarding/
│       │   ├── onboarding.pen            # Pencil design file (Pencil open to capture)
│       │   ├── onboarding.design.json    # Captured snapshot — commit for CI
│       │   └── README.md                 # Flow context for AI agents + developers
│       ├── 02-dashboard/
│       │   ├── dashboard.pen
│       │   ├── dashboard.design.json
│       │   └── README.md
│       └── 03-settings/
│           └── ...
│
└── prototype/                            # Built prototype output
    └── index.html                        # (typically gitignored; share standalone builds)

What nib Manages vs What You Own

Path	Owner	Notes
brand.md (root)	You	Your brand brief — source of truth for nib brand init
nib.config.json	You	Navigation links between prototype screens
.nib/brand.config.json	nib	Auto-generated — don't edit manually
.nib/components/*.contract.json	nib	Generated by nib component init
docs/design/system/design-system.pen	You (nib seeds it)	First created by nib brand push; then you design in it
docs/design/system/tokens/	nib	Generated — but commit to version-control
docs/design/system/build/	nib	Generated — safe to gitignore
docs/design/system/brand.md	nib	AI context file — re-generated on nib brand build
docs/design/screens/*/	You	Your UX flow files — own this entirely
docs/design/screens/*/*.design.json	nib (captures)	Commit these — CI rebuilds prototypes from them
prototype/	nib	Built output — gitignore or share the standalone HTML

Screen Directory Convention

Name each screen directory with a two-digit prefix so they sort in flow order:

docs/design/screens/
├── 01-onboarding/
├── 02-sign-in/
├── 03-dashboard/
├── 04-settings/
└── 05-checkout/

Each directory contains three files:

File	Purpose
<flow>.pen	Pencil design file — one file per UX flow, with one canvas per screen
<flow>.design.json	Captured snapshot — commit this so CI can run nib build without Pencil
README.md	Flow context — read by AI agents, developers, and stakeholders

Screen README Template

Copy this for each new UX flow:

# Onboarding Flow

## Overview
New user registration and initial account setup — 4 screens.

## Screens
1. **Welcome** — hero + primary CTA
2. **Sign Up** — email + password form with validation
3. **Verify Email** — confirmation page, resend option
4. **Done** — success state + redirect to dashboard

## User Journey
User lands on Welcome → clicks "Get started" → fills Sign Up form
→ receives email → clicks verify link → arrives at dashboard.

## Edge Cases
- Invalid email format → inline error on blur
- Password too weak → live strength indicator
- Email already registered → error + "Sign in instead" link
- Verification link expired → resend flow

## Navigation Links
Wire these in `nib.config.json` for the clickable prototype:

| From | Element | To | Transition |
|---|---|---|---|
| Welcome | `btn-get-started` | Sign Up | slide-left |
| Sign Up | `btn-back` | Welcome | slide-right |
| Sign Up | `btn-submit` | Verify Email | fade |
| Verify Email | `btn-resend` | Verify Email | none |

## Implementation Notes
- Sign Up form: client-side email validation, password strength indicator
- Error states: use `TextInput` component contract error variant
- Token to use for CTA: `color.interactive.default` (button fill)
- Spacing between form fields: `spacing.md` (16px)

The Full Sequence

One-time setup

# 1. Write your brand brief
#    Copy the template from the Brand System guide → "Creating a Brand Brief"
vim brand.md

# 2. Generate your design token system
nib brand init --from brand.md

# 3. Push tokens into Pencil — creates design-system.pen automatically
#    Open Pencil.app first, then:
nib brand push
# → Pencil opens docs/design/system/design-system.pen
# → Save it in Pencil (Cmd+S)

# 4. Scaffold the component kit in Pencil
nib kit --recipe --json
# → Returns component frames with brand variables pre-wired
# → Use Claude to draw the frames: "Draw the nib component kit in my Pencil file"

Per UX flow

# 1. Create the screen directory
mkdir -p docs/design/screens/01-onboarding
cp .nib/templates/screen-readme.md docs/design/screens/01-onboarding/README.md

# 2. Open a new Pencil file for this flow
nib pencil open new
# → Save as docs/design/screens/01-onboarding/onboarding.pen (Cmd+S)

# 3. Design your screens in Pencil
#    Use token variables (e.g. {var.color-interactive-default})
#    Use component frames from the kit

# 4. Capture the design
nib capture docs/design/screens/01-onboarding/onboarding.pen \
  -o docs/design/screens/01-onboarding/onboarding.design.json
# → Commit the .design.json — CI can rebuild without Pencil

# 5. Build the prototype
nib build docs/design/screens/01-onboarding/onboarding.design.json \
  --config nib.config.json \
  --standalone \
  -o prototype/

For AI agents

All docs/design/screens/*/README.md files are structured for AI consumption. Ask Claude: "Read the onboarding flow README and implement the Sign Up screen." — it will find token bindings, component states, edge cases, and navigation context without you repeating yourself.

Suggested .gitignore additions

# nib build outputs — regenerate with `nib brand build`
docs/design/system/build/

# Prototype builds — share standalone HTML files instead
prototype/

# Pencil editor cache
*.pen.bak

Do not gitignore:

• docs/design/system/tokens/ — source of truth for your token values
• docs/design/screens/*/*.design.json — enables CI builds without Pencil
• .nib/brand.config.json — keeps tool config in sync across the team
• .nib/components/*.contract.json — component specs used by all AI agents