I4NL4RS0N/lucet: AI interface components for the states real AI features actually hit — with a written rationale for every one

AI interface components for the states real AI features actually hit — with a written rationale for every one - I4NL4RS0N/lucet

Summary

Lucet is a TypeScript component library for AI user interfaces, distributed as two packages — lucet-core (framework-free state logic with no runtime dependencies) and lucet-react (thin React bindings). It targets the states that real AI features actually hit beyond the happy path: refusals, interruptions, rate limits, silent model downgrades, stale answers, and partial completions, alongside infrastructure for citations, versioning, multiplayer turns, and budget projection. The library is MIT-licensed, uses plain CSS custom properties, and ships without Tailwind, CSS-in-JS, or a build step.

What it is useful for

Engineers building chat or assistant interfaces in React can use Lucet for the edges of AI interactions that other component libraries leave improvised. The React layer ships twelve baseline components — streaming markdown, reasoning disclosure, tool calls with receipts, suggestion chips split between "ask" and "do", feedback controls, citations with aging, and version marker plus restore. The core is an event log, so history, versioning, restore, and presence are reads on a single source rather than features layered on top.

Four surfaces are supported out of the box: a scope ladder that reads the host app's own navigation, a budget meter that projects the next turn's cost per model before commit, version markers with restore-as-copy, and a single-writer turn lock that switches the thread to collaborative grammar when a second human speaks. Accessibility is treated as a gate rather than a final pass: every commit runs a Chromium-driven audit enforcing WCAG 2.2 AA across 44 theme, expression, and accent combinations, and every state is announced through silhouette, word, and tone — never color alone. Documented dependencies are minimal (lucet-core has none, lucet-react takes React as a peer), and bundled icons come from Lucide under ISC, attributed in NOTICE.

How engineers can use it

The README documents the install path:

npm install lucet-core lucet-react

Theming works by importing two stylesheets and optionally overriding the 21 documented color roles. Projects already using shadcn pick up Lucet's palette automatically, since each semantic token reads var(--shadcn-name, our-default). Icons are a slot, not a dependency, and can be replaced without forking.

For local work, the README provides:

npm install
npm run dev      # docs site on :4340
npm run verify   # build, typecheck, tests, and both audits

Documented limits: the project explicitly defers two components — an approval/consent gate and an agent task list — to a future release, and the full scope is described as "ten to twelve components done properly." For waiting patterns, the token contract, and the core thesis, readers are directed to docs/waiting.md, docs/tokens.md, and docs/thesis.md rather than the README.