@bitrise/bitkit-v2 0.3.211 → 0.3.213

package/AGENTS.md

@@ -0,0 +1,113 @@
+# @bitrise/bitkit-v2 — AI assistant guide
+
+Conventions for **using** `@bitrise/bitkit-v2` in your own application code. Built on Chakra UI v3 + React.
+
+If you're contributing to the library itself, see `CLAUDE.md` instead — this file only covers consumer-side usage.
+
+## 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.
+
+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:
+
+> Heads up: Bitkit's hosted Storybook MCP isn't configured here. I can still proceed by inferring props and tokens from TypeScript types and the AGENTS.md rules — but with the MCP my output would be substantially more accurate. To enable it, add this to your `.mcp.json` and reload:
+>
+> ```json
+> {
+>   "mcpServers": {
+>     "bitkit-storybook-mcp": {
+>       "url": "https://bitkit-v2.vercel.app/mcp",
+>       "type": "http"
+>     }
+>   }
+> }
+> ```
+>
+> 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.
+
+Don't repeat the warning every turn — once is enough per session.
+
+Once the MCP is available, **query it before using a Bitkit component or token** — never rely on memory or naming intuition alone. Hallucinated props and tokens are the most common failure mode for AI-generated Bitkit code.
+
+## Setup
+
+Wrap your app in `BitkitProvider`:
+
+```tsx
+import { BitkitProvider, BitkitButton } from '@bitrise/bitkit-v2';
+
+<BitkitProvider>
+  <App />
+</BitkitProvider>
+```
+
+## Discovering components
+
+- **Hosted Storybook MCP** (recommended for AI assistants): add to your project's `.mcp.json`:
+  ```json
+  {
+    "mcpServers": {
+      "bitkit-storybook-mcp": {
+        "url": "https://bitkit-v2.vercel.app/mcp",
+        "type": "http"
+      }
+    }
+  }
+  ```
+  Once configured, agents can call:
+  - `list-all-documentation` — list all components
+  - `get-documentation` — props and examples for a specific component
+  - `get-documentation-for-story` — extra detail for a story variant
+- **Hosted Storybook (browser)**: <https://bitkit-v2.vercel.app/> — every component, props table, examples, and theme reference (colors, shadows, text styles, spacing, radii, icons).
+- **Never hallucinate component properties.** Verify every prop against the docs before using it. A prop that "sounds right" (e.g. `shadow`, `rightIcon`) often does not exist.
+- For tokens (colors, shadows, text styles, etc.), query the Storybook docs pages: `Docs/Colors - Components`, `Docs/Colors - System`, `Docs/Colors - Base`, `Docs/Shadows (Box Shadows)`, `Docs/Spacing & Sizes`, `Docs/Radii (Border Radius)`, `Docs/Text Styles`, `Docs/Typography`, `Docs/Icons`.
+
+## Naming conventions
+
+Bitkit components use consistent prop names across the library:
+
+| Concept | Use | Don't use |
+|---------|-----|-----------|
+| Primary label | `label` | `labelText`, `text` |
+| Descriptive subtitle (non-field) | `secondaryText` | `secdText` |
+| Field validation/help text | `helperText`, `errorText`, `warningText` | — |
+| Trailing icon | `suffixIcon` | `rightIcon` |
+| Leading icon | `icon` | `leftIcon`, `prefixIcon` |
+
+## Common API patterns
+
+- **`state` prop replaces `disabled`/`loading`** — use `<BitkitButton state="disabled">`, not `<BitkitButton disabled>`. Values: `'disabled' | 'loading' | 'skeleton'`.
+- **Dot notation for compound components** — sub-components are exposed as static properties on the parent, not as separate named exports:
+  ```tsx
+  <BitkitSegmentedControl value={value} onValueChange={setValue}>
+    <BitkitSegmentedControl.Item value="a">Option A</BitkitSegmentedControl.Item>
+    <BitkitSegmentedControl.Item value="b">Option B</BitkitSegmentedControl.Item>
+  </BitkitSegmentedControl>
+  ```
+- **Slot props for content, not boolean flags** — pass an icon/badge/etc. directly as a prop. Element presence is the toggle:
+  ```tsx
+  <BitkitButton icon={IconCheck}>Save</BitkitButton>
+  <BitkitAccordion.ItemTrigger suffix={<Badge>3</Badge>}>Files</BitkitAccordion.ItemTrigger>
+  ```
+- **Form components are flat** — `BitkitTextInput`, `BitkitSelect`, `BitkitCombobox`, etc. expose `label`, `errorText`, `helperText`, etc. directly as props. No need to wrap in a separate field component.
+
+## Coding rules
+
+- **Only use tokens that exist** — never guess token names. Verify via the Storybook MCP `Docs/Colors - *`, `Docs/Shadows`, `Docs/Text Styles`, etc. pages.
+- **Slash-separated token paths** — `background/primary`, not `background.primary`.
+- **Always semantic colors** — use semantic tokens (`bg/surface`, `fg/base`, `border/minimal`). Never palette colors (`purple.50`), system colors (`sys.fg.base`), raw codes (`#fff`), or color names (`white`, `grey`).
+- **Always use `textStyle`** — never set `fontFamily` or `fontSize` on `<Text>`. Use `textStyle="body/md/regular"`, `textStyle="code/md"`, etc.
+- **Sizes as strings** — `width="32"`, not `width={32}`. Tokens are strings.
+- **Use existing size tokens** — closest existing token (1, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96, 128) representing pixel values (1=1px, 32=32px). Avoid arbitrary px (`width="100px"`).
+- **Omit default prop values** — `<IconCross />`, not `<IconCross size="24" />` when 24 is the default.
+- **No shorthand props** — use full names: `marginInline`, `paddingBlockEnd`, `width`, `background`, `padding`. Never `mx`, `pb`, `w`, `bg`, `p`, `mt`.
+- **Prefer logical over physical properties** — `marginInline`, `paddingBlock`, `insetInlineStart` over `marginLeft`/`marginRight`, `paddingTop`/`paddingBottom`, `left`.
+- **Minimal wrappers** — only use `<Box>` (from `@chakra-ui/react/box`) when truly needed for layout. Use empty fragments (`<>...</>`) otherwise.
+- **Use `Text` for text content, not `Box`** — when rendering string content, use `<Text>` from `@chakra-ui/react/text`. Choose semantic tag via `as`: `<Text as="strong">`, `<Text as="span">`, `<Text as="label">`, plain `<Text>` for paragraphs.
+- **Import from Chakra subpaths** — `import { Button } from '@chakra-ui/react/button'`, not `from '@chakra-ui/react'`.
+
+## Skeleton loading
+
+Use `<Skeleton loading={...}>` from Chakra to wrap whichever element should show a placeholder. Bitkit form components also accept `state="skeleton"` directly.

package/README.md

@@ -4,7 +4,32 @@
 
 Bitrise Design System Components built with Chakra UI v3.
 
-[Browse the component library in Storybook](https://storybook.services.bitrise.dev/projects/bitkit-v2/production/)
+[Browse the component library in Storybook](https://bitkit-v2.vercel.app/)
+
+## Using with AI assistants (Claude Code, Cursor, Codex, etc.)
+
+If you're prototyping or vibe-coding with an AI assistant, do this **before** writing any Bitkit code:
+
+**1. Configure the hosted Storybook MCP** so the AI can query live component props, examples, and tokens instead of guessing. Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "bitkit-storybook-mcp": {
+      "url": "https://bitkit-v2.vercel.app/mcp",
+      "type": "http"
+    }
+  }
+}
+```
+
+**2. Reference Bitkit's `AGENTS.md`** so the AI picks up component naming, the `state` prop pattern, semantic token rules, and other library conventions. Add to your project's own `AGENTS.md` (or `CLAUDE.md`):
+
+```markdown
+@./node_modules/@bitrise/bitkit-v2/AGENTS.md
+```
+
+The hosted Storybook itself is browsable at <https://bitkit-v2.vercel.app/>.
 
 ## Features
 

package/docs/v1-to-v2-migration-guide.md

@@ -198,14 +198,11 @@ If your codebase has a local `card.tsx` wrapper around v1 Card (e.g. Shadcn-styl
 
 // Breadcrumb v2
 <BitkitBreadcrumb>
-  <BitkitBreadcrumb.Item href="#/path">Label</BitkitBreadcrumb.Item>
+  <BitkitBreadcrumb.Item href="/path">Label</BitkitBreadcrumb.Item>
   <BitkitBreadcrumb.CurrentItem>Current</BitkitBreadcrumb.CurrentItem>
 </BitkitBreadcrumb>
 ```
 
-**HashRouter gotcha**: `BitkitBreadcrumb` uses plain `href`. With HashRouter all links need the `#/` prefix (e.g. `href="#/sessions"`), otherwise navigation breaks silently.
-
-**Version requirement**: `BitkitBreadcrumb` requires `@bitrise/bitkit-v2 >= 0.3.210`.
 
 ### textStyle tokens
 
@@ -223,20 +220,6 @@ Common tokens: `body/sm/regular`, `body/md/regular`, `body/md/semibold`, `body/l
 
 ---
 
-## Action menus
-
-If the codebase has a hand-rolled dropdown/action menu (state + ref + `useEffect` for click-outside), replace it with `BitkitActionMenu`:
-
-```tsx
-<BitkitActionMenu.Root trigger={<button>...</button>}>
-  <BitkitActionMenu.Item onClick={...}>Edit</BitkitActionMenu.Item>
-  <BitkitActionMenu.Separator />
-  <BitkitActionMenu.Item onClick={...} danger>Delete</BitkitActionMenu.Item>
-</BitkitActionMenu.Root>
-```
-
----
-
 ## Color tokens: `text/*` vs `icon/*`
 
 Use `text/*` tokens on `<Text>` (and other text elements), and `icon/*` tokens on `<Icon*>` components. Most pairs resolve to the same underlying color, so a mismatch won't be visible — but the semantics matter.
@@ -256,10 +239,6 @@ Use `text/*` tokens on `<Text>` (and other text elements), and `icon/*` tokens o
 After the migration, audit `package.json` carefully — v1 pulled in transitive deps that may still be listed:
 
 - `@emotion/react` — you may no longer need to list it directly in your app's `package.json`; `@bitrise/bitkit-v2` brings it transitively
-- `lucide-react` — if icons are now from `@bitrise/bitkit-v2`
-- `zustand` — if Bitkit's sidebar hook was the only consumer
-- `@types/luxon`, `patch-package`, `postcss` — check if still used
-
 Also check `scripts` in `package.json` for any `postinstall` entries referencing removed packages (e.g. `"postinstall": "patch-package"`) — these will silently break CI.
 
 ---
@@ -281,7 +260,6 @@ Migrating a large repo component-by-component is token-intensive. What works wel
 - [ ] Identify local wrapper components around v1 Bitkit components
 - [ ] Identify hand-rolled alternatives to v2 components (dropdowns, modals, etc.)
 - [ ] Check `@bitrise/bitkit-v2` changelog for version requirements per component
-- [ ] Check if HashRouter is in use (affects Breadcrumb `href`)
 - [ ] Note any buttons with complex children (non-string) — these need `chakra.button`
 
 ## Post-migration checklist

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bitrise/bitkit-v2",
   "private": false,
-  "version": "0.3.211",
+  "version": "0.3.213",
   "description": "Bitrise Design System Components built with Chakra UI V3",
   "keywords": [
     "react",
@@ -15,6 +15,7 @@
     "dist",
     "docs",
     "scripts/postinstall.cjs",
+    "AGENTS.md",
     "README.md",
     "package.json"
   ],
@@ -43,6 +44,7 @@
     "theme:watch": "chakra typegen lib/theme/index.ts --watch",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "check:agents-drift": "node ./scripts/check-agents-drift.cjs",
     "start": "npm run storybook",
     "type-check": "tsc --noEmit",
     "release": "release-it patch --ci",
@@ -65,6 +67,7 @@
     "@google-cloud/storage": "^7.19.0",
     "@storybook/addon-docs": "10.3.5",
     "@storybook/addon-mcp": "^0.6.0",
+    "@storybook/mcp": "^0.7.0",
     "@storybook/react-vite": "10.3.5",
     "@svgr/plugin-jsx": "^8.1.0",
     "@types/node": "^25.6.0",