Quick Start Guide

Get Saddle running with your component library in under 5 minutes.

Installation

Download Saddle

Download the latest release for macOS from GitHub:

# Or build from source:
git clone https://github.com/yarv-dev/saddle.git
cd saddle
npm install
npm run tauri dev

Prepare your component library

Saddle works with any React component library that uses a directory-per-component structure:

my-components/
├── saddle.config.json          # Global design tokens
├── design.md                   # Master design system docs
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.Primary.tsx
│   │   │   └── Button.Secondary.tsx
│   │   └── Input/
│   │       └── Input.Default.tsx
│   └── blocks/
│       └── CardBlock/
│           └── CardBlock.tsx

Add design.md frontmatter to components

Each component file uses YAML frontmatter that AI can parse:

---
name: Button Primary
description: Primary action button with high emphasis
tokens:
  backgroundColor: "#007AFF"
  color: "#ffffff"
  borderRadius: "8px"
  padding: "12px 24px"
props:
  - label: string
  - onClick: function
  - disabled?: boolean
usage: |
  Use for primary calls-to-action.
  Never use more than one per screen section.
---

import React from 'react';

export const ButtonPrimary = ({ label, onClick, disabled }) => (
  <button onClick={onClick} disabled={disabled}
    style={{ backgroundColor: '#007AFF', color: '#fff',
             borderRadius: '8px', padding: '12px 24px' }}>
    {label}
  </button>
);

Create saddle.config.json

Define your global design tokens:

{
  "name": "My Design System",
  "version": "0.1.0",
  "tokens": {
    "colors": {
      "primary": "#007AFF",
      "secondary": "#f5f5f7",
      "brand": "#1d1d1f",
      "success": "#34C759",
      "danger": "#FF3B30",
      "text": "#1d1d1f",
      "muted": "#86868b"
    },
    "spacing": {
      "xs": "4px", "sm": "8px", "md": "16px",
      "lg": "24px", "xl": "32px"
    },
    "rounded": {
      "sm": "4px", "md": "8px", "lg": "12px", "full": "9999px"
    },
    "fontSize": {
      "sm": "12px", "base": "14px", "lg": "16px", "xl": "18px"
    }
  }
}

Load in Saddle

Open Saddle, click Load Project, and select your project root. The wizard will auto-detect your component directories and file extensions.

Using the Editor

Style Editor (Figma-style)

Click any component in the sidebar to open the editor. The right panel shows all CSS properties organized by section: Layout, Size, Spacing, Fill, Stroke, Typography, Effects.

Token properties (blue labels) are editable and save to frontmatter
Code properties (gray labels) are read-only extractions from JSX
Click Tokenize to promote a code property to a token
Use the token picker to select from your global design tokens
Click x to remove a token property
Click + Add to add any CSS property

Preview

The center panel shows a live preview that updates in real time as you edit tokens. Switch between variants using the tabs at the top.

Code Editor

The Code tab shows a full Monaco editor (VS Code engine) with syntax highlighting, code folding, and line numbers.

AI Guidance

The AI tab lets you edit the design.md metadata that Claude Code uses to understand your components: name, description, and usage guidelines.

Creating Variants

Click + New Variant in the editor to create a new variant file with boilerplate frontmatter and code.

Claude Code Integration (MCP)

One-click setup

Go to Dashboard > Claude Code (MCP) > Install for Claude Code CLI. This writes a .mcp.json file to your project root that Claude Code auto-discovers.

Manual setup

Add to your Claude Code settings or ~/.claude.json:

{
  "mcpServers": {
    "saddle": {
      "command": "node",
      "args": ["/path/to/your/project/mcp-bridge.mjs"]
    }
  }
}

Available MCP tools

Once connected, Claude Code can use these tools:

saddle_list_components — List all components with variants and metadata
saddle_get_component — Get full schema (tokens, props, usage) for a component
saddle_update_tokens — Update design tokens (saves to file immediately)
saddle_read_component — Read full source code with frontmatter
saddle_create_variant — Create new variant with boilerplate
saddle_get_global_tokens — Read saddle.config.json tokens

Example: Ask Claude to create a variant "Create a Ghost variant for the Button component with transparent background, #007AFF text color, and no border."

Claude will use saddle_create_variant to generate the file with proper frontmatter and code.

Remote MCP (AWS)

Saddle also runs an MCP server on AWS Lambda for remote access:

Endpoint: https://nwkhrtp6qre2dna6muyfyztugu0kliiu.lambda-url.ap-southeast-2.on.aws/
DNS: mcp.saddle.staplelab.com (coming soon)

Exporting

npm Package

Go to Export > Build Package. Saddle generates:

Clean React components (frontmatter stripped)
Generated CSS Modules from tokens
Global tokens.css with CSS variables
package.json with conditional exports (dev reads source, prod reads dist)
index.ts barrel export

W3C Design Tokens (DTCG)

Click Export DTCG tokens.json to generate tokens in W3C Design Tokens Community Group format for interoperability with Figma, Style Dictionary, and other tools.

Deduplication Analysis

Click Run Analysis to scan all components for:

Token duplicates — Same value used across components (suggests creating a shared token)
Structure duplicates — Components with identical JSX patterns (suggests extraction)

Organization

Hierarchy View

The Hierarchy view in the sidebar shows an expandable tree of your entire component library: project root > components > variants.

Master design.md

The design.md tab in Hierarchy view lets you edit your master design system documentation in a full Monaco markdown editor. This file lives at your project root and documents the design system for both humans and AI.

Dev Server Connection

Go to Dashboard > Dev Server to connect to a running dev server:

Auto-detect scans common ports (3000, 5173, 8080, 4200, 3001)
Manual enter any URL

When connected, Saddle's file watcher detects changes and logs them in the terminal. Your dev server's HMR picks up token changes automatically.

File watcher Saddle watches your project directory for external changes (IDE edits, Claude Code modifications). All changes appear in the terminal feed.

Terminal Feed

The bottom panel shows a live log of all activity: file changes, token updates, Claude Code interactions, and build output. Click Terminal to toggle it. You can also type commands to send to Claude Code (when connected via MCP).

Back to Home View Source