# is-aesthetic

> Is this website well designed? is-aesthetic measures a public web page against a vetted design rubric and returns a score from 0 to 100, results in six design domains, and every finding with the flagged element, the measured value against its threshold, and a concrete fix.

Scans load up to three pages of one site in an isolated browser at 1440 and 390 px (and 320 px for reflow). They only read: robots.txt is honoured, nothing is submitted, nobody logs in. Checks that don't apply are excluded and never count as failures. A null score means nothing could be measured reliably; it is not a zero.

## Reports

- [Report page](https://is-aesthetic.com/r/{host}): the latest report for a host, for example https://is-aesthetic.com/r/www.benchflow.ai
- [Report as Markdown](https://is-aesthetic.com/r/{host}/report.md): or send `Accept: text/markdown` to the report page
- [Report as JSON](https://is-aesthetic.com/r/{host}/report.json)

## API

- [GET /api/v1/report?url=](https://is-aesthetic.com/docs#get): latest report for an absolute URL's host; 200 report, 202 job in progress (poll after Retry-After), 404 none yet, 422 failed
- [POST /api/v1/report](https://is-aesthetic.com/docs#post): body {"url": "https://example.com"}; starts a scan and returns 202 with the job
- [OpenAPI 3.1](https://is-aesthetic.com/openapi.json)
- [Report JSON Schema](https://is-aesthetic.com/schema/report-v1.json)

## Understanding a report

- [Methodology](https://is-aesthetic.com/methodology): the checks, what changed from the source taxonomy and why, scoring (80 essential points, 20 recommended, up to 5 bonus; grades A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60), exclusions and limits
- [Docs](https://is-aesthetic.com/docs): API details, errors, limits and the command-line client

## Command line

- Install: `pip install is-aes`, then `is-aes vercel.com`
- Without installing: `uvx is-aes vercel.com` or `python -m is_aes vercel.com`
- Options: `--wait` (poll until ready), `--timeout <seconds>` (default 120), `--json` (raw report or job)
- Python: `from is_aes import check`, then `check("vercel.com", wait=True)`
- Bare hosts work (is-aes 0.1.1 and later). An npm client is coming soon.

## Limits

- Text contrast isn't measured yet.
- Judgement calls (brand fit, tone, imagery, originality) aren't measured.
- Each IP address can start five new scans an hour; please cache reports.

## Optional

- [Scanner](https://is-aesthetic.com/bot): user agent `is-aesthetic (+https://is-aesthetic.com/bot)` and how to block it
- [Remove a report](https://is-aesthetic.com/removal)