Skip to content
Polytope

Space and layout

A 4px base, one reading column, heavy rules between regions, and square corners everywhere except on balls.


In this chapter 7 pages

Spacing scale

Use the scale for every margin, padding, and gap. Tight inside a group, generous between groups.

  • --ply-space-00
  • --ply-space-10.25rem
  • --ply-space-20.5rem
  • --ply-space-30.75rem
  • --ply-space-41rem
  • --ply-space-51.5rem
  • --ply-space-62rem
  • --ply-space-73rem
  • --ply-space-84rem
  • --ply-space-96rem
  • --ply-space-108rem

Page frame

  • Side margin --ply-layout-gutter: 16px on phones, growing to 72px.
  • Reading column --ply-layout-measure: 36rem, about 68 characters of body text. On a docs page, examples and .ply-wide blocks may run wider; in an article, everything outside the margin keeps to it. From 100rem, docs and article pages set their text at 18px in a 38rem column (--ply-layout-measure-wide), which holds the same number of characters.
  • Docs pages add a chapter sidebar from 56rem, with the on-this-page list under the current page. The text sits at the centre of the page once there is room for the sidebar beside it.
  • The page mast splits into title and exhibit from 64rem, when it has an exhibit; below that, the exhibit stacks under the title. A mast without one, as on a list page, keeps the whole width for its title. <Mast compact> sets a smaller title, for a list page under the chapter landings. For a mast you lay out yourself, such as an Atlas head, <MastTitle title="..." /> writes the title with its full stop, sized to its longest word.
  • Sidenotes and margin figures move into the margin (--ply-layout-margin, at least 14rem) when the main column (container ply-main) has 52rem: the measure, a 2rem gap, and the margin. There the margin widens with the page, up to 21rem, so notes end at the page's edge. Outside a ply-main column, they move there from 90rem, 14rem wide.

Articles

.ply-article is the frame for a paper, a post, or a page of notes. The text sits at the centre of the page. The on-this-page list hangs in a rail at the left edge, and the margin after the text holds sidenotes and margin figures. A header in an .ply-article--head of its own starts at the same edge as the text. The paper and post patterns use it.

html
<div class="ply-container ply-article ply-article--head">
  <div class="ply-article__main"><header class="ply-paper">...</header></div>
</div>
<hr class="ply-rule" />
<div class="ply-container ply-article">
  <div class="ply-article__rail">
    <nav class="ply-toc" data-auto aria-label="On this page">
      <p class="ply-toc__heading">On this page</p><ul></ul>
    </nav>
  </div>
  <div class="ply-article__main" data-toc-scope>
    <div class="ply-prose ply-has-sidenotes">...</div>
  </div>
</div>

In plain HTML, js/toc.js fills the list from the headings. In Astro, <Article> writes the same markup and builds the list from your h2 and h3 headings at build time, so it is there without JavaScript. Pass toc={false} to drop the list.

astro
<Article>
  <PaperHeader slot="header" title="..." authors={authors} />
  <h2>1. Introduction</h2>
  <p>...</p>
</Article>

A block in an article sits in one of two lanes, and no block straddles the edge between them. Readers take that edge for a column line, so a block that crossed it would read as a mistake.

LaneForHow
TextParagraphs, equations, figures, tables, and code.The default. A table with many columns or code with long lines scrolls in its own frame.
MarginSidenotes, and a small figure, table, or code block beside its paragraph.<Sidenote>; .ply-margin on a child placed before the paragraph, or <Figure margin>.

.ply-wide and <Figure wide> keep to the text in an article. On a docs page, where nothing hangs beside the text, they run a block on to the page's end edge.

  • Below 60rem the article is one column. Sidenotes and margin blocks drop under their paragraph.
  • From 60rem the margin opens after the text, and the text moves toward the centre as the page widens.
  • From 80rem the rail opens at the left edge and the text is centred on the page. Below that, the same list waits in an "On this page" disclosure above the text.
  • A section heading starts below any sidenote or margin figure still beside the text, so a note never sits beside the next section. Keep notes short; a long one leaves a gap in the text.

Space around things

Empty space is for a single focus. Around one central element, such as a paper title or a mast, it draws the eye. On a page that shows many elements side by side, such as a home page, a list, or a wall, an empty region reads as a gap, so it holds content: a block moves into it, a column widens, or a body sets in two columns. A card grid keeps three tracks at wide widths (.ply-cards--tracks) so a row never leaves one empty, and a wall's body splits into a description and a list (.ply-wall__body--split).

On a page with many parts, space that separates nothing comes down a step or two. Rules, panels, and display type do the grouping. A dense mast pads 2rem under its title, and a dense compact mast pads --ply-space-6 above it and --ply-space-5 below. .ply-cards--dense sets card rows as far apart as the columns. The sections after a mast carry their own 3px rule as the divider, and a long list of projects sets compact rows on a phone.

Two edges

A page has two edges. Labels (titles, years, topic names) start at the first, and everything they label starts one column in, at the width of an article's rail (--ply-layout-toc). Every wall, list, and home section uses the same label column, so the content of all of them starts on one line down the page.

List pages and entry pages

A list page sets its lede as wide as a title line, up to 52rem, and balances it, so a sentence a little longer than the measure never leaves one word on a line. An entry page (a paper, a post, a project) sets its title to its own column with a container query, and its lede keeps the reading measure.

html
<p class="ply-mast__lede ply-mast__lede--wide">Papers, newest first, with the topics they belong to.</p>

Mast takes these as props, so a list page is one line: wideLede sets that lede, and rule closes the mast on a 3px rule.

astro
<Mast title="Publications" lede="Papers, newest first, with the topics they belong to." compact wideLede rule dense />

PostHeader serves an entry page that has no date, such as a project: meta takes the facts for its meta line, stop ends the title in the tomato full stop for a page that is a section, and the default slot sits under the tags for actions.

astro
<PostHeader title="StapleGL" meta={["Open source", "2025"]} lede="A plotting library.">
  <a class="ply-button" href="https://github.com/...">Source</a>
</PostHeader>

A mast with its exhibit beside it

A home page puts its exhibit beside the title from 48rem, where Mast waits for 64rem. side sets the exhibit in a column of at most 35rem and 40% of the mast, and stacks it under the title at 24rem or less, on the content edge, below that. The left column runs the exhibit's height, and what is in the mast's after slot closes on the line where the exhibit's caption does, so a list such as DatedList fills the column and leaves no gap under the title.

astro
<Mast title="John Doe" lede="PhD student." dense side>
  <div slot="after"><a class="ply-button" href="/cv/">CV</a><DatedList items={latest} /></div>
  <Complex slot="exhibit" seed={7} autoplay="visible" />
</Mast>

Enlarged text and narrow windows

Layouts are built for 200% text-only zoom at 320px with the real copy in them, and at that size nothing scrolls sideways. Below 30rem, which is 960px at 200% text, these hold:

  • Titles (.ply-card__title, .ply-title, the paper, post, and mast titles, and their .ply-nowrap parts) may break inside a word.
  • Inline math wider than its paragraph scrolls inside itself.
  • The Atlas's list, stops, and filter stay inside the column, and the filter scrolls in its frame.
  • The top bar wraps to a second row once its tabs have folded into the menu. While tabs show, the bar stays on one line: a wrap would give the tabs a row of their own, and topbar.js would measure them as fitting. The wordmark may break inside a word, and the tools wrap at their end edge.

Test a new layout at that size before adding anything new to this list.

Touch targets

A small link row is 24px tall on a fine pointer and 44px under pointer: coarse. That covers tabs, small buttons, the skip link, link tags, the link rows of cards and publications, the Atlas filter, and sidebar and on-this-page links. A title that runs as text grows its target with padding and an equal opposite margin, so the lines stay where they are. Links inside running text keep their own size. For a link of your own, .ply-target does the same as Polytope's controls.

Rules and borders

TokenWidthUse
--ply-border-rule3pxBetween page regions: under the top bar, above a pager, at the top of a table.
--ply-border-control2pxButtons, inputs, table header rules.
--ply-border-hair1pxRows, list separators, swatch outlines.

A site spends retro once. The example is a section rule whose end climbs in three 3px pixel steps, as a bar on an Atari screen does, set on the rules inside the content width and left off the full-width rule under a mast. Mono labels and one-bit art are the other retro marks a site may use.

Corners

Panels, buttons, inputs, tags, and code blocks are square, like exhibit labels cut from board. Only round things are round: balls, points, radio buttons, status dots.

Layout helpers

.ply-stack stacks children with a gap, .ply-cluster wraps them in a row, .ply-grid makes responsive columns from a minimum width. Each reads a custom property for its gap (--ply-stack-gap, --ply-cluster-gap, --ply-grid-gap).

In a .ply-cluster of buttons, a ghost button draws its padding into the gap before it, so its word lines up with the row's edge when it wraps to a new line, as a filled button's box does.

Polytope's own controls grow to 44px targets under a finger (pointer: coarse). Give a link or button of your own that stands alone the class .ply-target to do the same.

Light and dark twins

A picture drawn for each theme takes .ply-light-only on one and .ply-dark-only on the other. The one for the theme in use shows: the switch's choice first, then the system's. Paper shows the light one. Do not set display on either element, since a rule that outranks the utility would show both.

This text shows in the light theme.This text shows in the dark theme.

HTML
<p><span class="ply-light-only">This text shows in the light theme.</span><span class="ply-dark-only">This text shows in the dark theme.</span></p>

Titles of your own

<WoodTitle title="..." /> is the title the paper and post headers use, for a header of your own, such as a project page's: about 22 characters to a line, longer lines for a long title, never so big that its longest word breaks, with split for a subtitle and stop for the tomato full stop. It sizes to the nearest container, so give its header container-type: inline-size. The helpers it uses, woodTitle, splitTitle, and emWidth, come from @dario-loi/polytope/astro.