# HaTchi-MaXchi
**An htmx-native design system.** The polish of the modern component
aesthetic — complete states, disciplined spacing, dark as a material —
with zero client framework. Server-rendered markup, semantic classes,
OKLCH design tokens, and interactions built on the htmx request
lifecycle.
**[Browse the live gallery →](https://manwithacat.github.io/hatchi-maxchi/)**
Every example *is* its copy-paste snippet — the demo and the docs are the
same string, so they cannot drift.
[](https://github.com/manwithacat/hatchi-maxchi/actions/workflows/ci.yml)
[](https://manwithacat.github.io/hatchi-maxchi/)
[](LICENSE)
## Quick start
Hosted on the [jsDelivr](https://www.jsdelivr.com/) free CDN, pinned to a
release tag (fonts resolve relatively — no extra setup):
```html
```
Each [release](https://github.com/manwithacat/hatchi-maxchi/releases)'s
notes carry the ready-to-paste snippet with that version's SRI hashes
(a CI drift gate pins the committed `dist/` to the sources, so the tag
serves exactly these bytes).
Prefer self-hosting? Download the same two files (plus `fonts/`) from the
[latest release](https://github.com/manwithacat/hatchi-maxchi/releases)
or build them yourself (`python build.py`):
```html
```
Then copy any component's HTML from the gallery and point its `hx-*`
attributes at your endpoints:
```html
Approved
```
No build step, no JSX, no utility soup. One semantic root class per
component, `data-*` attributes for variants, tokens for every value.
## The unit is a Hyperpart, not a component
A React component bundles structure, behaviour, and *client* state into a
tree. HaTchi-MaXchi's unit is different enough to deserve its own name — a
**Hyperpart**:
> **Hyperpart** = a *partial* (server-rendered markup + classes) + its
> *exchange contract(s)* (the endpoint request/response the server must
> satisfy) + an optional *controller* (vanilla JS, only where the platform
> lacks a primitive).
The naming is deliberate. "Component" imports React priors — client state,
props, composition trees — which are exactly wrong for a server-owned
partial, and an agent told to build a "component" reaches for them. A
Hyperpart has no client state graph: state lives on the server and htmx
swaps the markup.
The second half — the **exchange contract** — is the part shadcn never had
to standardise (React resolves state locally). For interactive Hyperparts
the gallery documents it explicitly: *what request the affordance makes,
and what fragment your server must return.* It's a first-class, CI-checked
artifact (a partial that makes an undeclared request fails the build). In
Dazzle the response is emitted automatically; in any other htmx app, return
matching markup from your endpoint. (Vocabulary from *Hypermedia Systems*:
a request/response round-trip is a "hypermedia exchange"; the individual
`hx-*` control that initiates it is an "affordance".)
### Dual-locks — if Zod is for JSON, this is for the fragment
If you come from React / SPA land, you already have tools for *half* of this
problem — just not under one name, and not usually aimed at **HTML as the
wire format**.
| You're used to… | Rough HM analogue |
|-----------------|-------------------|
| **Zod / Yup / PropTypes** — "this value matches a schema" | **Schema half** of a dual-lock: a Pydantic model for host-trusted props (when the part has real data, not only a root) |
| **Testing Library / Playwright** — `getByRole`, `data-testid` asserts | **DOM half**: `DOM_CONTRACT` — root selector + required attrs (`data-dz-*`, stable classes) checked against emitted HTML |
| **TS props on a component** | "What the host may put in" — but enforced on **server-rendered markup**, not a client component instance |
| **Storybook + Chromatic** | Gallery exemplars + optional visual smoke; dual-lock is the **structural** CI gate, not the pixel judge |
| **OpenAPI for endpoints** | Closer to the **exchange contract** above (request/response + **exchange envelope**). Dual-lock is the *partial* side; the [swap contract](docs/decisions/0012-swap-identity-contract.md) is the topology side |
A **dual-lock** is the pair of gates that freeze **one Hyperpart** so design
system and host (e.g. [Dazzle](https://github.com/manwithacat/dazzle)) cannot
silently drift:
1. **DOM contract** (`contracts/.py` → `DOM_CONTRACT`) — the markup shape
is machine-checkable. Exemplars and host emissions must `validate_dom`.
2. **Schema** (optional Pydantic models + `render()`) — the data shape that
produces that markup. Present when there is a real emit path; absent on
many gallery substrates (**DOM-only** dual-locks).
**"Dual"** is load-bearing only when both halves exist (**schema+DOM**). A
**DOM-only** dual-lock is still a first-class CI contract on the stable root —
think "public DOM API for this part" — not a half-finished Zod schema.
**Why invent a term?** Neither half is novel. The *pairing* is what SPA
mental models under-name: in React the component *owns* the DOM, so a props
schema is enough; the tree re-derives markup. In hypermedia, **the fragment
is the API** — clients swap HTML, they do not re-render from a client state
graph. Freezing **data shape + markup shape** (or at least the stable root)
is how multi-host design systems and coding agents stay honest under
velocity. Inventory: [`DUAL_LOCK_COVERAGE.md`](./DUAL_LOCK_COVERAGE.md);
authoring path: [`contracts/AUTHORING.md`](./contracts/AUTHORING.md).
One sentence for a SPA colleague:
> Zod contracts JSON. A dual-lock contracts a Hyperpart's **HTML** (and,
> when present, the model that renders it) — both checked in CI.
### One unit, distributed by the build — the manifest keeps it legible
A Hyperpart's code is physically scattered *by build necessity*: its CSS
is concatenated in cascade-layer order (so it lives in `components/*.css`
accumulators), its controller is bundled (`controllers/`), and its markup
and contract are in `site/registry.py`. We can't co-locate everything in one
file like shadcn — but the relationship must stay legible, both to an agent
and a human. Two mechanisms, kept honest by a gate:
- **Top-down** — the registry entry is the *manifest*: `partial` and
`exchanges` inline, `controller` and `mock` as pointers.
- **Bottom-up** — each CSS block and controller carries a
`/* HYPERPART: */` marker, so opening any file tells you which
Hyperpart it serves. Styles are *discovered* from these markers (a
component's CSS is genuinely many-to-many across files), not hand-listed.
`python tools/hyperpart.py ` assembles the full anatomy (including who
embeds / refuses this part):
```
$ python tools/hyperpart.py command
Hyperpart: command (Command palette)
partial site/registry.py (inline markup)
exchanges GET /app/command
styles components/hm-core.css:256
controller controllers/dz-command.js
mock /mock/command
```
**For coding agents:** start at [`AGENTS.md`](./AGENTS.md) (curriculum, stems,
layers, invention ladder). Procedures: `docs/agent/`. Constitution:
`docs/decisions/`. Do not treat the gallery mock as the product API.
**Consistency tools (committed + CI drift gates):**
| Tool | Output | Purpose |
|------|--------|---------|
| `tools/consumer_map.py --write` | `CONSUMER_MAP.md` | Reverse composition index + explicit non-compositions |
| `tools/contract_surface.py --write` | `CONTRACT_SURFACE.md` | DOM/model surface breaking-change detector |
| `tools/dual_lock_coverage.py --write` | `DUAL_LOCK_COVERAGE.md` | Dual-lock inventory (schema+DOM vs DOM-only) — see [Dual-locks](#dual-locks--if-zod-is-for-json-this-is-for-the-fragment) |
| Gallery Pages (`site/build_site.py`) | `site/hyperparts/*.html`, `site/guide.html` | Human-facing **Server exchange** + **Swap contract** (envelope column); rebuild after registry envelope changes |
`tests/test_hyperpart_cohesion.py` fails CI if the manifest and the markers
disagree (unowned controller, orphan marker, interactive Hyperpart with no
style marker, controller not marked). The gallery shows the same anatomy
inline for interactive Hyperparts.
## Why htmx-native (not transliterated React)
Most design systems assume a client framework owns the DOM. HaTchi-MaXchi
assumes **the server owns the DOM** and htmx swaps it:
- **The command palette** is an input with `hx-get` — results are a server
swap, scoped to the signed-in user, not a client-side index.
- **Confirm dialogs**: any element with `hx-confirm` gets the designed
dialog automatically (`dz-confirm.js` intercepts `htmx:confirm`) — no
per-button wiring.
- **Loading, empty, and error states** key off the htmx request lifecycle
(`htmx-request`, swap events), so states are complete by construction.
- **Menus and popovers** are ``/`