beautiful: an open-source, purely mathematical beauty score for any image

Can beauty be measured? Ninety years of experimental aesthetics and HCI research say that a surprising amount of it can: symmetry and balance, alignment to a grid, the share of white space, a harmonic palette, figure–ground contrast, intermediate complexity. Each of these has been measured and tied to what people prefer.

beautiful turns those findings into one formula. It is a small, MIT-licensed Python package that takes an image and returns a beauty score from 1 to 100, computed from pixels alone — no model, no dataset, every term readable:

from beautiful import beauty

r = beauty("screenshot.png", mode="ui")
r["score"]    # 82
r["factors"]  # composition, alignment, simplicity, whitespace, harmony, contrast ...
r["hints"]    # ["alignment (0.26): snap element edges to a shared column/row grid", ...]

Why a formula and not a model

Learned aesthetic predictors return a number without a reason, and inherit the taste of whoever rated their training set. Every term in beautiful is instead an explicit formula with a target range taken from the literature — Birkhoff's order and complexity, Ngo's balance and equilibrium, Miniukovich and De Angeli's grid quality and white space, Cohen-Or's colour harmony templates, Hasler and Süsstrunk's colourfulness. The breakdown tells you which property is weak; the hints tell you what would raise it.

Famous sites, scored

We ran it over well-known home pages. Apple scores 85, Hacker News 66, Google 61, Craigslist 60, GitHub 54, Stripe 26, Amazon 16. It is a ranking of visual form in a single viewport, not of good websites — Craigslist beats Stripe because Craigslist is symmetric and Stripe's hero is a diagonal gradient. Because the score comes with its factors, every disagreement you have with it points at a factor that is missing.

Help improve the formula

That is the invitation. The formula is deliberately incomplete: rhythm, proportion, typographic hierarchy, focal-point count and accent-colour discipline are not in it yet, and each is measurable from pixels. The repository has a factor wishlist and an issue template for proposing one — an idea with a source and two images the current score gets wrong is enough; no code needed.

The score is also smooth enough to optimise: on a card whose button drifts off centre it climbs from 54 to 91 as the offset closes, and re-composing a screen of our own Digital Office platform moved it from 51 to 82. It ships as a CLI, an MCP server, a GitHub Action, and a browser demo where the image never leaves your tab.

Modes

• ui — screens, web pages, apps
• art — paintings, photos, posters (adds fractal dimension, Fourier slope and rule of thirds)
• logo — marks and icons

No network, no dataset, no weights: numpy, pillow, scipy.

Get it

pip install beautiful-score
beautiful --mode=ui screenshot.png

The repository is at github.com/solomonBoltin/beautiful. Stars, issues and — especially — screenshots that break the score are welcome. If you want this kind of measurable quality loop in your own product, talk to us.