@televet/kibble-ui 5.0.31 → 5.1.0-ne.0

package/AGENTS.md

@@ -0,0 +1,120 @@
+# AGENTS.md - Kibble UI Component Library
+
+> Guidelines for AI agents working in this React/Chakra UI component library codebase.
+
+## Project Overview
+
+Kibble is a React component library (design system) for Otto. Built with:
+
+- **React 19** + **TypeScript 5.7**
+- **Chakra UI v3** for component primitives
+- **Vite** for building, **Storybook 10** for documentation
+- **Vitest** + **Playwright** for testing (via Storybook addon)
+
+This is an **npm workspace** containing two packages:
+
+| Package | Path | Description |
+|---------|------|-------------|
+| `@televet/kibble-ui` | `.` (repo root) | React component library — depends on Chakra UI |
+| `@televet/kibble-primitives` | `packages/kibble-primitives/` | Framework-agnostic design token primitives — zero framework dependencies |
+
+**Package boundary rule:** `*.records.ts` and `*.types.ts` token files live in `kibble-primitives`. `*.config.ts` files (which wrap tokens with `defineTokens`/`defineSemanticTokens` from Chakra) stay in `kibble-ui`.
+
+## Build / Lint / Test Commands
+
+```bash
+npm start                    # Start Storybook dev server on port 6006
+npm run build               # Full build (types, icons, logos, docs, then vite)
+npm run build:preparation   # Generate theme types, icons, logos
+npm run lint                # ESLint with auto-fix on src/
+npm run format              # Prettier on all TS/TSX files
+npm run test-storybook                          # Run all Storybook tests
+npx vitest --project=storybook Button           # Run tests for Button stories
+npm run create:component    # Create new component via plop
+npm run generate:icons      # Regenerate icon components from SVGs
+npm run generate:theme      # Generate Chakra theme types
+```
+
+## Project Structure
+
+```
+packages/
+  kibble-primitives/    # @televet/kibble-primitives — token records + types, no framework deps
+    src/
+      core/             # Raw token scales (colors, spacing, typography, etc.)
+      semantic/         # Theme-aware semantic tokens (light/dark mode mappings)
+src/
+  components/           # UI components (Button, Alert, Modal, etc.)
+    ComponentName/
+      componentName.component.tsx
+      componentName.types.ts
+      componentName.recipe.ts
+      componentName.records.ts
+      index.ts
+      docs/componentName.stories.tsx
+  hooks/
+  theme/
+    tokens/             # Chakra token config files (*.config.ts) — import from kibble-primitives
+    semanticTokens/     # Chakra semantic token config — imports from kibble-primitives
+    recipes/
+    providers/
+```
+
+## Key Patterns
+
+- **Variant system**: `variant` + `onContrast` props on most components
+- **Shared status type**: `'info' | 'success' | 'warning' | 'error' | 'default'`
+- **`forwardRef`**: All components that accept `ref` use `forwardRef` + set `displayName`
+- **Recipes**: Use `defineRecipe` for component variants — no inline styles
+- **Semantic tokens**: `background.primary`, `text.contrast` etc. — never raw Chakra colors
+- **Components & imports**: Prefer **Kibble** components over plain HTML or Chakra primitives. When you need Chakra, import from **`@chakra-ui/react` subpaths** — do not pull Chakra through local re-exports in this repo.
+- **DRY**: Follow **don't repeat yourself** across files: extract shared helpers and repeated patterns (utilities, handlers, layout) instead of duplicating them in each story or doc file.
+- **Micro-files & wrappers**: Don’t add a separate file or tiny wrapper for a **one-line** style or a component used **only once** — inline in the consumer unless it’s reused. See **[docs/conventions.md](./docs/conventions.md)** (*File and Component Extraction*).
+- **Function style & exhaustive records**: Use **arrow functions** for exported components and helpers; type token maps as **`Record<ConcreteTokenType, …>`** for exhaustiveness — see **[docs/conventions.md](./docs/conventions.md)** (*Function Style*, *Typed Records for Exhaustiveness*).
+- **Releases**: When you change **published library components** (anything consumers import), **bump the package version** according to semver.
+
+## How consumers import Kibble (v5)
+
+One rule, used everywhere: import each component from its own path.
+
+```tsx
+import { Button } from '@televet/kibble-ui/Button';
+import { Modal } from '@televet/kibble-ui/Modal';
+```
+
+The v5 exports map sends `@televet/kibble-ui/<Component>` to that component's built entry
+point, so this only works for a component directory that has an `index.ts`. Adding one is
+what makes a new component importable at all — see the barrel rule under **Don't**.
+
+Hooks, higher-order components and shared types keep their own prefixes:
+`@televet/kibble-ui/hooks/useColorMode`, `@televet/kibble-ui/hocs/withFormControl`,
+`@televet/kibble-ui/shared/types`. The theme is `@televet/kibble-ui/theme`.
+
+`otto-admin` is still on kibble-ui 3.0.8, which predates this exports map. Leave its
+imports alone until it upgrades.
+
+## The component manifest
+
+`npm run build` writes `dist/components.json` (via `npm run generate:manifest`) describing
+every component: props with types and defaults, variants, sizes, icon names, semantic
+tokens, and each Storybook story's args. It ships inside the published package.
+
+`@televet/kibble-mcp` (in `mcp/`) serves that file to coding agents. If you change a
+component's props, the manifest updates on the next build — there is nothing to hand-write.
+Regenerate it on its own with `npm run generate:manifest` (it needs `dist/` to exist, so run
+a build first).
+
+## Don't
+
+- Use `@ts-ignore` or `as any`
+- Create empty catch blocks
+- Skip the `data-testid` prop
+- Import from `@chakra-ui/react` directly — use subpaths (`@chakra-ui/react/box`)
+- Forget to export from `index.ts` barrel files
+- Use plain HTML elements (`<div>`, `<button>`, `<table>`, `<tr>`, `<td>`, `<span>`, etc.) in `.tsx` files (including Storybook and docs) — always use Kibble or Chakra components instead (prefer Kibble)
+- Build a custom component before checking whether `Button`, `Swatch`, `Text`, `Table`, or another existing Kibble/Chakra component already covers the need
+
+## Extended Documentation
+
+- **[docs/conventions.md](./docs/conventions.md)** — file naming, TypeScript, Chakra patterns, BEM/CSS class naming, records files, testing
+- **[docs/patterns.md](./docs/patterns.md)** — compound components, creating new components, variant system details