By Bitsy UI April 1, 2026 8 min read Foundation

Hero media placeholder

Use this area to judge surface tone, border weight, spacing around media, and how captions feel next to the surrounding copy.

A simple placeholder is enough here. The point is to validate image rhythm, caption styling, and page flow.

Foundation work starts with normal HTML

A small CSS foundation should improve plain content before anyone reaches for components. That means body text should feel readable, links should stand out without looking loud, and structural elements should work with little or no extra class naming. This paragraph includes a docs link, some emphasized language, some strong emphasis, and a short inline code example with @import "@bitsyui/core";.

The more useful question is not whether the page looks branded. It is whether a writer, developer, or product team can publish a basic article and trust the defaults to hold together without adding spacing patches everywhere.

A few smaller inline cases matter too: highlighted text, a keyboard shortcut like Shift + K, an abbreviation such as CSS, and a literal sample value with bitsy init --dry-run.

Lists should read clearly without turning into layout primitives

Lists are one of the fastest ways to expose weak defaults. Tight spacing makes them feel cramped. Loose spacing makes short content drag.

Unordered lists should scan quickly.
Items should have enough separation to breathe.
Nested content should remain readable.
- Nested bullets need a clear visual offset.
- They should not collapse into an unreadable block.

Start with the browser.
Layer in semantic tokens.
Add only the opinions that actually save effort.
1. Prefer calm defaults.
2. Keep utilities intentionally small.

If a foundation needs lots of exceptions to look reasonable in basic editorial content, it is probably doing too much in the wrong place.

Bitsy UI calibration notes

Media, references, and long-form rhythm

Real pages mix content types. A good foundation should keep those transitions predictable. The page should not feel like prose, then suddenly switch into a different visual system for code, figures, tables, or disclosures.

An abstract landscape used to test plain image defaults

An editorial composition used to test image and caption rhythm — A captioned image checks whether figure spacing, border treatment, and muted caption text still feel balanced in the middle of a reading flow.

Code and preformatted content

Code blocks should stay readable without becoming oversized callout cards. Preformatted blocks also need to handle raw text well, including wrapped context and horizontal overflow.

:root {
  --bitsy-body-size: clamp(1rem, 0.97rem + 0.15vw, 1.1rem);
  --bitsy-space-3: clamp(1rem, 0.85rem + 0.5vw, 1.35rem);
  --bitsy-brand-900: hsl(210 90% 35%);
}

docs/
  examples/
    foundation-test
packages/
  core/
    tokens.css
    theme.css
    base.css

Tables and definitions should still feel calm

Common editorial blocks and what they reveal about the foundation
Content type	What to inspect	Risk if off
Paragraphs	Measure, line-height, and spacing between blocks	Reading fatigue
Lists	Indentation, item rhythm, and nested structure	Scanning slows down
Tables	Cell padding, borders, and header clarity	Data becomes noisy

A wider table to check overflow behavior in a real article context
Layer	Primary job	Good default	Failure mode	Where to tune later
Tokens	Define semantic values	Small, legible set	Too many aliases	Core token docs
Theme	Map semantic colors	Readable light and dark	Contrast drift	Theme calibration
Base	Improve plain HTML	Calm defaults	Acts like a layout system	`u-prose` and rhythm tokens

Wide content should scroll when needed instead of forcing the whole page wider.

Measure: The ideal reading width for body text, usually tuned for sustained reading rather than dense dashboards.
Rhythm: The vertical spacing pattern that helps content feel deliberate instead of accidental.
Foundation: The shared layer of tokens, reset, themes, and semantic defaults that everything else should build on.

Why keep this page in the docs instead of Storybook?

Storybook validates individual foundation concerns. This page validates the same core rules in a realistic reading flow, where content types are mixed together on purpose.

What should this page help us judge first?

Body size, measure, list spacing, heading rhythm, and whether mixed content still reads like one system.

What should not happen here?

The example should not rely on custom card systems, page-shell abstractions, or a pile of utility classes just to make semantic HTML look acceptable.

Card-like content regions

The foundation itself does not define cards, but the current utility layer should make simple content regions easy to assemble without adding a full component system.

Tokens

Semantic values

Color, space, type, radius, and shadow values should be enough to frame simple content regions.

Theme

Visual tone

Changing the appearance should alter the card tone quickly without any structural changes to the markup.

Utilities

Light structure

The surface utility helps, but the page still needs local composition rules for card grids and sizing.

Advanced typography examples

This section is demonstrative rather than contractual. The Core baseline does not depend on these features, but they help evaluate what stronger typography could look like in a future optional prose or type layer.

If the active font lacks support for some features, several lines below will look similar. That is acceptable. The point is to judge whether the features are useful when the font stack allows them.

Ligatures and punctuation

Office workflows often suffer when punctuation-sensitive text feels mechanical. Affinity, efficient buffering, and offline-first drafting should read smoothly without calling attention to the type system.

“Quoted phrases”, em dashes, apostrophes, ellipses... and parenthetical notes should all sit together without making the line feel brittle.

Numeral styles

Oldstyle numerals in running prose: In 2026 the archive recorded 148 essays, 372 notes, and 64 interviews.

Lining numerals for more formal reference: Version 2.4 shipped on 2026-04-01 with 12 fixes and 3 follow-ups.

Small caps and code contrast

API, CSS, and HTML can read more gracefully when small caps are available.

Prose should feel quieter than code: Use a semantic token name in the sentence. --bitsy-text-xl

Tabular figures help align small runs of data when supported by the font.
Week	Words edited	Articles reviewed	Reading time
14	4,280	12	07:45
15	5,105	9	08:10
16	3,960	14	06:55

Small form section

Forms are part of the foundation too. This is only here to check label placement, control sizing, fieldset spacing, and whether the neutral foundation button style still feels usable before the Button Bit hook is applied.

Heading scale specimen

This block is a rendering specimen, not a recommended document outline. It exists to check the visual progression from h1 through h6 in one place.

Specimen only: the sequence below intentionally shows every heading level for calibration.

Heading 1 should feel like a page-level statement

This is the largest step in the system. It should feel clearly primary without becoming oversized or detached from the body copy that follows it.

Heading 2 should establish major sections cleanly

Most reading-heavy pages will rely on this level for structure. It should feel clearly subordinate to the page title while still carrying enough weight to organize long content.

Heading 3 should support subsectioning without feeling abrupt

This level often appears in guides, articles, and technical writing. If it is too close to h2, hierarchy collapses. If it is too close to body text, structure disappears.

Heading 4 should remain visible in denser content

A restrained foundation still needs enough contrast here for reference pages, nested documentation, and longer examples.

Heading 5 should read as a minor subsection, not body text pretending to be a heading

This is where compressed scales tend to fail. If the type, spacing, or weight are too weak, it stops reading as structure and starts reading like a bold paragraph lead-in.

Heading 6 still needs a job

Even the smallest heading should remain identifiable as structure rather than just muted metadata. It does not need to shout, but it should still help the reader orient themselves.