iA Presenter Theme Creation

Overview

Create or edit custom iA Presenter themes that control the visual appearance of presentations, including typography, colours, layouts, backgrounds, and responsive behaviour. Themes consist of CSS files, JSON configuration files, and optional custom fonts or images.

Core Concepts

Theme Structure

Every iA Presenter theme consists of:

1. template.json

   - Theme metadata (name, author, CSS filename, fonts)

2. presets.json

   - Colour presets for light/dark modes and gradients

3. theme.css

   - CSS rules for layouts, typography, and styling
4. Custom fonts (optional) -

   .woff2

   font files
5. Images/assets (optional) - Background images or other visual assets

Theme Location

Themes are stored in:

~/Library/Containers/net.ia.presenter/Data/Library/Application Support/iA Presenter/Themes/

Development Workflow

1. Create theme structure in ~/Library/Containers/net.ia.presenter/Data/Library/Application Support/iA Presenter/Themes/<YourTheme>
2. Created / edit CSS/JSON files
3. Ask the user to:
   1. Close and reopen iA Presenter to see changes
   2. Test in both light and dark modes
   3. Validate across different layouts

Task Decision Tree

When the user requests theme work, determine the appropriate task:

Creating a New Theme

Trigger: User wants to create a theme from scratch Steps:

1. Clarify requirements (colour palette, fonts, layout preferences)
2. Choose approach: starter templates or custom build
3. Load

   references/quick_reference.md

   for CSS classes
4. Create

   template.json

   ,

   presets.json

   , and CSS file
5. Write files to theme directory
6. Provide testing checklist

Resources:

assets/starter-theme/*

references/quick_reference.md

Modifying an Existing Theme

Trigger: User wants to customise an existing theme Steps:

1. Read the existing theme files
2. Identify what needs modification
3. Load relevant references based on changes
4. Edit the appropriate files
5. Validate changes

Resources:

references/official_guide.md

references/quick_reference.md

Adding Custom Fonts

Trigger: User wants to add custom typography Steps:

1. Verify font files (

   .woff2

   format) are available
2. Add

   @font-face

   declarations to CSS
3. Update

   template.json

   with display names
4. Update

   presets.json

   with CSS font family names
5. Confirm font files are in theme directory

Resources:

references/official_guide.md

Implementing Backgrounds

Trigger: User wants gradients, images, or SVG backgrounds Steps:

1. Determine background type (image, SVG, gradient)
2. For gradients: Update

   presets.json

3. For images/SVG: Add to CSS with proper selectors
4. Test in both light and dark modes
5. Validate across layouts

Resources:

references/official_guide.md

references/advanced_techniques.md

Troubleshooting

Trigger: Theme not working as expected Steps:

1. Identify the issue category
2. Load

   references/advanced_techniques.md

   for debugging tips
3. Apply debugging borders if needed
4. Validate JSON syntax
5. Check common issues (SVG colours, font paths, selectors)

Resources:

references/advanced_techniques.md

Common Customisations

Typography

Modify heading sizes, line heights, and font weights. The starter CSS includes a typography section with heading sizes for both desktop and mobile. Target headings within layouts:

section > :not([class*="layout-"]) h1,
[class*="layout-"] > div h1 {
  font-size: 2.986em;
  line-height: 1;
}

Layout Alignment

Available layouts and their CSS classes:

.cover-container

.layout-cover

.title-container

.layout-title

.section-container

.layout-section

.v-split-container

.layout-v-split

.grid-container

.layout-grid

.caption-container

.layout-caption

.title-image-container

.layout-title-image

.default-container

.layout-default

To align content, target the inner

div

.layout-cover > div {
  justify-content: center;  /* vertical: flex-start, center, flex-end */
  align-items: center;      /* horizontal: flex-start, center, flex-end */
}

Backgrounds

Image backgrounds:

.backgrounds .cover-container {
  background-image: url("cover-bg.jpg");
  background-size: cover;
  background-position: center;
}

Inline SVG (use

rgb()

.backgrounds .v-split-container {
  background-image: url('data:image/svg+xml;utf8,<svg>...</svg>');
}

Gradients (defined in

presets.json

{
  "LightBgGradient": ["#c7e7ff", "#f0c8ff", "#ffdada", "#ffebb2"],
  "DarkBgGradient": ["#15354c", "#3e154c", "#4c2828", "#4c3900"]
}

Light and Dark Modes

Configure colours for both modes in

presets.json

{
  "Appearance": "light",
  "DarkBodyTextColor": "#000000",
  "LightBodyTextColor": "#ffffff",
  "DarkTitleTextColor": "#000000",
  "LightTitleTextColor": "#ffffff",
  "DarkBackgroundColor": "#1a1a1a",
  "LightBackgroundColor": "#ffffff"
}

CRITICAL: Understanding iA Presenter Colour Naming

The colour field names in

presets.json

• DarkBodyTextColor

  = Dark-coloured text (e.g. #000000 black)
  • Used for text ON light backgrounds in light mode

• LightBodyTextColor

  = Light-coloured text (e.g. #ffffff white)
  • Used for text ON dark backgrounds in dark mode

• DarkBackgroundColor

  = Dark background colour (e.g. #1a1a1a)
  • Used as background in dark mode

• LightBackgroundColor

  = Light background colour (e.g. #ffffff)
  • Used as background in light mode

Example - For good contrast:

{
  "DarkBodyTextColor": "#000000",      // Black text for light backgrounds
  "LightBodyTextColor": "#ffffff",     // White text for dark backgrounds
  "DarkBackgroundColor": "#1a1a1a",    // Dark grey background
  "LightBackgroundColor": "#ffffff"    // White background
}

In light mode: Uses LightBackgroundColor (#ffffff) with DarkBodyTextColor (#000000) In dark mode: Uses DarkBackgroundColor (#1a1a1a) with LightBodyTextColor (#ffffff)

Common Mistake: Swapping DarkBodyTextColor and LightBodyTextColor, which results in invisible text.

Force appearance for specific layouts in

template.json

"Layouts": [
  {
    "Name": "Cover",
    "Classes": "dark"
  }
]

Responsive Design

Default CSS applies to mobile. Use media queries for larger screens:

/* Mobile (default) */
@media (max-width: 639px) {
  [class*="layout-"] > div h1 {
    font-size: 2.074em;
  }
}

/* Desktop/Tablet */
@media (min-width: 768px) {
  /* Desktop-specific styles */
}

Troubleshooting Guide

Text Not Visible (Invisible Text Issue)

Symptom: Text appears invisible in both light and dark modes

Cause: Incorrect colour assignments in

presets.json

Solution: Ensure colours are assigned correctly:

{
  "DarkBodyTextColor": "#000000",      // Dark text (for light backgrounds)
  "LightBodyTextColor": "#ffffff",     // Light text (for dark backgrounds)
  "DarkBackgroundColor": "#1a1a1a",    // Dark background
  "LightBackgroundColor": "#ffffff"    // Light background
}

Common Mistake: Setting

DarkBodyTextColor

Inline SVG Broken

Use

rgb(255,0,0)

#FF0000

Fonts Not Loading

Verify:

1. Font files (

   .woff2

   ) are in the theme directory

2. @font-face

   declarations use correct file paths

3. template.json

   has display font names

4. presets.json

   has CSS font family names

Layout Alignment Issues

Target the inner

div

.layout-cover > div { /* alignment properties */ }

Not the container:

.cover-container { /* this won't align content */ }

Debugging Technique

Use coloured borders during development:

.cover-container { border: 5px solid red; }
.layout-cover > div { border: 5px dashed red; }
.title-container { border: 5px solid blue; }
.layout-title > div { border: 5px dotted blue; }

Remove these before final distribution.

Validation Checklist

When creating or modifying themes:

• All required files exist (

  template.json

  ,

  presets.json

  , CSS file)
• JSON files have valid syntax
• Tested in both light and dark modes
• Responsive behaviour verified at different viewport sizes
• Custom fonts load correctly (if applicable)
• All layouts tested (cover, title, section, split, grid, caption, image title, default)
• Gradients render smoothly (if applicable)
• Backgrounds display correctly (if applicable)
• Debugging borders and comments removed

Best Practices

1. Start with templates - Use

   assets/starter-theme/*

   for consistency
2. Reference documentation - Load

   references/quick_reference.md

   for CSS classes
3. Test thoroughly - Verify in light/dark modes and all layouts
4. Use semantic names - Name colours and presets descriptively
5. Comment CSS - Add comments for complex or non-obvious rules
6. Mobile-first - Default styles for mobile, enhance for desktop
7. Consistent spacing - Use consistent units (em, rem) for scalability
8. Minimal overrides - Only override what's necessary
9. British English - Use British spelling in all comments and documentation

Key Reminders

• CRITICAL: Colour naming - DarkBodyTextColor = dark-coloured text (for light backgrounds), LightBodyTextColor = light-coloured text (for dark backgrounds). DO NOT swap these!
• No hot reload on theme creation - The user must close and reopen iA Presenter when you first create a theme, but subsequent updates will apply on the fly.
• Inner div targeting - Alignment rules target

  .layout-* > div

  , not the container
• Inline SVG colours - Use

  rgb()

  format, not hexadecimal
• Mobile-first - Default CSS applies to mobile, add

  @media (min-width: 768px)

  for desktop
• Both modes - Always configure and test light and dark appearances
• Grid modifiers - Grid layouts have

  .grid-items-2

  ,

  .grid-items-3

  , etc. classes
• British spelling - Use "colour", "centre", "customise" in all content
• Minimal CSS overrides - Avoid setting explicit colours in CSS for text/backgrounds - let presets.json handle them
• Update placeholders - Update any placeholder content in the template.json, theme.css, presets.json files
• If you need clarification on the theme you may ask the user for more details about their preferences and requirements.

Resources

references/

Reference documentation to load into context as needed:

• official_guide.md

  - Complete official iA Presenter theme documentation covering all layouts, CSS classes, font configuration, backgrounds, gradients, and appearances

• quick_reference.md

  - Condensed reference with CSS classes, selectors, file structure, and common patterns for quick lookup

• advanced_techniques.md

  - Advanced techniques including centring content, debugging borders, inline SVG backgrounds, and workflow tips

Load progressively:

• Always useful:

  quick_reference.md

  (CSS classes, structure)
• For new themes:

  assets/starter-theme/*

  files
• For complex customisation:

  official_guide.md

• For debugging:

  advanced_techniques.md

assets/

Starter theme templates in

assets/starter-theme/

• template.json

  - Minimal theme metadata template

• presets.json

  - Colour preset template with sensible defaults

• theme.css

  - Comprehensive CSS starter with commented sections for typography, layouts, backgrounds, headers/footers, responsive design

• README.md

  - Guide for using the starter templates

Use these templates as a starting point for new themes. Copy and customise based on user requirements.