# ADR-005: Spec Parser Two-Layer Architecture

**Status:** Accepted
**Date:** 2025-02-05

## Context

Users want to write presentation specs in markdown and have them auto-converted to PPTX. The spec format needs to be flexible enough for AI-generated content.

## Decision

- Two-layer parsing: `extract_spec()` → NormalizedSpec IR → `spec_to_presentation()`
- NormalizedSpec is a clean intermediate representation (title, slides, design tokens)
- Slide type inference from titles + content blocks via `_TYPE_KEYWORDS`
- Design system sections extracted into BrandConfig color tokens
- Card blocks: `### heading` + bullets → CardDefinition
- Callout blocks: `> **Warning:**` → CalloutBox

## Consequences

- Robust parsing that separates extraction from mapping
- Easy to extend with new content block types
