Skip to content

Serialization

Armonia supports serializing themes to and from dictionaries, which are compatible with JSON and YAML formats. It also includes native support for DESIGN.md files.

Dictionary Serialization

A theme can be completely represented as a nested dictionary.

# Export theme to dictionary
theme_dict = theme.to_dict()

# Load from dictionary
from armonia import Theme
new_theme = Theme.from_dict(theme_dict)

JSON/YAML Support

Since the dictionary is composed of standard types, it's easy to load from files:

import json

with open("theme.json", "r") as f:
    theme = Theme.from_dict(json.load(f))

DESIGN.md Integration

Armonia can parse a DESIGN.md file that follows a specific structure with YAML frontmatter.

Parsing a DESIGN.md File

The Theme.from_design_md() method allows you to load a theme directly from a markdown file:

# From a file path
theme = Theme.from_design_md("DESIGN.md")

# From content as a string
theme = Theme.from_design_md(markdown_content)

DESIGN.md Format

The file should include YAML frontmatter with the following sections:

  • colors: Manual colors (Hex or names).
  • computed_colors: Functions and arguments.
  • fonts: Manual font definitions.
  • computed_fonts: Functions and arguments.
  • spacing: Spacing tokens.
  • rounded: Shape tokens.
  • palettes: Named lists of color keys.
  • logotypes: Named logotype URIs.

Example Frontmatter

---
colors:
  primary: "#2563eb"
  secondary: "#7c3aed"
computed_colors:
  primary_light:
    function: "lighter"
    args: ["primary", 0.15]
fonts:
  body: { family: "Inter", size: 16, weight: 400, italic: false }
computed_fonts:
  body_bold:
    function: "bolder"
    args: ["body", 300]
spacing:
  md: "16px"
rounded:
  md: "4px"
---