The Document Spec v4

Contents

• 1 · Overview
• 2 · Layout grid · placement · spacing
• 3 · Brand
• 3.1 · Colour
• 3.2 · Typography
• 4 · Page
• 4.1 · Section
• 4.2 · Element fields · kinds · 7 types
• 5 · Assets
• 6 · Gaps
• A · Changes from v3
• B · What gets refused

1 · Overview

Architecture

LAYER 1 · AUTHORING

   website-generator      website-extractor      website-builder
   interview a user,      rebuild a captured     a person edits,
   birth a site           site                   on a canvas
   (planned)              (this repo)
           │                      │                     │
           └──────────────────────┼─────────────────────┘
                                  ▼
                              doc.json
                                  │
                                  ▼
LAYER 2 · RENDERING     compile doc.json into HTML — the builder's own engine

Every author writes the same document, and this reference is what an author reads to know what can be said. The layers meet only at the document, so one document serves two goals at once:

The document

{
  "version": 3,             // the builder's counter — this spec, v4, is v3 + Appendix A
  "title":   "…",              // the <title>. A plain field, not a setting
  "grid":    { … },            // §2 — the coordinate system
  "brand":   { … },            // §3 — colours and type
  "assets":  { id: { … } },    // §5 — every file, base64
  "page":    { … }             // §4 — holds sections, which hold elements
}

Depth is fixed: page → section → element. A page holds only sections, a section cannot hold a section, and elements hold nothing. There is no fourth level.

Core concepts

Translating another design system into this document — the principles — lives in docs/adapting.md.

2 · Layout

Where everything sits, how big it is, and how much room is around it. One coordinate system does all three — there is no margin, no padding and no spacing scale. Every diagram in this chapter is a real CSS grid carrying the same values a document would.

hatched — side space, (1600 − 1200) ÷ 2 = 200px each · amber edge — gutter 16px, the minimum side space, binding only below the cap · 800px of screen ≈ 26 rows. gutter is not a column gap — columns have none

left: a hero at real placements — at: [colStart, colEnd, rowStart, rowEnd], rows counted from the section's own row 1 · the stickers are floats: lifted out of collision, so they may overlap · right: the same hero on mobile — derived, not authored: ordered by row, stacked full width, floats ride along (schematic)

grid — the six fields

Placement — at

at: [colStart, colEnd, rowStart, rowEnd]

1-indexed, ends exclusive. It becomes grid-column: colStart / colEnd directly, so the last legal column value is cols + 1 = 25.

There is no gap between columns: space between elements is made by leaving columns empty. Elements may share rows, and an element is as tall as its row span says, not as tall as its content — you place a box; the words go inside it. Whitespace is authored, never injected: "website sections are made of intentional whitespace" — the engine's own rule, and why nothing compacts, on desktop or derived mobile.

Overlap. Two elements whose cells intersect collide, and collision is prevented rather than resolved. To overlap deliberately, lift one out:

Mobile — the derived view

Below 768px the grid is 8 columns, and the desktop at does not carry over — a mobile view is derived from it, and an element that stopped following writes its own mobile.at. derive decides what its box does with the band it is given: stretch fills the width, intrinsic keeps its own size and centres.

Examples

Two-up with a channel. The library's two-up is [1,12] and [14,25] rather than [1,13] and [13,25] — columns 12–13 are the channel. Dashed means columns nobody claimed.

Three-up. Same rule, two channels.

A band narrower than the column. A 1040px band inside the 1200px column wants 1.60 free columns each side; no such placement exists, so it rounds to 2 — 1000px against 1040px asked. Match the free count on both sides; the match is what centres the band.

col_width = 1200 ÷ 24           = 50.00px
side      = (1200 − 1040) ÷ 2   = 80px
          = 80 ÷ 50.00          = 1.60 columns  →  2

at: [3, 23]   20 columns = 1000px, 2 free columns each side

2 + 20 + 2 = 24 columns · centred because the free count matches

Mobile placements, same vocabulary. Full width is [1, 9]; a split is two placements.

the mobile grid · 8 columns

3 · Brand

brand: {
  name:    "…",
  colours: ["#…", …],     // AN ORDERED LIST, not a palette
  variant: 0,             // which curated light/dark pair fills what you left out
  type:    { display, body, scale },
  shape:   { radius, shadow }
}

Shape

shape.radius and shape.shadow are scales — corner rounding and elevation, named once for the whole brand rather than a number per element.

3.1 · Colour

You give an array of hexes. Everything else — section colours, text colours, scrims — is computed from it. The worked example throughout: jennakutcher.com's seven.

brand.colours — what you give

colours: ["#eb6c2f", "#6579be", "#eec3e5", "#f2dc53", "#ffffff", "#f2efe8", "#18161b"]

An ordered list, any length, and you do not assign roles — classification is the builder's. The only thing order decides is which accent leads.

Computed: the six section colours

Chroma splits accents from neutrals; lightness orders the neutrals; anything structural that is missing is filled from a designed light/dark pair (variant picks which). Six surface roles always resolve, and a section background names one of these — only these. Missing accents collapse onto the one before, so the set is fixed while the number of distinct colours is not.

Computed: text colours — four roles, resolved per surface

Text never holds a brand hex. It names one of 4 ink roles — ink-strong · ink-body · ink-muted · line — and the surface it sits on decides the value. Every ink is solved for contrast on its own ground:

What a picker offers, and what the document stores

Button fill can select — the surface roles, deduped (roles resolving to the same colour show one swatch, most general name wins) and context-filtered (a role too close to the band it sits on is dropped — on a canvas band, canvas itself is not offered), then "your other colours", then any hex. Here, for a button sitting on canvas:

Text colour can select — the four ink roles (resolved here on canvas), then your other colours, then any hex:

"Your other colours" holds two kinds, both exactly as typed: the originals of any shifted ground — somebody who typed a colour and cannot find it is looking for precisely that — and the colours no role took. Picking one stores a literal hex.

The colour fields this repo carries beyond this model are listed in Appendix A and are under review — they are not part of this chapter.

3.2 · Typography

Three tiers, one rule: the brand names fonts; a component chooses a slot; an element only deviates. type.display and type.body bind real typefaces to slots. A component layout welds a slot and a rung into its markup — font-display, never a typeface name — which is what keeps a component reusable across brands. An element overrides only where the origin disagrees with what the layout carries.

What the brand defines

Two family slots and a bounded scale. There is no text-[17px]: eight rungs — sm base lg xl 2xl 3xl 4xl 5xl — each a [size, leading] pair, everything above lg a clamp() that tracks the viewport up to the cap.

type = <rung> × (--content ÷ --content-max)   → nominal at the cap, smaller below

Above 1232px nothing grows: the column, the row and every type rung are frozen and the extra width becomes margin. Measured, the ratio of type size to column width is 1.60 at every width from 768 to 2560.

Body type is the exception: fixed at 16px, because fixed rem is what keeps browser zoom working. That is also why rowMin exists — a proportional row eventually cannot hold a fixed 16px line.

Recurring treatments are named once in brand.type.styles; more than two families needs brand.type.families, and shipping the files needs brand.type.faces — all marked v4 in the table above.

brand.type.styles: {
  "heading-2": { "category": "heading", "family": "display", "weight": "normal",
                 "size": "2xl", "tracking": "normal", "leading": "1.2", "transform": "normal-case" }
}

A flat map. Each style carries a category — heading, paragraph, label, stat, mono — for grouping and matching, and states its six axes fully: nothing is inherited from a group.

How a component or an element uses it

A text layout is a role — a title, an eyebrow, a quote — and carries its rung: pick the layout and the size comes with it. When the origin disagrees with what the layout carries, element.typography v4 overrides it:

4 · Page

page: { id, type: "page", kids: [ …sections… ] }

The root container, and the thinnest thing in the document. It holds sections and nothing else — an element directly on the page is refused. It carries no settings and no background, because every section paints its own and no page ever shows through.

title lives on the document rather than here: a <title> is not HTML content, and no setting kind fits it.

Its pieces: sections, and the elements inside them.

4.1 · Section

A band of the page. It carries a category — what it is for — and a layout — how it is arranged. Matching and migration read the category; the layout only decides where things sit.

Its own settings

The background bleeds; the content does not

┌───────────────────────────────┐
│  background — edge to edge    │   ← settings.background, settings.image
│  ┌─────────────────────────┐  │
│  │  content — grid width   │  │   ← the 24 columns live here
│  └─────────────────────────┘  │
└───────────────────────────────┘

settings.image renders as .sec-media — position:absolute; inset:0; object-fit:cover — outside the content grid. So a section ground is genuinely full bleed at any width. An element placed on the grid never is.

Categories, and the slots each is built around

A slot with nothing to put in it is left out. A piece of content with no slot to go in is a gap — worth recording, not worth forcing.

Every section layout

Section fields v4

4.2 · Element

One thing on the page: placed on the grid, holding its settings, containing nothing. Page, section and element are all written as the same record shape — id, type, then whatever applies. The fields below are the element's own; layout, tree and settings also appear on sections.

Fields

Setting kinds — nine, and this is the whole list

A setting's kind decides what a panel draws and what validation accepts.

Components

7 element types, 34 layouts. A type is a data contract; a layout is markup plus defaults. Adding a layout touches no schema and no document.

Authored size and min are in grid cells; the pixel figure beside them is what that resolves to with content at the 1200px cap.

Primitives — edited on the canvas

Composites — edited in a panel

Pieces held together so they cannot drift apart, edited in a panel because a composite has no single caret position. The split is the registry's own opaque flag.

5 · Assets

Every file the document uses, inline as base64.

assets: { "<id>": { type: "image/jpeg", data: "<base64>", name: "source.jpg" } }

Referenced from a setting as asset:<id>. A reference that does not resolve is a validation error, so a document cannot ship a broken image. Never a URL — a document pointing outward renders differently the day that URL rotates.

6 · Gaps

What the vocabulary cannot say. Every entry came from failing to express something during a real rebuild — that is the only way onto this list. Per-site evidence lives in sites/<host>/gaps.md.

Appendix A · Changes from v3

v4 is the builder's v3 model plus the fields below, every one produced by rebuilding a real site. Each is a new field beside the old ones, never a rewrite of one, and never a setting — the validator refuses an undeclared setting by name. A v4 document still validates in the builder, and --no-extensions renders the v3 view.

Appendix B · What gets refused

validateDocument runs the same checks the builder's Import runs. A document that fails here cannot be opened, however good its screenshot looks. Binary — there is no partial credit.

bun doc:validate --doc=sites/<host>/doc.json