Theme Folio

@wabbit/tome-theme-folio

Folio is a Tome theme for people whose business is themselves: coaches, therapists and counsellors, consultants and solo advisors, authors and speakers. Its stance is "read slowly". The site reads like a good book by its author, with the author writing in the margins: warm, unhurried, first person, never trying to look bigger than one person, and every page leading to one quiet ask, a first conversation. It ships four palettes (Deckle, Clay, Heath, Lamplight), each in light and a derived opposite mode.

This package is a theme (a ThemeManifest of kind: 'theme'). It owns no blocks. It declares the whole token surface blocks read, self-hosts its two OFL font families, and restyles blocks and chrome through their public hooks.

Layer: ui · Family / tier: themes / addon · Versioning: independent.

Install

pnpm add @wabbit/tome-theme-folio

| Peer | Range | Required | |---|---|---| | @wabbit/tome-ui | >=0.20.0 <1.0.0 | yes | | @wabbit/tome-core | >=1.23.0 <2.0.0 | no (optional) |

@wabbit/tome-ui is a CSS-contract peer. Its tokens.css re-declares the var()-aliased Layer 2 under [data-tome-theme] and defines the fixed-band ink family this theme sets, and it ships the platform scroll reveal Folio turns on (0.20.0 adds the font-waiting arm, --tome-reveal-wait: fonts). @wabbit/tome-core is needed only for the ./register subpath and the ThemeManifest type, and 1.23.0 is where a palette gains defaultMode, which Lamplight sets. The package imports no React and no Payload.

Folio styles hooks that the blocks it uses publish: the split hero's parts (data-hero-*), the two-path ledger of practice-modes, the Margin Voice of annotated-page and of an essay body, the essay header and running head of article-hero, the longform epigraph, the closing contact, the Reading Room archive, and the data-new-tab marker on links that open in a new tab. On older block packs the theme still applies, and the parts a pack does not publish render with the blocks' own look.

Usage

Import the stylesheet once at the app root, after tome-ui's tokens, and activate the theme on <html>:

// app/layout.tsx
import '@wabbit/tome-ui/tokens.css'
import '@wabbit/tome-theme-folio/styles.css'
import '@wabbit/tome-theme-folio/fonts.css'

<html data-tome-theme="folio">                                          <!-- Deckle, light -->
<html data-tome-theme="folio" data-tome-palette="clay">                 <!-- Clay -->
<html data-tome-theme="folio" data-tome-palette="heath" data-theme="dark">
<html data-tome-theme="folio" data-tome-palette="lamplight" data-theme="dark">

With no data-tome-palette the theme renders Deckle. The three light palettes have no dark bands at all: sections shift tone (ground, surface, surface-muted) and the footer is its own tonal zone. data-theme="dark" gives each its derived dark mode. Lamplight is the exception: it is a designed dark page, in its [data-theme="dark"] slot, with a derived light page in the plain palette slot. It is meant to open dark, so the manifest sets defaultMode: 'dark' on it, which createThemeConfig(), the admin switcher and the storefront read to set data-theme="dark" when it is picked. A site with its own switcher can read FOLIO_PALETTE_DEFAULT_MODES, the same fact as a map.

To have the admin ThemeSwitcher, createThemeConfig() and other registry readers list it, register it on the server before building the Payload config:

import '@wabbit/tome-theme-folio/register'

Header: Navbar 7, static

Folio recommends the tome-chrome Header global on Navbar 7 (design version '7'), static on every page: the header sits in the flow at the top and scrolls away with the page. There is no compact state, no hide-on-scroll and no sticky bar. Navbar 7 is position: fixed inside a sticky frame, so the theme sets both to relative, resets the offsets, and zeroes the curtain (radius, shadow, scrim and blur). The frame paints the header's tone: the surface colour by default, the ground colour when the Header global's navBackground is 'background' (the essay header).

• Set the Header global's `desktopBreakpoint` to `1024`, so below 1024 the links fold into the drawer behind a bordered "Menu" button (4px radius, an input-colour border, a 44px target). Set `menuLabel` to "Menu" so the button carries its label ([data-menu-label]). The call to action sits with the links, so it folds into the drawer as well, unless you set the Header global's `ctaVisibleBelowDesktop`: then the pill stays in the bar beside "Menu" from 768px up to the desktop breakpoint ([data-header-cta-bar]), and the drawer's copy is hidden over that range.
• The call to action is the ink pill: 44px, the sans at 500, hovering to the accent text colour, with a north-east arrow when it opens in a new tab.
• The name is your LogoComponent, rendered in chrome's logo slot. Mark it up with the lockup hook: <span data-folio-site-name>Your Name</span>. It is Piazzolla at 22px, 400 (24px in the footer).

Footer: footer 7 with backgroundColor: 'muted'

Set the Footer global to design version '7' and `backgroundColor: 'muted'`. The footer is its own tonal zone under a hairline; group labels are the meta voice; links are the nav size; small print is the meta voice at the measure. There is no footer call-to-action band.

Folios

Every labelled section opens with a small old-style number (Piazzolla, 22px, accent text) and its label in the left margin lane: folio above label from 1024px, in one baseline row below that. The numbers are a CSS counter in page order, never typed, so they stay correct when sections move. The hero counts as the first section and prints none, so a home page's first folio is 2. A block that continues a band (fit-prose) neither counts nor prints, and a page with a running head (an essay) prints no section folios. The folio prints on the label hooks [data-lane-kicker], [data-block-eyebrow] (testimonial and FAQ) and [data-contact-eyebrow].

Scroll reveal

Folio turns on tome-ui's opt-in platform scroll reveal (--tome-reveal: on) and maps its timing to the slowest of any theme: --tome-reveal-rise 22px, --tome-reveal-duration 1100ms, --tome-reveal-stagger 140ms. It also sets --tome-reveal-wait: fonts, which tome-ui releases that read the token use to arm only after fonts and layout settle. The reveal runs only where the site mounts the controller once in its root layout:

import { TomeReveal } from '@wabbit/tome-ui/reveal'

// inside <body>, once
<TomeReveal />

Without the controller nothing moves and nothing is hidden. Blocks that animate themselves (data-tome-motion="self") are skipped by the controller. data-tome-reveal="off" on <html>, a region or a block root turns it off there, and overrides the theme. Under reduced motion there is no reveal and no smooth scroll.

Fonts

Piazzolla (one variable face per style, roman and italic, carrying wght 100 to 900 and opsz 8 to 30) and Alegreya Sans (400, 500 and 400 italic) ship inside the package as latin-subset woff2, with their SIL OFL 1.1 licences (fonts/OFL-Piazzolla.md, fonts/OFL-AlegreyaSans.md). There is no third-party font request. Pick one delivery path:

• import '@wabbit/tome-theme-folio/fonts.css': the bundler resolves the files from this package.
• Your own host: copy the files from @wabbit/tome-theme-folio/fonts/* and inject getFolioFontStyles({ src }).
• next/font/local, using the file list from getFolioFontFaces().

import { getFolioFontPreloads } from '@wabbit/tome-theme-folio/fonts'

// in <head>: preload the serif roman and the 400 sans
{getFolioFontPreloads({ src: '/fonts/folio/' }).map((l) => <link key={l.href} {...l} />)}

Piazzolla is the upstream release, not the Google Fonts build: only the upstream build carries old-style figures (onum), which folios, stat figures, years and the proof line depend on. The shipped subset keeps onum, pnum, sups and smcp, and adds U+2197 (the new-tab arrow) to the latin range; it was produced by scripts/subset-piazzolla.py (a documented one-off; the build never runs it). Piazzolla has no Reserved Font Name, so the subset keeps the name. Alegreya Sans comes from fontsource 5.3.0. Its default figures are already old-style proportional, so it has no onum feature: never set lining-nums on sans figures.

The serif sets display, headings, essay text, the spoken line, notes, folios and figures. Alegreya Sans is the body and UI face: running copy on marketing pages, nav, buttons, forms, labels and captions. Display is light (300), text and notes 400, never bold. Italic means a person is speaking: the hero's spoken line, endorsement quotes, the first-person margin note, the epigraph and the sign-off; nothing else is italic, and no headline carries an italic accent word. The meta voice is the sans at 500 in sentence case and muted ink, never uppercase, small caps or monospace. There is one body size for all running copy (18 to 20.8px). Every --font-* slot is declared with its paired --tome-type-* alias on the theme selector (amendment A4.1).

The paper-fibre effect

There is one opt-in effect: a faint fractal-noise grain on the ground and on surface bands, the texture of unbleached paper. It is static, Deckle and Clay in light mode only (every other palette and mode declares its grain as none), and it never touches the muted band or the footer.

<html data-tome-theme="folio" data-folio-effect="paper-fibre">
<section data-folio-effect="paper-fibre">…</section>

On <html> it grains the page ground and the surface bands Folio paints itself (the header, the hero, the endorsements and the Reading Room index). A custom property cannot be interpolated into a url(), so each palette declares the whole image as --folio-grain, with its ink numbers in --folio-grain-ink.

Sites can also mark their own markup with data-folio-meta (the meta voice), data-folio-figures (old-style proportional figures) and data-folio-voice (the spoken line's italic serif).

Public API

| Export | Subpath | Purpose | |---|---|---| | folioThemeManifest (ThemeManifest) | ., ./manifest | The theme's manifest: name folio, kind: 'theme', tier addon, four palettes, fonts and one pairing, recommended blocks and chrome (Navbar 7, footer 7), styledBlocks, requires.tomeUi. | | FOLIO_PALETTE_IDS, FolioPaletteId | ., ./manifest | ['deckle', 'clay', 'heath', 'lamplight'], the data-tome-palette values. | | FOLIO_PALETTE_DEFAULT_MODES | ., ./manifest | The mode each palette opens in: light for three, dark for Lamplight. The manifest carries the same fact as each palette's defaultMode. | | FOLIO_STYLED_BLOCKS, FOLIO_RECOMMENDED_BLOCKS | ., ./manifest | The block slugs the theme restyles, and the slugs its demo is composed from. | | ThemeManifest (type) | . | Re-exported from @wabbit/tome-core/registry/theme. | | getFolioFontFaces(), getFolioFontStyles({ src }), getFolioFontPreloads({ src }) | ., ./fonts | Font descriptors, @font-face CSS for a custom host, and preload links. | | FOLIO_FONT_STACKS, FOLIO_FONT_LICENSES, FOLIO_LATIN_UNICODE_RANGE, FOLIO_PIAZZOLLA_UNICODE_RANGE, FOLIO_SERIF_WEIGHTS, FOLIO_UI_WEIGHTS | ., ./fonts | The CSS stacks the tokens use, the licence file per family, the two subset ranges (Piazzolla's adds U+2197), and the weights used. | | FolioFontFace, FolioFontPreloadDescriptor, FolioFontStylesOptions (types) | ., ./fonts | The descriptor shapes. | | side effect | ./register | Registers folioThemeManifest in tome-core's theme registry. | | stylesheet | ./styles.css | Tokens, treatments and the effect. The file that does everything visual. | | stylesheet | ./fonts.css | The five @font-face rules. Optional. | | font files | ./fonts/* | The woff2 files and their OFL licences, for self-hosting. |

import { folioThemeManifest } from '@wabbit/tome-theme-folio/manifest'

folioThemeManifest.palettes.map((p) => p.label)
// ['Deckle', 'Clay', 'Heath', 'Lamplight']

Tokens

The theme sets Layer 1 (the names tome-ui's tokens.css reads: --background, --foreground, --card, --primary, --accent, --muted, --border, --input, --ring, the feedback, chart and muted2 names) and lets tome-ui's generated re-resolution derive the aliased Layer 2. It sets these Layer-2 literals directly, because no Layer-1 input sits behind them:

• --tome-color-accent-text and the feedback *-text weights, and --tome-color-surface-tint (a step lighter than the muted band, because practice-modes' default band is the tint)
• the fixed-band inks: --tome-color-surface-solid-dark, --tome-color-on-solid-dark, --tome-color-on-solid-dark-muted, --tome-color-accent-on-solid-dark, --tome-color-primary-on-solid-dark, --tome-color-border-inverse, and the light fixed surface --tome-color-surface-inverse with --tome-color-on-inverse, --tome-color-on-inverse-muted, --tome-color-accent-on-inverse, --tome-color-primary-on-inverse. Folio paints no dark band; a foreign block may.
• the four --tome-type-* families, each paired with its --font-* slot

Selector ladder (specificity, never load order):

| Selector | Specificity | Holds | |---|---|---| | [data-tome-theme="folio"] | 0,1,0 | Deckle light, type, radius, rhythm, lanes, motion | | [data-tome-theme="folio"][data-theme="dark"] | 0,2,0 | Deckle dark | | [data-tome-theme="folio"][data-tome-palette="p"] | 0,2,0 | palette light (for Lamplight, its derived light page) | | [data-tome-theme="folio"][data-tome-palette="p"][data-theme="dark"] | 0,3,0 | palette dark (for Lamplight, the designed page) |

Every palette rule, light and dark, declares the full set: Layer 1, the literals, the band inks and the private colour tokens: --folio-placeholder, --folio-chip-fill (the fill of a chip sitting on a surface band: surface-muted in light modes, a 14% accent tint over the surface in dark modes), --folio-shadow (the recommended path's shadow ink), --folio-grain and --folio-grain-ink, and the photo and portrait filters (--folio-photo-filter, --folio-portrait-filter). The ledger block derives one more, --folio-chip-fill-card, from the surface colour and --folio-chip-fill. Other private tokens use the --folio-* prefix: the voices' sizes, the UI sizes, leading, opener and band spacing, shape, the control heights, and the reveal timing (mapped onto tome-ui's --tome-reveal-*).

Shape and rhythm. --radius 8px; --tome-radius-sm 4px (fields, chips, the menu button, the plate tag), md 8px (cards, media), lg and xl 14px (portraits and the two path columns), full 999px for actions only. Rules separate chapters, rows and ledger rows instead of card borders. One section rhythm (--tome-section-py, 72 to 136px), a 600px prose measure that is not negotiable, and tome-ui's grid with Folio's lanes: three columns of left and right marginalia and one prose-pad column, four and four from 1760px. tome-ui sets the root at 18px, so the approved design's 16px-root sizes are converted by 16/18.

The field-on-muted rule. No field, radio box, select or dashed slot sits on a surface-muted band, in any palette. As a safety net, --input itself is darkened in every light mode until a field outline clears 3:1 on surface-muted, so a field a buyer drops on a muted band still passes.

Palettes

| Palette | Ground / surface | Ink / muted | Accent / accent text | Opens | |---|---|---|---|---| | Deckle (default) | #F3ECDF / #FAF6EE | sepia #2B2018 / #5E5043 | ochre #95681B / #7E5717 | light | | Clay | #F4EAE5 / #FBF6F3 | plum #35202A / #654E55 | madder rose #A94A63 / #93394F | light | | Heath | #EBEEEE / #F7F8F8 | slate-teal #1F3236 / #4D5E61 | heather #7A5A93 / #664780 | light | | Lamplight | #221E1B / #2B2622 | oat #EDE5D8 / #BDB1A1 | apricot #E3A774 / #EBB386 | dark |

The accent is punctuation: folios, the margin rule, link hover, the active tab, the recommended path's top rule, list dashes, quotation marks and the signature. It is never a large fill. Each light palette uses coloured ink, so text is a deep warm or cool hue rather than black; that is most of Folio's warmth. Clay's plum is ink, a different role from a plum accent elsewhere.

Contrast

All ratios are WCAG 2.x. Text must reach at least 4.5. Field outlines, accent marks and the focus ring must reach at least 3. The test suite re-measures every pair in all eight palette modes from the shipped values.

| Pair | Deckle | Clay | Heath | Lamplight (dark) | |---|---|---|---|---| | ink on ground / surface | 13.52 / 14.73 | 12.75 / 14.07 | 11.48 / 12.59 | 13.23 / 11.97 | | muted on ground / surface-muted | 6.61 / 5.87 | 6.40 / 5.70 | 5.83 / 5.24 | 7.85 / 6.44 | | accent text on ground / surface-muted | 5.48 / 4.87 | 6.04 / 5.38 | 6.48 / 5.83 | 8.92 / 7.32 | | on-accent on an accent fill | 4.56 | 5.09 | 5.32 | 7.16 | | accent mark on surface-muted | 3.72 | 4.11 | 4.37 | 6.49 | | field outline on ground / surface-muted | 3.46 / 3.07 | 3.43 / 3.06 | 3.40 / 3.06 | 3.94 / 3.24 | | chip: ink on chip fill | 12.01 | 11.36 | 10.33 | 9.35 |

The tightest passes are accent text on surface-muted in Deckle (4.87) and the field outline on surface-muted in the light modes (3.06 to 3.07). Deckle's accent mark is a touch darker than a pencil ochre on purpose: paper on an ochre fill, which a foreign block may paint, clears 4.5.

What it styles

| Hook | Treatment | |---|---| | Chrome header ([data-visible][data-nav-theme][data-overlay], nav[data-nav-theme]) | Static: the frame and the nav in flow, painted surface (ground with data-nav-bg="background"); the lockup hook [data-folio-site-name]; nav links in the sans at 500 in ink, accent text on hover, [aria-current="page"]; the ink-pill call to action through --tome-header-cta-*; the bordered "Menu" button ([data-menu-label]); the curtain zeroed through --tome-header-curtain-*; the missing half of Navbar 7's mobile bottom padding put back so the header is one height at every width. | | high-impact-hero split | From 1024px on the page's 16 columns: the portrait ([data-hero-media], 4:5 in the 14px frame, the portrait filter) on the first five, the copy ([data-hero-copy]) from the seventh, centred against it; below 1024 the portrait leads at 62% of the width. The headline at the hero size, light; the spoken line ([data-hero-subheadline]) in italic Piazzolla at 34ch; two 48px pills in [data-hero-actions] (filled and data-appearance="outline"); one proof line ([data-hero-proof]) in the meta voice with old-style figures; the still-life motif ([data-hero-motif]) at the bottom right; the "Illustrative photo" tag ([data-compliance-label]) bottom left on the portrait. | | practice-modes ledger | Two paths compared row by row. From 768px each path is a column of surface cells under a 14px head and doors; the recommended path (data-mode-recommended) takes a 3px accent top rule and the one shadow Folio draws. Row labels (data-ledger-label) are the meta voice in the left lane. The "Good fit if" chips (data-mode-chip) take --folio-chip-fill-card, the surface colour mixed half toward --folio-chip-fill (set on the block, in sRGB), so they sit one step off the card they are on and never vanish into it; ink on them clears AA in every mode. Below 768px each row is a slice of one card with the tab list above it. | | fit-prose | Two third-level labels over body-size paragraphs; data-fit-order changes the order in the markup, not the look. | | dated-ledger rows | The year or data-date-label ("Now") in the left lane as a small old-style numeral in accent text, the title and paragraph on the prose line, the photo (data-ledger-photo) at 4:3 in the right lane, faded from the left. | | annotated-page voice and an essay body ([data-reading-body]) | Piazzolla at the body size on the 600px track; notes at the annotation size, inline below 1280px and in the margin from 1280px (data-notes-from), the author's aside italic and the other kinds upright under a sans label; anchor numerals and footnote marks in accent text; a folio and a third-level heading for each part (data-annotated-part); the end list of footnotes (data-footnotes); the drop cap (data-drop-cap on the root, data-drop-cap-target on the paragraph to cap, which both renderers set on the lede); part folios count from 2, because the opening text is part 1. | | article-hero margin and the running head | The essay header in the left lane and the reading column, the standfirst at the quote size, topic chips on the chip fill; the running head's hairline with the 3px accent fill that follows --tome-reading-progress. | | The longform epigraph ([data-epigraph]) | Italic Piazzolla at the quote size, left-aligned in the prose column; attribution and source in the meta voice. | | contact estimate | The closing: the label, heading, note, link-out pill, promise and sign-off in a note column from the prose line, the form straight on the band under it, the portrait on the last five columns and the motif directly under the label; fields are 48px surface wells with the input outline, path options 44px boxes with an accent dot; the send button sits at the start of its line with no hairline above it and the required marker is a small muted asterisk. | | archive filed | The Reading Room: a surface band with the section padding (the index layout only); a lead with the image on seven columns, ruled rows with the serial and kind in the left lane, the footer row (topics, sign-up, the dashed empty slot) and the single "next" teaser under a 3px accent rule. | | Section openers ([data-lane-kicker], [data-block-eyebrow], [data-contact-eyebrow]) | The meta label and the printed folio (see Folios). | | Dossier openers (practice-modes, fit-prose, dated-ledger) and [data-block-deck] | One rule puts the heading on the prose line from 1024px, where the voice block's heading sits, and the honest-fit columns start there too; the deck under a heading is the body size in the surface ink, 16px under the heading (the voice block's row gap is taken out of its margin). | | proposal-stat-strip (the figures) | Two to four figures from the prose line, in equal cells 32px apart (captions have no measure of their own and stay on one line): light Piazzolla numerals in old-style figures ([data-stat-value]), meta captions ([data-stat-caption]), the band between two hairlines, the folio in the left lane. A strip with no figures renders nothing and is not counted. | | testimonial quotes-grid (the endorsements) | A surface band with the section padding. The section title is the second-level heading whether the block prints it as an h2 or an h3. Three quotes in a row from the prose line: italic Piazzolla at the quote size with accent-text quotation marks (the opening one hangs), the name and affiliation on one plain caption line in the meta voice (the name at the same weight), the compliance label ([data-compliance-label]) a small meta line rather than a filled tag. No portrait, no stat tile. | | faq (the questions) | The ground band with the section padding. The questions on the prose column between hairlines, the question in the sans at 500, a Piazzolla plus that becomes a minus in accent text, and the bridge ([data-faq-callout]) as a plain line with an underlined link. | | Forms ([data-contact-form-slot], [data-filed-signup]) | The path choices as a wrapping row of pills (tome-forms and Form Builder markup both); name and email share a row from 768px ([data-form-fields]); a one-step form's step label is hidden accessibly ([data-form-step-count="1"] [data-form-step-legend]); the monthly-letter sign-up is one inline row. | | [data-appearance] links and buttons (in main, nav and the footer) | The ink pill, and the outline pill in ink; hover turns both accent text. | | [data-new-tab] | The north-east arrow after the link text, in the serif. | | [data-compliance-label] (every block) | The plate tag: a small sans label on the surface colour; inside a photo, the overlay at its bottom left. | | Chrome footer 7 | Below 768px one left-aligned column with the brand first (--tome-footer-nav-cols: 1). A hairline above; group labels in the meta voice, links in the nav size, text rows ([data-footer-text-row], emphasis [data-footer-text-strong]) and the fine print ([data-footer-fine-print], lead-ins [data-footer-fine-print-lead]) in the meta voice. |

Treatments target only public hooks: data-block-type on the block wrapper, data-block-variant on the root, the blocks' documented data-* part attributes, and published component tokens. Element names are used only where a block publishes no part hook (a hero's headline and portrait image, the header's link list). They never target class names. data-block-type is matched in its catalog form (high-impact-hero, not the stored highImpactHero), and a test fails any other form.

Server / client posture

The package is pure CSS plus constants. It has no React components and no 'use client' files, so it is inert under React Server Components. It adds nothing to a client bundle beyond the stylesheets the consumer imports. ./register is a server-side import.

Tests

pnpm --filter @wabbit/tome-theme-folio test

The vitest suites cover:

• the theme conformance check in theme mode (Layer-1 surface, *-text literals, radius and font slots, the full dark redeclaration, palette coverage, scoping, no module class names, font pairing) and in platform mode
• manifest validation, its agreement with package.json, Lamplight's opening mode, and registration
• every palette defining the full required set in both modes
• a contrast test that re-measures the token table in all eight modes, pins its tightest pairs, and checks the chip fill against the OKLCH tint it is meant to be
• the A4.1 font pairing, the figures rule (no lining-nums), the self-hosted faces with their licences, and the subset ranges
• hook coverage: every hook the theme is built against has a selector, and the few that carry behaviour only are listed with the reason
• no colour literal outside src/tokens/, no comment that swallows a rule, no structural or class selector, no drop shadow other than --folio-shadow, and every treatment rule scoped to the theme
• the reveal switch and timing, the page lanes, the header's static position, the hero's grid and the folio counter