henry.css
A small, classless design system for responsive web apps, built to be used with coding agents. Write semantic HTML, link one stylesheet, and it looks ok. No build step, no dependencies, and no utility classes. Inspired by Vercel's Geist, GitHub's Primer, and Pico. Built for me and my projects, YMMV.
Site and reference: https://css.henrypoydar.com/
How it works
- Link the stylesheet. One file, in cascade layers. Link the latest release from jsDelivr, pin an exact one, or copy
henry.css into your project.
- Give your agent
DESIGN.md. Copy DESIGN.md into your repo and point your agent at it. It lists every element, class, token, and rule, so the markup your agent writes fits the system.
- Write semantic HTML. A form, a table, a nav, or a dialog looks right with no classes. Add a class or custom element only where
DESIGN.md lists one.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/henrypoydar/henry.css@latest/henry.css">
Why it's small
Coding agents write better UI when the whole system fits into a context window. henry.css keeps the surface area tiny on purpose.
- Elements first. Most of the stylesheet styles plain HTML elements.
- Three custom elements.
ui-card, ui-toast, and ui-empty, for things HTML has no element for. They're unregistered, so there's no JavaScript.
- A short list of classes. Button and badge variants, tabs, and four layout helpers.
- Tokens for every value. Colors, spacing, type, radii, and shadows are custom properties, with dark mode built in.
- Overrides without a fight. Everything sits in cascade layers, so any rule in your own CSS wins.
See every element, component, and layout on the reference site.
How henry.css is organized
Everything sits in cascade layers, declared in this order:
@layer tokens, reset, base, components, utilities;
- tokens: custom properties on
:root, plus the dark-mode block. Copy this block alone if a project wants only the values.
- reset: about twenty lines. Box sizing, margins, media defaults. Not normalize.css.
- base: bare HTML elements. This is most of the file. Text, headings, links, lists, tables, forms,
nav, dialog, details, figure, code.
- components: things HTML has no element for. Three unregistered custom elements:
ui-card, ui-toast, and ui-empty. Eight classes: button variants .secondary, .ghost, .danger, .small, the status label .badge with .success, .warning, .danger, and .tabs. That's the whole layer. No more.
- utilities: layout helpers:
.container (and .narrow), .grid (set --min), .stack and .cluster (set --gap), .cluster.between, .visually-hidden. Optional background textures: .pattern-dots, .pattern-grid, and .pattern-diagonal.
Layers mean any project CSS outside a layer beats every rule in henry.css, so overriding the system never takes a specificity fight.
Decisions
Base font is the system stack. The conventional modern one, copied from Bootstrap 6 and nearly identical to Tailwind 4: -apple-system and BlinkMacSystemFont for Apple devices, Segoe UI for Windows, Roboto for Android, Noto Sans or Liberation Sans for Linux, then Arial, sans-serif, and four color emoji fonts. It leaves out system-ui on purpose, because system-ui resolves to the locale's interface font and can render Latin text in, say, a Chinese system font. Pages get San Francisco on Apple devices, Segoe UI on Windows, and Roboto on Android, with no download, no third-party request, and no flash of fallback text. San Francisco and Segoe UI Variable are variable fonts with built-in optical sizing, so the 650 heading and 850 brand weights render as drawn and headings get a display cut. Where a platform font has only static weights, the browser rounds to the nearest one. Inter, Archivo, Geist, Mona Sans, and Roboto Flex were all tried. None beat the platform font enough to justify a download. A project that wants a brand font sets --font-sans.
Headlines are medium weight, not bold. Weight 650, line-height around 1.1 at display sizes. Body is 400, 16px, line-height 1.5.
Tracking follows Inter's dynamic metrics. Inter publishes a formula for tracking by size: -0.0223 + 0.185 × e^(-0.1745 × px), in em. It tightens gradually as type grows, from about 0 at 12px to -0.011em at body size and -0.022em at display sizes. There's one token per size from md up, and the values are rounded from the formula. Body text sets the md value and smaller text inherits it, since the difference is under a tenth of a pixel. Code stays at 0, because negative tracking crowds monospace. The formula was tuned for Inter, but it suits the system fonts too. Fewer than seven sizes in the scale.
The brand name is heavy. The page header's title uses --weight-brand, 850, so a product name like Acme reads as a wordmark, not a heading. Sidebar links are inset by the gutter minus their own padding, so their icons line up with the brand at every width.
Paper, raised, and sunken. The page is a warm paper tone, not white. Surfaces step from it in both directions: cards, form controls, and dialogs are raised a little lighter, and sidebars, code blocks, and empty states are sunken a little darker. The grays carry a faint warm tint at the light end, and the ink leans faintly cool, so the page reads as paper rather than a screen. Separate things with tone first, whitespace second, and a hairline last. Hairlines are translucent ink, so they sit right on any surface. A surface gets a border or a tone shift, never both. Tables get horizontal hairlines only, no vertical rules, no outer frame.
Ink for actions, one accent for meaning. Primary buttons are near-black. The accent, an ultramarine blue, is reserved for links, focus rings, selection, and checked controls, so color always carries meaning. Eleven-step neutral gray ramp, one accent ramp, semantic success/warning/danger.
Components are custom elements, modifiers are classes. A card, a toast, and an empty state are things that stand alone, so they're elements: <ui-card>, <ui-toast>, <ui-empty>. They're unregistered custom elements, which have been valid HTML and rendered as a plain block in every browser since custom elements existed. No JavaScript, no registration, and no article pretending to be a box. Button and badge variants stay as classes because they modify an element that already means something. Layout helpers stay as classes too, because layout is an adjective: <ul class="grid"> keeps the list, and a wrapper element can't go between a ul and its li.
Small radii, subtle shadows. 6px on controls, 8px to 12px on surfaces. Shadows only for things that float: menus, dialogs, and toasts. A card doesn't need one, because it's already lighter than whatever it sits on.
Icons are Phosphor, regular weight. Pasted as inline SVG from the excellent phosphoricons.com library with aria-hidden="true", so they take the size and color of surrounding text and need no font or package. Label the button or link, not the icon.
Background patterns stay quiet and optional. Dots, grids, and diagonal lines use CSS gradients with faint neutral marks that adapt to dark mode. Apply them as utilities to an existing surface, with tokens for color, spacing, and stroke. They preserve the surface color and content opacity. Use one texture sparingly, without adding a border.
Mobile navigation is an optional native disclosure. Add details with a summary and nav inside the page header to replace crowded header links and the scrolling sidebar strip below 48rem. The menu expands in normal flow and needs no JavaScript or component class. Larger screens keep the header links and sidebar.
Spacing on a 4px grid. Tokens from 1 to 16, with 4 and 6 doing most of the work.
Layout and responsiveness
Layout is where classless CSS falls short, so here's the standards we use.
- Fluid by default. The base layer makes type, media, tables, and forms respond before any layout rule exists. Type uses
clamp(). A table inside a figure scrolls sideways instead of breaking the page.
- Page structure from landmarks. The base layer lays out
body > header, main, footer, and aside. Header, main, footer is a page. Add an aside and it's an app shell: sidebar on wide screens, stacked on narrow ones. No classes.
- Intrinsic layout classes.
.container, .grid, .stack, and .cluster respond to available space on their own, without media queries.
- Four tiers. Phone, tablet at 48rem, laptop at 64rem, and desktop at 90rem. The sidebar goes from a scrolling strip, to compact, to full width, and big monitors get a wider container. Touch targets grow on coarse pointers regardless of width.
DESIGN.md has the details.
- Container queries inside layouts. A component that rearranges itself checks its own width, not the viewport's.
Every reference layout must resize from phone width to wide with no horizontal scroll. bin/snap reference/<page>.html renders a page at phone, tablet, laptop, desktop, and dark with headless Chrome.
License
MIT. See LICENSE.
