# TokenMoulds

[![PyPI](https://img.shields.io/pypi/v/tokenmoulds)](https://pypi.org/project/tokenmoulds/)
[![Downloads](https://img.shields.io/pypi/dm/tokenmoulds)](https://pypi.org/project/tokenmoulds/)
[![Python](https://img.shields.io/pypi/pyversions/tokenmoulds)](https://pypi.org/project/tokenmoulds/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/BramAlkema/TokenMoulds/actions/workflows/05-quality.yml/badge.svg)](https://github.com/BramAlkema/TokenMoulds/actions/workflows/05-quality.yml)
[![Tests](https://img.shields.io/badge/tests-1629%20passing-brightgreen)](https://github.com/BramAlkema/TokenMoulds/actions)
[![MCP Tools](https://img.shields.io/badge/MCP%20tools-28-blueviolet)](docs/docs/reference/mcp-tool-catalog.md)

Generate branded Office templates from design tokens. Point it at a brand, get publication-quality Word, PowerPoint, Excel, LibreOffice, and Google Workspace templates — with embedded fonts, baseline grids, and OOXML compliance validation.

## Install

```bash
pip install tokenmoulds
```

## Quick Start

Generate templates from brand inputs:

```bash
tokenmoulds --org-id="acme" \
  --font-pair="inter-roboto" \
  --primary-color="#2563EB" \
  --secondary-color="#DC2626" \
  --locale="GB" \
  --brand-tone=0.3 \
  --generate-templates --generate-odf
```

Or from a DTCG token file:

```bash
tokenmoulds --org-id="acme" \
  --tokens-file="design.tokens.json" \
  --generate-templates
```

## What It Does

~30 brand inputs (colors, fonts, tone) produce **4,576 derived design tokens** across **11 output formats**. Every template ships with:

- WCAG AAA accessible contrast ratios
- Embedded fonts with ODTTF obfuscation
- Baseline grid-snapped typography via modular type scales
- ISO 29500 (OOXML) and ODF schema compliance
- Zero macros — all styling baked into document structure

## Output Formats

| Format | Extension | Highlights |
|--------|-----------|------------|
| Word | `.dotx` | 276 themed paragraph, character, and table styles |
| PowerPoint | `.potx` | Theme colors, embedded fonts, table styles, layouts |
| Excel | `.xltx` | Themed cell styles and number formats |
| Writer | `.ott` | 110 ODF styles with page geometry |
| Impress | `.otp` | ODF presentation template |
| Calc | `.ots` | ODF spreadsheet template |
| Draw | `.otg` | ODF drawing template |
| Google Docs | `.dotx` | Optimized for Google Workspace import |
| Theme | `.thmx` | Standalone Office theme package |

## MCP Server

For AI-assisted document creation via Claude, Cursor, or other MCP clients:

```bash
tokenmoulds mcp-server
```

28 tools for brand extraction, template generation, document creation, validation, and cache management. See the [MCP tool catalog](docs/docs/reference/mcp-tool-catalog.md).

## Python API

```python
from tokenmoulds.pipeline import BuildConfig, build

result = build(BuildConfig(
    org_id="acme",
    output_formats=["potx", "dotx", "xltx"],
    brand_inputs={
        "font_pair": {"sans": "Inter", "serif": "Roboto Slab"},
        "base_colors": {"primary": "#2563EB", "secondary": "#DC2626"},
        "locale": "US",
        "brand_tone": 0.5,
    },
))

for fmt, data in result.artifacts.items():
    open(f"acme.{fmt}", "wb").write(data)
```

## Architecture

TokenMoulds uses a single canonical build pipeline:

```
Design Tokens → DesignResolutionEngine → DocumentIR → Emitters → Validated Packages
```

- **DTCG pipeline**: W3C Design Tokens Community Group format with 5-layer resolution (core/fork/org/group/personal)
- **Design engine**: Modular type scale, baseline grid, OpenType features, tone/density adaptation
- **Document IR**: Format-agnostic intermediate representation
- **11 emitters**: Each produces a complete, valid package
- **Validation**: In-process ISO 29500 schema checking via [openxml-audit](https://github.com/BramAlkema/openxml-audit)

See [ADR 027](docs/adr/027-architectural-convergence.md) for the full convergence story.

## Development

```bash
git clone https://github.com/BramAlkema/TokenMoulds.git
cd TokenMoulds
python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
python -m pytest tests/ -v --tb=short   # 1,629 tests
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines, code conventions, and how to submit changes.

## Documentation

- [Getting Started](docs/docs/intro.md)
- [CLI Reference](docs/docs/reference/cli-reference.md)
- [MCP Tool Catalog](docs/docs/reference/mcp-tool-catalog.md)
- [Architecture Decisions](docs/adr/)

## License

[MIT](LICENSE)
