ia-presenter-themes

name	ia-presenter-themes
description	This skill should be used when creating, modifying, or troubleshooting custom themes for iA Presenter.

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/
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 (Custom Fonts section)

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 (Backgrounds section), 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:

Layout	Container Class	Content Class
Cover	.cover-container	.layout-cover
Title	.title-container	.layout-title
Section	.section-container	.layout-section
Split	.v-split-container	.layout-v-split
Grid	.grid-container	.layout-grid
Caption	.caption-container	.layout-caption
Image Title	.title-image-container	.layout-title-image
Default	.default-container	.layout-default

To align content, target the inner div of each layout:

.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() colours, not hex):

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

Gradients (defined in presets.json, not CSS):

{
  "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 can be counter-intuitive. They refer to the COLOUR OF THE ELEMENT, not the mode:

• 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. The colour naming refers to the colour of the element, not the mode.

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 to a light colour like "#ffffff" - this puts white text on a white background in light mode.

Inline SVG Broken

Use rgb(255,0,0) instead of #FF0000 in inline SVG. Hex colours break inline SVG in CSS.

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 of layouts:

.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.