Kookie UI

Kookie UI is a design system. A component library gives you parts and leaves the decisions to you. Kookie UI is the decisions: the rules, the patterns and the reason for each one. The components are how those decisions reach your screen.

Some design questions have measured answers. A fingertip needs a target of about 44 pixels, text needs enough contrast to read, and people group things that sit close together. Kookie UI applies these answers on every screen, and no prop can override them. Every other question is a judgment, such as a corner radius or the accent colour. Kookie UI makes each judgment once, in one place, so one change reaches every screen.

The same idea decides what a component is. Components are sorted by what they do, not by how they look, so tabs and a segmented control are two components, although both are a row of segments. Patterns, such as an app frame, a form or a dialog, are part of the system too, because consistency is won or lost where components meet.

The result is an app that stays consistent as it grows, because each decision is made in the system and not again in each file. Read the principles and the patterns at ui.kookie.design.

Pre-release. @kushagradhawan/kookie-ui-react is not on npm yet. Build the workspace to use it.

The rules that shape the API

• There is no variant prop. tone states what a thing means. emphasis states how loud it is. The two questions stay apart, so a quiet destructive action is expressible.
• A component sets no outer spacing. No control takes a margin prop. The container states every distance, through gap on Flex, Stack and Grid.
• size is an index, not a measurement. One numeral joins a designed set: the height, the inline padding, the corner, the icon box and the label step.
• No component sets a shadow. depth is one word on the Theme. Each family then decides what it does with light.
• No JavaScript runs at interaction time. CSS resolves hover, press, focus and validity from data attributes on the element.
• Every value is a token. No component stylesheet holds a raw pixel value or a colour.

Each of those is a refusal, and each refusal has a written reason and a stated escape.

Documentation

The site in apps/docs is the documentation. It has four parts.

route	what it holds
/	26 guideline chapters: getting started, patterns and foundations
/components	the reference for 64 components, with generated props tables and the refusals
/builder	a composition editor that exports React code and reviews the result
/preview and /matrix	the judging surfaces: real screens, and the axis grid
any path + .md, or Accept: text/markdown	the same page as markdown, for an agent
/llms.txt and /llms-full.txt	the index of every page, and the whole site in one file

Run it:

pnpm install
pnpm run build
cd apps/docs && pnpm run dev

Build the package first. The documentation app imports the built output.

AI agents

The library is built so that a coding agent learns it from the package rather than from you.

• A refused prop is a compile error that names the prop and says what to write instead — variant points at tone and emphasis, a margin prop points at Box.
• Every exported component carries its description in the shipped .d.ts.
• @kushagradhawan/kookie-ui-react/eslint-plugin catches the three mistakes the compiler cannot see: a data- axis attribute, utility classes or raw values in className and style, and a refused prop inside a spread. It brings no parser, so a TypeScript project puts it after its own parser entry.
• npx @kushagradhawan/kookie-ui-react init writes the library's rules into your AGENTS.md, CLAUDE.md or .cursor/rules. It prints its plan first and changes nothing without --write.
• @kookie-ui/mcp is an MCP server with four tools, including check_usage, which reports every refused prop, attribute, utility class and raw value in a piece of JSX.
• Every docs page is served as markdown at its path plus .md, and /llms.txt lists them all.

The AI agents chapter explains each one.

Repository layout

packages/ui     @kushagradhawan/kookie-ui-react: the components, the token generator, the ESLint plugin and the tests
packages/mcp    @kookie-ui/mcp: the MCP server, built from the documentation's own data
apps/docs       the documentation site, the component reference and the builder
docs/           the governance documents

Commands

Run these from the repository root. They need pnpm 12 and Node 24.

command	what it does
pnpm run ci	build, test, lint and the CSS budget gate. Run this before you push.
pnpm run build	checks the generated tokens, builds the JS and the types, bundles the stylesheet, then verifies the packed artifact
pnpm run test	two projects: the generator laws in Node, the computed values in a browser
pnpm run lint	ESLint and tsc --noEmit
pnpm run measure	the CSS budget gate. The numbers live in packages/ui/budget.json.

The token layer is generated. Regenerate it after you change packages/ui/src/tokens/config.ts:

pnpm --filter @kushagradhawan/kookie-ui-react run tokens

The governance documents

Read them in this order.

• docs/THESIS.md states what the system is for and how it governs itself.
• docs/DECISIONS.md is the specification. It states what the system is now.
• docs/REVIEW.md holds the audits and what each one resolved.
• docs/ENGINEERING.md states the code conventions and the testing rules.
• docs/LOG.md is the dated decision log. It states how the system became this, and what was rejected on the way.

DECISIONS.md is what the system is. LOG.md is how it got there. The chapters in apps/docs state both for a reader who did not make the decisions.

Contributing

See CONTRIBUTING.md. The tests assert system laws, never snapshots, and a law reads the value the browser computes rather than the value a stylesheet declares.

Acknowledgements

• Base UI (MIT) provides the behaviour, keyboard handling and accessibility of most components.
• shadcn/ui (MIT) provides the Message Scroller behaviour, through the @shadcn/react package. Many part names, such as those of Dialog, Menu and Select, follow shadcn/ui's.
• The glass lens follows the method in kube.io's "Liquid Glass in the Browser". The code is written for Kookie.

Licence

MIT.