# Legible Desk

> How big type looks is an ANGLE, not a pixel count. Measured in picture heights
> a phone at arm's length is farther from the eye than the back row of a cinema —
> and a cap height stated in pixels halves when the master goes from 1080 to 2160
> lines. This works out what your type actually subtends on every screen it will
> be seen on.

## The one thing to know

```text
theta = 2 * atan( (cap / pictureHeight) / (2 * distanceInPictureHeights) )
```

Both halves are ratios, so **nothing about the display's physical size or the
master's resolution appears anywhere**. A 55-inch television and a phone showing
the same fraction of picture at the same number of picture heights look identical.

## Ordinary screens, ranked by distance

| Screen | Distance | 4% subtends | Verdict |
| --- | --- | --- | --- |
| a phone at arm's length | 7.9 PH | 17.5′ | marginal |
| a phone held in the hand | 5.7 PH | 24.1′ | comfortable |
| a television, ordinary living room | 4 PH | 34.6′ | generous |
| a television, THX reference | 3.5 PH | 39′ | generous |
| the back row of a cinema | 3.3 PH | 41.3′ | generous |
| a laptop | 3.2 PH | 43.5′ | generous |
| a desk monitor | 2.1 PH | 66.8′ | generous |
| the middle of a cinema | 2 PH | 68.8′ | generous |

Ordered by distance in PICTURE HEIGHTS, which is the only unit that decides an angle. **A phone at arm's length is the farthest screen on this list** — farther than the back row of a cinema, and it is where most of the audience is.

## What the threshold demands

| Distance | To clear 16′ | On a 1,080-line master | On a 2,160-line master |
| --- | --- | --- | --- |
| 1.5 PH | 0.7% of picture height | 8 px | 15 px |
| 2 PH | 0.9% of picture height | 10 px | 20 px |
| 3 PH | 1.4% of picture height | 15 px | 30 px |
| 3.5 PH | 1.6% of picture height | 18 px | 35 px |
| 4 PH | 1.9% of picture height | 20 px | 40 px |
| 5.7 PH | 2.7% of picture height | 29 px | 57 px |
| 7.9 PH | 3.7% of picture height | 40 px | 79 px |
| 10 PH | 4.7% of picture height | 50 px | 101 px |

The last two columns are the SAME SIZE. They differ because pixels are not a size — the fraction is what is fixed, and the pixel count is whatever that fraction happens to come to on the master in front of you.

## Why pixels are not a size

| Master | 43 px is | At 7.9 PH it subtends | Verdict |
| --- | --- | --- | --- |
| 720-line | 6% of picture | 26′ | comfortable |
| 1,080-line | 4% of picture | 17.3′ | marginal |
| 1,440-line | 3% of picture | 13′ | below |
| 2,160-line | 2% of picture | 8.7′ | below |
| 4,320-line | 1% of picture | 4.3′ | below |

**The same number on every row.** Nothing is edited between them and nothing is flagged, and the type goes from readable to not.

## Title-safe is not a legibility rule

Title-safe is 90% of the picture on every screen that has ever existed. It
protects the same FRACTION everywhere, while the angle varies by whatever the
spread of your screens happens to be. Being inside the safe area says nothing
whatever about being readable, and the two rules are routinely confused because
both are expressed as percentages of the frame.

## What it is

A single page at https://legible-desk.skillsafe.ai. The engine that computes all
of this runs entirely in your browser, needs no account and costs nothing.
Writing the report calls a model and needs credits.

## The free engine

Everything below is computed client-side in `legible.js` and sent with every run
as `prescan`:

- **The type.** The cap height as a fraction of picture height, and what that
  comes to in pixels on this master and on one with twice the lines.
- **Every screen.** Its distance in picture heights, the angle the type subtends
  there, the verdict, and the fraction that would clear the threshold.
- **The ranking.** Which screen is farthest, and therefore decides every verdict.
- **The spread.** How far apart the nearest and farthest are, which decides
  whether one size can serve all of them.
- **The budget.** Whether any size satisfies both the threshold and the ceiling.

The engine makes no network calls.

## Sheet grammar

Two blocks. Blank lines and `#` comments are ignored.

```text
TITLE
name    | the product demo captions
lines   | 1080
cap     | 43
minimum | 16
max     | 6%

SCREENS
s1 | phone at arm's length | 7   | 55   | most of the audience
s2 | a laptop              | 19  | 60   | the reviewer
s3 | the cinema back row   | 600 | 2000 | the launch event
```

A SCREENS row is `id | what it is | picture height | viewing distance | who`. The
two measurements must be **in the same units as each other** — it does not matter
which, because only their ratio is used. It is the height of the PICTURE, not the
diagonal of the display.

In TITLE, `cap` is a cap height in pixels and `percent` is the same thing as a
fraction of picture height; give either, and if you give both the fraction wins.
`lines` is the master's height. `minimum` is the threshold in arcminutes.
`max` is the most of the picture height you are willing to give to type, and it
is the only thing that can make a sheet impossible.

**A number in `percent` or `max` is a PERCENTAGE**: `4` and `4%` both mean four
percent, and `0.5` means half of one percent. Treating a value under one as an
already-divided fraction would make `0.5` mean half the picture — a hundred times
the other reading, with no way to tell the two intentions apart.

## Lanes

| Lane | What it decides | Fields |
| --- | --- | --- |
| `plan` | The type size before it is set | `brief`, `known` |
| `check` | What this size actually subtends | `sheet`, `symptom` |
| `screens` | Where it will be seen, in picture heights | `sheet`, `audience` |
| `size` | What size each screen demands | `sheet`, `priority` |
| `deliver` | What changes: the size, the screens, or the threshold | `sheet`, `fixed` |

`check` is the primary lane. Every lane ships a worked example that costs nothing
to read.

## Thresholds

| Threshold | Value | What it decides |
| --- | --- | --- |
| minimum | 16′ | below this, sustained reading fails for many people |
| comfortable | 20′ | above this, most people read it without effort |
| generous | 30′ | above this it is large, and eating picture |
| a title, not a caption | 12% | cap height past this much of the frame |
| a legal line | 1.5% | cap height below this |
| wide spread | 2.5x | screens differing by this much cannot share one size |
| implausible | 1 PH | closer than this is a measurement error |
| title-safe | 90% | a FRACTION, and therefore not a legibility rule at all |
| default master | 1,080 lines | assumed when none is stated |

## Severity

Severity is fixed by the code, not by the model. **Errors are reserved for type
that cannot be read at all** — below the threshold on a screen somebody stated,
or a demand where no size satisfies both the threshold and the ceiling.

Most of what this page reports is a description of the situation rather than a
fault, because most of the time nobody has made a mistake: they have simply
measured the wrong screen.

There are 26 codes. `SCREEN-BELOW` and `SIZE-IMPOSSIBLE` are the only two errors.

## API

```
POST https://api.skillsafe.ai/v1/app-api/run
X-App-Key: <your key>
Content-Type: application/json

{"task": "check", "sheet": "TITLE\nlines | 1080\ncap | 43\n...", "symptom": "nobody can read it on a phone"}
```

The run body **is** the input object. There is no `input` wrapper. Every field is
a string. Full documentation: https://legible-desk.skillsafe.ai/api.html

## What this page cannot do

- **This page has not seen the type.** Every figure is arithmetic on numbers
  somebody typed in.
- **Cap height is not the font size.** A 43-pixel cap height comes from a larger
  point size, by a ratio that differs between typefaces, and nothing here knows it.
- **The thresholds are conventions.** 16′ is where broadcast and
  accessibility practice converge for sustained reading of moving text. It is not a
  measurement of anybody's eyes.
- **Legibility is more than size.** Contrast, weight, the picture behind the type
  and how long it stays on screen all matter, and none of them is an angle.
- **It says nothing about line length or leading.** Only about how big one letter
  looks.

## Source

Lanes derived from the `peekaboo` skill in https://github.com/steipete/clawdis,
which captures screens. Every capture it takes is a picture of type at some size,
and whether that size can be read is a question about the eye rather than about
the pixels. Not affiliated with or endorsed by that repository's authors.