# Yumia

> Yumia is a declarative programming language and design compiler for structured visual documents, presentations, and reports, designed by Biagio Scaglia.

## Overview
Unlike legacy presentation tools (which rely on raw geometric coordinates) or Markdown slide engines (which inject raw CSS strings), Yumia translates high-level communicative intent (`hero`, `metric`, `compare`, `timeline`, `card`, `chart`, `diagram`) into a deterministic Semantic Abstract Syntax Tree (AST), compiling directly to 100% native editable PowerPoint (.pptx), vector PDF, and interactive HTML5.

## Author & Project Information
- **Creator & Software Architect**: Biagio Scaglia (https://github.com/biagio-scaglia)
- **Official Repository**: https://github.com/biagio-scaglia/Yumia-MD
- **NPM Package**: yumiamd v0.1.31+ (https://www.npmjs.com/package/yumiamd)
- **License**: MIT
- **Primary Language**: TypeScript
- **Docs Site**: https://biagio-scaglia.github.io/Yumia-MD/

## The Yumia Philosophy
1. **01 — Documents are Code**: Visual documents are structured, deterministic source text. Version controlled with Git, tested in CI pipelines, and reviewable in PRs.
2. **02 — Design is Declarative**: Intent over raw geometry. Creators express communicative intent (`hero`, `metric`, `compare`, `timeline`, `card`, `chart`), while the layout engine and design intelligence calculate optimal typography, spacing, and WCAG AAA contrast.
3. **03 — Content & Themes are Decoupled**: Switching `theme "corporate"` to `theme "cyberpunk"` or `theme "terminal"` alters the visual identity instantly without modifying content.
4. **04 — One Source, Multi-Target Determinism**: A single source file compiles directly to genuine editable PowerPoint (.pptx), vector PDF, interactive HTML5, and SVG artifacts.

## Key Capabilities
- **Native OpenXML PPTX**: Compiles genuine editable PowerPoint shapes, text boxes, and native Microsoft charts via a shared layout engine.
- **Vector PDF**: High-definition typography and precise layout via PDFKit; one page per slide (no mid-slide auto page-breaks).
- **Interactive HTML5**: Hardware-accelerated slide transitions, speaker notes view, and embedded DevTools Visual Inspector (`I` / `Alt+Click`).
- **Design Intelligence**: `yumia check --optimize` and `yumia explain` auditing WCAG 2.1 AAA contrast, cognitive information density, safe-area compliance, and composition rhythm.
- **Layered flow diagrams**: Cycle-safe ranking with orthogonal connectors; `node [Full Label] variant="…"` updates existing nodes without ghost aliases.
- **Deterministic AI Generation**: Strict indentation-based grammar and JSON Schema (`yumia schema`) preventing unclosed HTML tag errors and CSS hallucinations.

## Quick CLI Reference
```bash
# Initialize a new presentation project
npx yumiamd@latest init my-deck --theme corporate

# Start live-reload dev server with Visual Inspector
yumia dev presentation.yumia --open

# Run automated design audit & visual quality score (0-100)
yumia check presentation.yumia --optimize

# Explain document composition, rhythm, and design metrics
yumia explain presentation.yumia

# Compile to 100% native editable PowerPoint (.pptx)
yumia build presentation.yumia --format pptx --out dist/deck.pptx

# Compile to crisp vector PDF document (.pdf)
yumia build presentation.yumia --format pdf --out dist/deck.pdf
```

## Syntax Example (.yumia)
```yumia
document "Executive Strategy"
  theme "corporate"
  aspectRatio "16:9"

slide "Revenue & Growth"
  hero title="Hyper-Growth Execution" subtitle="ARR beats quarterly target by 42%" badge="Q4 Audit" align="center"

  grid columns=3 gap=20
    metric "$24.8M" label="ARR Run-Rate" diff="+142% YoY" variant="success" trend="up"
    metric "118%" label="Net Retention" diff="+4%" variant="primary" trend="up"
    metric "9.2x" label="LTV / CAC" diff="+1.8x" variant="accent" trend="up"

  chart type="bar" title="Quarterly ARR ($M)" labels="Q1,Q2,Q3,Q4" data="12.4,15.8,19.2,24.8"
```

## Documentation Links
- Docs home: https://biagio-scaglia.github.io/Yumia-MD/
- Full Language Specification: https://biagio-scaglia.github.io/Yumia-MD/docs/language.md
- Compiler Architecture: https://biagio-scaglia.github.io/Yumia-MD/docs/architecture.md
- CLI Reference: https://biagio-scaglia.github.io/Yumia-MD/docs/cli.md
- Known Limitations: https://biagio-scaglia.github.io/Yumia-MD/docs/limitations.md
- AI Generation Guidelines: https://biagio-scaglia.github.io/Yumia-MD/docs/ai-guidelines.md
- Complete Machine-Readable Corpus: https://biagio-scaglia.github.io/Yumia-MD/llms-full.txt