cloudflare/kumo
Publicmirrored from https://github.com/cloudflare/kumoAvailable
AGENTS.md
156lines · modecode
| 1 | # KUMO KNOWLEDGE BASE |
| 2 | |
| 3 | **Generated:** 2026-03-18 | **Commit:** 38518e34 | **Branch:** rozenmd/fix-preview |
| 4 | |
| 5 | ## OVERVIEW |
| 6 | |
| 7 | Cloudflare's React component library (`@cloudflare/kumo`). pnpm monorepo: component library (Base UI + Tailwind v4), Astro docs site, Figma plugin, screenshot worker. ESM-only, Node 24+. |
| 8 | |
| 9 | ## STRUCTURE |
| 10 | |
| 11 | ``` |
| 12 | kumo/ |
| 13 | ├── packages/ |
| 14 | │ ├── kumo/ # Component library → see packages/kumo/AGENTS.md |
| 15 | │ ├── kumo-docs-astro/ # Astro docs site → see packages/kumo-docs-astro/AGENTS.md |
| 16 | │ ├── kumo-figma/ # Figma plugin → see packages/kumo-figma/AGENTS.md |
| 17 | │ └── kumo-screenshot-worker/ # Visual regression Worker → see packages/kumo-screenshot-worker/AGENTS.md |
| 18 | ├── ci/ # CI/CD scripts → see ci/AGENTS.md |
| 19 | ├── lint/ # Custom oxlint rules (5 rules in package, 4 at root) |
| 20 | ├── .changeset/ # Changeset files |
| 21 | ├── .github/workflows/ # 6 workflow YAMLs (release, pullrequest, preview, etc.) |
| 22 | └── lefthook.yml # Pre-push changeset validation |
| 23 | ``` |
| 24 | |
| 25 | ## WHERE TO LOOK |
| 26 | |
| 27 | | Task | Location | Notes | |
| 28 | | -------------------- | ------------------------------------------------ | -------------------------------------------------------- | |
| 29 | | Component API | `packages/kumo/ai/component-registry.{json,md}` | Source of truth. Query with `jq` or CLI | |
| 30 | | Component source | `packages/kumo/src/components/{name}/{name}.tsx` | Standard pattern | |
| 31 | | Blocks (installable) | `packages/kumo/src/blocks/` | NOT library exports; installed via CLI | |
| 32 | | Semantic tokens | `packages/kumo/src/styles/theme-kumo.css` | AUTO-GENERATED; edit `scripts/theme-generator/config.ts` | |
| 33 | | Custom lint rules | `lint/` (4 rules) + `packages/kumo/lint/` (+1) | Package copy adds `no-deprecated-props` | |
| 34 | | Demo examples | `packages/kumo-docs-astro/src/components/demos/` | Feed into registry codegen | |
| 35 | | CI scripts | `ci/` | Reporter system, versioning, deployment | |
| 36 | | Figma generators | `packages/kumo-figma/src/generators/` | 37 component generators | |
| 37 | |
| 38 | ## CONVENTIONS |
| 39 | |
| 40 | ### Styling (CRITICAL) |
| 41 | |
| 42 | - **ONLY semantic tokens**: `bg-kumo-base`, `text-kumo-default`, `border-kumo-line`, `ring-kumo-hairline` |
| 43 | - **NEVER raw Tailwind colors**: `bg-blue-500`, `text-gray-900` → fails lint |
| 44 | - **NEVER `dark:` variant**: dark mode automatic via `light-dark()` in CSS custom properties |
| 45 | - **Exceptions**: `bg-white`, `bg-black`, `text-white`, `text-black`, `transparent` |
| 46 | - **`cn()` utility**: Always compose classNames via `cn("base", conditional && "extra", className)` |
| 47 | - **Surface hierarchy**: `bg-kumo-base` → `bg-kumo-elevated` → `bg-kumo-recessed` |
| 48 | - **Mode/theme**: `data-mode="light"|"dark"` + `data-theme="fedramp"` on parent element |
| 49 | |
| 50 | ### Components |
| 51 | |
| 52 | - **Scaffold new**: `pnpm --filter @cloudflare/kumo new:component` (never create manually) |
| 53 | - **Registry first**: Always check `component-registry.json` before using/modifying a component |
| 54 | - See `packages/kumo/AGENTS.md` for component conventions (variants, forwardRef, displayName) |
| 55 | |
| 56 | ### Imports |
| 57 | |
| 58 | - **No cross-package relative imports**: Use `@cloudflare/kumo` not `../../kumo/src/...` (lint-enforced) |
| 59 | - **ESM-only**: `"type": "module"` throughout. No CJS. |
| 60 | |
| 61 | ### Changesets |
| 62 | |
| 63 | - **Enforced for `packages/kumo/`**: Pre-push hook requires changeset for npm-published library |
| 64 | - **Optional for `kumo-docs-astro`**: Version appears in `/api/version` endpoint (debugging) but nothing depends on it |
| 65 | - **Not needed for `kumo-figma`**: Figma plugin, not published to npm |
| 66 | - **Pre-push hook**: Lefthook validates before push. Bypass: `git push --no-verify` |
| 67 | - **AI agents NEVER**: `pnpm version`, `pnpm release`, `pnpm publish:beta`, `pnpm release:production` |
| 68 | |
| 69 | ### Pull Request Descriptions |
| 70 | |
| 71 | PR descriptions are validated by CI. Include this checklist at the end of your PR body: |
| 72 | |
| 73 | ```markdown |
| 74 | - Reviews |
| 75 | - [ ] bonk has reviewed the change |
| 76 | - [x] automated review not possible because: <your reason here> |
| 77 | - Tests |
| 78 | - [ ] Tests included/updated |
| 79 | - [ ] Automated tests not possible - manual testing has been completed as follows: <description> |
| 80 | - [x] Additional testing not necessary because: <your reason here> |
| 81 | ``` |
| 82 | |
| 83 | Rules: |
| 84 | |
| 85 | - Check ONE option in each section (Reviews and Tests) |
| 86 | - If providing a justification (`because:` or `as follows:`), text must follow on the same line |
| 87 | - Indentation is flexible — nested under headers is fine |
| 88 | - Skip validation entirely with the `skip-pr-description-validation` label |
| 89 | |
| 90 | ## ANTI-PATTERNS |
| 91 | |
| 92 | | Pattern | Why | Instead | |
| 93 | | ------------------------------ | ------------------------------------------------------------ | ------------------------------------------- | |
| 94 | | `bg-blue-500`, `text-gray-*` | Breaks theming, fails lint | `bg-kumo-brand`, `text-kumo-default` | |
| 95 | | `dark:bg-black` | Redundant; tokens auto-adapt | Remove `dark:` prefix | |
| 96 | | Missing `displayName` | Breaks React DevTools | Set `.displayName` on forwardRef components | |
| 97 | | Manual component file creation | Misses vite/package.json/index updates | Use scaffolding tool | |
| 98 | | Editing auto-generated files | `theme-kumo.css`, `ai/schemas.ts`, `ai/component-registry.*` | Edit source configs, run codegen | |
| 99 | |
| 100 | ## COMMANDS |
| 101 | |
| 102 | ```bash |
| 103 | # Cross-cutting |
| 104 | pnpm dev # Docs dev server (localhost:4321) |
| 105 | pnpm lint # oxlint + custom rules |
| 106 | pnpm typecheck # TypeScript check all packages |
| 107 | pnpm changeset # Create changeset (required for kumo changes) |
| 108 | |
| 109 | # Package-specific (see child AGENTS.md for full lists) |
| 110 | pnpm --filter @cloudflare/kumo build # Build library |
| 111 | pnpm --filter @cloudflare/kumo test # Vitest |
| 112 | pnpm --filter @cloudflare/kumo codegen:registry # Regenerate component-registry |
| 113 | pnpm --filter @cloudflare/kumo-figma build # Build Figma plugin |
| 114 | ``` |
| 115 | |
| 116 | ## BUILD PIPELINE |
| 117 | |
| 118 | ``` |
| 119 | kumo-docs-astro demos → dist/demo-metadata.json |
| 120 | ↓ |
| 121 | kumo codegen:registry → ai/component-registry.{json,md} + ai/schemas.ts |
| 122 | ↓ |
| 123 | kumo-figma build:data → generated/*.json → esbuild → code.js (IIFE, ES2017) |
| 124 | ``` |
| 125 | |
| 126 | Cross-package dependency: registry codegen requires docs demo metadata. Run `codegen:demos` in docs before `codegen:registry` in kumo. |
| 127 | |
| 128 | ## TOOLCHAIN |
| 129 | |
| 130 | | Tool | Version | Notes | |
| 131 | | ---------- | --------- | -------------------------------------- | |
| 132 | | Node | ^24.12.0 | Engine constraint | |
| 133 | | pnpm | >=10.21.0 | Workspace manager | |
| 134 | | TypeScript | 5.9.2 | Via pnpm catalog | |
| 135 | | Vite | 7.1.7 | Library mode (kumo), dev server (docs) | |
| 136 | | Tailwind | 4.1.17 | v4 with `light-dark()` tokens | |
| 137 | | oxlint | 1.42.0 | Primary linter + 5 custom JS rules | |
| 138 | | Vitest | 3.2.4 | happy-dom env, v8 coverage | |
| 139 | | Changesets | latest | Version management | |
| 140 | | Astro | latest | Docs framework | |
| 141 | |
| 142 | ## SECURITY |
| 143 | |
| 144 | - **NEVER commit** Figma tokens, npm tokens, or API keys |
| 145 | - `.env` files are gitignored |
| 146 | - `wrangler.jsonc` contains Cloudflare account IDs (not secret but don't expose) |
| 147 | |
| 148 | ## NOTES |
| 149 | |
| 150 | - `ai/component-registry.json`, `ai/component-registry.md` are auto-generated at build time and gitignored (shipped in npm package). `ai/schemas.ts` is a stub for fresh clones (full version generated during build) |
| 151 | - `src/primitives/` (40 files) are auto-generated Base UI re-exports |
| 152 | - Blocks in `src/blocks/` are NOT exported from package index; installed via CLI `kumo add` |
| 153 | - `src/catalog/` is a runtime JSON-UI rendering module (separate concern from component library) |
| 154 | - Dual linter: oxlint (fast, custom rules) + ESLint (7 jsx-a11y rules only via oxlint JS plugin) |
| 155 | - `PLOP_INJECT_EXPORT` and `PLOP_INJECT_COMPONENT_ENTRY` markers in source for scaffolding |
| 156 | - 6 GitHub Actions workflows exist in `.github/workflows/` (release, pullrequest, preview, preview-deploy, bonk, reviewer) |
| 157 | |