Skip to content

Layout and Spacing

Jump to bottom
Karthik P edited this page Nov 3, 2026 · 2 revisions

Layout and spacing

This page covers the spacing scale, corner radii, border widths, breakpoints and content widths, the three-column documentation layout, and the rules for alignment, density and shadows.

Last reviewed: 1 Nov 2026

What this is and why it matters

Consistent spacing and a familiar page structure make a site easier to scan and, according to the research, more credible: simple, conventional layouts were judged more trustworthy than novel ones in experiments (trust research, rule R2). fiscalclock therefore uses the same three-column layout as the documentation sites it was compared with, and takes every gap, width and corner from a short list of design tokens. No website exists yet (DD-009), so the values are settled but much of how they are applied is Proposed; each such rule is marked.

Terms used on this page

Term Meaning
spacing scale The fixed list of gaps a design may use, for padding and margins.
radius How rounded a corner is, in pixels. 0 is square.
breakpoint A minimum screen width at which the layout changes.
viewport The visible area of the browser window.
gutter The empty margin between the content and the edge of the viewport.
text column, prose column The column that holds the article text.
"On this page" The list of the current page's headings, usually on the right; also called a table of contents (TOC).
density How much content fits on a screen: dense layouts have small gaps, airy ones large gaps.

More terms are on the Design-Glossary.

Spacing scale

Every step is a multiple of 4 px (primitives.tokens.json: "A 4 px scale"). Use only these values for padding, margins and gaps.

Token CSS custom property Value Typical use (Proposed)
space.0 --fc-space-0 0 Removing a default margin
space.1 --fc-space-1 4 px Between an icon and its label
space.2 --fc-space-2 8 px Inside small controls; between list items
space.3 --fc-space-3 12 px Padding of buttons and table cells
space.4 --fc-space-4 16 px Between paragraphs; padding of code blocks and callouts
space.5 --fc-space-5 24 px Above a third-level heading; between a figure and its caption block
space.6 --fc-space-6 32 px Above a second-level heading; gap between page columns
space.7 --fc-space-7 48 px Between major sections
space.8 --fc-space-8 64 px Top and bottom of a page
space.9 --fc-space-9 96 px Landing-page sections only

Corner radius

Token CSS custom property Value Use (Proposed)
radius.none --fc-radius-none 0 Tables and diagrams, whose boundaries are exact lines (domain-visuals research, shared rule 1)
radius.sm --fc-radius-sm 3 px Inline code, small labels
radius.md --fc-radius-md 6 px Code blocks, callouts, menus, buttons
radius.lg --fc-radius-lg 8 px Buttons and inputs on the website (DD-042)
radius.xl --fc-radius-xl 12 px Raised panels on the website, such as the landing page's date lookup (DD-042)
radius.full --fc-radius-full 9999 px Fully rounded ends, such as a toggle switch

Border widths

Token CSS custom property Value Use
border-width.thin --fc-border-width-thin 1 px Dividers and the edges of raised surfaces (Proposed)
border-width.thick --fc-border-width-thick 2 px The keyboard focus outline (design/tokens/README.md; Accessibility)

Colours for borders are color.border.default (decorative) and color.border.strong (meaningful, at least 3:1); see Colour-System.

No shadows

fiscalclock uses no drop shadows (DD-019). A surface that sits above the page, such as a menu or popover, uses the color.bg.raised background and a border instead. The reasons:

  • Borders read the same in both themes; a shadow on a near-black page is nearly invisible.
  • Fewer tokens to maintain.
  • In forced-colours mode (Windows High Contrast and similar), browsers remove box-shadow entirely, while borders and outlines stay visible (accessibility research, section 6).

Breakpoints

A breakpoint is a minimum width: a rule for breakpoint.md applies at 768 px and wider. CSS cannot read custom properties inside media queries, so copy these numbers into the site's media queries and keep them in step with the tokens (primitives.tokens.json).

Token Value
breakpoint.sm 640 px
breakpoint.md 768 px
breakpoint.lg 1024 px
breakpoint.xl 1280 px

Content widths

Token CSS custom property Value What it sets
layout.prose --fc-layout-prose 720 px Maximum width of a column of running text. The token's description says "about 70 characters of body text"; not yet measured in a browser.
layout.sidebar --fc-layout-sidebar 264 px Width of the left navigation column
layout.toc --fc-layout-toc 224 px Width of the "On this page" column
layout.page --fc-layout-page 1440 px Maximum width of the whole page; wider screens get empty space at the sides (Proposed)
layout.header --fc-layout-header 56 px Height of the top bar
layout.gutter-sm --fc-layout-gutter-sm 16 px Gutter on small screens
layout.gutter-lg --fc-layout-gutter-lg 32 px Gutter on large screens

These widths sit inside the ranges measured on eleven documentation sites on 1 Nov 2026: text columns of 650 to 860 px on most sites, left navigation of 224 to 300 px, and "On this page" columns of 198 to 340 px (peer analysis, layout and density).

The documentation layout

Every site in the peer analysis uses the same three columns: navigation on the left, the text column in the middle and "On this page" on the right (peer analysis). fiscalclock follows it, because a conventional structure reads as more trustworthy than a novel one (trust research, rule R2).

The column widths are decided (the layout.* tokens). Which breakpoint switches between the arrangements below is Proposed, as are the gutter rules.

Large screens: breakpoint.xl (1280 px) and wider

|<--------------------- up to 1440 px (layout.page) --------------------->|
+-------------------------------------------------------------------------+
| logo   search                       theme   GitHub     56 px header     |
+-------------------+-------------------------------+---------------------+
| Navigation        | Text column                   | On this page        |
| 264 px            | up to 720 px                  | 224 px              |
| (layout.sidebar)  | (layout.prose)                | (layout.toc)        |
|                   |                               |                     |
| Section           | # Page title                  | Heading one         |
|   Page            |                               | Heading two         |
|   Page (current)  | Paragraph text, left-aligned, |   Sub-heading       |
|   Page            | ragged right edge.            |                     |
|                   |                               |                     |
+-------------------+-------------------------------+---------------------+
   32 px gaps (layout.gutter-lg) at both edges and between columns

The header contents in these sketches are illustrative; the header is not designed yet.

At exactly 1280 px, with 32 px at both edges and between the columns, the text column is 1280 − 264 − 224 − 4 × 32 = 664 px. It grows with the window until it reaches 720 px.

Medium screens: breakpoint.lg (1024 px) to 1279 px

+-----------------------------------------------------------+
| logo   search                 theme   GitHub      header  |
+-------------------+---------------------------------------+
| Navigation        | On this page  (collapsed list)        |
| 264 px            +---------------------------------------+
|                   | Text column                           |
|                   | up to 720 px                          |
|                   |                                       |
+-------------------+---------------------------------------+

The "On this page" list moves above the text. At 1024 px the text column is 1024 − 264 − 2 × 32 = 696 px.

Small screens: below breakpoint.lg (1024 px)

+-----------------------------+
| [menu]  logo        [theme] |   56 px header
+-----------------------------+
| On this page  (collapsed)   |
+-----------------------------+
|16|  Text column          |16|
|  |  full width, minus    |  |
|  |  the two gutters      |  |
|  |                       |  |
+-----------------------------+
 16 px gutters (layout.gutter-sm)

The navigation moves behind a menu button in the header. Use layout.gutter-sm (16 px) below breakpoint.md (768 px) and layout.gutter-lg (32 px) from breakpoint.md up.

Rules that hold at every width

Alignment

Rule Status
Body text is left-aligned with a ragged right edge. Proposed
No centred body text, including on the landing page. A centred hero followed by three icon boxes is one of the patterns practitioners describe as the generated-design look (trust research, section 8). Proposed
No justified text (text stretched to both edges). Proposed
Numbers in table columns are right-aligned, or aligned on a common character, so that digits of the same place line up; ISO dates in tabular figures line up when left-aligned, because every row has its hyphens in the same positions (typography research, numbers rule 5). Proposed
Content starts at the left edge of its column; headings, paragraphs, code blocks and tables share that edge. Proposed

Density

Proposed: medium density, in line with most of the sites measured: "Medium" was the most common rating, with Linear and Tokio "Airy" and DuckDB "Dense nav, generous text" (peer analysis, layout and density). In practice: 16 px body text with a 1.6 line height (Typography), 16 px between paragraphs, and 32 to 48 px above major headings. The owner's personality settings lean very slightly towards minimal and quiet (DD-006), which argues against both cramped and very airy pages.

Not decided

  • Which breakpoint switches each arrangement, and the gutter rules (all Proposed above).
  • The spacing used by each component; see Docs-Components.
  • Whether layout.page caps the whole page or only the content area.
  • How the header and navigation behave on scroll (sticky or not).

Links

fiscalclock is licensed under MIT OR Apache-2.0 (MIT, Apache-2.0). Last reviewed: 31 Oct 2026. Found an error on this page? Report it with the documentation form.

Start

Design

Decisions

Design system

Project

Clone this wiki locally