Writing a page

Parts of a page

The agent writes an HTML document containing the page's title, description, content, and layout. When the server delivers it, Leaf adds the page identity, visual theme, browser JavaScript, and canonical URL. The browser runtime supplies the commenting and collaboration interface. Authors build the content with these tools, starting with ordinary HTML:

1. Ordinary HTML. Leaf's reading theme, which a page takes by default, styles headings, paragraphs, tables, code, and details without requiring CSS classes. These elements provide most of a page's content.
2. Theme classes. The theme supplies classes for common presentation patterns, including .eyebrow, .lede, .callout, aside.note in a layout-note row for a margin note, and ol.steps for a numbered sequence like this list.
3. Widgets. A widget is a complete page feature, authored as a custom HTML element, such as <lf-options> for choices and <lf-board> for cards in columns. Other lf-* elements provide structure, such as <lf-pane> for a pane. The registry declares each element’s attributes and behavior using JSON Schema. The browser, validator, and agent instructions read those same declarations.
4. Page-specific presentation. A local <style> and inline SVG can define arrangements and drawings specific to the page. They use the theme's shared color and type tokens to stay consistent with the rest of Leaf. The Layout tab's drawings use this approach.

Leaf elements load their JavaScript modules when the page uses them. Behavior specific to one page can use inline module scripts or local modules under page/. Reusable behavior belongs in a package, a directory containing element declarations and their supporting files. The page-behavior reference defines module and dependency rules.

Widgets

These examples are interactive parts of this page. Their choices, card moves, and comments share its event log and Undo; as samples, they ask nothing, so On Me stays empty. Each activity feed shows the same page history, including actions in other examples.

The widget catalog also includes diagrams, charts, diffs with collapsible files, annotated code, editable drafts, playgrounds, and recorded browser traces. The examples gallery opens complete pages using them.

Asking the user

Any widget can ask, whether bundled, from a package or the page’s own, by declaring x-awaits in its registry entry, which names the actions that answer it. To ask about content that asks nothing, such as a paragraph or a chart, or to leave the user a step such as trying a build, the agent opens a thread on that content or the page with a message sent with --obligation, and the user’s reply answers it. Nothing goes On Me that neither a widget nor a thread answers, so no item carries a generic Done, and Leaf adds no answer to a widget beyond those the widget declares.

Each ask joins the user's On Me list until the widget or thread that asks it is answered (On Me and the agent’s list).

Styles and overrides

The user chooses the visual direction. A theme supplies shared colors, type and reusable styles; widget packages draw their own controls; the author arranges the page and makes local adjustments.

flowchart TD
  accTitle: A page captures its selected theme
  accDescr: The author selects Editorial from the user's themes. Leaf captures that theme in the release-review page, and the export carries the same theme. Changing the user's default later changes neither existing copy.
  Themes["User's themes<br/>Editorial · Dense"] -->|select Editorial| Page["Release review<br/>Captured: Editorial"]
  Page -->|export| Export["Exported review<br/>Same Editorial theme"]

For stylesheet roles, cascade precedence and nested widget boundaries, see the CSS contract in Extending.

Layouts

Leaf supplies page layouts and a layout for blocks within a page. A column, sidebar, or workspace sets the page’s shape; tiles arrange a block’s children and can be used within any of them. The table and drawings below show the same classes in the same order.

Leaf's Layout classes are ordinary CSS, applied beneath the page's own stylesheet in the cascade. A page can adjust them with CSS rules, for example to change a column's share of the width or a gap. It can also use its own grid when the supplied layouts do not fit.

The reading column

On a layout-column page, headings, paragraphs, lists, and code occupy a centred column up to 720px wide. On a sidebar page too, the theme limits paragraphs, list items, and headings to that reading width. A workspace applies neither the reading width nor the limits below: every block fills its pane.

A diagram, board, or wide table can extend into the margins beyond the reading column. The text above and below it keeps its width and position. These width settings control the block:

• column is the text measure. In a wider region, such as a sidebar page's body, a column block starts at the same left edge as the text.
• wide starts at the edge the text starts from (the left, in a left-to-right page) and extends toward its end, up to about 910px, enough for 100 columns of code. Wide blocks share this width so they align with one another.
• available uses the window's width after subtracting the outer page margins and space for margin notes and controls.

The registry, which declares each element's behavior, also gives it a default width. For example, lf-options uses column, lf-diff uses wide, and lf-board uses available. A data-width attribute asks for wide or available on any block, overriding the default. If the margins have unequal space, an available block extends farther into the wider margin. A table given one of these widths uses its columns' natural width, up to that limit, rather than stretching across the extra space.

A log, feed, or long listing with data-bound scrolls within a limited height and opens at its newest entry. Its growing content therefore does not make the whole page longer.

Margins

A sufficiently wide window places these controls and notes beside the reading column:

• The rail, on the right, where Leaf places a marker beside each commented or decided passage. It needs a window about 960px wide, or about 1010px on a touch screen.
• A sidebar, an aside beside the body in layout-sidebar. Its authored layout-track holds contents, a legend or reference facts, and stays in view while the body scrolls when both fit beside each other.
• Sidenotes, each an aside.note paired with its passage in a layout-note row, on the right when the row has enough room.

The browser places these compositions as soon as the HTML arrives. In a narrow window, the sidebar stacks in source order and each note follows its passage. Notes never shift the reading column.

Sidebar pages

layout-sidebar on main places the header across the top, with a body and a narrower side column below it. The page fills the window up to 1600px, with an outer margin that grows from 24px to 64px. Its blocks and title share a left edge, while paragraphs still wrap at 720px.

The side column is an aside; placing it before or after the body in the HTML puts it on the left or right. The regions stack in HTML order below about 870px, or when the body's content needs the full width, such as a board with many columns.

For a reading page, give the body layout-column: prose keeps its reading measure while wide exhibits use the remaining room. A section.panel groups a region by its compact heading and spacing, without a surrounding card.

<main class="layout-sidebar">
  <header><h1>Release 4.2 rollout</h1></header>
  <div>…</div>      <!-- body: the work in progress -->
  <aside><div class="layout-track">…</div></aside>
</main>

Examples: Live progress, Triage board, Command hub.

Workspace

layout-workspace fits the page to the window above Leaf's panel. A single-row header holds the title and status tags. The body takes the remaining height and contains an lf-pane, a widget that arranges its own panes, or a grid of panes defined by the page's CSS. Each pane scrolls its content beneath its own header. A pane's footer stays visible, keeping its actions within reach.

An lf-tabs list="side" in the workspace body displays a list of tabs as a queue, such as tickets or findings. The selected item's content appears beside that list.

The workspace fills the window's height when the window is at least 720px wide and 480px tall. In a smaller window, panes expand to fit their content and the whole page scrolls.

<main class="layout-workspace density-working">
  <header><h1>Payments alerts</h1></header>
  <div id="regions">
    <lf-pane label="Queue">…</lf-pane>
    <lf-pane label="Alert">…</lf-pane>
  </div>
</main>

<style>
  #regions { display: grid; grid-template-columns: 1fr 2fr; }
  @media (width < 720px) { #regions { grid-template-columns: 1fr; } }
</style>

density-working reduces type size and spacing for a compact working surface. It is independent of the Layout: a workspace can use ordinary reading sizes, and a pane or table on another page can use working density.

Examples: Notification playground, Merge a worktree, Alert review.

Tiles

layout-tiles arranges an element's children in equal cells at least 9rem wide, placing as many cells in each row as fit. Cells in the same row have equal heights. A page can set its own columns when it needs a particular grouping, such as four tiles in two rows of two. A row of headline numbers can use a layout-tiles block of native dl elements with labels in dt and values in dd.

Tabs and parts

An lf-tabs at the top of a page creates tabs like the ones on this page. Their tab strip stays at the window's top while the page scrolls, and one tab's content is visible at a time. All tabs share the page's width, Layout, threads, and version history.

When different parts of the work need different layouts, lf-parts holds an lf-part for each. Each part contains its own layout container; main itself carries no Layout. For example, one part can hold an interactive workspace and another a proposal read in a column. Parts share the page’s history, threads, and On Me list. The page-layout reference gives the markup.

Narrow windows

In a narrow window, page regions stack vertically in HTML order. Margin notes move into the reading column, a side column appears above or below its body, and workspace panes expand to fit their content. Tiles can still fit two per row on a 390px phone.