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 design-math-core as the source of truth for design calculations, with a CLI plus in-repo Node and WASM bindings sharing the same engine.

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
• Typography workflows: scale and fluid type generation
• Shadow workflows: layered elevation tokens for light and dark surfaces
• Output paths for JSON, CSS, HTML, and PNG
• Distribution through crates.io, npm, Homebrew, and GitHub Releases

Workspace layout

• design-math-core The pure Rust calculation engine for color, typography, and shadow logic.
• design-math The CLI crate 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.

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

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

Install

Cargo

cargo install design-math

If you build from source and want PNG export support:

cargo install design-math --features image

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 contrast "rgba(255,255,255,0.72)" "#111111" --json
design-math color palette --bg "#f5f4ed" --fg "#141413" --brand "#c96442" --format css
design-math type scale --base 16 --ratio major-third --json
design-math shadow generate --levels 5 --json

Packages

• design-math The end-user CLI package for terminals, scripts, CI, and npm/Homebrew installs.
• design-math-core The reusable Rust engine shared by the CLI and language bindings.
• 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.

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
• contrastColor
• manipulateColor
• mixColors
• generateColorScale
• generateColorHarmony
• generatePalette
• generateScheme
• generateTypeScale
• generateFluidScale
• generateFluidType
• generateShadowSystem

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

Current focus

The core product line from M0 through M7 is already in place:

• color workflows are usable
• typography workflows are usable
• shadow workflows are usable
• JSON, CSS, HTML, and PNG exports are usable
• crates.io, npm, Homebrew, and GitHub Release distribution are wired up

The next focus areas are:

• stronger agent-first workflows
• the remaining polish toward 1.0
• possible post-1.0 visual tooling such as a local preview server