Themes

A theme in Pitch Smith is a structured collection of brand design tokens -- colors, typography, shapes, spacing, and behavioral rules -- that define the visual identity applied to every slide you create. Rather than styling slides individually, you define your brand once in a theme, and Pitch Smith applies it consistently across all presentations.

What is a theme?

A theme is a JSON file (theme.json) stored in your project's .slide-builder/config/ directory. It captures the design decisions that make your brand recognizable: your color palette, font choices, border styles, component presets, and even personality traits that guide AI-generated content.

Think of a theme as the bridge between your brand guidelines and your slides. When a designer creates a brand book with specific hex codes, font stacks, and spacing rules, a Pitch Smith theme encodes those same decisions in a format that slide templates can consume automatically.

Every theme contains up to eleven top-level sections, each responsible for a different aspect of your brand's visual system:

Section	Purpose
name / version	Identifies the theme and tracks changes
colors	Primary, secondary, accent, background, text, data visualization, and semantic colors
typography	Font families, size scale, weights, and line heights
shapes	Border radii, box shadows, and border styles
components	Preset styles for reusable elements like boxes, buttons, and arrows
slides	Slide dimensions, aspect ratio, and named layout definitions
gradients	Named gradient definitions for backgrounds and decorative elements
workflowRules	Rules that govern slide generation -- background mode rhythm, color schemes, and narrative defaults
personality	Brand personality classification and do/don't guidance for AI content generation
meta	Extraction metadata -- where the theme came from, confidence level, change history
brandContext	Unstructured brand context data (voice, design philosophy, color usage notes) that informs AI slide generation

The first six sections (colors, typography, shapes, components, slides, gradients) define the visual tokens. The remaining sections (workflowRules, personality, meta, brandContext) provide behavioral context that guides how Pitch Smith generates and styles slides.

How themes work

Pitch Smith themes operate through CSS custom properties (CSS variables). When a slide is built, the theme's design tokens are injected as CSS variables into the slide's HTML. Templates reference these variables instead of hardcoding colors or fonts, which means changing your theme automatically updates every slide that uses it.

The flow works like this:

1. Theme defines tokens -- Your theme.json declares values like colors.primary: "#3a61ff" and typography.fonts.heading: "Fraunces".
2. Build injects variables -- At build time, these values become CSS variables: --color-primary: #3a61ff and --font-heading: 'Fraunces', Georgia, serif.
3. Templates consume variables -- Slide templates reference these variables in their CSS: color: var(--color-primary) and font-family: var(--font-heading).
4. Brand stays consistent -- Because templates never hardcode values, switching themes or updating a color propagates everywhere automatically.

This architecture means your slides are always brand-consistent without manual effort. Update your primary color in the theme, rebuild your slides, and every heading, button, and accent element reflects the change.

Theme file structure

Here is a simplified example of a theme.json file showing the major sections. Real themes include more detail in each section; this example highlights the structure:

{
  "name": "My Brand Theme",
  "version": "1.0",
  "colors": {
    "primary": "#3a61ff",
    "secondary": "#334155",
    "accent": "#8455ff",
    "background": {
      "default": "#f8fafc",
      "alt": "#f1f5f9",
      "dark": "#131023",
      "light": "#ffffff"
    },
    "text": {
      "heading": "#131023",
      "body": "#334155",
      "muted": "#64748b",
      "onDark": "#f0eeff",
      "onPrimary": "#ffffff"
    },
    "dataViz": {
      "palette": ["#3a61ff", "#8455ff", "#22c55e", "#f59e0b"],
      "positive": "#22c55e",
      "negative": "#ef4444"
    },
    "semantic": {
      "success": "#22c55e",
      "warning": "#f59e0b",
      "error": "#ef4444",
      "info": "#3b82f6"
    }
  },
  "typography": {
    "fonts": {
      "heading": "Fraunces",
      "body": "DM Sans",
      "mono": "JetBrains Mono"
    },
    "scale": {
      "hero": "72px",
      "h1": "48px",
      "h2": "36px",
      "h3": "24px",
      "body": "16px",
      "caption": "14px"
    },
    "weights": {
      "light": 300,
      "regular": 400,
      "semibold": 600,
      "bold": 700
    }
  },
  "shapes": {
    "borderRadius": {
      "small": "8px",
      "medium": "10px",
      "large": "12px",
      "full": "9999px"
    },
    "shadow": {
      "small": "0 1px 3px rgba(0,0,0,0.06)",
      "medium": "0 4px 12px rgba(0,0,0,0.08)",
      "large": "0 10px 40px rgba(0,0,0,0.10)"
    }
  },
  "components": {
    "box": {
      "default": { "background": "#ffffff", "border": "1px solid #e2e8f0", "radius": "12px" },
      "callout": { "background": "#f1f5f9", "border": "1px solid #e2e8f0", "radius": "12px" }
    },
    "button": {
      "primary": { "background": "#3a61ff", "color": "#ffffff", "radius": "8px" }
    }
  },
  "gradients": {
    "brandGradient": "linear-gradient(135deg, #3a61ff, #8455ff)"
  },
  "workflowRules": {
    "rhythm": {
      "defaultMode": "mixed",
      "maxConsecutiveDark": 2,
      "maxConsecutiveLight": 3
    },
    "narrativeDefaults": {
      "openingSlideMode": "dark",
      "closingSlideMode": "dark",
      "dataSlideMode": "light"
    }
  },
  "personality": {
    "classification": "bold",
    "traits": ["confident", "clear", "human"],
    "guidance": {
      "do": ["Use bold, direct statements", "Lead with benefits and outcomes"],
      "dont": ["Never use jargon without explanation", "Never use passive voice in CTAs"]
    }
  },
  "brandContext": {
    "voice": "Professional but approachable. Use active voice and concise sentences.",
    "designPhilosophy": "Clean, modern minimalism with strategic use of bold color as accent."
  }
}

For the complete field-by-field reference of every section, see the Theme Schema Reference (coming in Story 4.6).

Customizing your theme

Pitch Smith provides several approaches for creating and refining your theme, depending on how much control you need:

Brand extraction

The most common starting point is automatic brand extraction. During brand setup, you provide brand assets -- a website URL, logo files, brand guidelines, or style references -- and Pitch Smith's AI analyzes them to generate a complete theme.json. The extraction process identifies your colors, infers typography choices, and creates a cohesive set of design tokens.

This approach gives you a working theme in minutes. The meta section of the generated theme records what assets were analyzed and the extraction confidence level, so you can evaluate how well the automated process captured your brand.

To learn more about the extraction workflow, see Brand Setup.

Natural language theme editing

Once you have a theme, you can refine it through natural language commands. Using /pitchsmith:theme-edit, you describe the change you want -- for example, "make the primary color warmer" or "increase heading font sizes by 10%" -- and Pitch Smith updates the theme accordingly. This approach is useful for iterative refinement when you know what you want but don't want to manually edit JSON.

Manual JSON editing

For precise control, you can edit theme.json directly. The file is standard JSON, so any text editor works. This approach is best when you need to set exact hex codes, adjust specific spacing values, or configure advanced sections like workflowRules or brandContext.

You can view your current theme summary at any time using the /pitchsmith:theme command, which displays a formatted overview of all theme sections.

The Theme Customization guide (coming in Story 4.5) walks through each of these approaches step by step.

Dark and light themes

Pitch Smith themes handle dark and light modes through the workflowRules section rather than maintaining separate theme files. A single theme contains color values for both dark and light slide backgrounds, and the workflowRules.rhythm configuration controls when each mode is used.

The workflowRules.colorSchemes section defines complete color palettes for dark and light contexts:

{
  "workflowRules": {
    "colorSchemes": {
      "dark": {
        "background": "#131023",
        "surface": "#1a1730",
        "text": "#f0eeff",
        "textSecondary": "#c4bfdf",
        "border": "#2d2b45"
      },
      "light": {
        "background": "#f8fafc",
        "surface": "#ffffff",
        "text": "#131023",
        "textSecondary": "#334155",
        "border": "#e2e8f0"
      }
    }
  }
}

The rhythm settings control the visual cadence of your deck. For example, maxConsecutiveDark: 2 prevents more than two dark-background slides in a row, creating visual variety. The narrativeDefaults specify that opening and closing slides typically use dark backgrounds (for dramatic impact) while data slides use light backgrounds (for readability).

This single-theme approach means you don't need to manage separate "dark" and "light" themes. Your brand identity stays unified across all slide background modes, and the rhythm rules ensure a visually engaging flow throughout your presentation.

Related resources

• Brand Setup -- How to extract a theme from brand assets
• Theme Schema Reference (coming in Story 4.6) -- Complete field-by-field documentation of every theme.json section
• Theme Customization guide (coming in Story 4.5) -- Step-by-step instructions for refining your theme