Phase 0 · Genesis

Origin & Build Decision

Why stitchwand exists, what it replaces, and the prototype lineage that led to v0.9. This is the pre-build story — Kenos Method Phase 0, captured from the repository's own git history and the surviving PRD documents in the project root.

Origin Story

Stitchwand began life as Stitch Tools — the first commit (61bea74: "Initial commit: Stitch Tools app with docs and landing page") established a monorepo with apps/web and a self-contained docs/ folder. The project was renamed to Stitch Wand in commit 04bd33a, and the wand SVG identity shipped in 12a9bf9.

The founding insight: DESIGN.md is to design systems what README.md is to code. AI coding agents (Cursor, Claude Code, Copilot, Gemini CLI) generate UI constantly but have no structured way to consume design-system context. Every existing tool in the space (Figma Tokens, Style Dictionary, token studios) targets humans or build pipelines, not the coding agents that now write most of the UI. Stitchwand exists to close that gap — by generating a single markdown file that encodes colors, spacing, typography, components, and voice in a form AI agents can read and reason over.

The launch window is non-negotiable: Google Cloud Next, April 22–26. Feature freeze April 14, soft launch April 18, LinkedIn announce April 21, conference coverage April 22–26.

Competitor Snapshot

At the time of writing, there are no direct competitors building AI-consumable design-system context files as a formalized standard. The adjacent landscape:

Figma Tokens / Tokens Studio

Figma plugin for authoring design tokens. Outputs JSON for build pipelines. Gap: no AI-agent-readable format, no compliance scoring, no MCP surface.

Style Dictionary

Amazon's token transformation library. Compiles JSON tokens into every platform format. Gap: build-time only, no runtime agent context, no natural-language semantic layer.

Specify / Supernova

Token platforms with Figma sync and multi-format export. Gap: humans and build tools are the primary audience; AI agents are not a first-class consumer.

◉

Decision: Green Light

No direct competitor is shipping a DESIGN.md standard targeted at AI coding agents. The category is emerging and necessary, and there is a clear time-bounded market window (Google Cloud Next) to plant a first-mover flag. Build decision: ship v0.9 before the conference.

PRD Reference

The product requirements are distributed across four living documents in the project root. They are the authoritative source — the content below is a summary, not a replacement.

OVERVIEW.md

Executive summary: what stitchwand is, who it's for, and how the monorepo is laid out. Primary onboarding read for new contributors and agents.

AUTH_PLAN.md

Phase 3 auth + billing stack: Auth0, Neon Postgres + Drizzle, Stripe (Free / Pro $19 / Team $49 / Enterprise). localStorage → DB migration on first login.

V0.9-LAUNCH-PLAN.md

Soft-launch plan: April 14 freeze, April 18 launch, April 21 LinkedIn, April 22–26 Google Cloud Next. Dogfooding commitment: use Google Stitch to design stitchwand's own UI.

CLAUDE.md

Project instructions for AI agents: monorepo layout, tech stack, key types, upcoming auth stack, TypeScript conventions, dev port 3333.

◆

[NEEDS INPUT]

If any section of this Genesis tab drifts from the live PRD documents, the PRDs win. Re-run the make-docs skill or update this tab by hand to re-sync. Flag for human review: [NEEDS INPUT: verify against current OVERVIEW.md] wherever an ambiguity is noticed.

Prototype Lineage

Four meaningful prototype generations from the git history. Each row represents a paradigm shift, not an incremental commit. See the Builds doc for the interactive prototype tracker and the released builds timeline.

Version	Paradigm	Theme	Tool	What was tested	Outcome
v0.1	Portal / Hub	Editorial / Press	Handwritten HTML · `stitch.tools`	Can a docs-first landing page carry the narrative?	Abandoned — renamed
v0.2	Dashboard	Dark Command	Next.js + Stitchwand rebrand	Does the "Stitchwand" name + wand identity read better?	In progress — rebrand stuck
v0.3	Multi-Agent Workspace	Dark Command	Claude Code + 5 git worktrees	Can 5 parallel agents build a dashboard faster than 1?	Winner — current build methodology
v0.9	Dashboard + Command Palette	Dark Command + Startup/Modern	Next.js 16 · React 19 · Tailwind 4	Is the current surface shippable at Google Cloud Next?	Winner — shipping

Naming Record

Final name: Stitchwand. Domain: stitch.tools (active since commit 984dfaa).

"Stitch"

Signals the Google Stitch integration (the primary upstream tool) and the stitching metaphor — pulling disparate design artifacts into one unified, AI-readable file.

"Wand"

Signals transformation — a tool that takes raw design intent and turns it into structured context for AI agents. Also gives the brand a memorable visual hook (the wand SVG identity).

Rejected: "Stitch Tools"

Too broad, too plural, no transform metaphor. The original name didn't signal what the product does — only that it exists alongside Stitch. The rename shipped in 04bd33a.

Build Decision

The build decision was made when the Google Cloud Next announcement created a time-bounded market window and the competitor scan came back clean. The validating commitment: dogfood Google Stitch — use the same tool stitchwand targets to design stitchwand's own UI. First meaningful milestone: v0.9 dashboard feature-complete with 35+ pages, admin panel, demo mode, and the community system gallery.

◆

Go Criteria — all met

Green light on competitor scan · PRDs written (OVERVIEW.md, AUTH_PLAN.md, V0.9-LAUNCH-PLAN.md, CLAUDE.md) · Name + domain locked (Stitchwand, stitch.tools) · Winning prototype paradigm identified (dashboard + command palette) · Build methodology validated (5-agent Claude Code worktrees, see AGENTS-SETUP-REPORT.md) · Launch date committed (April 18).

Last updated: 2026-04-11 · Added as part of the Kenos Method Phase 0 Genesis pass.

Architecture Overview

How stitchwand Is Built

A monorepo architecture where a pure TypeScript core engine powers every surface — MCP server, CLI, and web application. All processing lives in @stitchwand/core; every surface is a thin wrapper.

System Architecture

The architecture follows a strict layering principle: the core engine has no knowledge of its consumers. Each surface layer (MCP, CLI, Web) adapts the engine's API to its transport mechanism.

External Tools (Consumers)

Claude Code

Cursor

Gemini CLI

GitHub Actions

Surface Layer (Transport Adapters)

MCP Server
stdio transport

CLI
commander.js

Web API Routes
Next.js POST

Core Engine

@stitchwand/core
convert • validate • diff • parse • lint

Web Application

Next.js 16 App
31 pages → API Routes → Core Engine

◆

Key Architectural Decision

The web app calls the core engine through API routes, not directly from client components. This ensures the same code path is used whether the request comes from a browser, an MCP client, or a CLI invocation. The core engine never needs browser APIs.

Updated 2026-04-11 Codebase scan — current counts from the v0.9 monorepo

MCP tools

CLI commands

443

Tests passing

35+

Web pages

API routes

Monorepo Structure

The project uses an npm workspace monorepo managed by Turborepo. Each package has clear boundaries and a single responsibility.

@stitchwand/ ├── packages/ │ ├── core/ # The engine — zero platform deps │ │ ├── src/ │ │ │ ├── convert/ # Token → DESIGN.md conversion │ │ │ ├── validate/ # HTML validation against DESIGN.md │ │ │ ├── diff/ # DESIGN.md A vs B comparison │ │ │ ├── shared/ # Shared parsers & utilities │ │ │ ├── types.ts # All TypeScript interfaces │ │ │ └── index.ts # Public API surface (27 exports) │ │ └── __tests__/ # 315+ tests (Vitest) │ │ │ ├── mcp-server/ # MCP tool definitions │ │ └── src/ │ │ ├── server.ts # MCP server setup & tool registration │ │ └── tools/ # convert, validate, diff tools │ │ │ └── cli/ # Command-line interface │ └── src/ │ ├── commands/ # convert, validate, diff commands │ └── utils/ # chalk output formatting │ └── apps/ └── web/ # Next.js 16 application ├── app/ │ ├── page.tsx # Landing / dashboard │ ├── design-md/ # Token conversion UI │ ├── lint/ # Validation UI │ ├── live-prd/ # Live PRD scan & enrich │ ├── brand-voice/ # Brand voice studio │ ├── voice-studio/ # Voice style editor │ ├── swarm/ # Design Swarm multi-agent │ ├── figma-bridge/ # Figma token bridge │ ├── prompts/ # Prompt library │ └── api/ # API routes (convert, validate, diff) └── components/ # Shared React components

Data Flow

Convert: Tokens → DESIGN.md

Input
JSON / CSS / JS

Parser
format detect

TokenCollection
normalized

DesignSystem
semantic layer

DESIGN.md

Validate: HTML → Grade

HTML + DESIGN.md

Cheerio DOM
parse & traverse

8 Rule Checks
parallel eval

Grade A–F
+ violations

Diff: System A vs System B

DESIGN.md A + B

Category
Matching

DiffResult
additions, removals, modifications

Tech Stack

TypeScript 5

Strict mode, ESM output. Zero any types. Result<T, E> error handling pattern throughout.

Vitest

Test framework with 80%+ coverage target. 315+ tests across core. Colocated in __tests__/ directories.

Turborepo

Build orchestration. Caches builds per package. Dependency-aware task execution across the monorepo.

Next.js 16

React 19, App Router, server components. Web app runs on port 3333 in development.

MCP SDK

@modelcontextprotocol/sdk with stdio transport. Zod schemas for input validation on all tools.

Commander.js

CLI argument parsing with chalk for styled terminal output. 5 commands wrapping core engine functions.

Design Principles

Engine First

All logic in @stitchwand/core with zero platform dependencies. MCP, CLI, and web are thin wrappers. Same code runs in Claude Code, GitHub Actions, or a browser.

Semantic Output

DESIGN.md uses natural language, not raw values. Colors get names ("Deep Ocean" not #1A73E8), spacing gets labels ("generously padded" not 24px). LLMs perform better with natural language context.

MCP Native

Tools designed as MCP server tools first, web UI second. Works inside Claude Code, Cursor, Gemini CLI, or any MCP-compatible client.

Stitch-Specific

Optimized for Google Stitch output patterns — inline styles, specific HTML structures, particular CSS property usage. Specificity is a feature.

Core Engine

The Token Processing Pipeline

Convert design tokens from four formats into semantic DESIGN.md. Validate AI-generated HTML against your design system. Diff two systems to track changes over time.

Token Conversion

Design tokens exist in four widely-used formats. The conversion engine normalizes, resolves references, generates semantic names, and produces DESIGN.md output.

Format	Structure	Reference Syntax	Prevalence
Style Dictionary	Nested JSON with `$value`	`{color.primary.500}`	Very Common
Tokens Studio	Nested JSON with `value`	`{colors.primary.500}`	Common
Tailwind	Flat theme config object	None (direct values)	Very Common
CSS Variables	Flat `:root` declarations	`var(--color-primary)`	Common

Two-Pass Reference Resolution

Token files frequently contain references where one token points to another. The engine uses a two-pass algorithm with circular reference detection.

          TypeScript
          packages/core/src/shared/parse-design-md.ts
        

function resolveReferences(tokens: DesignToken[]): DesignToken[] {
  const tokenMap = new Map(tokens.map(t => [t.name, t]));
  // Pass 1: Resolve direct references
  // Pass 2: Resolve chained references (A → B → C)
  // Circular reference detection via visited set
}

        

Semantic Name Generation

Raw token values are enriched with human-readable names using color-namer and HSL-based fallbacks for colors, and descriptive threshold labels for spacing.

Hex Value	Raw Name	Semantic Name
`#1A73E8`	color-primary-500	Deep Ocean
`#34D399`	color-success	Emerald Glow
`#F59E0B`	color-warning	Warm Amber
`#09090B`	color-bg-dark	Near Black

DESIGN.md Output

The generator produces six standard sections using natural language with parenthesized values. LLMs perform better with semantic context than structured data.

Vibe

Auto-generated personality description based on color warmth, spacing density, and typography.

Color Palette

Every color with semantic name, hex value, and usage hint. Grouped by role.

Typography

Font families, weights, sizes, line heights. Organized by usage.

Spacing & Layout

Base unit, scale values with descriptive labels.

Shape Language

Border radius, shadows, border treatments.

Components

Common component patterns derived from tokens (when sufficient tokens exist).

Validation Engine

Eight validation categories check AI-generated HTML against a DESIGN.md reference. Each violation includes what was expected, what was found, and how to fix it.

CRITICAL COLOR-MATCH

Compares colors using deltaE (CIE2000). Tolerance < 5 deltaE = match.

CRITICAL CONTRAST-CHECK

WCAG 2.1 contrast ratios: 4.5:1 (AA normal), 3:1 (AA large).

SERIOUS TYPOGRAPHY-MATCH

Font-family, weight, and size against the design system spec.

SERIOUS SPACING-MATCH

Padding, margin, gap against spacing scale. 2px tolerance. Unit conversion.

MODERATE RADIUS-MATCH

Border-radius values against shape language. Per-corner validation.

SERIOUS TOUCH-TARGET

44×44px minimum per WCAG 2.5.5 on interactive elements.

MODERATE HEADING-ORDER

h1 → h2 → h3 hierarchy. No skipped levels.

MINOR GUIDELINE-VIOLATION

Anti-patterns: inline styles, !important, hardcoded colors, magic numbers.

Grade Calculation

Scores start at 100, reduced by severity: Critical −10, Serious −5, Moderate −3, Minor −1.

90–100

80–89

70–79

60–69

Below 60

✓

HTML Parsing

The validator uses cheerio for DOM traversal, not JSDOM. 10× faster and sufficient for inline-style inspection, which is all AI tools like Stitch output.

Code & Types

Type System & Public API

A small set of well-defined TypeScript interfaces govern all data flowing through the system. Strict typing with zero any and a Result<T, E> error handling pattern.

Core Type Definitions

          TypeScript
          packages/core/src/types.ts
        

// ─── Token Layer ──────────────────────────────────

interface DesignToken {
  name: string;            // e.g., "color-primary-500"
  value: string;           // e.g., "#6366F1"
  type: TokenType;         // "color" | "spacing" | "typography" | ...
  category?: string;      // e.g., "primary", "neutral"
  description?: string;   // human-readable description
  reference?: string;     // reference to another token
}

interface TokenCollection {
  tokens: DesignToken[];
  format: InputFormat;     // "style-dictionary" | "tokens-studio" | ...
  metadata: { name?: string; version?: string; tokenCount: number; };
}

// ─── Semantic Layer ───────────────────────────────

interface DesignSystem {
  name: string;
  vibe: string;              // generated "vibe" description
  colors: SemanticColor[];
  typography: TypographySet;
  spacing: SpacingScale;
  shapes: ShapeLanguage;
  components?: ComponentPattern[];
}

// ─── Validation Layer ─────────────────────────────

interface ValidationResult {
  grade: "A" | "B" | "C" | "D" | "F";
  score: number;            // 0-100
  violations: Violation[];
  summary: string;
}

interface Violation {
  category: ValidationCategory;
  severity: "critical" | "serious" | "moderate" | "minor";
  selector: string;        // CSS selector where violation found
  expected: string;
  actual: string;
  suggestion: string;
}

// ─── Diff Layer ───────────────────────────────────

interface DiffResult {
  summary: string;
  totalChanges: number;
  changes: TokenChange[];
}

interface TokenChange {
  type: "added" | "removed" | "modified";
  category: string;
  name: string;
  before?: string;
  after?: string;
}
        

Package Dependency Graph

Dependencies are strictly one-directional. The core package has no internal dependencies. Surface packages depend only on core.

No Dependencies (Leaf)

@stitchwand/core

Depends on Core

@stitchwand/mcp-server
+ @modelcontextprotocol/sdk, zod

@stitchwand/cli
+ commander, chalk, ora

Depends on Core (via API routes)

apps/web
+ next, react, framer-motion, tailwindcss

Core Engine External Dependencies

Package	Purpose	Size Impact
`cheerio`	HTML parsing and DOM traversal for validation	~85KB
`chroma-js`	Color manipulation, deltaE calculation, contrast ratios	~40KB
`color-namer`	Generating human-readable color names from hex values	~120KB
`marked`	DESIGN.md Markdown parsing for validation and diff	~50KB

Integrations

Making stitchwand Work Everywhere

MCP (Model Context Protocol) makes stitchwand available as native tools inside any AI-powered development environment. Convert, validate, and diff without leaving your workflow.

What is MCP (Model Context Protocol)?

MCP is an open standard created by Anthropic that defines how AI applications discover and use external tools. Think of it as USB for AI tools — a universal connector that lets any MCP-compatible client (Claude Code, Cursor, Gemini CLI) use any MCP-compatible server (stitchwand, filesystem tools, database tools).

Client

An AI application that wants to use tools. Examples: Claude Code, Cursor, Windsurf, Gemini CLI. The client discovers available tools and calls them during conversations.

Server

A process that exposes tools via the MCP protocol. stitchwand runs as an MCP server, advertising three tools (convert, validate, diff) over stdio transport.

AI Client
e.g., Claude Code

MCP Protocol
stdio / SSE

stitchwand Server
3 tools exposed

Core Engine
execution

Three MCP Tools

convert_tokens

Converts design tokens from any supported format into DESIGN.md.

            Schema
            Input / Output
          

// Input parameters (zod-validated)
{
  tokens: string,       // raw token content (JSON or CSS)
  format?: string,     // "style-dictionary" | "tokens-studio" | "tailwind" | "css"
                        // auto-detected if omitted
}

// Output
{
  designMd: string,    // the generated DESIGN.md content
  stats: {
    tokensProcessed: number,
    referencesResolved: number,
    format: string
  }
}
          

validate_html

Validates HTML output against a DESIGN.md reference, returning a compliance grade and detailed violations.

            Schema
            Input / Output
          

// Input parameters
{
  html: string,        // the HTML to validate
  designMd: string,    // the DESIGN.md to validate against
}

// Output
{
  grade: "A" | "B" | "C" | "D" | "F",
  score: number,
  violations: Violation[],
  summary: string
}
          

diff_systems

Compares two DESIGN.md files and identifies all additions, removals, and modifications.

            Schema
            Input / Output
          

// Input parameters
{
  systemA: string,     // first DESIGN.md content
  systemB: string,     // second DESIGN.md content
}

// Output
{
  summary: string,
  totalChanges: number,
  details: TokenChange[]
}
          

Integration Matrix

How stitchwand connects to different environments and at which stage of development:

Integration	Transport	Convert	Validate	Diff	Status
Claude Code	MCP (stdio)	✓	✓	✓	Live
Cursor	MCP (stdio)	✓	✓	✓	Live
Gemini CLI	MCP (stdio)	✓	✓	✓	Live
Web App	API Routes	✓	✓	✓	Live
CLI	Direct import	✓	✓	✓	Live
GitHub Actions	CLI	✓	✓	✓	Planned
Google Stitch	Chrome Extension	—	✓	—	Phase 2
Figma	Variables API	✓	—	✓	Phase 4
Windsurf	MCP (stdio)	✓	✓	✓	Testing

MCP Server Implementation

The MCP server uses the official @modelcontextprotocol/sdk with stdio transport. Each tool is registered with a Zod schema for input validation.

          TypeScript
          packages/mcp-server/src/server.ts
        

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from
  '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
import { convertTokens, validateHtml, diffSystems } from
  '@stitchwand/core';

const server = new Server({
  name: 'stitchwand',
  version: '1.0.0',
}, {
  capabilities: { tools: {} },
});

// Register convert_tokens tool
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'convert_tokens',
      description: 'Convert design tokens to DESIGN.md format',
      inputSchema: {
        type: 'object',
        properties: {
          tokens: { type: 'string', description: 'Token file content' },
          format: { type: 'string', enum: ['style-dictionary', ...] },
        },
        required: ['tokens'],
      },
    },
    // ... validate_html, diff_systems
  ],
}));

// Start server on stdio
const transport = new StdioServerTransport();
await server.connect(transport);
        

CLI Implementation

The CLI wraps the core engine with commander.js for argument parsing and chalk for styled terminal output.

          Shell
          Usage examples
        

# Convert tokens to DESIGN.md
$ stitch convert tokens.json --format style-dictionary -o DESIGN.md

# Validate HTML against DESIGN.md
$ stitch validate output.html --design DESIGN.md --format json

# Diff two design systems
$ stitch diff v1/DESIGN.md v2/DESIGN.md

# Exit codes:
#   0 = success (or grade A/B for validate)
#   1 = failure (or grade C/D/F for validate)
#   2 = invalid input
        

API Routes

The Next.js web app exposes three POST endpoints, each a thin wrapper around the core engine:

Endpoint	Method	Body	Response
`/api/convert`	POST	`{ tokens, format? }`	`{ designMd, stats }`
`/api/validate`	POST	`{ html, designMd }`	`{ grade, score, violations }`
`/api/diff`	POST	`{ systemA, systemB }`	`{ summary, totalChanges, details }`

Visual Design

The stitchwand Visual Language

Complete token reference, color palette, typography, spacing, shadows, and component patterns for the stitchwand application. Dual-theme support with dark and light modes.

Color Palette — Dark Mode

Primary application palette. Click any swatch to copy the hex value.

Background

Surface

Border

Text

Brand / Accent

Semantic

Extended

Color Palette — Light Mode

Google AI-inspired palette, Material Design 3-influenced. Used when light theme is active.

Background

Surface

Border

Text

Accent

Semantic

Typography

Two font families cover all use cases. Body letter-spacing: -0.011em. Font smoothing: antialiased on all platforms.

Inter — Primary

Display Heading

800 / 44px-0.04em

Section Heading

700 / 28px-0.03em

Card Title

700 / 20px-0.02em

Body text renders at 15 pixels with medium weight and comfortable line height for sustained reading.

500 / 15px-0.011em

Secondary body text and descriptions use regular weight at 13px with muted color.

400 / 13pxdefault

Caption / Label

600 / 11px0.05em upper

JetBrains Mono — Monospace

const token = convert(input, 'w3c');

500 / 14pxmono

--color-accent: #6366F1

400 / 12pxmono

SECTION LABEL

600 / 10pxmono upper

Spacing & Border Radius

Consistent spacing and radius scales create visual rhythm across every component.

Border Radius

8px

--radius-sm

12px

--radius-md

16px

--radius-lg

9999px

--radius-full

Spacing Scale

Shadows

Three elevation levels for dark mode, with lighter variants for light theme.

Dark Mode

Small

0 1px 2px rgba(0,0,0,.4)

Medium

0 4px 12px rgba(0,0,0,.5)

Large

0 8px 32px rgba(0,0,0,.6)

Light Mode

Small

0 1px 2px rgba(0,0,0,.06)

Medium

0 4px 12px rgba(0,0,0,.08)

Large

0 8px 32px rgba(0,0,0,.12)

Component Patterns

Reusable component recipes used throughout the stitchwand interface.

Cards

Surface containers with subtle borders and optional gradient top border on hover.

bg-surface/40 border border-border rounded-xl

Card Title

Card body content here.

Buttons

Three button variants: Primary (filled), Ghost (transparent), and Outline (bordered).

Inputs

Dark-field inputs with subtle borders. Focus state highlights with accent color.

bg-bg-2 border-border rounded-lg focus:border-accent

Badges & Pills

Rounded-full pills for status, tags, and categories. Four semantic variants.

Accent Success Warning Error

Glass Morphism

Frosted-glass overlays for modals, popovers, and floating panels.

backdrop-blur-xl bg-surface/60

Frosted glass panel with backdrop blur

Transitions

Standard easing for all interactive state changes. Consistent timing creates a cohesive feel.

0.2s cubic-bezier(0.4, 0, 0.2, 1)

Hover any element on this page to see the standard transition curve in action.

Animation

Motion design principles for micro-interactions and page transitions.

Page Transitions

Framer Motion fade + translateY entrance. Pages slide up 8px while fading in over 300ms.

initial={{ opacity: 0, y: 8 }}

Staggered Lists

Child items enter sequentially with 40-60ms stagger delay. Creates a cascade effect for grids and lists.

staggerChildren: 0.04

Hover States

150-200ms transition with standard ease. Scale, color, and elevation changes feel immediate but smooth.

transition: all 0.15s ease

Pulse Glow

Notification indicators use a pulsing glow animation. Accent-colored ring scales between 1x and 1.5x.

animation: pulse 2s infinite

Aurora Gradients

Hero backgrounds use slowly moving liquid aurora gradients. Radial gradients shift position over 15-20s loops.

animation: aurora 20s ease infinite

Skeleton Loading

Content placeholders shimmer with a traveling gradient highlight from left to right over 1.5s.

animation: shimmer 1.5s infinite

DESIGN.md Integration

How the stitchwand design system maps to the DESIGN.md format consumed by Google Stitch and AI design agents.

Token Mapping

Each design system section maps directly to a DESIGN.md token category. stitchwand reads and writes these tokens through @stitchwand/core using convert(), validate(), and diff().

Color Palette → colors

Typography → typography

Spacing Scale → spacing

Border Radius → radii

Shadows → shadows

Components → components

Theme Modes

The design system supports dual themes declared as modes: [dark, light] in DESIGN.md. Token values resolve differently per mode, enabling automatic theme switching through Stitch's mode resolution engine.

Google Stitch Usage

When connected to Google Stitch, these tokens are ingested as a DesignSystem object. Stitch uses the token collection to enforce consistency across generated UI, validate designs against the system, and produce accurate diffs when tokens change. The MCP server at @stitchwand/mcp-server exposes these operations to AI agents.

Responsive Breakpoints

Breakpoint	Width	Behavior
Desktop	> 1024px	Full layout, max-width 1140px, side-by-side grids
Tablet	769px – 1024px	Reduced grid columns, maintained padding
Mobile	≤ 768px	Single column, stacked layouts, tab scroll

Additional Notes

Dual Theme Support

stitchwand supports both dark and light themes. The dark aesthetic is the default, matching the Kenos Method brand and developer tool conventions. Light mode uses a Google AI-inspired Material Design 3-influenced palette.

Icon System

Lucide React icons throughout the web application. 20px default size, 1.5px stroke width. Icons use text color hierarchy, never standalone brand colors.

Bonus: Docs System

How the Documentation Is Built

Every doc is a single self-contained HTML file with no external dependencies beyond Google Fonts. No build step, no framework, no bundler.

Self-Contained HTML Pattern

Each documentation page (pitch, demo, architecture, strategy, vision, launch plan) is a standalone .html file in /docs. All CSS and JavaScript is inlined. The only external resources are Google Fonts (Inter + JetBrains Mono). This means:

Zero Build Step

Edit HTML directly, refresh browser. No webpack, no Vite, no compilation. Changes are instant.

Portable

Copy any HTML file anywhere and it works. No server required. Opens from file:// protocol.

Version Controlled

Every change is a git diff. No generated output to ignore. The HTML is the source of truth.

Docs Design System

All docs share a consistent dark-mode design language defined through CSS custom properties.

          CSS
          Shared variables (inline in each doc)
        

:root {
  --border: #27272A;
  --text: #FAFAFA;
  --text-secondary: #A1A1AA;
  --text-muted: #71717A;
  --surface-2: #111114;
  --surface-3: #18181B;
  --accent: #6366F1;
}

/* Fonts: Inter (UI) + JetBrains Mono (code) */
/* Background: #09090B */
/* Selection: rgba(99, 102, 241, 0.35) */
        

Two-Level Navigation System

Every doc has a two-level sticky navigation. The primary nav links between docs. The secondary nav (section-nav) switches between tabs within a doc.

Primary Nav

Sticky at top: 0, z-index 9999. Centered flex layout with blur backdrop. Links: Pitch, Demo, Architecture, Strategy, Vision, Launch Plan, Open App.

          HTML
          Canonical nav structure
        

<nav class="sw-nav">
  <div class="sw-nav-inner">
    <a href="index.html" class="sw-nav-brand">stitchwand</a>
    <div class="sw-nav-links">
      <a href="pitch.html">Pitch</a>
      <a href="demo.html">Demo</a>
      <a href="technical-architecture.html">Architecture</a>
      <!-- ... Strategy, Vision, Launch Plan, Open App -->
    </div>
  </div>
</nav>
        

Section Nav (Subnav)

Sticky at top: 52px (below primary nav), z-index 90. Centered items, blur backdrop, active state via .snav-active class. Each link has a data-tab attribute matching a tab panel ID.

          CSS
          Section nav pattern
        

.section-nav {
  position: sticky;
  top: 52px;
  z-index: 90;
  background: rgba(9,9,11,.92);
  backdrop-filter: blur(16px);
}
.section-nav-inner {
  justify-content: center;
  height: 40px;
  font-family: 'JetBrains Mono', monospace;
}
.section-nav-inner a.snav-active {
  color: #818CF8;
  background: rgba(99,102,241,.08);
}
        

Tab System

Each doc with subtabs uses a panel-based system. Tab panels are div.tab-panel elements shown/hidden by toggling an .active class. The JavaScript syncs both the hidden button bar and the visible section-nav links.

Panel IDs

Tab panels use id="tab-{name}" format. The data-tab attribute on nav links matches the {name} portion.

URL Hash

Active tab is persisted in the URL hash (#engine, #code). Deep linking works on page load.

Keyboard Nav

Arrow keys cycle tabs. Home/End jump to first/last. Focus management follows WAI-ARIA tab pattern.

Fade Animation

Panels enter with a 350ms fade + 8px translateY animation via @keyframes fadeIn.

Auth Gate

Some docs have a simple password gate (password: docs) implemented as an inline JavaScript overlay. The password is stored in localStorage after first entry, so returning visitors bypass it. This is not security — it's a soft gate for pre-launch privacy.

Documentation Files

File	Tabs	Description
`index.html`	—	Hub page with 6 doc cards in a grid
`pitch.html`	—	Slide deck for investors and partners
`demo.html`	3	Videos, Scripts, Interactive Demo
`technical-architecture.html`	6	This document
`strategy.html`	7	AI strategy, GTM, growth, sales, ops
`vision.html`	6	Product vision, labs features, roadmap
`launch-plan.html`	13	Launch plan with task checkboxes
`paid-ads.html`	4	Paid advertising plan and assets

◆

Why Not a Framework?

Self-contained HTML means zero dependencies, zero build failures, zero package updates, and instant iteration. For documentation that needs to be reliable and portable, the simplicity cost of inline CSS/JS is lower than the complexity cost of a framework. Each file is ~3-5K lines but loads in under 200ms.