Theme Shelf

Shelf is a Tome theme for small-batch shops: makers, studios and independent sellers whose product and whose story are one page. Its stance is "small batch, big care". The site reads like a well-made printed catalogue that happens to take your order: the maker's voice sits beside the price and the add button, every row of products stands on a 2px shelf line, and nothing is louder than the thing you came to buy. It ships four palettes (Bisque, Stone, Pantry, Smoke), 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. It is the first of the commerce themes: the storefront blocks it styles ship in their own packs.

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

@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 Shelf 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 Smoke sets. The package imports no React and no Payload.

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-shelf/styles.css'
import '@wabbit/tome-theme-shelf/fonts.css'

<html data-tome-theme="shelf">                                           <!-- Bisque, light -->
<html data-tome-theme="shelf" data-tome-palette="stone">                 <!-- Stone -->
<html data-tome-theme="shelf" data-tome-palette="pantry" data-theme="dark">
<html data-tome-theme="shelf" data-tome-palette="smoke" data-theme="dark">

With no data-tome-palette the theme renders Bisque. data-theme="dark" gives each its derived dark mode. Smoke 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 SHELF_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-shelf/register'

Header: Navbar 5, links centred

Shelf recommends the tome-chrome Header global on Navbar 5 (design version '5'): the wordmark left, the shelf links centred, the account link and the bag on the right, in a full-width square bar on the page ground. Set the Header global's `navAlignment` to `"center"`; Navbar 5 honours it from chrome 0.23.0 and writes data-nav-align="center" on its root.

• The bar earns its chrome on scroll. At the top of the page it is bare (the page ground, a transparent hairline). Once the page has scrolled past 20px, Navbar 5 reports the state (useReportNavScrolled) and the frame carries data-nav-scrolled="true"; the theme then gives the bar the surface tone and a hairline. The frame keeps chrome's own sticky and hide-on-scroll behaviour; the theme only paints it. A transparent overlay header over a hero (data-overlay="true") stays the platform's.
• The name is your LogoComponent. Mark it up with the lockup hook: <span data-shelf-wordmark>Your Shop</span> (Anybody at wdth 140, 600, uppercase, tracked 0.04em).
• The call to action is the buy pill: ink, 44px, bone on Smoke.

Footer 7 (its own tonal zone, no footer call-to-action band, the credits line in the small print wherever plates show) is recommended and is styled in the next release, with the cart slot, the numbered shelf prefix and the checkout mode.

Scroll reveal

Shelf turns on tome-ui's opt-in platform scroll reveal (--tome-reveal: on) and maps its timing to a short glide: --tome-reveal-rise 14px, --tome-reveal-duration 640ms, --tome-reveal-stagger 70ms, with --tome-reveal-wait: fonts. It 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. Under reduced motion there is no reveal and no smooth scroll.

Motion

User-triggered motion springs; scroll motion glides. Three private tokens carry it, each a transition fragment (duration and easing) so a treatment writes transition: transform var(--shelf-spring):

Under prefers-reduced-motion all three become 0.01ms linear and the reveal rise is 0, so steppers swap instantly, counts change without rolling, and the drawer and sheet appear without sliding. treatments/base.css settles every other transition and animation once for the whole themed document.

Fonts

Anybody (the shop: display, UI, names, prices, the meta voice) and Spectral (the maker) ship inside the package as latin-subset woff2, with their SIL OFL 1.1 licences (fonts/OFL-Anybody.md, fonts/OFL-Spectral.md). There is no third-party font request. Pick one delivery path:

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

import { getShelfFontPreloads } from '@wabbit/tome-theme-shelf/fonts'

// in <head>: preload Anybody and the maker's roman
{getShelfFontPreloads({ src: '/fonts/shelf/' }).map((l) => <link key={l.href} {...l} />)}

Both are subset from the repo TTFs by scripts/subset-fonts.py (SHA-pinned sources, byte-identical output, and a fail-loud tnum check), not taken from the served builds, because the served builds strip features Shelf depends on: the served Spectral has no onum and the served Anybody drops case. Anybody is one variable face, wdth 100 to 150 and wght 300 to 700 (39,264 bytes); Spectral is 400 (29,484), 400 italic (30,600) and 600 (31,192). Neither family has a Reserved Font Name.

Two voices. The shop speaks in Anybody and the maker speaks in Spectral. A sentence in the serif always reads as a person; a line in the grotesk always reads as a fact you can act on.

• Display: Anybody at an expanded width (titles at wdth 125, the hero at 118), weight 500, never heavier than 600, text-wrap: balance.
• UI, names, prices: Anybody at wdth 100, weights 400, 500 and 600.
• Meta voice: Anybody at wdth 140, 500, 12px, uppercase, 0.1em, tabular, with case on. Always above a heading, never alone.
• Maker's voice: Spectral 400 at 19 to 21px on the 600px measure, with old-style figures. Italic only inside a quoted person; 600 is the bold.
• Every Anybody rule sets its weight. The default instance of the subset is wght 300, the axis floor, so a rule that sets the family and no weight draws light text.
• Every number in a row is tabular, in Anybody (prices, quantities, counts, edition and order numbers, dates), set explicitly on the price and count hooks. A price never appears in Spectral. Anybody has no U+2197, so the new-tab arrow is set in Spectral.

Sites can mark their own markup with data-shelf-meta (the meta voice), data-shelf-maker (the maker's voice), data-shelf-quote (a quoted person, italic) and data-shelf-figures (tabular figures).

Effects

Two opt-in effects. Both are off unless a site asks, on <html> or on one section:

<html data-tome-theme="shelf" data-shelf-effect="keyed-plates">
<html data-tome-theme="shelf" data-tome-palette="pantry" data-shelf-effect="grain keyed-plates">
<section data-shelf-effect="grain">…</section>

• `keyed-plates`. Product plates are exported keyed to the well (the white sweep normalised to white, the shadows kept), so a plate laid on the well with mix-blend-mode: multiply makes the well its ground and the piece stands on the shelf line instead of in a white box. The blend is the per-mode private token --shelf-plate-blend: multiply in light modes, normal in dark modes, where plates show as lit prints in their 4px frame (no cut-outs in v1). Only the primary tile image and the drawer's thumbnails of it blend; close-ups and in-use frames are real photographs and never do. Without the effect, plates show as lit prints in every palette, which is safe for any merchant's photos.
• `grain`. A faint fractal-noise grain (alpha .05) on the ground, the earned header and the hero: Pantry in its designed light mode only. Every other palette and mode declares --shelf-grain as none, so the effect is inert there. It never touches the dark band or the footer.

Public API

import { shelfThemeManifest } from '@wabbit/tome-theme-shelf/manifest'

shelfThemeManifest.palettes.map((p) => p.label)
// ['Bisque', 'Stone', 'Pantry', 'Smoke']

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
• 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. The page's one dark band is the closing conversion.
• the four --tome-type-* families, each paired with its --font-* slot

Selector ladder (specificity, never load order):

The palette rules are generated from shelf/scripts/palettes.mjs --fix (zero failures), never retyped. Every palette rule, light and dark, declares the full set: Layer 1, the literals, the band inks and the private colour tokens (--shelf-mark, --shelf-well, the role colours and their 12% tints, --shelf-ink-hover, the badge and chip fills, --shelf-placeholder, --shelf-shadow, --shelf-grain-ink, --shelf-grain, --shelf-plate-blend).

Colour by commerce role. Exactly four role colours per palette, and nothing else may wear them:

--warning maps to the notice colour and --tome-color-info-text to ink, so a foreign block cannot add a fifth role colour. The mark (--shelf-mark) draws bars, rules and dots (the free-shipping bar, the link underline, the focus ring where it clears 3:1); where the accent carries text, the text-safe shade is used. Pantry's bright marmalade (`#C9640E`) is a mark only and never sits behind text; anything that carries a number fills with the deep marmalade #9A470C, which is also Pantry light's platform --accent.

Shape and rhythm. --radius 8px; plates 4px, cards, fields and drawer lines 8px, the buy object 22px (the roundest thing on the page), pills (999px) for things you press only; bands and the drawer's viewport edge are square. The shelf line is a 2px ink rule every row stands on (--shelf-line). One section rhythm (56 to 104px), a 600px prose measure that is not negotiable, and tome-ui's grid with Shelf'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-well rule. No field sits on the well (the well holds chips, swatches, plates and tracks). As a safety net, --input clears 3:1 on the well in every mode, so a foreign field placed on a well still passes.

Palettes

Contrast

All ratios are WCAG 2.x. Every text pair clears 4.5:1 and every mark 3:1 in all eight modes, including on the well. The test suite re-measures every pair from the shipped values. The tightest passes are the field outline on the well (3.06 to 3.78) and the role text on the well (4.73 to 6.14).

What it styles

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 photo, 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.

Not in this release (the home bands): the product tile and its flags, the shelf rows and the next-edition tile, the contents rows, the closing band, the testimonial, FAQ, term-ledger, split-view and journal bands, and Footer 7. The restock alert's form (S7) is styled on the contract's hooks and is checked when that block publishes.

Commerce treatments

The shop, the product page, the bag and the single-task pages, built to the approved mockups (a-r2-catalog.html, a-r2-product.html, a-r2-lookup.html). Every rule is scoped to the theme, reads colour from tokens only, and reaches blocks through their public hooks.

The rules the treatments hold to: buy is ink on every pill (bone on Smoke); the notice colour appears only on a sale, on low stock and on the filter count; prices and counts are tabular and right-aligned in the drawer and on the order pages; controls are 44px (the 36px chips and small add pills carry a 44px hit area); the bright marmalade is never behind text and the focus ring is the palette's ring token (the darkened marmalade on Pantry light). The stepper swap, the count and price rolls and the free-shipping growth are the packs' own and run only under prefers-reduced-motion: no-preference; the drawer and the sheet spring in on --shelf-spring under the same condition.

Stripe hosted-checkout branding

Stripe's hosted checkout is branded in the Stripe Dashboard (Settings, Branding, Checkout), once per merchant account. It takes a background colour, a button colour, a font from Stripe's list, a border style, a logo and an icon; Stripe picks the button text colour itself. Values below are each palette in its designed mode, from the generated palette tables.

For every palette:

• Font: be_vietnam_pro, the nearest Stripe font to Anybody at wdth 100. The alternative montserrat is closer to the expanded display but too wide at form sizes. Spectral has no near match, and the checkout carries no maker prose.
• Border style: rounded. Shelf's fields and lines are radius 8; pill would round Stripe's inputs too, and Shelf keeps pills for things you press.
• Logo: the store's wordmark on the palette's background colour. Icon: the store's mark. Display name: the store's name.
• Branding is dashboard-only in v1: per-session branding_settings would need a change to the economy Stripe adapter.
• Merchant of record: the Stripe account is the merchant's own, so the business name and logo must match the store, as card-network rules require.

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-shelf test runs the suites: theme conformance (both modes of assert-theme-conformance), palettes (the full required token set in all eight modes, the commerce-role invariants, the grain and the plate blend), contrast (every text pair at 4.5:1 and every mark at 3:1 in all eight modes, the role tints re-computed), no colour literals outside tokens/, fonts (A4.1 pairing, explicit Anybody weights, tabular figures, and the shipped woff2 files read for tnum, case, onum and the variation axes), the manifest, the hook contract and hook coverage.

License

Wabbit Tome Commercial License (see LICENSE.md). The bundled fonts keep their SIL OFL 1.1 licences.