Metadata-Version: 2.4
Name: tokenmoulds
Version: 3.5.1
Summary: Generate branded Office templates from design tokens
Author-email: TokenMoulds Team <team@tokenmoulds.dev>
License: MIT
Project-URL: Homepage, https://github.com/BramAlkema/TokenMoulds
Project-URL: Repository, https://github.com/BramAlkema/TokenMoulds
Project-URL: Issues, https://github.com/BramAlkema/TokenMoulds/issues
Keywords: design-tokens,ooxml,odf,templates,office
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml>=4.9.0
Requires-Dist: fonttools>=4.38.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: structlog>=23.1.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: imaging
Requires-Dist: Pillow>=10.0.0; extra == "imaging"
Provides-Extra: media
Requires-Dist: httpx>=0.23.0; extra == "media"
Requires-Dist: Pillow>=10.0.0; extra == "media"
Provides-Extra: validation
Requires-Dist: jsonschema>=4.20.0; extra == "validation"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.3.0; extra == "dev"
Requires-Dist: pytest-html>=4.0.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: factory-boy>=3.3.0; extra == "dev"
Requires-Dist: freezegun>=1.2.0; extra == "dev"
Requires-Dist: responses>=0.23.0; extra == "dev"
Requires-Dist: faker>=19.0.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: pre-commit>=3.4.0; extra == "dev"
Requires-Dist: lxml-stubs>=0.5.0; extra == "dev"
Requires-Dist: httpx>=0.23.0; extra == "dev"
Requires-Dist: Pillow>=10.0.0; extra == "dev"
Requires-Dist: numpy>=1.24.0; extra == "dev"
Requires-Dist: openxml-audit>=0.4.5; extra == "dev"
Requires-Dist: svg2ooxml>=0.3.2; extra == "dev"
Requires-Dist: ipython>=8.15.0; extra == "dev"
Requires-Dist: pdbpp>=0.10.3; extra == "dev"
Requires-Dist: rich>=13.5.0; extra == "dev"
Provides-Extra: all
Requires-Dist: tokenmoulds[dev,imaging,media,validation]; extra == "all"
Dynamic: license-file

# 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-2060%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)

A **corporate template system** for Microsoft Office and LibreOffice. Point it at a brand, get publication-quality Word, PowerPoint, Excel, and LibreOffice templates — with embedded fonts, baseline grids, OOXML compliance validation, and **long-form document support** for whitepapers, annual reports, manuals, and bound books.

## 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 (Word) and EOT with GSUB (PowerPoint)
- OpenType typography: contextual figures, size-dependent tracking, ligatures
- Baseline grid-snapped typography via modular type scales
- ISO 29500 (OOXML) and ODF schema compliance
- Zero macros — all styling baked into document structure

## Long-Form Documents

Corporate whitepapers, annual reports, manuals, and bound books need more
than a single page layout. They need **sections** — front matter with
roman-numeral page numbers, a body with running chapter titles and
decimal numbering, an appendix that continues the count. Each section
with its own headers, footers, and page geometry.

TokenMoulds generates long-form structure from a small token vocabulary
and emits it consistently across both Word (`.dotx`) and LibreOffice
Writer (`.ott`) from **one shared IR**. Features:

- **Per-section page geometry** — A4, A5, B5, Letter, portrait or
  landscape, margins as formulas against the baseline grid
- **Mirror margins** — inner/outer semantics for bound documents, facing
  pages automatically flip
- **Running headers** — `STYLEREF:Heading1` fields that update as the
  reader moves through chapters (Word) / `<text:chapter>` fields (Writer)
- **Per-section page numbering** — `lowerRoman` for front matter,
  `decimal` restart for the body, continuing counts for appendices
- **Odd/even headers** — book-style layouts with different left-hand and
  right-hand page content
- **First-page different** — cover pages, chapter openers
- **Multi-column sections** — indexes, newsletters
- **Cross-format parity** — one IR → structurally identical `.dotx` and
  `.ott`, locked down by a golden master test suite

See [Long-Form Documents guide](docs/docs/guides/long-form-documents.md)
for a walkthrough with a three-section whitepaper example.

## 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   # 2,060 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)
