Table of Contents

1. Architecture Overview - System structure and CSS variables
2. Moods - Emotional slide atmospheres (8 moods)
3. Slide Layouts - Structural layouts (11) and content types (8)
4. Container Components - Reusable content blocks (15 components)
5. Modifiers - Size, emphasis, and position modifiers
6. Combinations - Real-world usage examples
7. For AI Usage - Guidelines for automated generation
8. Theme Creation - How to create new themes
9. Advanced Container Syntax - Extended ::: container features
10. AI Generation: Container Patterns - Best practices for containers

Three-Layer Architecture

The design system uses a hierarchical approach to CSS variables:

LAYER 1: Primitives       → Raw values (colors, fonts, spacing)
           ↓
LAYER 2: Semantic Tokens  → Context-aware (--accent-1, --surface, --fg)
           ↓
LAYER 3: Component Tokens → Component-specific (--callout-border)

Key Principle: Components only reference Layer 2/3 tokens, never primitives.
This allows moods to change the entire slide appearance by overriding Layer 2.

Contrast Requirements (WCAG)

Themes must maintain these minimum contrast ratios:

Lightness Scale Reference

Mood Overview

Moods set the emotional tone of a slide through color and atmosphere.
Apply with <!-- _class: mood-name --> for single slides.

Content-Type Layouts

Container Overview

Containers are applied using the markdown-it-container syntax:

::: container-name [modifiers]
Content here
:::

Nested Containers

When nesting containers, add one colon per nesting level:

:::: col                          <!-- Outer: 4 colons -->
### Column Title

Some text here.

::: callout warning               <!-- Inner: 3 colons -->
Nested callout inside a column
:::

::::                              <!-- Close outer: 4 colons -->

Rules:

• Standard container: ::: (3 colons)
• First nesting level: :::: (4 colons)
• Second nesting level: ::::: (5 colons)
• Opening and closing must match

Caption

Small annotations and descriptions.

Callout

Highlighted information boxes.

Card

Content cards with borders and shadows.

Box & Panel

Steps

Badge

Inline labels and tags:

Size Modifiers

Apply to slides or containers to adjust scale:

Slide example: <!-- _class: small --> or <!-- _class: lead large -->
Container example: ::: callout small

Emphasis Modifiers

Position Modifiers

For absolute positioning within slides:

Usage: ::: caption bottom-right

Escape hatch: For pixel-precise positioning:
::: caption bottom:40px right:20px

AI Generation Guidelines

When generating presentations with this design system:

Mood Selection

1. Analyze content sentiment - Match mood to message
2. Consider audience - Premium for executives, confident for corporate
3. One mood per slide - Don't combine moods
4. Default to neutral - When uncertain

Layout Selection

1. Lead for titles and chapter starts
2. Columns/Split for comparisons
3. Metrics for KPIs (max 4-6 metrics)
4. Quote for impactful statements
5. Process for workflows (max 4-5 steps)

AI Generation Rules

Do's

• Use small class for data-heavy slides
• Apply consistent moods within sections
• Use callouts for important notices
• Leverage semantic container variants (success, warning, danger)
• Use :::: (4 colons) for outer containers when nesting

Don'ts

• Don't mix multiple moods on one slide
• Don't exceed 4-6 bullet points per column
• Don't forget to increase colons when nesting containers
• Don't use huge for content slides (only for impact)
• Don't position-override without clear purpose

Content-to-Layout Mapping

Example Prompt Structure

Generate a Marp presentation using reference-dark theme:

Topic: [Topic]
Audience: [Technical/Executive/Sales]
Tone: [Professional/Energetic/Serious]
Slides: [Number]

Include:
- Lead slide with title
- Agenda slide
- Content slides with appropriate moods
- Summary/thank you slide

Use moods consistently within sections.
Prefer columns/split for comparisons.
Use metrics layout for KPIs.

Creating a New Theme

1. Copy the template - Start with reference-dark.css or reference-light.css
2. Update metadata - Change @theme name and author
3. Modify primitives - Adjust Layer 1 variables only
4. Test contrast - Verify WCAG compliance
5. Test all moods - Ensure each mood is visually distinct

What to Change (Layer 1 Only)

• Font families
• Color hues and saturations
• Spacing scale (if brand requires)
• Border radii

What NOT to Change

• Semantic token names (Layer 2)
• Component token structure (Layer 3)
• Class names and selectors

Mood Customization

When defining moods for a new theme:

section.your-mood {
  /* Background gradient using brand colors */
  --bg-gradient: linear-gradient(135deg,
    hsl(YOUR_HUE, 30%, 12%) 0%,
    hsl(YOUR_HUE, 25%, 8%) 100%);

  /* Primary accent - must contrast with bg (4.5:1 min) */
  --accent-1: hsl(YOUR_HUE, 80%, 55%);

  /* Secondary accent - complementary or analogous */
  --accent-2: hsl(YOUR_HUE + 30, 70%, 50%);

  /* Muted accent for subtle elements */
  --accent-muted: hsl(YOUR_HUE, 40%, 35%);

  /* Glow effect color */
  --glow-color: rgba(R, G, B, 0.15);

  /* Typography overrides */
  --heading-accent: var(--accent-1);
  --text-emphasis: var(--accent-1);
  --marker-color: var(--accent-1);
}

Hue Relationships

For consistent mood palettes:

Recommendation: Use analogous (+30°) for accent-2 in most moods.
Reserve complementary for high-impact moods like energetic.

Testing Checklist

Before deploying a new theme:

• [ ] All 8 moods render correctly
• [ ] Contrast ratios meet WCAG AA minimum
• [ ] All slide layouts work as expected
• [ ] All containers display properly
• [ ] Size modifiers scale correctly
• [ ] Code highlighting is readable
• [ ] Tables maintain structure
• [ ] Export to PDF preserves colors
• [ ] Export to PPTX is functional

Container Syntax Overview

The Obsidian Marp Plugin extends standard markdown-it containers with powerful features:

::: [tag.]class[#id][ additional-classes][ style-declarations]
Content here
:::

Basic Container Examples

Simple class

::: callout
This creates a div with class="callout"
:::

Multiple classes

::: callout warning small
Multiple classes: class="callout warning small"
:::

Custom HTML tag

::: aside.note
Creates: <aside class="note">...</aside>
:::

With ID

::: card#featured-card
Creates: <div class="card" id="featured-card">...</div>
:::

Inline Style Declarations

Two formats - do not mix them:

1. Space-separated (preferred)

::: caption width:50% top:20px background:rgba(10,0,40,0.5)
Creates: style="width: 50%; top: 20px; background: rgba(10,0,40,0.5)"
:::

Works for most values including rgba() - no spaces after commas!

2. CSS-literal with semicolons (escape hatch)

::: box width:50%; background:url(https://example.com/img.jpg);
Use ONLY when values contain colons (like URLs)
:::

Critical: Semicolon is a mode switch - use everywhere or nowhere:

• width:50% background:rgba(0,0,0,0.5) - OK
• width:50%; background:rgba(0,0,0,0.5); - OK
• width:50% background:rgba(0,0,0,0.5); - BROKEN (mixed)

Nesting Containers

When nesting, add one colon per level:

:::: columns                    <!-- Outer: 4 colons -->

::: col                         <!-- Inner: 3 colons -->
### Left Column
Content here
:::

::: col
### Right Column
::: callout warning             <!-- Nested in col: still 3 (sibling) -->
Warning inside column
:::
:::

::::                            <!-- Close outer: 4 colons -->

Matching rule: Opening and closing colons must match count.

Deep Nesting (3 Levels)

::::: card                      <!-- Level 1: 5 colons -->
#### Card Title

:::: columns                    <!-- Level 2: 4 colons -->
::: col                         <!-- Level 3: 3 colons -->
Left content
:::
::: col
Right content
:::
::::

:::::

Rarely needed - prefer simpler structures when possible.

Recreating Legacy Caption Classes

The legacy space-legacy theme had preset caption classes. Replicate them:

Add background:rgba(10,0,40,0.5) for translucency.

AI: Caption Selection Guide

When generating slides with background images:

Always ensure text contrast - darker backgrounds for light images.

AI: Multi-Column Patterns

Two Columns (Equal)

<!-- _class: columns -->
::: col
Left content
:::
::: col
Right content
:::

Two Columns with Nested Components

<!-- _class: split -->
:::: col
### Before
::: callout danger
Problem description
:::
::::
:::: col
### After
::: callout success
Solution description
:::
::::

AI: When to Use Inline Styles

Principle: Use CSS classes for reusable patterns, inline styles for exceptions.

AI: Container Syntax Quick Reference

# Basic
::: class
::: class modifier
::: class modifier1 modifier2

# With ID
::: class#element-id

# Custom tag
::: span.highlight
::: aside.note#sidebar

# With styles (space-separated)
::: class width:50% top:20px

# With styles (CSS-literal - only for URLs with colons)
::: class background:url(https://example.com/img.jpg);

# Nested (increase colons)
:::: outer
::: inner
:::
::::

AI: Common Mistakes to Avoid

Wrong: Style without class

::: width:50%          <!-- Missing class name -->

Wrong: Mismatched colon counts

:::: container
Content
:::                    <!-- Should be :::: -->

Wrong: Mixing semicolon modes

::: caption width:50% background:rgba(0,0,0,0.5);   <!-- Mixed! -->

Correct versions:

::: caption width:50% background:rgba(0,0,0,0.5)    <!-- All without ; -->
::: caption width:50%; background:rgba(0,0,0,0.5);  <!-- All with ; -->

Wrong: URL without semicolons (contains :)

::: box background:url(https://example.com/img.jpg)  <!-- Needs ; mode -->

Correct:

::: box background:url(https://example.com/img.jpg);  <!-- ; everywhere -->