Tokens, theming and motion

Palette

Raw values. Change these to shift the whole brand, or leave them and remap the roles below.

Roles

These are what components actually reference — no component reads a palette token directly, and the checker fails the build if one does. Override the roles and every module follows.

One colour in, a whole theme out

Hover, wash, line and ring colours are derived from the accent with color-mix(), so a theme can be a single declaration:

:root { --pf-accent: #d9734e; }

Buttons darken toward that colour on hover, badges and accent cards take a wash of it, emphasised borders and focus rings follow it. Override any derived token directly when the mix is not what you want.

One caveat, which is how CSS works rather than a choice: custom properties resolve where they are declared. Set --pf-accent on :root and everything follows. To retint one region, add .pf-retint to the element carrying the new accent — it re-derives the dependent colours there.

.promo { --pf-accent: #7aa7ff; }

<section class="promo pf-retint">…</section>

Readability

Six decisions, each of which can be overridden, and each of which was made in the same direction: toward the reader.

Headings also carry more space above than below, because a heading belongs to what follows it. Without that asymmetry a page reads as a list of fragments rather than as sections.

Type

Three stacks and a nine-step scale. The top four steps are fluid, clamped between a phone and a desktop width.

Try the scale

Three controls, six token overrides, no reclassing. The specimen below is ordinary markup — a heading, a lede, body copy and a card — reading whatever the stage declares.

Space and shape

Nine space steps from 4px, multiplied by a single density knob. Radii are deliberately few — angles do the distinctive work through --pf-cut.

Density

Set --pf-density on :root to make a whole site tighter or roomier with one number — 0.85 suits an admin screen, 1.5 an editorial page. For one region, use .pf-compact (0.8) or .pf-airy (1.4): they recompute the scale on that element, which setting the variable on a random element would not. See it on the components page.

Layout and motion

Four easings and four durations is deliberate. Libraries that ship thirty easings tend to get thirty different ones used, and motion stops feeling like one product. When a reader asks for reduced motion, Core shortens every transition and animation to effectively zero under prefers-reduced-motion: reduce, so anything you build on these tokens inherits that without extra work.

Renamed in 0.16 and 0.17

Palette tokens were named after hues, which is correct in one palette and wrong in every other: --pf-blue-800 held #f4f7fa in the cream theme and --pf-green held #ccff00 in the electric one. They now name position on a scale instead. The aliases file that kept the old names working was removed in 0.20, so update markup using the table below.

Light and dark

The framework ships dark and can follow the operating system. Only the palette is redeclared; every role, and therefore every component, follows.

The accent darkens in light mode rather than staying put. A pastel green that reads at 6.7:1 on deep blue reads at 1.6:1 on near-white — a palette that does not change with its background is decoration, not a palette. This site pins itself to dark because the dark page is its identity.

Adapting to the device

Six preference and capability queries are handled in Core, so a component never has to think about them.

Try it

Every control below sets one custom property on the stage. No classes are swapped and no script runs — the components re-render because none of them reference a raw value. This is the entire theming argument, made interactively.

Override the roles

Load your theme file after Core and redeclare on :root. Because components reference roles rather than the palette, this repaints buttons, links, focus rings, borders, alerts, tables and the mesh in one go.

:root {
  --pf-bg: #0f172a;
  --pf-bg-deep: #020617;
  --pf-accent: #38bdf8;
  --pf-accent-2: #fb7185;
  --pf-text: #e2e8f0;
  --pf-text-muted: #94a3b8;
  --pf-border: rgba(148, 163, 184, .22);
  --pf-border-strong: rgba(56, 189, 248, .45);
  --pf-focus: #38bdf8;
  --pf-base-950: #04121f;
}

Light islands

Add .pf-invert to any element — the body, one section, a single card — and the roles flip to a light palette inside it. Nested components follow automatically because they were never referencing the palette in the first place.

Shape and density

Two properties change the personality of the whole framework without touching a component.

• --pf-cut sets the depth of the clipped corner on .pf-facet and .pf-card--facet. Set it to 0 and every angular surface becomes a plain rectangle.
• --pf-radius-lg drives cards, plan cards, heroes and CTA bands. Drop it to 4px for a sharper, more technical feel, or raise it to 32px for a softer one.

Density is the space scale. Multiplying the four largest steps tightens every section, grid and stack at once, because nothing hard-codes padding:

:root {
  --pf-space-6: 1.5rem;
  --pf-space-7: 2rem;
  --pf-space-8: 3rem;
  --pf-space-9: 4rem;
  --pf-cut: 0px;
}

Scoped themes

Roles are inherited, so scoping a theme to part of the page is the same technique with a different selector. This is how you give one section its own accent without a second stylesheet:

.promo {
  --pf-accent: var(--pf-hue-2);
  --pf-border-strong: rgba(229, 177, 137, .45);
}

Everything inside .promo — buttons, links, markers, focus rings — picks up the orange. Everything outside is untouched.

Anatomy of a theme file

A theme is a stylesheet that redeclares roles. It loads after Core and nothing else about the framework changes. The nine shipped with the site are each under forty lines, and every one carries its measured contrast figures in the file header.

/* Monospace display face, no mesh, tight radii. */
:root {
  --pf-bg: #0d1117;
  --pf-bg-deep: #010409;
  --pf-text: #e6edf3;
  --pf-text-muted: #8b949e;
  --pf-accent: #7dd3fc;
  --pf-base-950: #04121f;
  --pf-font-display: "IBM Plex Mono", ui-monospace, monospace;
  --pf-radius-lg: 6px;
  --pf-cut: 0px;
  --pf-mesh: none;
}

The eleven roles that carry a theme

The one duty a theme cannot skip

Recolour the accent and you have changed the contrast of every button label, link and focus ring on the site. A pastel that reads at 10.7:1 on deep navy reads at 1.6:1 on near-white — the same hex, a different page.

Scoping a theme to part of a page

Roles are inherited custom properties, so declaring them on an element themes that subtree and nothing else. This is how .pf-invert works and how the playground retints a live page without touching the page around it.

/* One section on a warm palette, the rest of the page untouched. */
.promo {
  --pf-bg: #171310;
  --pf-accent: #f5b544;
  --pf-base-950: #1a1208;
  background: var(--pf-bg);
}

Two cautions. A scoped theme must set its own background, because redeclaring --pf-bg does not repaint anything by itself. And .pf-invert uses a doubled class to reach specificity (0,2,0), because a component declared later in the cascade would otherwise win with a single class.

Beyond colour

Motion in this framework is deliberately small: four easings, four durations, a handful of named animations, and one policy that overrides all of it. Everything here is optional — the Effects module is not part of a minimal page.

The reduced-motion policy comes first

Core collapses every transition and animation to effectively zero under prefers-reduced-motion: reduce, and it does so for your CSS as well as the framework's, because the rule matches everything:

@media (prefers-reduced-motion: reduce) {
  html { scroll-behavior: auto; }
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

Note that it completes animations rather than cancelling them. Slowing an animation that starts at opacity: 0 leaves the element invisible forever; finishing it instantly leaves the page in its end state, which is what someone asking for less motion actually wants. If you animate through JavaScript, check the query yourself — CSS cannot help you there.

Easings and durations

Four of each is a deliberate limit. A system with thirty easings gets thirty different ones used, and motion stops reading as one product. Read the tokens directly in your own transition — transition: opacity var(--pf-duration-2) var(--pf-ease-out) — which is what the utilities that wrapped them did, in one line, in the place that needs it. For a blanket transition, .pf-transition and .pf-transition-colors remain.

Named animations

.pf-animate-fade, -rise, -pulse and -spin. To stagger a small set, set animation-delay on the items yourself, and resist staggering a large one: past about five items a stagger stops reading as choreography and starts reading as lag.

<li class="pf-animate-rise">One</li>
<li class="pf-animate-rise">Two</li>

/* in your stylesheet */
.steps li:nth-child(2) { animation-delay: var(--pf-duration-1); }
.steps li:nth-child(3) { animation-delay: var(--pf-duration-2); }

Scroll-driven reveals

.pf-reveal and .pf-reveal-soft fade content in as it enters the viewport, using a scroll-driven animation timeline rather than an intersection observer — no script, and no work on the main thread when nothing is scrolling. Engines without support show the content immediately, which is the right fallback.

One caveat worth knowing if you write tests: an element waiting to be revealed sits at reduced opacity, so an automated contrast check run before it scrolls into view will report a failure that no reader ever sees. Run such checks with reduced motion emulated.

Surface effects

• .pf-frost for a frosted panel over content, with a solid fallback where backdrop-filter is missing.
• .pf-gradient-accent, -surface, -deep, -edge and .pf-gradient-text — all built from role tokens, so they follow the theme.
• .pf-rule-fade for a hairline that fades at both ends.
• .pf-ring, .pf-focus-ring and .pf-hover-lift for interactive affordances.

The particle field

.pf-particles puts a drifting field of accent-coloured specks behind a hero or title band. It is two pseudo-element layers of radial gradients at different sizes and speeds — no canvas, no script, no extra DOM node.

<section class="pf-hero pf-particles"> … </section>

.hero-quiet {
  --pf-particle-size: 160px;     /* spacing of the field */
  --pf-particle-opacity: 0.3;    /* how present it is */
  --pf-particle-speed: 140s;     /* slower drift */
}

Two variants swap the round specks for SVG tiles: .pf-particles--mesh draws the triangle motif the brand already uses, and .pf-particles--constellation draws points with lines between them. The SVG is used as a mask rather than a background image — a data URI cannot read a custom property, so a tile with the colour baked in would ignore every theme. Masking a plain --pf-accent fill takes the shape from the SVG and the colour from the token.

It paints behind content in an isolated stacking context, takes no pointer events, and animates only transform and opacity — so it cannot move layout, cannot cost a layout shift, and cannot intercept a click. Under reduced motion it stays visible but still.

A note on restraint

Every effect here is opt-in and none of them are load-bearing: remove the Effects module and the page still works, still reads, still submits. That is the test to apply to your own additions. If removing an animation breaks comprehension, it was carrying meaning that should have been in the markup.