Skip to content

Text Elements

Heading

Headings divide the text into blocks a reader can see and jump between. They are signposts, not decoration: a reader scanning the page should be able to follow the argument from the headings alone.

  • h2, h3, h4 structure the prose: sections, subsections and the minor breaks inside them. They use the heading typeface.
  • h5, h6 are technical labels, not part of the argument: the name of a table, a dashboard panel, a note or a column in the footer. They use the text face and are set in capitals to read as labels; h6 is set light.
Comparison Table (h5)
LevelSizeMargin (top / bottom)
h21.8em--space-md / --space-sm
h31.4em--space-md / --space-sm
h41.2em--space-sm / --space-sm
h5, h61em, capitals--space-sm / --space-sm

An h2, h3 or h4 that opens the article, or opens a section that opens the article, has no top margin.

The margins are tuned for the library's own typefaces. If you set your own fonts through --heading-font and --primary-font, choose your own heading margins as well: a face with a different x-height or line height needs a different rhythm.

Body Text

Body text is the default. Paragraphs sit on the text-content column at a comfortable measure, the line-height is tuned for sustained reading, and nothing extra is needed — just write.

The measure (--text-content-width) holds for paragraphs and lists anywhere in the article: in its sections, cards, details and sidenotes, and in a plain <table> that sets prose in two columns. It stops at the edge of a data component — a data table (.table-scroll, .table-bordered), a .panel, a .stat, an embedded chart (.rc-chart) — which lays out its own text across its full width, and at the edge of a .caption, which is its own measure: its text runs the block’s full width. A definition list, a quote and a figure keep the measure anywhere in the article too, and stop at the same edges: the details list of a chart spans its panel. Another component opts out with its own max-width.

Paragraphs and headings carry their own vertical margins. Most block components — cards, panels, grids, lists, quotes, callouts, sidenote rows — bring no top margin of their own. In the article flow (and in its sections) a block that directly follows another block keeps --space-md from it, so a card followed by code or a list never touches it. Next to a paragraph, the paragraph's own margin is the gap; two sidenote rows one after the other are two blocks, --space-md apart. To change or remove the gap, put a margin-top utility on the second block (.margin-t-0 closes it); a margin-bottom on the first block does not reduce it.

.lead

A single oversized opening paragraph. Think of it as the page's TL;DR: one or two sentences that tell the reader what this page is about and whether to keep reading. Use it once, at the top of a long-read.

Typography is not decoration; it is the path the reader walks. A well-set page tells the reader, before a single word is parsed, that the content was thought about. Selector .lead is how you say that out loud.

The treatment is intentionally restrained — larger size, lighter weight, slightly tighter leading. Loud enough to set the page, quiet enough to step out of the way.

Meta Copy

.meta-info

Technical information set apart from the prose: the line under a heading, an article's imprint (author, date, reading time), a file path or a version. Muted, small and light, so the eye skips it until it is needed.

By Jane Doe · 12 October 2026 · 6 min read

Its look is the same as .note; the difference is the vertical margin. .meta-info keeps var(--space-md) below it (and var(--space-sm) above inside an <article>), so it stands as its own line between a heading and the text. .note has no margin of its own and sits inside the flow it comments on.

<h1>Where the price rise came from</h1>
<p class="meta-info">By Jane Doe · 12 October 2026 · 6 min read</p>

Special Text Elements

A handful of blocks sit slightly past the text-content column on both sides — a small but deliberate signal that they are not the prose, they are about the prose. Captions, highlights, and content-captions all share this outdent: var(--space-lg) on a tablet and a desktop, tightening to var(--space-sm) on mobile, and none on paper. A .caption spans the content column, not the measure. On the right it hangs only into the room beside the page: 16px on a tablet and up to about 1150px, the full 32px from 1280px. The amount is one internal value in typography/_text-content.scss, read by every block that hangs past the column, so they stay coherent.

.text-content-caption

A wrapper that widens its content past the regular text column by one outdent on each side. Use it for figures, illustrative cards, or any block that needs slightly more horizontal room than a paragraph but should still belong to the article.

.highlight

An emphatic, centered block with a thick brand-color border. The reading flow stops here and reads this carefully — so use it sparingly, for the single sentence on the page that has to land.

Make it beautiful by making it understandable. Not loud. Not clever. Just right.

.caption

An aside-style block with a soft gray background and a thick black left rule (--primary-color). Used for editor's notes, observations, or short asides that comment on the prose without being part of it.

A bad font doesn't just look bad. It feels irrelevant. The reader decides in the first second whether the page is worth their attention, long before the first sentence is read — and a face chosen for decoration, not for reading, answers that question for them. The words stay the same; the trust does not.

<mark>

Inline highlighting for words or phrases inside running text. Use it to flag the single phrase a skimming reader must not miss.

<cite>

<cite> marks the title of a work, and a bare one stays inline, as the browser sets it: in running text, in quoted prose, in a <figcaption>. The <cite> that closes a <blockquote>, as its direct child, is the attribution: its own line, right-aligned, small and light — see the <blockquote> example below. A credit under an image goes in the image’s <figcaption>:

<figure>
    <img src="…" alt="…">
    <figcaption>Illustration: Rare Digits</figcaption>
</figure>

Blockquote

A good quote is like a well-timed assist in basketball—it brings someone else’s brilliance into play exactly when you need it. Blockquotes give voice and weight to borrowed wisdom, letting other people’s words do the heavy lifting while you focus on connecting the dots.

The quote is a strange literary device. It allows us to borrow authority we haven’t earned, to dress our modest thoughts in borrowed finery.

Yet there’s honesty in the quote, too. It admits that all our ideas are built on foundations laid by others. Every writer is, in some sense, a plagiarist—not by theft, but by inheritance.

Jorge Luis Borges, “The Library of Babel and Other Essays”

In Rare Styles, <blockquote> are set apart with comfortable margins and a subtle background treatment—enough to signal “this is someone else talking” without turning your page into a ransom note made of clippings. Citations are handled through the <cite> element, because proper attribution is the difference between scholarship and plagiarism, and we prefer the former.

.boilerplate

A muted block for text notes, fine print, or a short standing notice, set off from the prose by a top rule and a leading info marker. Each <p> inside carries the marker, so the block reads as a small notice about the page rather than part of the argument. The glyph is drawn from the library’s SVG icon set (an SVG mask on ::before). Harvested into the library in v0.6.15.

Rare Styles is a narrow, professional CSS library for clarity-first longreads and decision-first data views — not a general-purpose framework.

.callout

A short notice between two thin rules: small, muted and centered. Use it for a tip or a side remark the reader may skip.

Tip: the same shortcut works in every view.

When the reader must not skip it, add a variant. The notice then reads at full strength, left-aligned in the body text color, with a stripe on the left. An information notice takes a stripe in the text color (black on the page, light on .card-inverted) and no fill; a state takes the stripe in its role color and a fill of that color at 25%, the role’s -bg mix, worked out on the callout itself, so a role re-mapped on a surface re-colors both:

Info. The table below is updated every Monday.

Done. All 14 checks passed.

Experimental. This chart type is outside the 1.0 stability guarantee: its options may change.

Error. The data source did not respond; the figures are from yesterday.

<p class="callout callout-warning">
    <strong>Experimental.</strong> Its options may change.
</p>

The four variants — .callout-signal, -success, -warning and -danger — go next to .callout. The three state variants take their color from the semantic role of the same name, so a project that re-maps --warning re-colors its warnings too. .callout-signal is plain information: its stripe is the text color, --primary-text-color, with no fill, so it does not compete with the states. The aliases (--positive, --negative, --neutral, --fail) are the same colors as their roles and have no variants of their own. The color is never the only cue: name the state in the first words. A callout that must be announced as it appears, such as a form error, also needs role="alert" on the element; the class does not add it.

Definition Lists

A plain <dl> is styled directly: readable spacing, bold enlarged terms, and extra separation before each new term. Use it for glossary-style or principle-style content where each term introduces a short block — the manifesto principles are set exactly this way.

Clarity first
Every component should help the reader decide faster, not admire the styling longer.
Scannability
Dense information should still reveal structure at a glance.
Narrow scope
Rare Styles is for longreads and decision-first views, not for general-purpose UI theming.

.dl-grid

The grid variant turns a definition list into a compact key:value grid. Use it for metadata, settings summaries, technical facts, or small inspection panels.

Version
v0.6.14
Status
In progress
Next release
v0.6.14_1

dt > code inside .dl-grid is intentionally rendered at normal weight, so code-like keys do not become too heavy.

.tag

A topic label on an article, a feed entry or a tag cloud: muted text in a light outline that takes the primary colour on hover. The open background, the softer corners and the text face keep it apart from <code>, a gray box in the monospace face. Put it on the link to the tag’s page; the # is part of the text, if the site marks tags that way. The line height leaves room between rows when a cloud of tags wraps.

#release #typography #audit

<a class="tag" href="/tags/release/">#release</a>

<code> and <pre>

Inline <code> is set in the code face, a step smaller than the text, in a light gray box with a thin frame. A long token, such as a path or a call, breaks anywhere rather than widen the page. In a table’s scroll box it keeps its shape.

A <pre> is a gray block that hangs into the left margin by as much as its padding, so the code lines start on the text edge. On a phone it hangs by 8px and its padding is 16px. Lines do not wrap: a long one scrolls sideways. The <code> inside drops its box, and .code-comment mutes a comment in it:

// The lines start on the text edge
<pre><code>…</code></pre>

Figures

A <figure> inside an <article> is styled directly: it sits on the reading measure, its image fills it, and its <figcaption> reads as a quiet note under it. Outside an article, add .figure for the same treatment — in a card, a section or an island. Carousel slides keep their own layout.

An illustrated poker table seen from above, cards and chips mid-game
An ordinary figure keeps to the measure of the prose around it. Illustration: Rare Digits

.figure-source

The source or credit line, set on its own line in a smaller size at the end of the caption. A long URL in it breaks rather than widening the page.

<figure class="full-width">
    <img src="chart.png" alt="What the image shows" width="1648" height="720" loading="lazy">
    <figcaption>
        The caption says what to take from it.
        <span class="figure-source">Source: …</span>
    </figcaption>
</figure>

Epigraph

The whole of science is nothing more than a refinement of everyday thinking.

— Albert Einstein

A <figure class="epigraph"> sets a short, attributed quotation at the head of a section or page. Unlike a blockquote, it is small, italic, and right-aligned — a voice from outside the text, placed at the threshold rather than woven into the argument. It is a figure with its own layout: the article figure rules above do not apply to it.

Keep epigraphs brief. Their job is to set a tone before the reader enters, not to carry an argument.

Widths

A figure takes the library's generic width classes, the same ones any block uses. With each of them the caption stays on the reading measure. Inside a card or a collapsible they all simply fill the content width.

.full-width

The full width of the content column — the article, not just the prose.

An illustrated figure doing a split between two ledges
The full-width figure spans the column. Illustration: Rare Digits

.text-content-caption

The caption width that the lead and the highlight use, --text-content-caption: the measure plus an outdent on both sides.

An illustrated figure doing a split between two ledges
The caption-width figure steps just past the prose on both sides. Illustration: Rare Digits

.full-width-caption

Outdented on the left like .caption, and out to the edge of the content column on the right, like pre. .card-caption is the same class under its older name.

An illustrated figure doing a split between two ledges
The widest figure: the outdent on the left, the column edge on the right. Illustration: Rare Digits

Images that load well

  • Always set width and height to the image's real pixel size. The browser reserves the box from them, so the text does not jump when the image arrives; CSS still scales the image to the column.
  • Write alt for what the image says in this article, not what it looks like in general. A purely decorative image gets alt="". The caption is not a substitute: it is read after the image, and only when there is one.
  • Add loading="lazy" below the fold, never on the first image a reader sees. The browser then fetches the image only as the reader scrolls near it. With JavaScript turned off, browsers load lazy images straight away — by design, so nothing is lost.
  • Offer sizes with srcset and sizes. The ordinary figure is at most the reading measure (about 800 px on the widest desktop, the full screen on a phone): sizes="(width < 769px) 100vw, 800px". Producing the image files is your build's job — the library only lays them out.

Tips

Cheatsheet

Teasers

Next:

Colors