Skip to content

theme-guide.md

Latest commit

 

History

History
722 lines (520 loc) · 14.9 KB

theme-guide.md

File metadata and controls

722 lines (520 loc) · 14.9 KB
Raw

Edera V2 Theme Customization Guide

Complete guide to understanding and customizing the Edera V2 MARP theme.

Table of Contents

Overview

The Edera V2 theme is a professional presentation theme featuring:

  • Dark teal and light mint color palette
  • Clean, minimal design aesthetic
  • High contrast for excellent readability
  • Multiple layout options
  • Responsive typography
  • Accessible color combinations

Theme File: themes/edera-v2.css

Licensing

License: MIT License Copyright: Copyright (c) 2025 Lewis Denham-Parry

The Edera V2 theme is original work created for this project:

  • Original design: Google Slides template by Lewis Denham-Parry
  • MARP CSS implementation: Ported from SVG exports for this repository
  • License: MIT (same as parent project)

You are free to:

  • Use the theme in your own presentations
  • Modify and customize the theme
  • Distribute the theme with your projects
  • Use commercially

See LICENSE file for complete terms.

Color Scheme

Primary Colors

--edera-dark-teal: #013a3b     /* Main brand color */
--edera-light-mint: #d0fdf2    /* Secondary background */
--edera-cyan-accent: #02f4d5   /* Accent and highlights */
--edera-white: #ffffff         /* Clean backgrounds */
--edera-black: #000000         /* Text on light */

Semantic Usage

Color Used For
Dark Teal Title slide background, body text, dark slides
Light Mint Content slide background, light text
Cyan Accent Headings, links, emphasis, bullets
White Alternate backgrounds
Black High contrast text

Color Accessibility

✅ Fully Accessible: All color combinations meet WCAG 2.1 Level AA standards as of 2025-12-03.

Verified WCAG Compliance

Audit Date: 2025-12-03 Status: ✅ FULL COMPLIANCE - All combinations pass WCAG AA Standard: WCAG 2.1 Testing Tools: wcag-contrast v3.0.0, Playwright MCP, Chrome DevTools

All color combinations have been empirically verified with automated contrast checking tools:

Combination Ratio WCAG AA WCAG AAA Status
Dark teal on light mint 11.39:1 ✅ Pass ✅ Pass Excellent
Cyan on dark teal 8.93:1 ✅ Pass ✅ Pass Excellent
Light mint on dark teal 11.39:1 ✅ Pass ✅ Pass Excellent
White on dark teal 12.58:1 ✅ Pass ✅ Pass Excellent
Dark teal on white 12.58:1 ✅ Pass ✅ Pass Excellent

Accessibility Fix Applied

Date Fixed: 2025-12-03

What Changed: The default H1 color has been changed from cyan to dark teal to ensure accessibility by default.

/* Default H1 styling - Now accessible (11.39:1 contrast) */
h1 {
  color: var(--color-text-dark);  /* Dark teal #013a3b */
}

Cyan color is now explicitly used only on dark backgrounds where it's accessible:

/* Title slides - Dark background */
section.title h1 {
  color: var(--color-primary);  /* Cyan on dark teal: 8.93:1 ✅ */
}

/* Dark variant slides - Dark background */
section.dark h1 {
  color: var(--color-primary);  /* Cyan on dark teal: 8.93:1 ✅ */
}

Result: All slides are now accessible by default without requiring special classes.

See full audit: docs/accessibility-audit.md

Presentation Readability Guidelines

Font Size Recommendations:

  • ✅ 24px base text: Current theme complies with presentation standards
  • ⚠️ 18px small text: Use sparingly, only for non-critical content (footers, captions)
  • 💡 Large rooms: Consider using .text-large class (28px) for very large venues
  • ✅ Always test: Display slides on target hardware before presenting

Content Best Practices:

  1. Limit text per slide: 5-7 bullet points maximum for readability
  2. Use high-contrast combinations: Prefer dark on light or light on dark
  3. Avoid small text: Don't use text < 18px for important content
  4. Test before presenting: View slides on actual projector/display
  5. Provide alternatives: Offer PDFs with proper accessibility tagging
  6. Use .content class: No longer required - All slides are accessible by default (fixed 2025-12-03)

Accessibility Checklist for Presenters:

  • All text uses high-contrast color combinations (4.5:1 minimum)
  • Large text (≥18pt) has 3:1 contrast minimum
  • Content slides use .content class No longer required - fixed by default
  • No reliance on color alone to convey information
  • Font sizes appropriate for room size and viewing distance
  • Slides tested on actual presentation hardware
  • Alternative formats provided (accessible PDFs)

Common Mistakes to Avoid:

❌ Forgetting .content class on content slides No longer an issue - fixed by default ❌ Using 18px text for critical information ❌ Mixing cyan and light mint without proper contrast Fixed - theme now uses dark teal by default ❌ Not testing on actual projector before presentation

✅ Always use .content class for content slides No longer necessary - accessible by default ✅ Keep body text at 24px or larger ✅ Test contrast ratios when customizing colors ✅ View slides on presentation hardware

Typography

Font Family

Default sans-serif stack:

font-family: 'Arial', 'Helvetica', sans-serif;

Recommendation: Keep the default for maximum compatibility, or replace with web-safe fonts.

Type Scale

Element Size Usage
Title 4rem (64px) Title slides only
H1 3.5rem (56px) Main slide headings
H2 2.5rem (40px) Section headings
H3 1.75rem (28px) Sub-headings
Body 1.5rem (24px) Standard text
Small 1.125rem (18px) Captions, labels

Font Weights

  • Headings: 600-700 (Semi-bold to Bold)
  • Body: 400 (Regular)
  • Emphasis: 700 (Bold)

Layout System

Responsive Sizing

The Edera V2 theme uses MARP's native responsive sizing system:

  • Viewport-responsive: Slides automatically scale to fill the browser viewport
  • Aspect ratio: Maintains 16:9 aspect ratio (1280x720 default)
  • Fullscreen support: Works seamlessly with MARP's fullscreen mode
  • Print support: Maintains proper dimensions when exporting to PDF

Design Dimensions

The theme is designed for 16:9 slides with these reference dimensions:

  • Reference Width: 960px (design canvas)
  • Reference Height: 540px (design canvas)
  • Actual Display: Scales responsively to viewport size
  • Margins: 60px vertical, 84px horizontal

When building presentations, content will scale proportionally to fit any screen size.

Available Classes

1. .title - Title Slide

Purpose: Opening and closing slides

<!-- _class: title -->
# Main Title
## Subtitle

Styling:

  • Dark teal background
  • Centered content (vertical & horizontal)
  • Large typography
  • Minimal padding

Best for:

  • Conference talk titles
  • Section breaks
  • Thank you slides

2. .content - Content Slide (Default)

Purpose: Standard presentation content

<!-- _class: content -->
# Slide Title
Content here

Styling:

  • Light mint background
  • Left-aligned content
  • Standard margins
  • Dark teal text

Best for:

  • Bullet points
  • Paragraphs
  • Mixed content

3. .dark - Dark Variant

Purpose: High-impact slides

<!-- _class: dark -->
# Dark Slide

Styling:

  • Dark teal background
  • Light mint text
  • Cyan accents
  • High contrast

Best for:

  • Emphasis
  • Visual variety
  • Code-heavy slides

4. .two-columns - Two-Column Layout

Purpose: Side-by-side content

<!-- _class: two-columns -->
# Title Spans Both Columns
## Left      ## Right
Content      Content

Styling:

  • CSS Grid layout
  • Equal width columns
  • Gap between columns
  • Responsive alignment

Best for:

  • Comparisons
  • Before/After
  • Code + Explanation

5. .image - Full-Screen Image

Purpose: Visual impact

<!-- _class: image -->
![](image.jpg)

Styling:

  • No padding
  • Full-screen coverage
  • Centered image
  • Object-fit: cover

Best for:

  • Diagrams
  • Screenshots
  • Hero images

6. .image-overlay - Image with Text

Purpose: Text over background image

<!-- _class: image-overlay -->
![](bg.jpg)
# Title

Styling:

  • Background image
  • Dark overlay (70% opacity)
  • White/cyan text
  • Centered content

Best for:

  • Conference branding
  • Visual storytelling
  • Section breaks

Customizing the Theme

Method 1: CSS Variables

Easiest way to customize colors. Edit themes/edera-v2.css:

:root {
  /* Change brand colors */
  --edera-dark-teal: #your-color;
  --edera-light-mint: #your-color;
  --edera-cyan-accent: #your-color;
}

Method 2: Override Styles

Add custom styles in your markdown:

---
marp: true
theme: edera-v2
---

<style>
section {
  font-family: 'Georgia', serif;
}

h1 {
  color: #ff0000;
}
</style>

Method 3: Create New Class

Add to themes/edera-v2.css:

section.custom {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
}

Use in slides:

<!-- _class: custom -->
# Custom Styled Slide

Creating New Themes

Step 1: Copy Edera V2

cp themes/edera-v2.css themes/my-theme.css

Step 2: Change Theme Name

Edit the first line:

/*
 * @theme my-theme
 * @author Your Name
 */

Step 3: Customize Colors

Update CSS variables:

:root {
  --primary-color: #your-color;
  --background-color: #your-bg;
  --text-color: #your-text;
  /* ... */
}

Step 4: Adjust Typography

:root {
  --font-family: 'Your Font', sans-serif;
  --font-size-base: 1.5rem;
  /* ... */
}

Step 5: Modify Layouts

Customize section classes:

section.title {
  background: your-custom-styles;
}

Step 6: Use Your Theme

---
marp: true
theme: my-theme
---

Best Practices

Colors

  1. Maintain contrast - Test with contrast checkers
  2. Limit palette - 3-4 colors maximum
  3. Brand consistency - Match company colors
  4. Test projectors - Colors look different on screens
  5. Avoid pure colors - Slightly muted looks better

Text and Fonts

  1. Readable sizes - Minimum 24px for body text
  2. Line height - 1.5-1.6 for paragraphs
  3. Font pairing - Use max 2 font families
  4. Hierarchy - Clear size differences
  5. Weight variation - Use for emphasis

Layout

  1. White space - Don't fill every pixel
  2. Alignment - Be consistent
  3. Grid system - Use structured layouts
  4. Responsive - Test at different sizes
  5. Simple - Clarity over complexity

Content

  1. One idea per slide - Keep focused
  2. Visual hierarchy - Guide the eye
  3. Consistency - Use same layouts
  4. Breathing room - Generous margins
  5. Balance - Distribute content evenly

Advanced Customization

Custom Fonts

Use web fonts (requires internet):

@import url('https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap');

section {
  font-family: 'Roboto', sans-serif;
}

Or use local fonts:

@font-face {
  font-family: 'CustomFont';
  src: url('./fonts/custom-font.woff2') format('woff2');
}

section {
  font-family: 'CustomFont', sans-serif;
}

Animations

Add subtle animations:

section {
  animation: fadeIn 0.5s ease-in;
}

@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

Background Patterns

Add texture:

section {
  background-image:
    linear-gradient(rgba(255,255,255,0.9), rgba(255,255,255,0.9)),
    url('pattern.svg');
}

Logo Integration

The Edera V2 theme includes a logo in the top right corner of slides (added in v2.1.0).

Logo Asset: themes/assets/edera-logo.png

Implementation:

The logo is implemented using CSS ::before pseudo-element:

section::before {
  content: '';
  position: absolute;
  top: var(--spacing-sm);           /* 1rem = ~16px */
  right: var(--margin-horizontal);  /* 84px */
  width: 110px;
  height: auto;
  background: url('./assets/edera-logo.png') no-repeat center;
  background-size: contain;
  z-index: 10;
}

section.title::before {
  display: none;  /* Hidden on title slides */
}

section.dark::before {
  opacity: 1;  /* Full visibility on dark slides */
}

Customization:

To show logo on title slides:

/* Remove or comment out this rule in themes/edera-v2.css */
/* section.title::before { display: none; } */

To adjust logo size:

section::before {
  width: 130px;  /* Increase from default 110px */
}

To change logo position:

section::before {
  top: 30px;     /* Move down from default */
  right: 50px;   /* Move left from default */
}

To use a different logo:

  1. Replace themes/assets/edera-logo.png with your logo
  2. Adjust width in CSS if needed
  3. Rebuild: npm run build

To completely remove the logo:

section::before {
  display: none;
}

Troubleshooting

Colors Look Different

  • Test on target display (projector, screen)
  • Check color space (sRGB recommended)
  • Adjust brightness/contrast
  • Provide both light and dark slides

Text Not Readable

  • Increase font size
  • Improve contrast
  • Add text shadows
  • Use solid backgrounds

Layout Breaks

  • Check content length
  • Verify CSS specificity
  • Test with different content
  • Use responsive units (rem, em)

PDF Export Issues

  • Simplify complex layouts
  • Remove animations
  • Use standard fonts
  • Check marp.config.js settings

Examples

Corporate Theme

:root {
  --primary: #003366;    /* Corporate blue */
  --secondary: #ffffff;  /* White */
  --accent: #ff6600;     /* Brand orange */
}

Minimalist Theme

:root {
  --primary: #000000;    /* Black */
  --secondary: #ffffff;  /* White */
  --accent: #666666;     /* Gray */
}

section {
  font-family: 'Helvetica Neue', sans-serif;
  font-weight: 300;
}

Academic Theme

:root {
  --primary: #2c3e50;    /* Navy */
  --secondary: #ecf0f1;  /* Light gray */
  --accent: #e74c3c;     /* Red */
}

section {
  font-family: 'Georgia', serif;
}

Resources

Support

For theme-related issues:

  1. Check this guide
  2. Review docs/theme-analysis.md
  3. Inspect themes/edera-v2.css
  4. Test with example templates
  5. Open GitHub issue

Version

Guide Version: 1.0 Theme Version: 2.0.0 Last Updated: December 3, 2025