# makeover-layout

The renderer-agnostic half of the make-family design system.

`makeover` answers *what colour*, and varies by theme. `makeover-geometry`
answers *how much space*, and varies by density and surface. This crate answers
*what the thing is*, and varies by nothing.

## The deferral rule

A description names intents and relationships, never values. Say `Fill::Raised`,
never `#D9DDF4`. Say `Gap::Peer`, never `6px`. What is left once colour and
spacing are deferred is composition: which edges are lit, what inverts on press,
what nests in what.

The constraint that shapes it: a renderer that can only paint rectangles has to
be able to express the result. egui has no `box-shadow: inset` and one stroke per
widget with no per-side control. A terminal has box-drawing characters and one
cell of resolution, and cannot draw a two-tone lit edge at all. So this crate
names the intent, and each renderer picks an expression it can produce, including
dropping half of one.

## What is here

**Depth**: `Bevel`, `Edge`, `Fill`, `Depth`. Fill and bevel are named together,
because naming them apart is what let them disagree. Every consumer had at least
one region carrying a raised bevel over a recessed fill; audiofiles fixed it and
wrote the bug down, Balanced Breakfast still had twelve of them a year later.
`Depth` makes that unrepresentable.

**Components**: `Token` (a badge does not answer a click, a chip does), `Notice`
(a toast is transient, a banner is persistent), `RowPart`, `Heading`, `Selector`,
`Readiness`, and `Tone`, the one intent family they share.

**Schemas**: `Field` for forms, `Column` for lists and tables. A column carries a
drop priority, which is what replaces addressing columns by position. Both
webview apps hide narrow-screen columns with `nth-child`, so inserting a column
silently hides the wrong one.

**Structure**: `Region` for the parts of a screen, `Arrangement` for how a screen
is put together. Two arrangements, because the two apps have two. `Showing` says
how many of a region's children are visible at once, which is what lets a
renderer derive a tab strip or a prev/next row for itself instead of recognising
a widget by name.

The vocabulary was read off audiofiles, the only implementation written by a
consumer with no CSS, then checked against both webview apps.

## What is not here, on purpose

Validation. `Field` describes fields, not constraints. Neither app has a shared
story, and a schema that describes one without the other acquires a constraint
layer per app, which is how the divergence this crate exists to end got started.

## Where the description stops

The bespoke widgets: a day-plan timeline, a kanban board, a calendar. A
description expressive enough to produce those is not a description any more, it
is a widget library with one app on top. Generate the boring 80% so the bespoke
20% gets the attention.

`Region::Bespoke` states that limit instead of hiding it. The description names
the place, the app owns the contents, and a screen with a timeline in it is still
a whole screen. Without that member the description would cover only the boring
screens, and the interesting ones would need a second path beside the router.
One opaque member, and `Region::described()` is how a renderer tells it from the
rest.

## Status

On crates.io at 0.2.0, published 2026-07-29. 0.1.0 went out the day before, and
the sequencing decision behind it was not to publish until a second renderer had
exercised the vocabulary; three had, and it cost the description exactly one
deletion (`Fill::fallback`, which turned out to be renderer policy).

0.2.0 went out on a different basis: no renderer has been through the components,
schemas or structure yet. So expect the first renderer to force a correction, and
expect that correction to be a 0.3.0 with a migration rather than an edit.

Design lives in the wiki note `makeover-layout`; the backlog is in GoingsOn under
the project of the same name.

## Licence

MIT.