Toolcrib

Hi! Welcome to Toolcrib, an AI-generated UI toolkit, targeting AI model consumption. The AI doesn't just create the code; it is an active design partner (with the human).

This file is the only human-created content in the whole repo! The rest was generated by AI, using various IDEs and AI models.

Can't wait to get started?

npx toolcrib init

Features

AI Optimized

• We repeatedly asked the models what their weaknesses were, and put guardrails up
  • Enforced by Typescript
  • Coerced via System Prompt
  • ES Lint Custom Rules
• Agent-directed layered documentation to guide models to patterns and anti-patterns
• llms.txt for discovery by your harness
• MCP for tighter integration

AI-First Documentation

• Built to aid the AI models in consuming Toolcrib "patterns" and knowledge
• A machine-readable component manifest (JSON) plus generated CORE.md — both derived directly from source, never hand-maintained, so they can't drift from what's actually there
• Contributor AGENTS.md with an accumulated log of real bugs found and fixed, so the same mistake doesn't get regenerated twice
• MCP uses the vendored source so it is always 100% accurate, not whatever is "in the registry"

Skill Enabled

• Applies to Toolcrib repo itself
  • Going to lengths to earn the trust of consumers, since this is AI generated
• Using Claude Code skills to provide additional levels of assurance
  • OWASP
  • Github Actions
  • ARIA Compliance

Tested & Hardened

• Committing to 95% test coverage!
• Unit tests, plus E2E coverage including real axe-core accessibility scanning and actual CSP nonce enforcement (not just attribute presence)
• CodeQL static analysis on every push, Dependabot on all five independent dependency trees, branch-protected main, and private vulnerability reporting enabled

Component Library

• Many production components across Layout Primitives, Containers, Overlays, Data Display, and Form Controls
• Built on Base UI and React Aria Components primitives — real keyboard nav, focus traps, and ARIA semantics, not approximated
• No style/className on any component — every visual axis goes through a typed overrides prop instead

Theming

• Built to counteract the Tailwind Soup of CSS classes applied inconsistently by models
• All aspects of styling (typography, margin, padding) are "slice" based and consistent
• HSV-derived CSS variable system with a four-layer override hierarchy (global → component-type default → contextual domain → per-instance)
• Color theory accurate via Harmonies (e.g. Analogous, Split-Complementary)
• Live, in-app Theme Editor — style without touching code, then bake presets into your own app at init
• Automatic WCAG contrast enforcement — no manually-picked color pair silently fails accessibility
• Responsive breakpoint framework via real @media CSS

Cross-Tree Communication

• Built to counteract the prop-drilling anti-pattern
• A single typed event bus replaces prop-drilling for anything that needs to reach across the component tree
• Router-agnostic navigation bridge and an auth:unauthorized announcement channel — wire your own app's routing/auth without toolcrib assuming either

Forms

• Zod-schema-driven — field binding, validation, and submission payload shape all derive from one schema, not hand-wired onChange/register() boilerplate

Vendoring, Not a Dependency

• Full-vendoring CLI (init/merge/doctor/apply) — the code lands in your repo as reviewable patches, same model as shadcn
• Every release download is SHA-256 checksum-verified before it's applied — a failed or missing checksum fails the install rather than silently skipping verification
• MCP and docs always exactly match what is installed

Rationale

Vibe coding UI is terribly painful. Getting an initial result is quite a rush, but long-term "tweaking" is a horrible affair of wasted turns adjusting padding, margins, etc. Unfortunately, models do not carry this out consistently, so there are extra turns/expense involved.

Even a task as simple as "add a button" is combinatorical. Do you want:

• a ghost button?
• A solid button?
• Round corners?
• Rounded edges?
• A label?
• ALL CAPS?!
• A glyph? Which glyph?
• The "primary" color?
• The "danger" color?
• Is there a "danger" color even defined app-wide?

Tailwind Version

<button className="px-4 py-2 rounded-md bg-blue-600 text-white font-medium
  hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2">
  Save
</button>

<button className="px-4 py-2 rounded-md bg-red-600 text-white font-medium
  hover:bg-red-700 focus:outline-none focus:ring-2 focus:ring-red-500 flex items-center gap-2">
  <TrashIcon className="w-4 h-4" /> Delete
</button>

Toolcrib Version

<Button variant="primary">Save</Button>
<Button subtheme="error" icon="🗑️">Delete</Button>

That's the whole decision — no CSS, no guessing what "error" resolves to.

It gets worse! Each time you ask for the "same" UI element, like a Toolbar, the model simply regenerates it anew. And it may use the same or similar styling it used last time. The same applies to popups, modals, forms, etc. So consistency is not likely.

After experiencing this "herding the cats" personally, we asked numerous different AI models about "whether a specially-designed toolkit optimized for AI model consumption" would be a good idea. They all said yes! So here it is!

Philosophy

Following the Rodney Dangerfield joke of "I told my doctor: It hurts when I do that. He said: Don't do that".

It starts with the visuals, but the rabbit hole runs deep!

Left to its own devices, the model works out a "fuzz" of tailwind-inspired ad hoc styling (aka The Prior). And it does this anew with each turn. And it looks great--at first blush. But then you start tweaking, and it falls apart. The problem is the model has no "memory" of the styles it has already generated, nor the semantics associated with them. There is no real "cohesion" to the output.

Toolcrib remedies this by (among other techniques) removing the model's ability to generate class or style attributes. Instead, the model is forced to use the components provided. This gives the model a solid foundation to build on. If the model wants a "button", it uses the <Button /> component. This Button component already knows how to be a primary button, a success button, etc. The model does not have to constantly re-specify that, for example. There is a single source of truth.

<Card>
  <Card.Header>Order #4471</Card.Header>
  <Card.Content>Shipped — arriving Thursday.</Card.Content>
</Card>

Padding, radius, border, shadow — all resolved from the theme, zero props for any of it.

This pain doesn't end at visuals! Modal forms, Drawers, Popups, all get one-shotted, and are unlikely to come with the required focus trap, etc. that is expected for correct operation. Want second Drawer or Modal? It gets rebuilt from scratch each time, and maybe it works the same as the first one!

The Floor and Guardrails

We introduce the QoS Floor where you apply a layer of functionality that ensures a certain Quality of Service (QoS) in the form of important UX axes and biased for AI model consumption.

The Floor provided by "unguided" code generation is fairly limited. You are subject to the myriad deficiencies Toolcrib was designed to eliminate.

This is just the tip of a long list of features unguided generation re-invents anew and inconsistently:

• Theme Control
• Layout Control
• Keyboard
• ARIA
• WCAG
• Focus Traps
• Portaling (e.g. Drawers and Modals)
• Form Validation
• Real Composite UI Components (e.g. Autocomplete, Combobox, DataTable)

The Floor and Guardrails you get with Toolcrib are extensive and multi-layer!

• Leverage existing hardened primitives (Base UI, React ARIA)
• Model Guidance
• E2E tests
• OWASP Scans
• ARIA Scans

The Floor raises itself over time through a reactive feedback loop of repair and redistribution.

Human-in-the-Loop (HITL)

Just having the model is not enough! A competent driver must operate the equipment. Models make mistakes on every turn, and without The Human to challenge it, all hope is lost!

The amount of structure in toolcrib is not a natural occurrence of AI; it is The Human introducing and guiding the AI, and letting it perform what it's best at.

Installation

Install before you get started vibe coding!

The deployment model for Toolcrib is "Full Vendoring" meaning you copy all the source into your repo. This is also how shadcn operates. This gives the model complete access to how the toolkit works, and allows the model to alter the toolkit for your specific needs.

Refer to the USER_GUIDE.md file for detailed instructions!

Examples

• feed-farmer-pwa — a real RSS/Atom feed reader PWA, not a component showcase: a small real product, fully client-side (IndexedDB + a service worker, no backend), built entirely with toolcrib — Zod-driven forms, the event bus, Tree, CommandPalette, Combobox, the live Theme Editor, UIGroup, Skeleton, and the responsive breakpoint framework. → Live demo
• founders-desk — a personal command-center PWA for a fictitious CEO who journals meeting notes and tracks discretionary/reimbursable spend, fully client-side (IndexedDB, no backend), built entirely with toolcrib — Tree + TabStrip + Splitter for the notebook, DataTable + the @visx BarChart + DatePicker for the ledger, Zod-driven forms, and CommandPalette quick-open across both. → Live demo

AI Guidance

The source code alone is not sufficient for good usage; you also get extensive System Prompt support in the ai-docs folder:

• AGENT/CLAUDE instructions
• component manifests in JSON
• knowledge base examples/anti-patterns
• new app and refactor specific templates

This is all auto-generated (for accuracy) and/or AI-composed; the model acknowledges its own weaknesses and guides around them.

To get the most out of Toolcrib, tell your AI agent to use it.

An AI agent (or search tool) encountering this project for the first time can also start from llms.txt — a curated map of the repo per the llmstxt.org convention — or llms-full.txt for everything inlined in one file. Both are generated, same as everything above.

The CLI will install these for you (as patches)!

Project

Project goals:

• Built by AI.
• Designed and Guided by Human-in-the-loop.
• Skills for dedicated scans: OWASP, Actions, ARIA.
• High test coverage.
• Unit and E2E test coverage.
• github actions suite.
• Transparency via AI Generated Discussions of design sessions.
• Extensive AI instructions describing the workflow (the agent must use).

Theming

Theming goals:

• Cohesive styling achievable without knowledge or desire of Tailwind/CSS.
• Take styling away from the AI, and give it to you (or the user).
• Retain the ability to style at fine grains.
  • Style Domains: localized visual style.
  • Layout Domains: localized layout style.
• OOTB Theme Editor, your easiest entry point to self-styling.
• Once you have "presets" nailed down, you can integrate them directly into your app during init.
• Automatically applies WCAG Contrast and Color Theory correctly.
• Pass theming capabilities directly to users!

Infrastructure

Infrastructure goals:

• Codify the boilerplate AI can get wrong or inconsistently apply.
• Reliability is in the framework, not your "vibe".
• Signal techniques that guide away from anti-patterns like prop-drilling.
• Leverage Base UI primitives for ARIA etc.
• Leverage other primitives where it makes sense.