Getting started
Felt and clean
felt-css comes in two looks. One attribute on the page switches between them, and nothing moves when you do.
View page source on GitHubOn this page
Switching looks#
Without any attribute you get the clean look: flat surfaces, hairline borders, Bootstrap-like. Add data-look="felt" to the <html> element and the same page is cut from wool felt and sewn together.
<html lang="en" data-look="felt">The look is for the whole page: data-look only acts on <html>. (Colour modes are different: data-bs-theme works on any element.) Try it with the Felt / Clean switch at the top of this page: every example in these docs follows it.
Remembering the choice#
felt-css doesn't store anything itself. If you offer a switch, set the attribute before the first paint so the page doesn't flash, for example with a tiny inline script in the <head> — this is what these docs do:
<script>
(() => {
let look = null
try { look = localStorage.getItem('look') } catch {}
document.documentElement.dataset.look = look === 'clean' ? 'clean' : 'felt'
})()
</script>How the felt works#
Two felt recipes#
Saturated pieces (buttons, stat tiles, badges, the active pagination item) are patches: grey felt blended soft-light onto the colour, a soft cut edge and a cast shadow. Light surfaces (page, cards, alerts, list groups) are quiet felt: cream felt blended multiply, flat, at the same fibre scale. The grey felt is SVG noise; the cream felt is a photo. In dark mode the sheet is charcoal felt, also a photo.
Thread#
Seams are drawn 9-slice SVGs, taut stitches in a pressed groove, laid on with border-image; pills and square pieces get a seam that follows their edge, and round pieces one drawn for their size. They're tinted with mix-blend-mode: hard-light, so the thread is always a tone of the felt underneath: lighter on colour, a shade darker on cream. Dividers inside a piece (card headers, table rows, .vr, <hr>) are single rows of stitches. Border utilities are thread too: .border-{colour} dyes a piece's seam, and a bordered element without one gets a seam of its own (Firefox keeps the plain line).
Never moves#
The felt layer only changes colours, textures, shadows and seams — never padding, borders or fonts. Toggling the look doesn't shift a single pixel, so you can design in clean and switch to felt at the end, or let your users choose.
Opt-out friendly#
All felt rules sit in @layer felt, each under :where(:root[data-look="felt"]), with the specificity of the component's own selector (.card stays one class). Unlayered CSS of yours always wins over the layer. To tune the felt, change its tokens (see Felt tokens).
Weight#
felt.css is about 38 KB gzipped. The felt textures and seams in img/ add about 48 KB and are only downloaded when the felt look is on.
Rebuilding the assets#
tools/build_assets.py draws the seam frames in img/ and their sizes into tools/feltgen/stitches.json; tools/build.py writes them into felt.css as tokens. Want longer stitches or rounder corners? Change LEN, PERIOD or SHAPES at the top of the script and run it again. The felts are photos: with --felt the script turns a photo of grey felt into the colours' felt (img/felt.webp), evenly lit, seamless and as strong as before.
python3 tools/build_assets.py # plain python3
python3 tools/build.py # the seam sizes into felt.css
python3 tools/build_assets.py --felt photo.png # needs numpy and ImageMagicktools/combos.html shows every surface with every button, badge, border colour and seam radius, to check a change in both themes (?theme=dark).