gelium-ui

Server-rendered UI components for Tailwind CSS 4 and HTMX. HTML-first, 0-JS contract by default; progressive enhancement for toast, validation swap, and slider fill.

This directory is the public gelium-ui npm package. The repository's site/ directory is only the Go docs/dogfood consumer; package contracts, templates, styles, skills, and release metadata are authoritative here.

Inspiration and boundaries

Gelium learns from public design systems and open-code libraries, including Material Design 3, USWDS, GOV.UK Design System, Mozilla Protocol, Base UI, Basecoat UI, Naive UI, shadcn/ui, Material Web, and Material Symbols.

These sources inform structure, tokens, accessibility, documentation, naming, and visual studies. Gentle AI also informs Gelium's outcome-first agent routing and delegation boundaries; it does not replace Gelium's UX contracts. Gelium reimplements those ideas as original semantic HTML, --ui-* tokens, server-rendered templates, and optional progressive-enhancement JavaScript. It does not ship their branding, assets, copied markup, or runtime dependencies. The full attribution and adaptation matrix is maintained in the repository acknowledgments.

Install

npm install gelium-ui

CSS (drop-in bundle)

<link rel="stylesheet" href="node_modules/gelium-ui/dist/gelium.css" />

Or from a bundler / CSS pipeline:

@import "gelium-ui/dist/gelium.css";

The prebuilt bundle includes Tailwind preflight, theme-material, theme-basecoat, tokens, and component styles.

Source styles (your own Tailwind entry)

@import "tailwindcss";
@import "gelium-ui/styles/index.css";
@import "gelium-ui/themes/theme-material.css";
@import "gelium-ui/themes/theme-basecoat.css";

Pick themes you need; Material, Basecoat, and the optional Neubrutalism direction ship with the package. For Neubrutalism:

@import "gelium-ui/themes/theme-neubrutalism.css";

Theme selection

Put the direction class on the document root:

<html class="theme-material">

Dark scheme (class route, no media-only dark):

<html class="theme-material theme-dark" data-theme="dark">

Consumer JS (optional)

<script defer src="node_modules/gelium-ui/js/gelium.js"></script>

Provides:

• HTMX 422 swap when X-Gelium-Validation: true
• gelium:toast region helpers
• Same-document view transitions guard (prefers-reduced-motion)
• Native range slider fill (--ui-slider-fill)

Templates

Copyable HTML partials live under templates/ (e.g. templates/button.html). Wire them with your server or paste into pages.

What this package is / is not

| Is | Is not | | --- | --- | | CSS + HTML open-code components | A React/Vue runtime | | Token + class themes | A full app framework | | Optional small JS enhancements | Required hydration |

Agent guidance

This package teaches LLM tools how to apply Gelium's good practices. When you write UI with an AI agent, start with the canonical routing layer:

• SKILL.md — discoverable wrapper for agent registries such as Gentle AI.
• skills/00-agent-routing.md — outcome-first route selection and delegation boundary.
• AGENTS.md — Gelium entry point: golden rules + how to read the guidance.
• skills/ — actionable decision skills for foundations, screens, forms, states, server contracts, a11y, architecture, criteria, approval, and references.
• llms-ux.txt — the compact decision-id pack (SURFACE / SCREEN / WF / DATA / FEED / JOURNEY / MEDIA / SKEL) for fast agent lookup.

Install the guidance as a project-local skill so every agent working in the consumer project can discover the same contract:

bash node_modules/gelium-ui/install-agents.sh
# writes .agents/skills/gelium-ui/

To install into a specific host's global skill directory instead, pass an explicit host option such as --claude, --cursor, or --codex. Use --target <path> for an agent host not covered by the shortcuts.

For projects using Gentle AI, refresh its project-local registry after installation:

./node_modules/gelium-ui/scripts/agent-start.sh .

Then select a task route explicitly when implementation begins:

go run ./cmd/gelium-preflight route --route delegated-direct --format json

The startup hook refreshes discovery only; it does not infer intent, enable SDD/RDD, or authorize delivery. See SKILLS.md for the full skill index.

Monorepo

This package is lib/ in gelium-ui. The docs site dogfoods it via npm workspaces.

License

MIT