README

Strict mathematical scales for typography, spacing, grids, and rhythmic design systems.

ALTO Scale turns a mathematical progression into predictable design values. Build modular, linear, Fibonacci, or multi-strand scales through one small API, then generate ranges, snap arbitrary values, infer an existing scale, or lint a collection.

use Alto\Scale\Scale;

$type = Scale::majorThird(16);

$type->range(-1, 2);
// [-1 => 12.8, 0 => 16.0, 1 => 20.0, 2 => 25.0]

The package has no runtime dependencies. Every scale implements the same typed interface and the codebase is checked at PHPStan's maximum level.

Installation

Install ALTO Scale with Composer:

composer require alto/scale

ALTO Scale requires PHP 8.4 or later.

Quick Start

Create a scale through the Scale facade and request the values needed by your design system:

use Alto\Scale\Scale;

$spacing = Scale::linear(base: 0, increment: 8);

echo $spacing->get(3);  // 24
echo $spacing->snap(19); // 16

All scales expose get(), stepOf(), snap(), and range() and can be iterated over steps zero through ten.

Scale Types

Scale	Progression	Typical use
Modular	Multiply by one ratio	Type sizes and proportional spacing
Linear	Add one increment	Baseline grids and fixed spacing
Fibonacci	Follow Fibonacci numbers	Integer rhythms and counts
Multi-strand	Interleave modular scales	Multiple coordinated bases

Named constructors provide common ratios:

$type = Scale::majorThird(16);
$display = Scale::perfectFifth(48);
$golden = Scale::golden(1);

Custom ratios are available through Scale::modular(). See the scale guide for every progression and its constraints.

Guessing

Infer a modular scale from existing positive values and align the originals to it:

use Alto\Scale\ScaleGuesser;

$values = [15.9, 20.1, 24.8, 31.5];
$guesser = new ScaleGuesser(tolerance: 0.05);

$scale = $guesser->guess($values);
$aligned = $guesser->align($values, $scale);

Read Guessing a scale for the estimation rules and limitations.

Linting

Audit values against a known scale and normalize deviations:

use Alto\Scale\Scale;
use Alto\Scale\ScaleLinter;

$linter = new ScaleLinter(Scale::linear(0, 8));

$report = $linter->lint([8, 15, 24]);
$fixed = $linter->fix([8, 15, 24]); // [8.0, 16.0, 24.0]

Read Linting values for the report format and inferred-scale behavior. The complete documentation also covers installation, the shared API, and each scale type.

Contributing

Contributions of all kinds are welcome. Visit the project on GitHub to report a bug, suggest a feature, or open a pull request.

Before submitting code, run:

# Runs PHP CS Fixer, PHPStan, and PHPUnit
composer qa

Changes to public behavior should include tests and documentation.

Support

ALTO Scale is open source. You can support its continued development through GitHub Sponsors.

Sharing this package with others or starring it on GitHub is also much appreciated.

License

ALTO Scale is released by ALTO PHP under the MIT License.

alto / scale

Maintainers

Package info

Fund package maintenance!

Statistics

Security