Customize Theme

View your current theme, edit it with natural language feedback, adjust CSS variables manually, and preview theme changes on your slides. This guide covers both the AI-assisted and manual approaches to theme customization.

Prerequisites

Before customizing your theme, make sure you have:

• A Pitch Smith workspace scaffolded in your project (run /pitchsmith if you have not set one up yet -- see Quickstart)
• Brand setup complete with an existing theme (run /pitchsmith:setup first -- see Brand Setup)
• Claude Code running in your project directory

View Current Theme

Display a summary of your current theme settings including colors, typography, shapes, and available templates.

1. Open a Claude Code session in your project directory.

2. Run the theme command:

   /pitchsmith:theme

3. Pitch Smith reads your theme.json file and displays a formatted summary with color swatches:

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     THEME: Your Brand (v1.0)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   
   COLORS
     Primary:    ## #CCFF00
     Secondary:  ## #5DBAB6
     Accent:     ## #FF6B6B
     Background: ## #FFFFFF (default) | ## #F5F5F5 (alt)
     Text:       Heading #1A1A1A | Body #4A4A4A
   
   TYPOGRAPHY
     Heading: Outfit (700)
     Body:    Outfit (400)
     Scale:   Hero 72px > H1 48px > H2 36px > Body 18px
   
   SHAPES
     Boxes:   8px corners, medium shadow
     Callout: 8px corners, lime border
   
   LAYOUTS (4 templates)
     title, content, split, data
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Verify: Theme summary displayed

The output should show your brand's colors, fonts, shape styles, and template count. If you see a "No Theme Found" message, run /pitchsmith:setup to create your theme first.

Edit Theme with Natural Language

Modify your theme by describing the changes you want in plain English. Pitch Smith interprets your feedback and adjusts the theme primitives (colors, typography, shapes) accordingly.

1. Open a Claude Code session in your project directory.

2. Run the theme-edit command:

   /pitchsmith:theme-edit

3. Pitch Smith displays your current theme and saves a backup to the version history. You are then prompted to describe what you want to change.

4. Describe your desired changes using natural language. For example:

   • "warmer colors" -- shifts palette toward orange and red tones
   • "bolder fonts" -- increases font weights and contrast
   • "more minimal" -- reduces shadows and simplifies shapes
   • "larger corners" -- increases border radius values
   • "make the headings larger and use a darker background"

5. Pitch Smith applies your feedback and regenerates sample slides so you can preview the changes.

6. Review the samples and either:

   • Provide more feedback to continue refining (for example, "a bit less saturated")
   • Type approved to save the changes and update your theme
   • Type cancel to discard all changes and restore the original theme

Verify: Theme changes applied

After approving changes:

1. Run /pitchsmith:theme to view the updated theme summary.
2. Check that the version number has been incremented (for example, v1.0 to v2.0).
3. Verify that theme-history/ contains a backup of the previous version.

Expected: The theme summary reflects your requested changes (updated colors, adjusted fonts, modified shapes).

How the feedback loop works

The theme-edit command understands both specific requests ("change the primary color to blue") and gestalt feedback ("make it feel more corporate"). You can go through as many rounds of feedback as you need before approving. Each round regenerates sample slides so you can see the effect of your changes before committing them.

Manual CSS Variable Adjustment

For fine-grained control, edit the theme JSON file directly. This approach is useful when you know exactly which values you want to change.

1. Open the theme file in your editor:

   code .slide-builder/theme.json

2. The theme file is organized into sections. Here are the key sections you can modify:

   Section	Controls	Example Variables
   colors	Brand color palette	primary, secondary, accent, background, text
   typography	Font families, sizes, weights	heading.fontFamily, body.fontSize, scale
   shapes	Border radius, shadows, borders	boxes.borderRadius, boxes.shadow, callout.border
   components	Component-specific styles	Button styles, card styles, list styles
   gradients	Gradient definitions	Linear and radial gradient presets
   slides	Slide-level defaults	Default background, padding, content width

3. Edit the values you want to change and save the file.

Maintain valid JSON

When editing theme.json manually, ensure the file remains valid JSON. A missing comma or unclosed bracket will cause build errors. Consider using a JSON-aware editor that highlights syntax errors.

Verify: Manual changes saved correctly

After saving your edits:

1. Run /pitchsmith:theme to verify the theme summary reflects your changes.
2. If the command reports an error, check theme.json for JSON syntax issues.

Theme schema reference

For a complete list of all available theme variables, their types, and default values, see the Theme Schema Reference. The schema covers 9 major sections: colors, typography, shapes, components, slides, gradients, workflowRules, personality, and brandContext.

Preview Theme Changes

After modifying your theme (either via AI editing or manual adjustment), preview how the changes look on your slides by rebuilding them.

Rebuild a Single Slide

To quickly preview your theme changes on one slide:

/pitchsmith:build-one

This rebuilds the next pending slide using the updated theme. Open the result in the Slide Viewer to see how the new theme looks applied to real content.

Rebuild All Slides

To apply your theme changes across the entire deck:

/pitchsmith:build-all

Slides must be marked as pending

Build commands only regenerate slides with a "pending" status. To force a rebuild with the new theme, set the slide's status back to "pending" in plan.yaml first. See Build Slides for details on the rebuild workflow.

Using the Slide Viewer

After rebuilding, view the results in the Slide Viewer:

1. The Slide Viewer auto-opens after builds (if using the VS Code extension).
2. Navigate through your slides to verify the updated theme is applied consistently.
3. Check that colors, fonts, and shapes match your expectations across different layout types.

Verify: Theme changes visible in slides

Open a rebuilt slide in the Slide Viewer or browser. Confirm that:

• Colors match the updated theme palette
• Fonts reflect the typography changes
• Shapes (borders, shadows, corners) match the updated shape primitives
• The overall visual feel matches your intent

If slides still show the old theme, ensure they were rebuilt after the theme change (check their status in plan.yaml).

See Also

Related documentation

The following pages provide deeper context on the concepts used in this guide:

• Themes (Concept) -- How themes work, theme anatomy, and the design system
• Theme Schema Reference -- Complete reference for all theme.json variables
• Commands Reference -- Complete command reference including /pitchsmith:theme, /pitchsmith:theme-edit, and /pitchsmith:setup
• Brand Setup -- Create your initial theme from brand assets
• Build Slides -- Rebuild slides after theme changes