Getting Started

Get up and running with StyleScribe in minutes.

Prerequisites

• Node.js 20.0.0 or higher
• npm or pnpm

Installation

Global Installation (Recommended)

npm install -g stylescribe

Project-local Installation

npm install --save-dev stylescribe

Create Your First Project

The init command scaffolds a new StyleScribe project with sensible defaults.

stylescribe init my-design-system
cd my-design-system
npm install

Interactive Setup

Running init without flags starts an interactive wizard:

stylescribe init

You'll be prompted for:

• Project name - Your design system name
• Dark mode - Enable dark theme support
• Theme variant - Add a custom theme (e.g., "comic", "brand")
• CSS prefix - Class prefix for components (e.g., "ds-")
• Claude Code support - Generate CLAUDE.md for AI assistance

Quick Setup

Skip prompts with flags:

stylescribe init my-docs --yes --dark --prefix="ui-"

Project Structure

After initialization, you'll have:

my-design-system/
├── .stylescriberc.json    # Configuration
├── sass/
│   ├── base.scss          # Base styles & CSS layers
│   └── components/        # Component SCSS files
│       └── button/
│           └── button.scss
├── tokens/
│   └── design-tokens.json # W3C DTCG tokens
├── docs/
│   └── index.md           # Documentation pages
└── package.json

Development Server

Start the live development server:

npm run dev
# or
stylescribe dev

Open http://localhost:4142 in your browser.

The dev server:

• Compiles SCSS to CSS
• Extracts component annotations
• Generates documentation pages
• Hot reloads on file changes

Create a Component

Use the CLI to scaffold a new component:

stylescribe create-component alert --group="Communication"

This creates sass/components/alert/alert.scss with annotation template:

/**
 * @title Alert
 * @description Add a description
 * @group Communication
 * @examples
 * - title: Default
 *   code: |
 *     <div class="ds-alert">Content</div>
 */
.ds-alert {
  /* Component styles */
}

Add Documentation Pages

Create markdown documentation:

stylescribe create-page usage-guide --title="Usage Guide"

This creates docs/usage-guide.md:

---
title: Usage Guide
navtitle: Usage Guide
slug: usage-guide
order: 10
---

Your content here...

Build for Production

Generate the static documentation site:

npm run docs
# or
stylescribe docs --output=./site

The site/ folder contains your complete documentation ready for deployment.

Next Steps