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.
