HaTchi-MaXchi — an htmx-native design system (Hyperparts, not “components”)

[manwithacat]

Hi all,

I wanted to share a project that’s been cooking in the open and is aimed squarely at people building real apps with htmx (and at the coding agents that increasingly author that markup).

HaTchi-MaXchi is an htmx-native design system: server-rendered partials, semantic classes + design tokens, and a small amount of vanilla JS only where the platform doesn’t give you a primitive. The goal is the maturity of a modern component aesthetic (complete interaction states, dark as a material, disciplined spacing) without a client framework, SPA state graph, or “rebuild the world in JS.”

Live gallery (demo markup is the copy-paste snippet, so the two cannot drift):

https://manwithacat.github.io/hatchi-maxchi/

---

Why not just call them components?

Because “component” drags in the wrong priors.

In React-land a component bundles structure, behaviour, and client state into a tree. Agents (and a lot of human muscle memory) hear “component” and reach for props, local state, composition via imports, and JSON APIs.

That’s a poor fit for hypermedia. On the htmx path, the durable unit is closer to:

Hyperpart = a partial (server-rendered markup + classes)
+ its exchange contract(s) (what request the affordance makes, and what fragment the server must return)
+ an optional controller (vanilla JS, DOM-local state, only when needed)

A Hyperpart has no client state graph. Application state lives on the server; the DOM is the client’s working memory; htmx swaps markup. Controllers are document-delegated IIFEs — not a mini-React, not Alpine-as-framework-in-the-design-system.

The naming is deliberate. If you tell a model (or a junior engineer) to “build a component,” you get React-shaped answers. If you tell them to implement a Hyperpart, the job description is: this markup → this DOM contract → this exchange.

Vocabulary here follows Hypermedia Systems: the round-trip is a hypermedia exchange; the control that starts it is an affordance. We just made that first-class in the design system, not a footnote.

---

The half of the problem “component libraries” often skip

Most design systems that grow up around SPAs can get away without standardising what the server owes the browser. React resolves state locally; the “API” is often props and events.

Interactive Hyperparts can’t. If a button says hx-get="/…" and the server returns the wrong shape, the UI is broken even if the CSS is perfect. So the gallery documents, for interactive parts:

• Copy this — the partial (and the demo is that string)
• Server exchange — method, trigger, response fragment, swap intent
• DOM contract — root + required attributes (machine-checkable)
• optional controller notes

That’s the piece we treat as design-system surface, not app-private folklore.

Internally we call the freeze between design system and host a dual-lock (DOM contract ± schema): roughly “if Zod is for JSON, this is for the fragment.” It’s aimed at multi-host honesty and CI, not at making the gallery heavier to use. Standalone htmx apps can ignore the dual-lock machinery entirely and still copy markup + implement the exchange.

---

Design philosophy (short)

A few stances that show up everywhere:

1. Server owns truth. Markup is the payload. Tokens and data-* variants carry variation — not a second styling language of utility soup.
2. htmx owns navigation between states. Prefer morph-safe, stable surfaces for shells/tables/forms; replace disposable fragments. Stable ids and DOM-carried state are load-bearing.
3. Controllers are a last resort. Vanilla, delegated, DOM-local. No TypeScript runtime for shipped controllers; no Alpine-in-the-kit.
4. Touch is not an afterthought. Interactive Hyperparts should work under a finger, not only a mouse.
5. Demo ≠ contract. Gallery mocks (/mock/*, flash “Deleted (demo).” toasts) are scaffolding. Production implements the exchange row, not the mock host.

If that sounds like “just write good HTML,” good — the kit’s job is to make good the default, and checkable when agents or teams scale.

---

AI-first tooling (on purpose)

A lot of markup is now written by coding agents. We designed for that audience alongside humans, not as an afterthought.

What that looks like in practice:

• AGENTS.md — a short curriculum for agents: reconstruct judgement in order (stems → pick-a-surface → one-part pack → maps/CI), not “dump the gallery into context.”
• Stems — compressed claims (“Hyperpart ≠ component”, composition is declared, morph-safe hypermedia, …) so models reconstruct why, not only what.
• Per-part agent packs (agents/<id>.md) — Copy → exchange → DOM contract for one Hyperpart.
• Machine truth over prose — registry, dual-lock contracts, consumer/map CI gates. If the model and the maps disagree, the maps and tests are the organisation.
• Gallery interaction probes — automated “does this hyperpart still behave?” checks (Escape dismiss, exclusive tabs, confirm intercept, etc.), so agents can expand the system without silent regressions.

Humans still get a pretty gallery and glossary tooltips. Agents get tables, curricula, and gates. Same Hyperpart; different entry.

This isn’t “AI-generated CSS.” It’s agent-legible architecture: restricted vocabulary, explicit contracts, fail-loud checks.

---

Who it’s for

Audience	Fit
htmx4 apps you own	Copy partials, load CSS/JS, point hx-* at your endpoints, return HTML fragments.
Teams with coding agents	Curriculum + contracts so agents emit the right shape instead of inventing a SPA.
Dazzle (our higher-level app framework)	Optional host that already speaks Hyperparts; HM is still usable standalone.

Standalone path is first-class: two includes, gallery copy-paste, your server.

<link rel="stylesheet" href="…/hatchi-maxchi.css">
<script src="…/hatchi-maxchi.js" defer></script>
<!-- then real htmx, not the gallery mock -->

Releases on the repo include CDN/SRI notes; gallery: https://manwithacat.github.io/hatchi-maxchi/

---

What I’m hoping for from this discussion

• Feedback from people deep in htmx production: where does “Hyperpart + exchange” help, and where does it feel heavy?
• Gaps vs how you already structure partials and endpoints.
• Whether agent-facing packs/stems are useful outside our stack, or only when a host framework (like Dazzle) consumes them.

Happy to dig into dual-locks, swap/envelope vocabulary, gallery probes, or composition rules if useful — or just lurk and learn how others package hypermedia UI for teams and agents.

Thanks for reading, and thanks to everyone who keeps making hypermedia a serious alternative to “the SPA by default.”

—
Repo: https://github.com/manwithacat/hatchi-maxchi
Gallery: https://manwithacat.github.io/hatchi-maxchi/