# largen 0.6.3: the complete authoring contract

A property algebra for CSS. Plain CSS, with no build step, no preprocessor and no plugin.

TOKENS      --canvas --ink --surface --line, --primary/--primary-on …   theme sets these
SLOTS       --bg --fg --pad --gap --radius --font-size …                library, fixed
AXES        tone · variant · size · state                               library, fixed
PAINT       one universal rule                                          library, fixed
─────────────────────────────────────────────────────────────────────────────────────
UTILITIES   stack row cluster center grid switcher sidebar              library, fixed
─────────────────────────────────────────────────────────────────────────────────────
COMPONENTS  whatever this project needs                                 ← YOU WRITE THESE

Only the last row grows. A component is about six lines because everything above
it is already solved. The tones, the variants, the sizes, the states and both
themes are supplied by the rows it never mentions.

## Writing a component

@layer largen.components {
  .notification, notification {
    --bg: var(--tone-soft);
    --fg: var(--tone-ink);
    --border-width: 0 0 0 3px;
    --border-color: var(--tone);
    --border-style: solid;
    --radius: var(--radius-md);
    --pad: .75em 1em;
    --gap: .75em;
    display: grid;
    grid-template-columns: auto 1fr;
    align-items: center;
  }
}

<notification data-tone="warning">Two accounts need review.</notification>
<div class="notification" data-tone="warning">…same thing…</div>

That is a complete component: seven tones, four variants, five sizes, every
state and both themes, none of which it mentions.

## Slots

--bg --fg --border-color --border-width --border-style --radius --pad --gap
--font-size --weight --line-height --letter-spacing --shadow --transition

A slot splits deciding a value from applying it. Plain CSS does both in one
rule, so every change after that needs another rule that knows the component.
Here a component only fills blanks, `--bg: var(--tone-soft)`, and one shared
rule applies them. A rule like `[data-variant="outline"] { --bg: transparent }`
knows nothing about any component, so it works on all of them, including ones
not written yet. The cost of the system drops from axes times components to axes
plus components.

Every component is painted from these slots and only these. All are registered
`inherits: false` with no `initial-value`, so a component's background cannot
cascade onto its children, and an unset slot stays guaranteed-invalid. That is
what makes `var(--pad, revert-layer)` hand the property back to the UA
stylesheet.

@property --bg { syntax: "*"; inherits: false; }
@property --fg { syntax: "*"; inherits: false; }
@property --border-color { syntax: "*"; inherits: false; }
@property --border-width { syntax: "*"; inherits: false; }
@property --border-style { syntax: "*"; inherits: false; }
@property --radius { syntax: "*"; inherits: false; }
@property --pad { syntax: "*"; inherits: false; }
@property --gap { syntax: "*"; inherits: false; }
@property --font-size { syntax: "*"; inherits: false; }
@property --weight { syntax: "*"; inherits: false; }
@property --line-height { syntax: "*"; inherits: false; }
@property --letter-spacing { syntax: "*"; inherits: false; }
@property --shadow { syntax: "*"; inherits: false; }
@property --transition { syntax: "*"; inherits: false; }
@property --scale { syntax: "<number>"; inherits: true; initial-value: 1; }

Inheriting, registered: --scale
Inheriting, unregistered: --tone --tone-contrast --tone-ink --tone-line
--tone-soft

`--scale` is the only *registered* inheriting property: it is declared
`@property --scale { syntax: "<number>"; inherits: true; initial-value: 1 }`, so
it is type-checked and animatable. `--tone` and its derivations are not
registered at all. They inherit because inheritance is the default for a custom
property. The distinction matters: only a registered property is checked against
a syntax, only a registered property can be transitioned, and only a registered
universal property with no initial value becomes guaranteed-invalid when unset.

## The paint rule

* {
  color: var(--fg, revert-layer);
  background-color: var(--bg, revert-layer);
  border-width: var(--border-width, revert-layer);
  border-style: var(--border-style, revert-layer);
  border-color: var(--border-color, revert-layer);
  border-radius: var(--radius, revert-layer);
  padding: var(--pad, revert-layer);
  gap: var(--gap, revert-layer);
  font-size: var(--font-size, revert-layer);
  font-weight: var(--weight, revert-layer);
  line-height: var(--line-height, revert-layer);
  letter-spacing: var(--letter-spacing, revert-layer);
  box-shadow: var(--shadow, revert-layer);
  transition: var(--transition, revert-layer);
}

One rule reads the slots and applies them to every element. It is safe
universally only because an unset slot is guaranteed-invalid, so `var(…,
revert-layer)` fires and hands the property straight back to the UA stylesheet.
A `<ul>` keeps its indent and an `<h1>` its size. The selector is a bare `*`,
not `:where(*)`: the universal selector already contributes no specificity, so
there is nothing to wrap. Note `background-color`, not the `background`
shorthand, which would also reset `background-image` and the rest of the family.

Universal is also what keeps generated CSS uniform. Because every element is
paintable the same way, "is this element paintable?" is never a question you
have to answer, and a question you do not answer is one you cannot answer
differently twice. Narrow the rule and it becomes a real decision, slots here
and plain CSS there, made fresh for every component; that choice point is where
drift enters. The closed vocabulary depends on it too: CSS has hundreds of
properties and this algebra has fourteen slots, and an element outside the rule
is an element where the only option left is arbitrary CSS. Uniformity then
follows by construction rather than by discipline. Every painted surface goes
through the same slots, so tone, variant, size and theme reach all of it. A
narrowed rule would sort elements into two tiers and produce pages where some
parts follow the theme and some quietly do not. It is also nothing to remember.
An allowlist would have to be carried in this contract and consulted correctly
every time, while `*` costs no tokens and cannot be misremembered.

## Axes

tone: data-tone, inherits
  values: primary secondary success info warning danger neutral
  Tone inherits, and that is the point rather than a convenience: `<section
  data-tone="danger">` re-tones every component inside it with no per-child
  markup. A component never names a colour; it names `var(--tone)` and its
  derivations, and the theme decides what that resolves to.

variant: data-variant, does not inherit
  values: solid soft outline ghost
  Derived from the tone, never a separate colour. It deliberately does NOT
  inherit: with a universal paint rule there is no marker separating a component
  from a bare `<span>`, so a subtree variant would paint every wrapper element
  it passed through.
  
  This axis is optional, and that is worth saying because the other three are
  not. The four variants are *ways of applying a tone*. If a component's
  variations are a surface treatment rather than a tone, say a hairline in
  `--line` over `--canvas`, routing them through `data-variant` will tint the
  border and the label. Write classes instead. Tone, size and state still apply;
  only this one has a premise your component can fail to meet.

size: data-size, inherits
  values: xs sm md lg xl
  A single `--scale` multiplier, not a set of per-size rules. Multiply by
  `var(--scale)` where you set a size and express everything else in `em`, and
  padding follows type for free. This is why a component never needs a size
  variant of its own.

state: (DOM state), from the DOM
  values: :disabled :user-invalid :read-only :focus-visible
  State comes from the DOM and from real HTML attributes. It is not settable
  through the generative-UI manifest and should never be simulated with a class,
  because the browser already knows the answer.

## Layer order

largen.fallback < largen.reset < largen.tokens < largen.paint < largen.tone < largen.elements < largen.components < largen.modifiers

`elements` sits before `components` so a component class beats a bare-element
default; `modifiers` sits last so an explicit variant beats a component's own
default fill. Consumer CSS always wins without `!important` because unlayered
author CSS outranks every layer, and because the element and component selectors
are `:where()`-wrapped to contribute no specificity. The paint rule is the one
that is not wrapped, because a bare `*` is already specificity-free. `fallback`
sorts below everything and exists only for engines that predate `@property`
(Firefox 113–127, Safari 16.2–16.3): behind an engine-sniff `@supports`, it
re-declares every slot to `initial` per element so a slot cannot inherit; in a
conforming engine it matches nothing and the registrations are authoritative.

## Rules

Project-architecture rules — "Two token tiers", "Density and direction are not
axes" — are in `get_contract` section "rules" and at
https://largen.dev/docs/contract.

1. Author inside `@layer largen.components`. Override from outside it.
   Unlayered CSS beats every layer. That is what makes overriding largen work
   without `!important`. It is also exactly what breaks an unlayered
   *component*: it outranks `largen.modifiers`, so `data-variant` silently stops
   applying while tone and size keep working. If a variant "isn't applying",
   check this before anything else.

2. A component sets slots. It does not set colours.
   Write `--bg: var(--tone-soft)`, never `--bg: #fee`, and never `--bg:
   var(--danger)`. A colour literal cannot follow a theme swap, and reaching
   past `--tone*` to a raw semantic token breaks tone inheritance. The component
   pins itself to one colour and stops responding to the `data-tone` on its
   container. `largen verify` enforces both.

3. Never write a dark-mode rule.
   `--tone-soft` and `--tone-ink` resolve against `--canvas` and `--ink`, so a
   theme swap carries every component with it. If a component seems to need a
   dark-mode rule, the algebra has failed to cover something, and that failure
   is the bug worth fixing. A dark rule would only hide it.

4. Never write a size variant.
   Multiply by `var(--scale)` where you set a size, express the rest in `em`,
   and padding follows type automatically. Five hand-written size variants per
   component is the cost the size axis exists to remove.
   
   The rule is about not writing the same component five times. It is not a rule
   about units, and the distinction matters for the shape it appears to forbid:
   a control that shrinks its box while holding its type at one size. `em` is
   what couples padding to type; `rem` is what decouples them. Set `--pad` in
   `rem` and the box stops following the size axis while the type keeps up with
   it. Measured at `data-size="lg"`: padding in `em` grows from 16px to 18px,
   padding in `rem` stays at 12.8px. That is a unit choice inside one component,
   not a size variant.

5. Reach for HTML first.
   `<dialog>` is the modal, `<details>` is the collapse. Both are already themed
   by `largen.elements`. Reimplementing focus trapping or open-state management
   in CSS and JS buys nothing the platform has not already shipped and tested.

6. A coined tag is for a container with no role. Otherwise use the element.
   `<notification>` is fine; `<button-primary>` is not: it claims a role it
   lacks. A coined tag has no role and no accessible name, so assistive
   technology sees a span. largen paints from slots, so `<button
   class="button-primary">` styles identically and keeps the role, focus ring
   and keyboard behaviour. Use the native element, or set `role=`.

7. Never add an `initial-value` to a slot.
   With universal syntax, omitting `initial-value` makes an unset slot the
   *guaranteed-invalid* value, so `var(--pad, revert-layer)` falls back and
   hands the property back to the UA stylesheet untouched. Add an initial value
   and the slot is never unset, the fallback never fires, and the universal
   paint rule resets every element's UA defaults. Every `<ul>` loses its indent
   and every `<h1>` its size. This descriptor is the reason largen needs no
   build step.
   
   One registered property does carry an initial value, deliberately: `--scale`
   is declared `initial-value: 1`. It is not a paint slot, since nothing reads
   it through `var(--scale, revert-layer)`. It is a multiplier that every size
   calculation depends on, so it must always resolve to a number. `largen
   verify` exempts it by name for exactly this reason. The rule holds for the
   paint slots without exception.

## How it fails

Symptom and fix. For why, fetch `get_contract` with section "failureModes", or
read https://largen.dev/docs/authoring

SYMPTOM A gradient set through `--bg` produces no background at all.
FIX Keep the slot and write the gradient beside it: `--bg: var(--tone);
background-image: linear-gradient(…)`.

SYMPTOM Type resizes with `data-size` and the padding around it does not.
FIX Use `em` for a component's own padding. Keep `--space-*` for the rhythm
between things.

SYMPTOM `data-variant` has no effect, but `data-tone` and `data-size` still
work.
FIX Wrap the component rule in `@layer largen.components { … }`.

SYMPTOM A component ignores the `data-tone` on its container.
FIX Use `var(--tone)`, `var(--tone-soft)`, `var(--tone-ink)` or
`var(--tone-line)`.

SYMPTOM Every element on the page loses its browser defaults. Lists unindent and
headings shrink.
FIX Remove the `initial-value`; keep the universal rule inside `@layer
largen.paint`.

SYMPTOM Your own CSS is inside a cascade layer, and largen still wins. Or your
"base" layer beats largen when you meant it to lose.
FIX Declare every layer in one statement, before largen loads, with flat names
on both sides of it:

@layer app-base,
largen.fallback, largen.reset, largen.tokens, largen.paint,
largen.tone, largen.elements, largen.components, largen.modifiers,
app-overrides;

SYMPTOM A fill is the right colour and the text on it is unreadable. It shows
the old tone's contrast colour on the new tone's background.
FIX Set the pair together: `--tone: var(--danger); --tone-contrast:
var(--danger-on)`.

SYMPTOM largen is painting something you want it to leave alone: a third-party
widget, a chart, markup another framework owns.
FIX Set the slot to `initial`: `--bg: initial; --pad: initial`.

SYMPTOM A link is tinted with the tone when it should take the colour of the
text around it.
FIX Set `--fg: currentColor` on the link component. `color: inherit` is
equivalent.

SYMPTOM A component looks right in one theme and wrong in the other.
FIX Route the colour through a token or a `--tone*` derivation.

## Layout utilities

Seven utilities, configured by custom properties the same way components are.
`--gap` is a slot, so the paint rule applies it. Responsiveness is intrinsic:
`switcher` and `sidebar` reflow on the CONTAINER, so there are no breakpoints
and no `sm:` / `xl:` variants to learn.

stack     vertical flow                                                     --gap (1rem)
row       horizontal, does not wrap                                         --gap (1rem)
cluster   horizontal, wraps: tags, icon groups, metadata                    --gap (0.5rem)
center    constrained measure, centred                                      --measure (56rem), --pad
grid      as many columns as fit, no breakpoints                            --gap (1rem), --min-item (16rem)
switcher  a row that becomes a stack below a container width                --gap (1rem), --threshold (24rem)
sidebar   side column plus fluid main, collapses when main gets too narrow  --gap (2rem), --side (16rem), --min-content (50%)

Alignment is attributes, not classes:
`data-align="start|center|end|baseline|stretch"` and
`data-justify="start|center|end|between"`. They are orthogonal, so the utilities
take two attributes instead of a class per combination. Reach for these before
writing `align-items` by hand.

Do not hand-write `display: flex` with `align-items` and `gap`. That is `row` or
`cluster` plus `data-align`, and the hand-written version leaves the algebra.
`--gap` set as plain `gap` is no longer a slot, so nothing can reach it.

## Composing a page

SPACE IS A SCALE, AND THE UNIT CARRIES MEANING

Use `--space-1` … `--space-24` for the rhythm BETWEEN things: section gaps, page
padding, the distance from a heading to what it introduces. They are rem,
because a gap between two sections should not grow when a component inside one
carries `data-size="lg"`.

Use `em` for a component's OWN padding. `--scale` inherits and a component
multiplies its `--font-size` by it, so `em` padding follows: `0.5em 1em` is 7px
14px at `sm` and 10px 20px at `xl`. The same padding as `var(--space-2)
var(--space-4)` is 8px 16px at every size. The type grows, the box does not, and
nothing looks wrong. `largen verify` reports it.

Sections need space between them, not only inside them. Padding a hero does
nothing for the gap after it: `<body class="stack" style="--gap:
var(--space-24)">`. A page whose sections butt together reads as unfinished
however good each section is.

ELEVATION EXISTS

`--shadow` is a slot and two tokens already fill it: `--lift-1` (`0 1px 2px
var(--shade)`) for resting surfaces, `--lift-2` (`0 8px 28px
var(--shade-strong)`) for the one thing you want picked out.

Use it sparingly. If everything is raised, nothing is. A recommended pricing
tier gets `--lift-2`; the tiers either side get `--lift-1` or nothing.

DEPTH: WRITE THE SLOT, THEN THE PLAIN PROPERTY

Atmosphere is usually a gradient, and a gradient needs one extra line because
`--bg` drives `background-color`. Set the slot, then add what has no slot beside
it:

    .hero {
      --bg: var(--canvas);
      background-image:
        radial-gradient(60rem 40rem at 20% 0%, var(--shade), transparent 70%),
        radial-gradient(50rem 40rem at 90% 30%, var(--shade), transparent 70%);
    }

The slot keeps the element inside the algebra, so tone, variant and theme still
reach it. The plain declaration adds the rest. A soft wash behind a large
headline is most of the difference between a page that looks composed and one
that looks unstyled, and it costs two lines.

Two things to get right. Every colour stop is a token: `--shade` and
`--shade-strong` are there for this, and a literal in a gradient is still a
literal that cannot follow a theme. And `--bg: linear-gradient(…)` paints
NOTHING. There is no warning and no fallback; the element silently does not
appear. `verify` reports it.

The same shape covers anything the fourteen slots miss: set the slot for what is
in the algebra, write the plain property for what is not.

THE AXES ARE NOT ONLY FOR COLOURFUL DESIGNS

A restrained or monochrome page is where authors quietly assume the tone axis is
not for them, and then hand-write the variation it would have given free. It is
for them. `--tone` can be `--neutral`; a near-black surface, a hairline and its
text are `--tone-soft`, `--tone-line` and `--tone-ink` whether or not there is a
hue in sight.

The test for tone is not "is this colourful" but "does a group of elements vary
together". If a section, a card and its button should all shift when one
attribute changes, that is `data-tone` on the ancestor and nothing on the
children. Tone inherits, which is the whole reason it is an axis and not a
class.

Size is narrower and it is honest to say so: `--scale` is consumed by
components, not by page layout. A hero or a section has nothing to scale against
and should not pretend otherwise. Reach for `data-size` on the things that come
in sizes, such as buttons, inputs, badges and a compact table, and let the page
around them stay on the rem scale.

TEXT ON A TONED SURFACE TAKES ITS COLOUR FROM THE TONE

A muted grey that reads well on `--canvas` can be almost invisible on
`--tone-soft`, and it lands on exactly the element you most want read: a price
suffix, a caption, a label. On a toned surface use `--fg: var(--tone-ink)` or
`var(--tone-contrast)`. Keep `--ink-muted` for the untoned page.

LOUD IS RELATIVE

If the hero is to be the loudest thing, the rest of the page has to be quiet:
one accent used sparingly, one step between resting and raised, one type scale,
generous and CONSISTENT space.

Detail earns its place. A nav, an eyebrow above the headline, an icon tile or a
ribbon on the recommended tier is fine on its own; all of them together is
noise. Choose two or three.

## Generative UI

`genai/manifest.json` is the approved-component allowlist; `schema.json` and
`prompt.md` are generated from it by `largen gen`. `genai/validate.js` turns a
model-emitted node into an attribute bag and rejects anything else. There is no
field for a colour, class or handler, so the safety property is structural
rather than defensive. The worst a compromised model can do is pick the wrong
approved component. Replace the `components` array with the project's own
components.

- State (disabled, invalid, checked, read-only) is NOT settable here. It comes
from the DOM and from real HTML attributes.

- There is no field for a colour, a class, or inline CSS. The safety property is
structural, not defensive: the worst a compromised model can do is pick the
wrong approved component.

## Commands

npx largen verify [css...] [--entry main.css]   # check your components against the contract, and resolve the cascade across your files
npx largen eval <dir> [dir2] [--entry main.css] [--json]   # score a directory of authored components against the contract, offline and deterministic, with no model
npx largen build   # bundle and minify to dist/ for the CDN. Optional, with no dependencies
npx largen gen   # regenerate genai artifacts from genai/manifest.json
npx largen theme <file.tokens.json>   # validate a DTCG token document against the token vocabulary and emit a theme stylesheet
npx largen tokens <file.css>   # derive a DTCG token document from a project's stylesheet
npx largen manifest <css...>   # derive a component manifest from a project's CSS
npx largen cascade --property P --at CHAIN <css...>   # which declaration wins for a property on an element, and why, with no browser
npx largen slot --slot S --at CHAIN <css...>   # whether the paint rule applies a slot, or it reverts, and to what
npx largen probe --page URL --select SEL --prop P   # emit a browser harness for what static checks cannot see

`verify` lints the files you point it at, or the component stylesheets it finds
under the working directory. A stylesheet is a component file when it declares
inside `@layer largen.components`, or sets paint slots without using a largen
layer at all, which is a component that forgot the layer. Run inside a clone of
largen it also checks the library's own invariants.

`cascade` and `slot` take the element as an ancestor chain written like a
selector: `--at "html body p.prose kbd"`. A chain carries no siblings and no
interaction state, so rules turning on `:hover`, `:last-child`, `:nth-*` or a
sibling combinator cannot be decided from it. Those are reported as undecidable
rather than dropped, because an omission reads as "no rule here" and any one of
them could be the rule that actually wins. `probe` settles those.

`verify` also resolves the cascade across your files when it can work out the
order they load in, inferred from an entry stylesheet or given with `--entry`.
That is the check that catches a component whose declaration is correct, whose
file is correct, and which still never applies because another layer wins.
Without an order it says so rather than guessing.

What it still cannot see is rendering. It has passed clean on visibly broken
components before; render the result in a browser, in both themes.

`build` needs nothing installed. It inlines imports, strips comments and
squeezes whitespace, which is all this stylesheet requires. If your own CSS
wants a real minifier, bring one and point it at your build; largen does not
need one and does not ship one.