φ-css

Install

One stylesheet. Use the bundled file in production, the source entry while developing.

Build dist/phi.css with npm run build. It runs every check first and refuses to build if one fails.

Page template

A minimal accessible starting point.

Adding your own CSS

Your styles win without !important. Either leave them unlayered, or join the layer stack.

Use semantic tokens (--color-*, --space-*, --step-*) rather than raw values, so your CSS follows the theme, contrast mode and brand automatically.

Browser support

Chrome / Edge 123+, Safari 18+, Firefox 128+.

Cascade layers

Later layers always win, regardless of selector specificity.

!important is banned. Inside layers it reverses priority, so the reset layer would win.

Token tiers

Primitive values feed semantic tokens, which feed component tokens. Your code uses the middle tier.

State comes from ARIA

There are no state classes like .is-active. Components read the attribute that assistive tech reads, so wrong semantics look wrong.

Example: the attribute is the style

Remove aria-current, aria-invalid, checked or disabled and the styling goes with it. No class to keep in sync.

Grid & rhythm

Every size lands on a 4px / 8px grid, so any stack of elements stays aligned.

• Spacing follows Fibonacci numbers snapped to 8px: 8, 16, 24, 32, 56, 88, 144.
• Type follows 16 × 1.272ⁿ (√φ) rounded to 4px; every line height is a multiple of 4px.
• Bordered components subtract the border from their padding, so the outer box stays on the grid.
• Add .debug-baseline to any element to overlay the grid.

Light & dark

Follows the OS by default. Force a theme on any element with data-theme.

Each semantic color is declared once as light-dark(light, dark) and resolved by color-scheme, so native controls and scrollbars switch too.

Contrast & forced colors

Three levels, all automatic.

Opt a page out of the OS high-contrast preference with data-contrast="standard" only if you provide your own setting. Forced colors cannot be emulated here; test with Windows Contrast themes or the browser's DevTools rendering panel.

Brand color

Write one line of CSS. The whole brand ramp is derived in the browser; no tools needed.

• Hue comes from your color. Lightness comes from the fixed ladder, so contrast never changes. Chroma is capped to what the screen can show for that hue.
• Every possible input is checked in CI: 720 hues × 21 chroma levels, both themes, both contrast levels. Any brand color is safe.
• Your exact hex will not appear on buttons: bright brands (orange, yellow, cyan) become darker at step 700.
• Keep your brand hue away from the status hues (red ≈ 12°, amber ≈ 66°, teal ≈ 165°) so primary and danger buttons don't look alike.

Brand scope

Give one section its own brand color with .brand-scope.

The class is required. Custom properties resolve var() where they are declared, so the brand-derived tokens must be declared again on the scope element. High-contrast and forced-color modes cover scopes too.

Reduced motion

With prefers-reduced-motion: reduce, every --duration-* token becomes 0ms.

Use the duration tokens in your own transitions and you get this for free.

Space

Fibonacci numbers snapped to the 8px grid.

Type

16 × 1.272ⁿ rounded to 4px. Always pair a step with its leading.

In markup, the .step-N utilities set both at once: <p class="step-2">.

Also: --font-sans, --font-mono, --weight-regular | medium | semibold | bold, --measure (66ch).

Shape, size, motion

Color

Use these. Each one adapts to theme, contrast mode, forced colors and brand.

Never use primitives such as --brand-700 or raw values: only semantic tokens follow theme, contrast mode, forced colors and brand.

Container

Centred page width with side padding (16px, 32px from 48rem).

Tokens: --container-pad. Max width is --container-max.

Stack

Vertical rhythm between children.

data-gap: 2xs | sm | md | lg | xl | 2xl (default xs, 16px). Token: --stack-gap.

Cluster

A wrapping row, e.g. buttons or tags.

data-gap: xs | sm (default 8px). Token: --cluster-gap.

Switcher

All children in one row above a threshold, all stacked below it. Never a 2 + 1 split.

Tokens: --switcher-threshold (40rem), --switcher-gap. Five or more children always stack.

Flow

Spacing for long-form content: more space above headings, less below.

Applies to direct children. Headings (h2–h4) get --space-lg above and --space-2xs below. Token: --flow-space.

Golden split

Two columns in exactly φ : 1 (61.8% / 38.2%). Wraps when they no longer fit.

data-flip puts the minor column first. Tokens: --golden-min (15rem minor basis), --golden-gap.

Sidebar

Fixed-width side column plus a fluid main column. Wraps when main would drop below 61.8%.

data-side="end" makes the last child the sidebar. Tokens: --sidebar-width (15rem), --sidebar-content-min, --sidebar-gap.

Grid

As many columns as fit. Cards with data-subgrid align title, body and actions across the row.

data-min: sm (9rem) or lg (24rem); default 15rem. Tokens: --grid-min, --grid-gap, and --card-rows (default 3) on subgrid cards.

Frame

Aspect-ratio box, golden (1.618 : 1) by default. Media inside is cropped to fill.

data-ratio: portrait (1 : 1.618) or square. Token: --frame-ratio.

Cover

Full-height block: first and last children pin to the edges, .cover__principal centres.

Tokens: --cover-min (100svh), --cover-pad.

Reel

Horizontal scroll-snap strip. Each item is 61.8% wide so the next one peeks.

Always add role="region", a label and tabindex="0" so keyboard users can scroll it. data-item="sm" gives 38.2% items. Tokens: --reel-item, --reel-gap.

Bento golden

Four tiles in the Fibonacci subdivision of a golden rectangle (89², 55², 34², 21×34). Single column below 36rem.

Needs both elements: the outer one measures its width. Token: --bento-gap.

App shell

Page skeleton: sticky header, side nav, main, optional aside. This page uses it.

Single column below 48rem; nav + main from 48rem; three columns from 80rem when an aside exists. Tokens: --shell-nav, --shell-aside, --shell-header, --shell-min. The nav is never hidden automatically; collapsing it is up to you.

Button

Works on <button> and <a>.

Icon

Mask-drawn glyphs that take the current text color.

data-icon: close, chevron-down, chevron-start, chevron-end, check, plus, menu, more, success, warning, error, info. Size with --icon-size (1.25em). Icons are decorative: always aria-hidden="true", with the name on the control. Chevrons mirror in right-to-left text.

Card

A raised container. The border is transparent but real, so forced-color modes still draw its edge.

data-variant: outlined | sunken (default raised). Parts: __title, __meta, __actions (sinks to the bottom). data-subgrid: see Grid. Tokens: --card-pad, --card-gap, --card-bg, --card-border, --card-shadow, --card-radius.

Alert

In-page status message. Color is always paired with a shape and a text label.

data-status: success (circle), warning (triangle), error (octagon), info (square). Start the title with the status word. Use role="alert" only for urgent errors.

Badge

Small inline status label. Neutral without data-status.

Field & input

Label, control, hint and error. The invalid state is a thicker edge, an icon and a message, never color alone.

.input works on input, textarea and select. data-size="sm" for 32px. Link hint and error with aria-describedby.

Checkbox & radio

Native controls, sized to 20px and tinted with the brand.

Group with fieldset.choice-group + legend. data-inline lays the options out in a row.

Switch

A checkbox with role="switch". The thumb position shows state, not color alone.

Tokens: --switch-w, --switch-h.

Segmented control

Radios styled as joined buttons. Arrow keys work natively.

Table

Plain tables are styled already; .table adds options. Wide tables scroll inside their own region.

Give the scroll region role="region", aria-label and tabindex="0". The header checkbox needs your JS to select all rows.

Skip link

First focusable element on the page; visible only when focused.

Navbar

Brand, links and actions. The current page gets a thick underline.

Tabs needs JS

WAI-ARIA tabs. CSS styles the state; a few lines of JS handle selection and arrow keys.

Breadcrumb

Separators are decorative and hidden from screen readers.

Pagination

40px targets. Mark the current page with aria-current.

An unavailable link has no href, plus role="link" and aria-disabled="true".

Nav list

Vertical navigation. The current item gets a fill and an edge bar. This page's sidebar uses it.

Disclosure

Native <details>. The same name makes an exclusive accordion without JS.

Dialog & drawer

Native <dialog>: top layer, focus trap, Esc and focus return are built in.

data-size: sm | lg. data-variant="drawer": full-height sheet from the inline end. closedby="any" adds click-outside to close. The page stops scrolling while it is open. Token: --dialog-width.

Menu

An action list in a native popover: light dismiss, Esc and focus return with no JS. Anchored under its button.

Items are plain buttons and links reached with Tab. For full role="menu" arrow-key behaviour, add JS; the styles stay the same. Token: --menu-min.

Toast needs JS

Transient notification in a live region.

• If toasts close on their own, pause the timer while hovered or focused (WCAG 2.2.1).
• Anything the user must act on belongs in a dialog.
• A modal dialog covers toasts. Put the region in the top layer with popover="manual" if they must float above.

Hero

Eyebrow → display headline → lede → call to action, next to a golden frame.

Use h1 for the headline on a real page (the example uses h2 because this page already has one). Put an img, video or svg inside the .frame.

Chart

Styles for your SVG. Each series is encoded by color, dash, marker shape and fill texture, and labelled directly.

Copy the <svg class="chart-defs"> sprite from this page's source into your page once. Give every chart a text summary (aria-label) and ideally a data table. Use at most six series.

Utilities

Top layer: each one wins over any component.

.visually-hidden text is an alternative to aria-label for icon-only buttons. .hidden removes an element for everyone, screen readers included.

Accessibility checklist

What φ-css handles, and what your markup still has to do.

Handled for you

• Contrast: AA in standard mode, AAA in high-contrast mode, for every brand color.
• Visible focus ring on every interactive element.
• Status and selection never rely on color alone (shape, weight, position).
• Forced colors, reduced motion and right-to-left text.

Your job

• Set lang on <html> and add a skip link.
• Give every input a <label>, every icon-only button an aria-label, and every chart a text summary.
• Set state with ARIA: aria-current, aria-selected, aria-invalid, aria-describedby.
• Start status messages with a word ("Error:", "Saved") so meaning does not depend on the icon.
• Make scroll regions focusable: role="region", aria-label, tabindex="0".

Scripts & contract

For contributors. Every rule below fails the build.

Lint rules

1. No !important.
2. No raw color values outside src/tokens/.
3. No primitive tokens outside src/tokens/.
4. Every var(--x) must be defined, or have a fallback.
5. src/layout/: layout properties only, logical properties only, no color or type tokens.
6. No state classes (.is-active, .selected…); use ARIA and native state.

Contrast checks

Every semantic pairing in light and dark, standard and high contrast; the lightness-ladder invariants; chart luminance staggering; and an exhaustive brand sweep (every hue × chroma, all inside sRGB).