Typography and accessibility

The scale

Ten steps from --pf-text-xs (0.8125rem) to --pf-text-5xl. The display sizes are fluid: 5xl is clamp(3.25rem, 1.75rem + 6.2vw, 6rem), so a headline grows with the screen instead of jumping at a breakpoint. Body sizes are fixed, because body copy that changes size as you resize is disorienting rather than responsive.

The whole scale can be re-based by changing the root font size, and the ratio between steps is deliberately narrow: large jumps make a page feel like a poster and read like one. The tokens page has a live control for trying a different scale against real components.

Measure, and why it matters more than size

p and li carry a maximum inline size of --pf-measure, 66 characters. This is the one place the framework constrains content without being asked, and it is the single highest-leverage typographic decision on any page: a line you cannot track back to is a line nobody reads.

.long-read { --pf-measure: 72ch; }   /* looser, for large type */
.dense-ui  { --pf-measure: 52ch; }   /* tighter, for dense panels */

Override it per region rather than globally, and remember that the number is in ch units — it tracks the font, so a wider face automatically gets a wider column in absolute terms.

Three families, and their fallbacks

Each stack names a metric-matched fallback before the system fonts — "Bricolage Fallback" before "Trebuchet MS", and so on. Those fallbacks are real @font-face declarations with measured size-adjust, ascent-override and descent-override values, which is why the swap from fallback to web font moves nothing and cumulative layout shift measures 0.00 on a throttled phone. If you swap the display face for your own, generate new overrides for it rather than keeping ours.

Wrapping, balance and hyphenation

• Headings use text-wrap: balance, so a two-line headline splits evenly instead of leaving one word alone on the second line.
• Body copy uses text-wrap: pretty, which prevents orphans without rebalancing the whole block. Firefox does not support it yet, so treat it as a polish pass rather than a layout you depend on — the paragraph wraps normally there.
• Below 30em, h1, h2 and h3 may hyphenate. This exists because a single long word at display size is wider than a 320px screen — the page scrolled sideways before it was added. It needs a lang attribute on <html> to work, which every page should carry anyway.
• Inline code wraps and may break inside a token when the token alone cannot fit a line. It used to be nowrap, which made every long identifier an unbreakable box that widened its container.

Prose blocks

.pf-prose is for a run of authored content — a blog post, a documentation page, anything from a CMS. It sets rhythm between elements so you do not have to put a class on every paragraph, and it constrains width with .pf-measure-prose or .pf-measure-wide.

<article class="pf-prose pf-measure-wide">
  <h2>…</h2>
  <p>…</p>
</article>

Inside a prose block you write plain HTML: headings, paragraphs, lists, tables, code. If your CMS emits markup you do not control, this is the class that makes it presentable without touching the output.

Tips

• Set the eyebrow and metadata in the mono family. Small text in a display face is where legibility goes first.
• Use font-variant-numeric: tabular-nums — or .pf-table--numeric — wherever numbers are compared vertically.
• Do not add weights you will not use. Each one is a font file, and the fallback has to be matched for every one of them.
• Check headings at 320px before shipping a new display face. That is where the word "Documentation" broke this site.

What is claimed, and what is not

A framework cannot make your site accessible — most of it is your content, your headings and your alt text. It can be responsible for its own components, and this is the honest accounting of which WCAG 2.2 AA criteria the framework carries versus which it can only help you meet.

Handled for you

Focus you can actually see

Tab through the two panes below. The right one has the ring removed — the single most common accessibility regression in a redesign, and usually introduced on purpose because someone thought the outline was ugly.

Contrast, measured rather than eyeballed

Both palettes are checked on every build. These are the numbers as shipped.

This is also why the accent darkens in light mode rather than staying put: the pastel green reads 6.7:1 on deep blue and 1.6:1 on near-white. A palette that does not change with its background is decoration, not a palette.

See the guards working

Three of the accommodations in this module are invisible until the condition applies. These switches apply them on demand, so you can check the behaviour without changing your operating system settings.

Still yours

No stylesheet can do these, and a framework that implies otherwise is selling something.

• Heading order. The framework styles h1 to h6; it cannot know whether your h3 should have been an h2. One h1 per page, no skipped levels.
• Accessible names. Every control needs a <label for>, an aria-label or an aria-labelledby. An icon button without one announces as "button" and nothing else.
• Alt text. Empty alt="" for decoration, a description for anything that carries meaning. There is no third option, and a missing attribute is not the same as an empty one.
• Landmarks. <header>, <nav>, <main>, <footer>, and an aria-label on a second nav so the two can be told apart.
• Language. <html lang> decides which voice a screen reader uses. Getting it wrong makes a page unintelligible rather than merely wrong.
• Link text. "Read more" four times on a page is four identical entries in a screen reader's link list.

Attributes that carry the styling

Several components style themselves from ARIA state rather than a modifier class. This is deliberate: a class and an attribute can disagree, and when they do it is the attribute that assistive technology believes.

Known limits

Three places where the CSS-only version is honestly weaker, all documented in the source of the component rather than here alone.

Right to left and i18n

Most "RTL support" is a second stylesheet that mirrors the first. This framework has no such file, because it never wrote a physical direction in the first place. Set dir="rtl" and the layout mirrors — margins, padding, borders, offsets, alignment, and the direction every component opens in.

Logical properties, everywhere

The rule is absolute inside the framework: no margin-left, no padding-right, no left or right, no text-align: left. Their logical equivalents describe the start and end of a line rather than a side of the screen.

The checker enforces this on every build, including the longhands. That detail matters: border-left-color slipped past an earlier version of the rule and three alert variants coloured the wrong edge under dir="rtl" for several releases. If you write your own rules, the same discipline is what keeps a mirrored page correct.

Setting a page up

<html lang="ar" dir="rtl">

That is the whole configuration. There is no class to add, no stylesheet to swap and no build flag. For a single mirrored region inside an otherwise left-to-right page, put dir on that element instead — the attribute inherits, and the logical properties follow it.

There is a complete mirrored page in the examples: right to left, using the same markup and the same classes as its left-to-right counterpart.

Why lang is not optional

• Hyphenation only works when the browser knows the language. The framework hyphenates large headings below 30em to stop a long word running off a phone, and that silently does nothing without lang.
• Screen readers choose a voice and pronunciation rules from it. An English voice reading French is close to unusable.
• Quotation marks, date formats and the correct font for a script all depend on it.
• Mark a passage in another language inline: <span lang="fr">.

Type across scripts

The bundled faces cover Latin only. For Arabic, Hebrew, Greek, Cyrillic, or CJK, add a face that covers the script and put it first in the family token — do not rely on the fallback chain to find something reasonable.

:root[lang="ar"] {
  --pf-font-sans: "Noto Sans Arabic", system-ui, sans-serif;
  --pf-font-display: "Noto Kufi Arabic", var(--pf-font-sans);
  --pf-measure: 58ch;   /* scripts differ in average character width */
}

Two things to re-check per script: the measure, because 66 characters of Arabic or Japanese is not the same line length as 66 of English; and the line height, because scripts with taller ascenders and descenders need more room than a Latin-tuned 1.65.

Numbers, dates and figures

Tabular figures (.pf-table--numeric) assume the font has them, which is true of the bundled mono face and not necessarily of a script-specific face you add. Format dates and numbers with Intl on the server or at render time rather than styling around a fixed format, and remember that numerals inside RTL text still run left to right — that is correct, not a bug to fix with CSS.

Checking your own work

Flip the page and look at it. Most mirroring bugs are visible in seconds: an icon on the wrong side of a label, a border on the wrong edge, an arrow pointing the wrong way. The things to look at first are anything with a direction — chevrons, progress, breadcrumb separators, and any illustration containing text.

document.documentElement.dir = 'rtl';

Paste that in a console on any page. If something does not mirror, the cause is a physical property — in your CSS, or in ours, in which case it is a bug worth reporting.