Pages and interface

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 styles headings, paragraphs, tables, code, and details without requiring CSS classes. These elements provide most of a page's content.
2. Theme classes. Leaf supplies classes for common presentation patterns, including .eyebrow, .lede, .callout, aside.sidenote 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, Undo, and On me. 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.

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, the page's first aside.sidebar, on the left. It holds a table of contents, a legend or reference facts, and stays in view at the window's top as the page scrolls. It needs about 1130px.
• Sidenotes, each an aside.sidenote, on the right, level with the block they annotate. They need about 1150px.

The column shifts sideways to make room for a sidebar or sidenotes. In a narrow window, those notes appear within the column at their original positions in the HTML.

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, and uses a larger title than a column page. 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.

A side column made by layout-sidebar is part of that layout's content area. An aside.sidebar instead places a note in the margin of a column page. 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>…</aside>  <!-- side column: status, counts, contents -->
</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.

Panel, rail and thread cards

Leaf adds controls around the authored HTML. This interface is called chrome: the Leaf panel floating at the window's foot, comment and decision markers, and thread cards. At rest the panel is one row: the leaf, coloured by the agent's state; the comment field, which shows the agent's status while it is empty; and the On me mark, counting what waits on the user, with a dot while a thread holds a reply they haven't read. The leaf opens a small menu of the page's other controls. Pressing the On me mark opens its view above the row. A ✕ replaces the mark while the view is open and closes it when pressed. A folded panel shows only the leaf in the window's corner.

The On view shows one list at a time, under a tab named for its actor, with completed items under Done, and a Threads tab listing the open threads, then the resolved ones under Resolved. On me and the agent’s list defines their membership. Opening a view preserves the page’s text wrapping and reading position.

The page reserves space at the bottom for the panel's row, so the last lines can scroll above it. A view opens above the row and overlays the page without moving its content. Escape or a press on the page closes the view. Phones and touch screens describes the panel on a touch screen.

The rail is the strip to the right of main where Leaf places comment and decision markers. It appears when the window has enough space: about 960px on a column page or about 1920px on a sidebar page. data-rail="right" keeps it visible above 640px, except on a workspace, whose panes scroll on their own. Where no rail fits, and inside a scrolling pane, a small pin appears beside the target on the page. Leaf places it clear of text and controls when space permits. The o shortcut hides pins and passage highlights.

A thread card opens beside its marker in the margin. If the margin is narrower than the card, it overlaps the text's edge. Threads, a thread opened from it, the On view and All pages open as views above the panel's row, one at a time.

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.

Navigation

Leaf's shortcuts act where focus is. A thread, its passage and its margin card count as one place. Text fields keep typing and caret movement; native controls keep their activation keys. Escape leaves one interaction, browser Back returns to a reading place, and Undo withdraws a recorded action.

? opens the command reference for the current context; menu rows show their own shortcuts. On touch screens, use thread titles, markers, Page Map and the leaf’s menu. The movement rules distinguish walks that wrap from lists that stop.

Named destinations and visible hints

Reading and text search

Threads and work waiting on the user

t / Shift + t walk open threads in page order. Focus on a thread or its accompanied passage makes that thread the origin. Moving elsewhere changes the origin; Leaf keeps no separate “last thread” cursor.

Resolving and replying

r resolves the focused open thread. A thread opened from Threads advances to the next open thread in page order, or the previous at the end; with none left, it returns to the list. A margin card returns to its passage. An embedded thread folds in place.

Panels and Escape

Back and Forward

A successful navigation step to a destination that is not fully readable adds a return stop. Consecutive navigation steps form a navigation group and share that stop while part of the preceding landing remains visible and the user has not clicked or Tabbed onto another passage. Back returns to the navigation group’s start. A fully readable destination adds no stop.