OfficeCLI Theme Color Resolution for PowerPoint: Technical Implementation

OfficeCLI resolves PowerPoint theme colors by extracting the ThemePart, building a name-to-hex color map via ThemeColorResolver, and substituting theme references during rendering to ensure accurate visual output.

When programmatically manipulating PPTX files, maintaining accurate color fidelity is essential for professional presentations. The OfficeCLI theme color resolution for PowerPoint implementation in the iOfficeAI/OfficeCLI repository ensures that theme slots like accent1 or background1 are correctly mapped to their RGB values. This pipeline guarantees that shapes, fills, and text rendered via the CLI match the visual appearance of Microsoft PowerPoint.

The OfficeCLI Theme Color Resolution Pipeline

Theme Part Extraction

When PowerPointHandler loads a PPTX file (src/officecli/Handlers/Pptx/PowerPointHandler.cs), it immediately extracts the ThemePart from the package. This part contains the <a:theme> element with <a:themeElements> and <a:clrScheme> sections that define the color palette. If the file lacks a theme—common in stripped or third-party generated files—the EnsureThemePartExists method creates a minimal default theme structure, ensuring the resolution logic always has valid color definitions to reference.

Building the Color Map

The ThemeColorResolver.BuildColorMap method constructs a dictionary mapping theme color names to their final hex values. Located in src/officecli/Handlers/ThemeColorResolver.cs, this resolver accounts for theme overrides and palette aliases. The PowerPointHandler.SvgPreview class calls ResolveThemeColorMap to cache this mapping, making it available for all subsequent rendering operations.

Applying Theme Colors to Shapes and Text

During rendering of shapes, fills, or text runs, the code in src/officecli/Handlers/Pptx/PowerPointHandler.SvgPreview.cs checks for explicit <a:solidFill>/<a:srgbClr> values. When the color attribute is marked as auto or omitted entirely, the engine falls back to the themeColor XML attribute. The ResolveFillColor method (lines 92-108) then looks up this theme reference in the pre-built color map to determine the final hex value.

Tint and Shade Processing

If a theme color includes tint or shade modifiers, ThemeColorResolver.ApplyTintShade applies the standard Office OpenXML algorithm. This multiplies the base RGB values by the specified tint or shade factors to calculate the final displayed color, ensuring accurate reproduction of subtle color variations defined in the theme.

Fallback Handling for Missing Themes

OfficeCLI handles theme-less PPTX files gracefully. The EnsureThemePartExists method in PowerPointHandler.cs generates a minimal <a:theme> containing the default color scheme when none exists. This fallback guarantees that the resolution pipeline functions correctly even on corrupted or minimally generated files, enabling reliable round-trip operations without errors.

Rendering Consistency Across Output Formats

Both HTML and SVG previews use identical color resolution logic. The PowerPointHandler.HtmlPreview class (src/officecli/Handlers/Pptx/PowerPointHandler.HtmlPreview.cs) and the SVG preview share the same ResolveThemeColorMap implementation. This shared approach ensures that officecli view output matches Microsoft PowerPoint's rendering regardless of whether you generate HTML or SVG.

Working with Theme Colors in OfficeCLI

# Create a new deck and add a shape using a theme color

officecli create deck.pptx
officecli add deck.pptx /slide[1] --type shape \
  --prop text="Hello" \
  --prop fill=accent2          # Uses the theme color "accent2"

# View the slide as SVG (theme colors resolved automatically)

officecli view deck.pptx svg > slide1.svg

# Inspect the generated color map for debugging

officecli dump deck.pptx /theme --json

// Manually invoke the color resolver (used internally)
var ppt = PowerPointHandler.Load("deck.pptx");
var themeMap = ppt.GetThemeColorMap();   // Dictionary<string,string>
string accent2Hex = themeMap["accent2"]; // e.g., "#4472C4"

Summary

• OfficeCLI extracts the ThemePart from PPTX files and creates default themes via EnsureThemePartExists when missing.
• The ThemeColorResolver.BuildColorMap method constructs a name-to-hex dictionary that handles theme overrides and palette aliases.
• During rendering, ResolveFillColor substitutes theme references with actual RGB values, applying tint/shade adjustments via ApplyTintShade.
• Both SVG and HTML preview handlers share the same resolution logic, ensuring consistent visual output across formats.

Frequently Asked Questions

How does OfficeCLI handle PowerPoint files without theme parts?

When a PPTX file lacks a theme part, the PowerPointHandler.EnsureThemePartExists method creates a minimal <a:theme> structure containing the default color scheme. This ensures the resolution pipeline functions correctly and the file can be round-tripped without errors.

What algorithm does OfficeCLI use for tint and shade calculations?

OfficeCLI implements the standard Office OpenXML algorithm in ThemeColorResolver.ApplyTintShade. This method multiplies the base RGB values by the tint or shade factors specified in the theme XML to derive the final color values.

Can I retrieve the resolved hex values programmatically?

Yes. You can access the resolved theme color map through the GetThemeColorMap() method, which returns a Dictionary<string,string> mapping theme slot names (like accent1 or background2) to their hex color values (e.g., #4472C4).

Why do my SVG and HTML previews show the same colors as PowerPoint?

Both the PowerPointHandler.SvgPreview and PowerPointHandler.HtmlPreview classes use the same ResolveThemeColorMap implementation and ThemeColorResolver logic. This shared approach guarantees that theme color resolution remains consistent across all output formats supported by OfficeCLI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}