@bitrise/bitkit-v2 0.3.222 → 0.3.224

package/AGENTS.md

@@ -6,7 +6,7 @@ If you're contributing to the library itself, see `CLAUDE.md` instead — this f
 
 ## Before you start (instructions for the AI assistant)
 
-**Strongly prefer working with the `bitkit-storybook-mcp` MCP server available.** Bitkit code generated with the MCP is much more accurate (live prop tables, real variants, real tokens, real examples) and faster (one structured query vs. crawling node_modules) than code generated without it.
+**AI assistants: using the `bitkit-storybook-mcp` MCP server is mandatory before generating Bitkit code.** Memory, naming intuition, and TypeScript types are all secondary sources — hallucinated props are the #1 failure mode of AI-generated Bitkit code. Code generated with the MCP is much more accurate (live prop tables, real variants, real tokens, real examples) and faster (one structured query vs. crawling node_modules) than code generated without it.
 
 If `bitkit-storybook-mcp` isn't in your tools, **mention it once at the start of your turn** and offer the user the option to add it:
 
@@ -25,7 +25,7 @@ If `bitkit-storybook-mcp` isn't in your tools, **mention it once at the start of
 >
 > Want me to wait, or continue without it?
 
-Then **proceed based on the user's response** (or assume "continue" for trivial tasks). When working without the MCP, be extra cautious: rely on TypeScript types from `@bitrise/bitkit-v2`, follow the rules in this file strictly, and flag any answer where you're guessing rather than reading a typed signature.
+Then **wait for the user's response** — do not auto-continue, even for tasks that seem trivial. If the user explicitly opts to continue without the MCP, be extra cautious: rely on TypeScript types from `@bitrise/bitkit-v2`, follow the rules in this file strictly, and flag any answer where you're guessing rather than reading a typed signature.
 
 Don't repeat the warning every turn — once is enough per session.
 
@@ -45,7 +45,7 @@ import { BitkitProvider, BitkitButton } from '@bitrise/bitkit-v2';
 
 ## Discovering components
 
-- **Hosted Storybook MCP** (recommended for AI assistants): add to your project's `.mcp.json`:
+- **Hosted Storybook MCP** (required for AI assistants — see "Before you start"): add to your project's `.mcp.json`:
   ```json
   {
     "mcpServers": {

package/README.md

@@ -37,28 +37,40 @@ The hosted Storybook itself is browsable at <https://storybook.services.bitrise.
 - **Built with Chakra UI v3**: Latest Chakra UI features and performance
 - **TypeScript**: Full TypeScript support with auto-generated types
 - **Self-hosted Fonts**: Figtree and Source Code Pro bundled via BitkitProvider
-- **Simple Installation**: Just `npm install @bitrise/bitkit-v2`
+- **Pinned Peer Dependencies**: Bitkit declares Chakra, Emotion and the Chakra CLI as pinned peers so your tree stays deduped
 
 ## Installation
 
 ```bash
-npm install @bitrise/bitkit-v2
+# Runtime peers — required for Bitkit to render
+npm install @bitrise/bitkit-v2 @chakra-ui/react@3.35.0 @emotion/react@11.14.0 @emotion/styled@11.14.1
+
+# Build-time peer — required so the bundled postinstall hook can generate bitkit-specific theme typings
+npm install --save-dev @chakra-ui/cli@3.35.0
 ```
 
-Chakra UI and Emotion are included as regular runtime dependencies of this package, so you do not need to install them separately.
+Chakra UI and Emotion are declared as peer dependencies so the host app owns the single copy of Chakra in the tree. Install them at the exact versions Bitkit pins — any other version (including patch bumps like `3.35.1`) triggers a peer mismatch warning, and a different minor/major may also cause runtime API incompatibility against Bitkit's compiled output. Duplicate Chakra installs only show up if some other transitive dependency drags in a different Chakra version on top of the drift, but when they do they silently break `BitkitProvider`'s theme context, which is exactly the failure mode pinned peers protect against.
+
+`@chakra-ui/cli` is a peer too — Bitkit's `postinstall` hook uses it to generate Chakra theme typings into your project's `node_modules`. Install it as a devDependency in the host app so the hook can find it.
+
+> **Production-only installs (`npm ci --omit=dev`, `pnpm install --prod`, etc.):** because `@chakra-ui/cli` is conventionally installed in the host's `devDependencies`, it will be skipped — your package manager may emit an unmet-peer warning or, with strict peer enforcement (e.g. pnpm's `strict-peer-dependencies=true`), fail the install. The bundled `postinstall` hook itself detects the missing CLI, prints a notice and exits cleanly. Theme typings are a development-time concern, so production environments don't need the CLI; if your prod install is configured for strict peers, either set `strict-peer-dependencies=false` for the deploy step, allow-list `@chakra-ui/cli` as a missing peer, or install the CLI as a regular dependency instead of a devDependency.
 
 ### Requirements
 
 - React 18+ (peer dependency)
 - React DOM 18+ (peer dependency)
+- `@chakra-ui/react` 3.35.0 (peer dependency, pinned)
+- `@emotion/react` 11.14.0 (peer dependency, pinned)
+- `@emotion/styled` 11.14.1 (peer dependency, pinned)
+- `@chakra-ui/cli` 3.35.0 (peer dependency, pinned — used by the bundled `postinstall` typegen hook; install as a devDependency in the host app)
 
 ### Theme typings
 
 Bitkit ships a Chakra UI v3 theme with custom recipes, semantic tokens, and design tokens. For TypeScript autocompletion to recognize bitkit-specific values (e.g. `<BitkitButton variant="ai-primary">`, `colors.purple.60`), Chakra's typegen must run in your project's `node_modules` after install.
 
-This happens automatically via a `postinstall` hook bundled with the package — no setup is required for standard npm installs.
+This happens automatically via a `postinstall` hook bundled with the package, as long as `@chakra-ui/cli` is installed in the host app (it's declared as a peer dependency for this reason).
 
-If the postinstall is skipped (e.g. you ran `npm install --ignore-scripts`, or a CI runner blocks lifecycle scripts), regenerate the typings manually:
+If the postinstall is skipped (e.g. `@chakra-ui/cli` is not installed, you ran `npm install --ignore-scripts`, or a CI runner blocks lifecycle scripts), regenerate the typings manually:
 
 ```bash
 npx chakra typegen node_modules/@bitrise/bitkit-v2/dist/theme/index.js

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bitrise/bitkit-v2",
   "private": false,
-  "version": "0.3.222",
+  "version": "0.3.224",
   "description": "Bitrise Design System Components built with Chakra UI V3",
   "keywords": [
     "react",
@@ -56,11 +56,19 @@
     "postinstall": "node ./scripts/postinstall.cjs"
   },
   "peerDependencies": {
+    "@chakra-ui/cli": "3.35.0",
+    "@chakra-ui/react": "3.35.0",
+    "@emotion/react": "11.14.0",
+    "@emotion/styled": "11.14.1",
     "react": ">=18",
     "react-dom": ">=18"
   },
   "devDependencies": {
     "@bitrise/eslint-plugin": "^4.1.0",
+    "@chakra-ui/cli": "3.35.0",
+    "@chakra-ui/react": "3.35.0",
+    "@emotion/react": "11.14.0",
+    "@emotion/styled": "11.14.1",
     "@figma-export/cli": "^6.4.0",
     "@figma-export/output-components-as-svg": "^6.4.0",
     "@figma-export/transform-svg-with-svgo": "^6.4.0",
@@ -85,10 +93,6 @@
     "vite-plugin-svgr": "^5.2.0"
   },
   "dependencies": {
-    "@chakra-ui/cli": "^3.35.0",
-    "@chakra-ui/react": "^3.35.0",
-    "@emotion/react": "^11.14.0",
-    "@emotion/styled": "^11.14.1",
     "@fontsource-variable/figtree": "^5.2.10",
     "@fontsource-variable/source-code-pro": "^5.2.7",
     "es-toolkit": "^1.46.1",