Install

pnpm exec vegastack-design verify document-layout

pnpm dlx shadcn@4.21.0 add @vegastack/document-layout

Usage

import {
  DocumentLayout,
  DocumentLayoutBody,
  DocumentLayoutContents,
  DocumentLayoutFoot,
  DocumentLayoutHeader,
  DocumentLayoutIcon,
  DocumentLayoutMargin,
  DocumentLayoutTitle,
  DocumentLayoutTitleGroup,
} from "@/components/ui/document-layout";

<DocumentLayout margin={threadCount > 0 || drafting}>
  <DocumentLayoutHeader>
    <DocumentLayoutTitleGroup>
      <DocumentLayoutIcon>📘</DocumentLayoutIcon>
      <DocumentLayoutTitle>Pricing v2</DocumentLayoutTitle>
    </DocumentLayoutTitleGroup>
    <MetaLine>
      <MetaLineItem>Updated 3m ago</MetaLineItem>
    </MetaLine>
  </DocumentLayoutHeader>
  {outline.length > 1 ? (
    <DocumentLayoutContents>
      <TableOfContents
        variant="rail"
        side="start"
        sticky={false}
        items={outline}
      />
    </DocumentLayoutContents>
  ) : null}
  <DocumentLayoutBody>
    <MarkdownView typeScale="document">{markdown}</MarkdownView>
  </DocumentLayoutBody>
  <DocumentLayoutFoot>{pagesInside}</DocumentLayoutFoot>
  <DocumentLayoutMargin>{threads}</DocumentLayoutMargin>
</DocumentLayout>;

DocumentLayout is the frame of a page people read and write as a document — a wiki page, a spec, its public view and a version's full view all wear the same one. The text column is fluid: about three quarters of the layout's width, between bounds that grow with each tier, so a large monitor gets a generous column rather than a narrow strip. The title area sits above the text and what follows it — sub-pages, the page's own comments — below, in the same column. Before the text, in its gutter, a contents rail; after it, when there is room, a comment margin.

The layout follows its own width, not the window's (container queries in rem), so a collapsed sidebar or a split view lands in the right tier:

At the document type scale (14px Geist) that is about 94 characters a line at M's 36rem, 128 at L's 52rem, 150 at XL and 161 at 2XL; the 24px line height carries the longer lines.

The tier bounds are the system's layout tiers — tablet 40rem, laptop 64rem, wide 90rem (LAYOUT_TIERS in page-layout) — plus a document-only 120rem step.

The rail, the text and the margin are one block, centred, and the text stays in the middle when the comment margin shows: the start side widens to mirror the margin, so wherever the width can hold the margin on both sides the text sits exactly where it sat without comments. With less room the start side gives way first, and the margin shifts the block towards the start only by what is missing; the text narrows only when the width cannot hold the text, the margin and the gutters at once.

It is one subtree at every width: a column with no room is display: none, never unmounted, so an editor inside never remounts when the window resizes. margin shows the comment column from L up; set it only while the column holds something (open threads beside the text, or a comment being written), decided with the text so the first paint is right. A page's first comment keeps its text in place while there is room for the margin on both sides. From M up the grid keeps its start gutter whether or not a page has headings, and DocumentLayoutContents sits in it, stacked above the text and the margin: a TableOfContents variant="rail" side="start" there is a slim column of dashes that opens into the labelled list over the text — so headings that arrive (or go) never move the text, and the open list takes the pointer wherever it lies. Put the parts in reading order — header, contents, body, foot, margin. Server-safe: the tiers are CSS.

Anatomy

Examples

Wide

measure="wide" gives the text the whole width less the gutters (and the margin, where it shows), up to 75rem (1200px), past which a line is too long to read — each reader's choice, never the document's.

Aside

aside gives the layout a rail after the text: "discussion" (the comments) or "outline" (the contents), and null while it is closed. A layout with an aside — even null — keeps the end track for it from the L tier, so opening or closing the rail never moves or narrows the text; in wide the text and an open aside share wide's min(100%, 1200px) block — the text keeps its start edge and gives the aside its end. Put a DocumentLayoutAside of each kind in the layout and the one aside names shows:

• Discussion — a non-modal rail as tall as the window: the heading with its count, a × (onClose), and tabs such as Open · Resolved · Page, plus Review while a review is open, each with an optional count. The page stays readable and editable beside it. It takes the comment margin's place, so pass CommentMargin quote={false} for the cards beside the text and keep the quote in the rail. Below the L tier it is a bottom sheet instead, the whole screen below 640px.
• Outline — the contents list, pinned from the XL tier while the discussion is closed; below XL the contents rail's hover ticks stay.

Leave aside unset and nothing changes: the margin and the rail behave as before.

<DocumentLayout
  aside={discussion ? "discussion" : wideScreen ? "outline" : null}
>
  …
  <DocumentLayoutAside
    count={open.length}
    onClose={() => setDiscussion(false)}
    tabs={[
      {
        value: "open",
        label: "Open",
        count: open.length,
        content: <OpenThreads />,
      },
      { value: "resolved", label: "Resolved", content: <ResolvedThreads /> },
      { value: "page", label: "Page", content: <PageThread /> },
    ]}
  />
  <DocumentLayoutAside kind="outline">
    <TableOfContents items={outline} sticky={false} />
  </DocumentLayoutAside>
</DocumentLayout>

Title

DocumentLayoutTitle is the document type scale's top step: 30/36 semibold in the heading face, one step above the text's # (24/32). DocumentLayoutTitleGroup holds an optional DocumentLayoutIcon over it, 4px apart: an emoji at the title's size, or the control that changes it. reveal hides an "Add icon" control until the title group is hovered or holds focus (always shown on a coarse pointer). The row is 32px whatever it holds, so showing, adding or removing an icon moves nothing.

<DocumentLayoutTitleGroup>
  <DocumentLayoutIcon reveal>
    <Button variant="ghost" size="xs">
      <SmilePlus aria-hidden />
      Add icon
    </Button>
  </DocumentLayoutIcon>
  <DocumentLayoutTitle>Pricing v2</DocumentLayoutTitle>
</DocumentLayoutTitleGroup>

Meta lines

DocumentLayoutMeta is a line of small facts under the title — who updated the page, where it came from, what links to it. Each DocumentLayoutMetaItem opens with a ·, and the row is drawn one dot's width to the start of a clipped box, so a wrapped line never starts (or the line before it ends) with a stray dot. An item takes an icon, and nowrap keeps a fact built around a link on one line (the link truncates); DocumentLayoutMetaButton is a fact that opens something ("Used in 2 tasks") and DocumentLayoutMetaLink a fact's link (render takes the router's link).

variant="status" is the status row: one reserved line from sm and two on a phone, from the first paint, so chips that stream in move nothing. Group its facts: a DocumentLayoutMetaGroup (kind="unit") stays together — a DocumentLayoutMetaField ("Owner Sanjay") and its chip, wrapping inside only when even the chip's short form doesn't fit — and a kind="flow" group of flags flows with the row from sm; on a phone each group is a whole line. A DocumentLayoutMetaBadge with label and short keeps all its words while the row has room; on a tight row the chips drop to their short forms, the longest first (the whole label stays in the chip's tooltip), and only if those don't fit either does the row wrap. Pass what the chips say as watch, and DocumentLayoutMetaSkeleton while they stream in.

<DocumentLayoutMeta variant="status" watch={[status, review]}>
  <DocumentLayoutMetaGroup>
    <DocumentLayoutMetaField label="Owner">
      Sanjay Desai
    </DocumentLayoutMetaField>
    <DocumentLayoutMetaBadge
      variant="success"
      label="Verified · Oct 14"
      short="Verified"
    >
      <BadgeCheck data-icon="inline-start" aria-hidden />
    </DocumentLayoutMetaBadge>
  </DocumentLayoutMetaGroup>
  <DocumentLayoutMetaGroup kind="flow">
    <DocumentLayoutMetaItem>
      <DocumentLayoutMetaBadge variant="warning">
        2 out of date
      </DocumentLayoutMetaBadge>
    </DocumentLayoutMetaItem>
  </DocumentLayoutMetaGroup>
</DocumentLayoutMeta>

Where the contents rail has no room (the S tier), DocumentLayoutContentsButton is a round "On this page" button floating at the window's bottom end — give it to TableOfContents as its trigger. DocumentLayoutTitle takes editable when the title renames in place (the text cursor over the whole row).

Page tools

The tools a page lays over or around its text, each without a class of your own:

• DocumentLayoutFindBar — find in the text: a search field docked at the top of the text on a band of the page's background, with where the find stands ("3 of 12") and Previous, Next and Close (Enter, Shift+Enter, Escape). The host finds the matches; pass highlights (two CSS Custom Highlight names) and the bar paints them.
• DocumentLayoutJumpCue — "2 new comments ↓", a pill pinned to the bottom of the view while something new is out of sight; it takes no room.
• DocumentLayoutFloatingButton — a phone's one floating action ("Edit"), at the window's bottom end, clear of the home indicator.
• DocumentLayoutStarters with DocumentLayoutStarter pills — ways to start an empty page ("Start from: Meeting notes · Spec · More templates…"; more for the quiet last one).
• DocumentLayoutNote — a quiet line under the text.
• DocumentLayoutDecisionBar with DocumentLayoutDecisionBarText and DocumentLayoutDecisionBarActions — a decision the reader owes the page ("Asha asked you to review this page · Approve"). Put it first in DocumentLayoutBody: it sticks under the top bar while the text is in view, and on a phone floats at the bottom with the floating buttons above it.
• DocumentLayout focusable — the canvas takes focus from a click in its read text (never a tab stop) and shows no focus cue of its own.

Sections, pages and live blocks

What a document holds besides its prose, again without a class of your own:

• DocumentLayoutSection — a section at the foot ("Pages inside"), named by its DocumentLayoutSectionTitle (count follows it in the muted ink: "Pages inside · 3"), its title row a DocumentLayoutSectionHeader with an action at the end. DocumentLayoutSectionButton is its quiet button: look="more" loads the rest ("Show more pages", "Load earlier"), look="add" is the one line an empty section shows to someone who can fill it. DocumentLayoutSectionSkeleton holds its place while it loads.
• DocumentLayoutPageList with DocumentLayoutPageItem rows — the pages under a document, ruled above, between and below. DocumentLayoutPageLink is a row's target: its emoji (icon, a page icon without one), name, one-line excerpt and meta, the whole row the link; a ⋯ menu follows it in the item.
• DocumentLayoutBlock — a live block drawn into the text (a task list): a card with a DocumentLayoutBlockHeader (DocumentLayoutBlockTitle, a ghost button at the end), then DocumentLayoutBlockRows of DocumentLayoutBlockRows (DocumentLayoutBlockRowMain with a DocumentLayoutBlockRowRef, then DocumentLayoutBlockRowMeta, which wraps under the main line below 640px), or a DocumentLayoutBlockNote ("No tasks match") or a DocumentLayoutBlockSkeleton, and a DocumentLayoutBlockFooter. DocumentLayoutBlockAction is the link-styled action inside it (Try again, Open in Tasks →). A block of a table's records shows them as a DocumentLayoutBlockTable (columns, the name column first): a DocumentLayoutBlockTableHead row of DocumentLayoutBlockTableColumns, then a DocumentLayoutBlockTableBody of DocumentLayoutBlockTableRows of DocumentLayoutBlockTableCells (primary on the name column's, a row header). It is read-only, every row's columns line up, and it scrolls sideways when its columns don't fit.

Skeleton

DocumentLayoutSkeleton is the page's loading state on the SAME grid and tier — an icon row (icon), a title line, metaLines meta lines (default 1) and paragraphs of text bars at the document line pitch (a 14px bar every 24px, 16 every 26 on a coarse pointer), 12px between paragraphs — so nothing moves when the page arrives. Pass it the margin, measure, icon and metaLines the page will have. It is one status region, named by label.

The tier in script

Branches CSS cannot take — comments in the margin or in a popover, the contents on the rail or in a menu — read the tier with useDocumentLayoutTier(ref). It reads --document-layout-tier, which the container queries set, so script and stylesheet never disagree about where a tier starts. fallback (default "xl") is the answer on the server and before the first measurement.

import { useDocumentLayoutTier } from "@/components/ui/document-layout";

const ref = React.useRef<HTMLDivElement>(null);
const tier = useDocumentLayoutTier(ref);

<DocumentLayout ref={ref} margin>
  …
  {tier !== "s" && tier !== "m" ? (
    <DocumentLayoutMargin>{threads}</DocumentLayoutMargin>
  ) : null}
</DocumentLayout>;

Print

A document prints as one column of its header, body and foot — the contents and the comment margin drop out — on a named page with a 16mm × 14mm paper margin, in the light palette whatever the reader's theme. With typeScale="document", MarkdownView and TextEdit add the text's own print rules: code wraps, tables print in full, highlights and controls drop out, and an external link prints its address.

API Reference

DocumentLayoutHeader, DocumentLayoutTitleGroup, DocumentLayoutBody and DocumentLayoutFoot take a div's native props, DocumentLayoutTitle an h1's; DocumentLayoutContents and DocumentLayoutMargin take an aside's. What the contents hold sticks --document-layout-sticky-top (default --spacing(8)) below the top of the scroll container. The discussion rail sticks there too, as tall as the window less --document-layout-aside-offset (default --spacing(24): the bar above and the offsets). DocumentLayoutAsideTab is { value, label, count?, content }.

Accessibility

• The contents and the margin are two aside landmarks, named "Contents" and "Comments" (override with aria-label). Below their tier they are display: none, so they leave the accessibility tree with the screen.
• The aside is an aside landmark named by its title ("Comments", "On this page"); its tabs are a Base UI tab list named the same, and the × is a "Close" button. It is non-modal: focus stays where the reader puts it, and the page beside it keeps working. Below L the discussion is a modal bottom sheet with its own close.
• Source order is reading order: the title area, the contents, the text, what follows it, then the comments — whatever the columns look like.
• The skeleton is one status region named "Loading page" with aria-busy; its bars are hidden.

Do / Don't