design-math

design-math

design-math is a Rust-powered design math toolkit for AI agents, automation, CI, and human workflows.

It turns the parts of design systems that are easy to hand-wave and easy to get wrong into deterministic tools:

• color conversion, contrast, palettes, and schemes
• typography scales and fluid type
• shadow systems for light and dark surfaces

This repo is not just a small color utility. It is a product-shaped workspace built around a shared Rust engine as the source of truth for design calculations, with a CLI plus in-repo Node and WASM bindings sharing the same implementation.

Why it exists

When an agent or automation script needs to do design work, mental math is not reliable enough for tasks like:

• expanding a brand color into a full semantic token set
• generating light and dark themes
• checking WCAG and APCA contrast
• producing modular scales and fluid type
• generating multi-layer elevation tokens

design-math exists to make those calculations repeatable, inspectable, and safe to automate.

What ships today

• Color workflows: convert, contrast, manipulate, mix, scale, harmony, palette, and scheme
• Color analysis: luminance, tone, temperature, gamut flags, and compact descriptions
• Typography workflows: scale, fluid type, standalone letter-spacing, and px/rem conversion
• Shadow workflows: layered elevation tokens for light/dark surfaces, colored shadows, and inset mode
• Output paths for JSON, CSS, HTML, and PNG
• Distribution through npm, Homebrew, and GitHub Releases
• In-repo bindings for Node, WASM, and Python

Workspace layout

• crates/core The shared Rust calculation engine for color, typography, and shadow logic.
• crates/cli The CLI layer for argument parsing, formatting, exports, and release distribution.
• bindings/node The design-math-node native Node binding package built with napi-rs.
• bindings/wasm The design-math-wasm fallback package built with wasm-bindgen.
• bindings/python The design-math-python PyO3 binding crate for Python-native dict/list results.

If you are new to the repo, these docs are the best starting points:

• POSITIONING.md
• ARCHITECTURE.md
• IMPLEMENTATION-PLAN.md
• VALIDATION.md

License

This repository is licensed for free use, copying, and redistribution in unmodified form for personal or commercial purposes. Modification and derivative works are not permitted. See LICENSE for the full terms.

Install

npm

npm install -g design-math

Or run it without a global install:

npx design-math color convert "#c96442" --json

The npm distribution uses a main package plus platform-specific binary packages, all resolved through the npm registry.

Homebrew

brew tap eric8810/design-math
brew install design-math

Quick examples

design-math color convert "#c96442" --json
design-math color analyze "#c96442" --json
design-math color contrast "rgba(255,255,255,0.72)" "#111111" --json
design-math color palette --bg "#f5f4ed" --fg "#141413" --brand "#c96442" --format css
design-math type letter-spacing 24 --json
design-math type convert 24px --to rem --json
design-math type scale --base 16 --ratio major-third --json
design-math shadow generate --levels 5 --inset --json
design-math completion zsh > _design-math

Packages

• design-math The end-user CLI package for terminals, scripts, CI, and npm/Homebrew installs.
• design-math-node The native Node binding package that wraps the core API with a small JS layer.
• design-math-wasm The WASM package that exposes the same API shape for JS runtimes that want a non-native fallback.
• design-math-python The Python binding crate in this repo. It is implemented and buildable locally, but not yet published to PyPI.

JavaScript bindings

If you want function calls instead of shelling out to the CLI, there are two JS-facing bindings:

• design-math-wasm The easiest integration path for JS and TS consumers. It exposes the shared design-math API without requiring a native Node addon toolchain.
• design-math-node The native Node binding with the same public API shape. It is published as a main npm package plus platform-specific optional dependency packages.

The shared API includes:

• convertColor
• analyzeColor
• contrastColor
• manipulateColor
• mixColors
• generateColorScale
• generateColorHarmony
• generatePalette
• generateScheme
• generateTypeScale
• generateFluidScale
• generateFluidType
• queryLetterSpacing
• convertTypeUnits
• generateShadowSystem

For integration examples and API notes, see docs/javascript-bindings.md.

Current focus

The core product line from M0 through M10 is now in place:

• color workflows are usable
• typography workflows are usable
• shadow workflows are usable
• color analyze, standalone letter-spacing, and px/rem conversion are usable
• JSON, CSS, HTML, and PNG exports are usable
• npm, Homebrew, and GitHub Release distribution are wired up
• Node, WASM, and Python bindings exist in this repo

The next focus areas are:

• stronger agent-first workflows
• publishing the Python binding to PyPI
• longer-tail performance and DX polish
• possible post-1.0 visual tooling such as a local preview server