Skip to content

20 Theming

Roberto Ferranti edited this page Sep 29, 2026 · 21 revisions

Theming

ful.css is the whole design system in one stylesheet, with no other stylesheet, icon font or javascript to load.

It rests on two ideas. Every visual decision hangs off a --ful-* custom property, and the styling hooks are the style-only tags the templates render, such as ful-control-group, ful-affix, ful-badge and ful-note.

What matters about the second idea is that the chrome matches the rendered structure, not a list of host tags. A component's css anchors on whatever hosts its pieces, as *:has(> ful-control-group) and *:has(> ful-toast) do. A subclass under any tag of your own therefore keeps the look, and so does foreign markup built from the same tags. The pre-render flash guards are tag-based, and so are a few rules keyed on a host itself: the menu's placement, the hiding of an empty toast region, the loading state of the sectioned components and the table's sort arrows.

Those guards keep an element invisible until it has rendered, rather than letting it show markup the author never meant to be seen:

ful-select:not(:state(rendered)),
ful-dialog:not(:state(rendered)),
/* … one entry per guarded tag … */ {
    visibility: hidden;
}

rendered is a custom state the base adds when a render completes, and it is deliberately not :defined. :defined is true from the constructor, which runs before the element has built anything, so a guard written against it reveals an empty element and hides only the wait for the class to arrive. The state marks the moment the dom exists.

What is guarded, and what is not

The guard is for an element whose own markup is misleading before it renders. A ful-select paints its slotted <select> as a native dropdown. A ful-dialog shows its modal body inline in the page flow. A ful-tabs shows every panel at once and then collapses to one.

An element whose markup already reads correctly is left alone, and the two that matter are worth knowing:

  • ful-form is not guarded. Its fields guard themselves, so hiding the host would additionally hide the submit button and any plain markup around them, trading a partly drawn form for a completely blank one, for longer.
  • ful-accordion is not guarded. It is <details> and <summary>, which the platform renders correctly on their own.

Guarding a field of your own

The list is tags, so a field you register under your own tag is not in it. Two ways in:

<x-rating class="ful-input" name="score">How did it go?</x-rating>
x-rating:not(:state(rendered)) { visibility: hidden }

The class is the same hook the library uses for a field rendered under a foreign tag; the rule is the explicit form. Either works, since both key on the state the base sets for every ParsedElement.

An element whose render threw never gets the state, so it stays hidden rather than showing chrome it never built. The failure still reaches the console, Rendering.waitFor and your error reporter.

The tokens

Base palette, defined on :root:

Token Default Drives
--ful-color / --ful-bg light-dark(#212529, #dee2e6) / light-dark(#fff, #212529) text and surfaces
--ful-border-width / --ful-border-radius 1px / 0.375rem every border and corner
--ful-border-color light-dark(#dee2e6, #495057) resting borders
--ful-disabled-bg light-dark(#e9ecef, #343a40) disabled surfaces, scrollbar track
--ful-selected-bg light-dark(#f8f9fa, #343a40) selected rows, chips (ful-badge) and selected dropdown items. Checked radio cards carry their own --ful-radio-group-label-checked-bg
--ful-active-color / --ful-active-bg white / #007376 the accent: active options, buttons, pagination
--ful-accent-ink the accent in light, lifted 55% toward white in dark the accent as text: ghost outlines, done steps, success toasts, hover chips
--ful-muted-color light-dark(#495057, #adb5bd) muted ink (resting tabs, quiet labels)
--ful-focus-border-color / --ful-focus-box-shadow derived from --ful-active-bg via color-mix the focus ring
--ful-invalid-color / --ful-invalid-border-color / --ful-invalid-box-shadow light-dark(#dc3545, #ea868f) + derived the invalid ring and error text
--ful-error-* / --ful-warning-* red / amber triads, light-dark() pairs like the rest ful-errors banner, ful-field-warning
--ful-scrollbar-* width 12px, track --ful-disabled-bg, thumb --ful-active-bg dropdown scrollbar
--ful-controls-bg/-border-width/-border-radius/-border-color alias the base tokens the control chrome
--ful-controls-height calc(1.5em + 0.75rem + 2px) density: every control's height
--ful-backdrop-color rgb(0 0 0 / 50%) the dialogs' and drawers' scrim

--ful-border-width, --ful-border-radius and the scrollbar widths are registered with @property (typed, inherited, with initial values), so they behave as real inherited custom properties everywhere.

Derived values are the point of the arrangement. The focus ring is color-mix(in srgb, var(--ful-active-bg) …) and the invalid ring mixes --ful-invalid-color, so retuning the accent moves every ring, glow and active surface with it. No colour is hardcoded where a token could carry it, though a few literals survive in inline svg strokes and the spinner backdrop.

Customizing

Override on :root for the page, or on any subtree to theme a region:

:root {
    --ful-active-bg: #6741d9;                 /* your accent: rings, actives, thumb follow */
    --ful-invalid-color: #b3261e;
    --ful-border-radius: 0;                   /* squarer */
    --ful-controls-height: 2.75rem;           /* denser or roomier, uniformly */
}

.sidebar {                    /* a dark pocket without a second theme */
    --ful-bg: #1c1f26;
    --ful-color: #e6e8ec;
    --ful-border-color: #333945;
}

Dark mode is light-dark(). The palette flips when the page declares color-scheme: dark, or light dark for automatic; the library declares nothing itself. Pinning color-scheme: light disables the dark side, per subtree included. If your brand defines explicit pairs instead, overriding the light-dark() tokens with plain values is equally fine.

The theme's ink pairs hold WCAG AA in both schemes, and a test suite computes the ratios on every run so they keep holding. Wherever the accent must be read rather than filled, use --ful-accent-ink: raw --ful-active-bg as text drops to 2.7:1 on the dark surface.

The overlay geometry is not on :root

Three tokens are declared on the component itself, not on :root, because each is a default the component needs whether or not the page sets one:

token declared on override on
--ful-dialog-width dialog.ful-dialog dialog.ful-dialog
--ful-drawer-width dialog.ful-drawer dialog.ful-drawer
--ful-toasts-max-width whatever hosts the toasts ful-toasts

A local declaration beats an inherited one, so setting the first two on :root has no effect at all: the component's own declaration wins. Override them where they are declared.

dialog.ful-dialog { --ful-dialog-width: min(90vw, 44rem); }
dialog.ful-drawer { --ful-drawer-width: min(90vw, 40rem); }
ful-toasts       { --ful-toasts-max-width: min(90vw, 30rem); }

Your layers and [hidden]

ful's css is layered, and every layer a page declares of its own comes after ful's, so an unimportant declaration of yours beats any of ful's whatever the selectors say. That is the point, and it costs one thing worth knowing about.

[hidden] { display: none } lives in ful.hidden, the last of ful's layers, deliberately without !important so a page can still override it. The browser's own [hidden] rule loses to an author display in exactly the same way, so this is the platform's behaviour rather than ful's. But a component rule of yours that sets display defeats hidden on its own elements by accident:

@layer app { .pane { display: flex; } }
<div class="pane" hidden>this shows</div>

Rather than patching each component as it bites, declare the rule once:

@layer app {
    [hidden]:not([hidden="until-found"]) { display: none !important; }
}

An important declaration inside a layer beats every later layer and unlayered css alike, so one line settles it for the whole page. The :not() keeps hidden="until-found" working, which is findable-but-hidden content the browser reveals on a find-in-page.

--ful-drawer-width additionally collapses to 100vw below 30rem of viewport, so a phone gets a full-width drawer; override inside the same media query if you do not want that.

Per-component namespaces

Components alias or extend the base tokens under their own prefixes, so one widget can be retuned without touching the system.

Prefix Component
--ful-dropdown-* the select dropdown: colors, border, scrollbar, radius
--ful-spinner-icon-* the spinner and a loading section's ring: size, border width, color, animation (--ful-spinner-icon-animation-name defaults to the ful-spinner-border keyframes)
--ful-radio-group-label-* radio card borders and the checked card's background
--ful-button-* the opt-in button chrome: height, borders, colors, hover pair
--ful-errors-color, --ful-errors-bg, --ful-errors-border-color a form's ful-errors banner, set on ful-errors
--ful-field-error-invalid-color a field's error text, set on ful-field-error
--ful-item-list-item-color, --ful-item-list-item-bg, --ful-item-list-item-border-radius the rows of a select's or a file field's item list, set on ful-item-list

The filter operator/sensitivity buttons keep a fixed min-width (4rem / 2.5rem) so filter rows never jiggle when the operator changes.

Icons

Icons are ful-icon elements: an empty inline box, 1em tall on a -0.125em baseline, painted with background-color: currentcolor behind an svg mask-image. They inherit text colour for free and scale with the font.

<ful-icon name="search" aria-hidden="true"></ful-icon>

Built-in shapes (from bootstrap-icons 1.11.3, MIT): search, chevron-left, chevron-right, chevron-down, arrow-clockwise, x-lg, info-circle, info-circle-fill (the tooltip's default, since the outline one goes noisy at 1em), upload, arrow-up, arrow-down, inbox, star.

Adding your own is one css rule per shape:

ful-icon[name='bell'] {
    mask-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='black' viewBox='0 0 16 16'><path d='…'/></svg>");
}

Where components pick icons it is static config, assignable before configure():

ful.Pagination.config = { ...ful.Pagination.config, reloadIcon: 'arrow-repeat' };
ful.Table.config = { ...ful.Table.config, searchIcon: 'magnifier' };

Structural hooks

Components render structure, classes are yours to add. The hooks that carry styling:

  • ful-control-group: the control's row. It rings on :has(:focus-visible), dims when disabled, and reddens when :invalid (see fields).
  • ful-affix: a cell inside the row, for icons, @ signs and buttons.
  • labels: the field's real <label>/<legend> is styled directly, required adds the * marker through ::before.
  • internal parts also carry data-ref attributes such as [data-ref=dropzone] and [data-ref=value1]. They are handy for targeted overrides, but they are the components' internals rather than a promised api, so prefer the tokens and the tags.
  • the disclosure and navigation family adds its own: ful-note (the tooltip bubble, or its .ful-note class on any element, sized by --ful-note-gap and --ful-note-callout-size), ful-toast (a toast item, whoever hosts them being the region), ful-tablist, ful-accordion-group, ful-steps, ful-table-wrapper, ful-pagination-bar, ful-radio-list and ful-empty (the stand-in for content that is not there, in an empty table and an empty dropdown alike).
  • ful-spinner is a style-only tag entirely: the glyph is its own pseudo-element, the label its light-dom children, role="status" (and any name) the author's to carry.

A ful-item-list row is as tall as a control, so a readonly field showing nothing but its list lines up with an ordinary input beside it. The height follows --ful-controls-height and --ful-controls-border-width, so a denser theme takes the rows with it. A focused row is outlined in --ful-active-bg rather than wearing --ful-focus-box-shadow, the one place the library departs from that ring: the row is filled with the accent, and a translucent ring of the same accent would be hard to see against it.

.ful-stacked, on a ful-checkbox, lays the choice out the way every other field is laid out: the label above and the control below it, a control tall, so a checkbox or a switch in a column of inputs lines up with them instead of sitting on one short line of its own. The control is drawn a little larger there, having no box around it to give it presence. Without the class the label stays beside the control, which is the right shape for a checkbox on a line of its own.

<ful-checkbox class="ful-stacked" name="urgent" type="switch">Urgente</ful-checkbox>

Buttons

The opt-in class chrome is .ful-button, with its .ghost, .soft and .small modifiers, which apply only alongside it:

class look
.ful-button a filled primary resting on the accent pair
.ful-button.ghost an accent outline that fills on hover
.ful-button.soft a neutral fill that turns accent on intent
.ful-button.small a shorter button in a smaller font

All of them theme through --ful-button-* and carry the canonical focus halo and disabled dimming. Any button or a wears them. Anchors have no :disabled, so aria-disabled="true" is what dims those.

When building your own components, reuse ful-control-group and ful-affix in your template: the chrome, focus and disabled styling arrive for free, and your control stays themeable by the same tokens.

Clone this wiki locally