Fundamentals
Concepts that apply across the whole library. The two tables below are the entire mental model — every component page assumes them.
How HC works (the six conventions)
Section titled “How HC works (the six conventions)”| Convention | What it means in your templates |
|---|---|
Semantic classes — hc-<block>__<part>, variants via data-variant / data-size | You emit meaningful class names from the server; there are no utility classes to compose. |
State lives in HTML attributes — aria-*, data-*, native disabled / invalid | Re-render with different attributes and the look follows. No client state to reconcile. |
htmx attributes use the data-hx-* form (not hx-*) | Validators and templating tools that require data- attributes stay happy; both spellings work at runtime. |
| Behaviors never own the network — htmx does | URLs, routing, and responses stay in your server code. installX() functions are idempotent, return uninstallers, and auto-install from the zero-config /behaviors bundle (full list). |
Tokens are the visual source of truth — DTCG JSON → generated --hc-* custom properties | Theme by overriding variables (or use the Theme builder), never by editing component CSS. |
| Strings are translatable — behaviors read one message catalog | setMessages({ 'confirm.cancel': '…' }) covers every string a behavior injects (i18n). |
The five runtime axes
Section titled “The five runtime axes”All five are attributes on <html>; components re-resolve live — no
rebuild, no JavaScript.
| Axis | Values | Owns |
|---|---|---|
data-theme | light (default) / dark | Surface, text, and border colors. |
data-color | accent name (e.g. indigo) | The accent used by primary controls. |
data-neutral | gray-ramp name | The neutral gray family. |
data-density | comfortable (default) / compact / dense | Control heights, paddings, gaps. |
dir | ltr (default) / rtl | Writing direction — all components use logical properties. |
The section, in reading order
Section titled “The section, in reading order”- Naming — classes, data attributes, custom properties, events.
- Tokens — the DTCG token layers behind every
--hc-*value. - Layout utilities — intrinsically responsive layout primitives.
- Responsive design — the container-first strategy and where each tool fits.
- Internationalization (i18n) — translate the strings behaviors inject, with one message catalog.
- Accessibility — Forced Colors / Windows High Contrast support via CSS system colors.
- Writing UI copy — voice & tone for the strings your app renders: errors, toasts, confirms, empty states.
- Motion — the three-duration motion scale, easing curves, and when to animate at all.
- Icons — the inline-SVG stance and sizing conventions.
- Anchored positioning — the shared floating-placement machinery behind menus, popovers, and tooltips (internals; useful when debugging placement).
Interactive components rely on small JS behaviors — see the behaviors reference for the full roster and Installation → Behaviors for how they install and why they are idempotent.