@bitrise/bitkit-v2 0.3.212 → 0.3.214
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# @bitrise/bitkit-v2 — AI assistant guide
|
|
2
|
+
|
|
3
|
+
Conventions for **using** `@bitrise/bitkit-v2` in your own application code. Built on Chakra UI v3 + React.
|
|
4
|
+
|
|
5
|
+
If you're contributing to the library itself, see `CLAUDE.md` instead — this file only covers consumer-side usage.
|
|
6
|
+
|
|
7
|
+
## Before you start (instructions for the AI assistant)
|
|
8
|
+
|
|
9
|
+
**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.
|
|
10
|
+
|
|
11
|
+
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:
|
|
12
|
+
|
|
13
|
+
> 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:
|
|
14
|
+
>
|
|
15
|
+
> ```json
|
|
16
|
+
> {
|
|
17
|
+
> "mcpServers": {
|
|
18
|
+
> "bitkit-storybook-mcp": {
|
|
19
|
+
> "url": "https://bitkit-v2.vercel.app/mcp",
|
|
20
|
+
> "type": "http"
|
|
21
|
+
> }
|
|
22
|
+
> }
|
|
23
|
+
> }
|
|
24
|
+
> ```
|
|
25
|
+
>
|
|
26
|
+
> Want me to wait, or continue without it?
|
|
27
|
+
|
|
28
|
+
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.
|
|
29
|
+
|
|
30
|
+
Don't repeat the warning every turn — once is enough per session.
|
|
31
|
+
|
|
32
|
+
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.
|
|
33
|
+
|
|
34
|
+
## Setup
|
|
35
|
+
|
|
36
|
+
Wrap your app in `BitkitProvider`:
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
import { BitkitProvider, BitkitButton } from '@bitrise/bitkit-v2';
|
|
40
|
+
|
|
41
|
+
<BitkitProvider>
|
|
42
|
+
<App />
|
|
43
|
+
</BitkitProvider>
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Discovering components
|
|
47
|
+
|
|
48
|
+
- **Hosted Storybook MCP** (recommended for AI assistants): add to your project's `.mcp.json`:
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"mcpServers": {
|
|
52
|
+
"bitkit-storybook-mcp": {
|
|
53
|
+
"url": "https://bitkit-v2.vercel.app/mcp",
|
|
54
|
+
"type": "http"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
Once configured, agents can call:
|
|
60
|
+
- `list-all-documentation` — list all components
|
|
61
|
+
- `get-documentation` — props and examples for a specific component
|
|
62
|
+
- `get-documentation-for-story` — extra detail for a story variant
|
|
63
|
+
- **Hosted Storybook (browser)**: <https://bitkit-v2.vercel.app/> — every component, props table, examples, and theme reference (colors, shadows, text styles, spacing, radii, icons).
|
|
64
|
+
- **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.
|
|
65
|
+
- 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`.
|
|
66
|
+
|
|
67
|
+
## Naming conventions
|
|
68
|
+
|
|
69
|
+
Bitkit components use consistent prop names across the library:
|
|
70
|
+
|
|
71
|
+
| Concept | Use | Don't use |
|
|
72
|
+
|---------|-----|-----------|
|
|
73
|
+
| Primary label | `label` | `labelText`, `text` |
|
|
74
|
+
| Descriptive subtitle (non-field) | `secondaryText` | `secdText` |
|
|
75
|
+
| Field validation/help text | `helperText`, `errorText`, `warningText` | — |
|
|
76
|
+
| Trailing icon | `suffixIcon` | `rightIcon` |
|
|
77
|
+
| Leading icon | `icon` | `leftIcon`, `prefixIcon` |
|
|
78
|
+
|
|
79
|
+
## Common API patterns
|
|
80
|
+
|
|
81
|
+
- **`state` prop replaces `disabled`/`loading`** — use `<BitkitButton state="disabled">`, not `<BitkitButton disabled>`. Values: `'disabled' | 'loading' | 'skeleton'`.
|
|
82
|
+
- **Dot notation for compound components** — sub-components are exposed as static properties on the parent, not as separate named exports:
|
|
83
|
+
```tsx
|
|
84
|
+
<BitkitSegmentedControl value={value} onValueChange={setValue}>
|
|
85
|
+
<BitkitSegmentedControl.Item value="a">Option A</BitkitSegmentedControl.Item>
|
|
86
|
+
<BitkitSegmentedControl.Item value="b">Option B</BitkitSegmentedControl.Item>
|
|
87
|
+
</BitkitSegmentedControl>
|
|
88
|
+
```
|
|
89
|
+
- **Slot props for content, not boolean flags** — pass an icon/badge/etc. directly as a prop. Element presence is the toggle:
|
|
90
|
+
```tsx
|
|
91
|
+
<BitkitButton icon={IconCheck}>Save</BitkitButton>
|
|
92
|
+
<BitkitAccordion.ItemTrigger suffix={<Badge>3</Badge>}>Files</BitkitAccordion.ItemTrigger>
|
|
93
|
+
```
|
|
94
|
+
- **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.
|
|
95
|
+
|
|
96
|
+
## Coding rules
|
|
97
|
+
|
|
98
|
+
- **Only use tokens that exist** — never guess token names. Verify via the Storybook MCP `Docs/Colors - *`, `Docs/Shadows`, `Docs/Text Styles`, etc. pages.
|
|
99
|
+
- **Slash-separated token paths** — `background/primary`, not `background.primary`.
|
|
100
|
+
- **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`).
|
|
101
|
+
- **Always use `textStyle`** — never set `fontFamily` or `fontSize` on `<Text>`. Use `textStyle="body/md/regular"`, `textStyle="code/md"`, etc.
|
|
102
|
+
- **Sizes as strings** — `width="32"`, not `width={32}`. Tokens are strings.
|
|
103
|
+
- **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"`).
|
|
104
|
+
- **Omit default prop values** — `<IconCross />`, not `<IconCross size="24" />` when 24 is the default.
|
|
105
|
+
- **No shorthand props** — use full names: `marginInline`, `paddingBlockEnd`, `width`, `background`, `padding`. Never `mx`, `pb`, `w`, `bg`, `p`, `mt`.
|
|
106
|
+
- **Prefer logical over physical properties** — `marginInline`, `paddingBlock`, `insetInlineStart` over `marginLeft`/`marginRight`, `paddingTop`/`paddingBottom`, `left`.
|
|
107
|
+
- **Minimal wrappers** — only use `<Box>` (from `@chakra-ui/react/box`) when truly needed for layout. Use empty fragments (`<>...</>`) otherwise.
|
|
108
|
+
- **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.
|
|
109
|
+
- **Import from Chakra subpaths** — `import { Button } from '@chakra-ui/react/button'`, not `from '@chakra-ui/react'`.
|
|
110
|
+
|
|
111
|
+
## Skeleton loading
|
|
112
|
+
|
|
113
|
+
Use `<Skeleton loading={...}>` from Chakra to wrap whichever element should show a placeholder. Bitkit form components also accept `state="skeleton"` directly.
|
package/README.md
CHANGED
|
@@ -4,7 +4,32 @@
|
|
|
4
4
|
|
|
5
5
|
Bitrise Design System Components built with Chakra UI v3.
|
|
6
6
|
|
|
7
|
-
[Browse the component library in Storybook](https://
|
|
7
|
+
[Browse the component library in Storybook](https://bitkit-v2.vercel.app/)
|
|
8
|
+
|
|
9
|
+
## Using with AI assistants (Claude Code, Cursor, Codex, etc.)
|
|
10
|
+
|
|
11
|
+
If you're prototyping or vibe-coding with an AI assistant, do this **before** writing any Bitkit code:
|
|
12
|
+
|
|
13
|
+
**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`:
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{
|
|
17
|
+
"mcpServers": {
|
|
18
|
+
"bitkit-storybook-mcp": {
|
|
19
|
+
"url": "https://bitkit-v2.vercel.app/mcp",
|
|
20
|
+
"type": "http"
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
**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`):
|
|
27
|
+
|
|
28
|
+
```markdown
|
|
29
|
+
@./node_modules/@bitrise/bitkit-v2/AGENTS.md
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The hosted Storybook itself is browsable at <https://bitkit-v2.vercel.app/>.
|
|
8
33
|
|
|
9
34
|
## Features
|
|
10
35
|
|
|
@@ -1,15 +1,16 @@
|
|
|
1
1
|
import { BoxProps } from '@chakra-ui/react/box';
|
|
2
|
+
import { ReactNode } from 'react';
|
|
2
3
|
import { NotificationVariant } from '../../theme/common/AlertAndToast.common';
|
|
3
4
|
import { NotificationAction } from '../common/notificationMaps';
|
|
4
5
|
export type BitkitNoteCardProps = Omit<BoxProps, 'children' | 'title'> & {
|
|
5
6
|
action?: NotificationAction;
|
|
6
|
-
message:
|
|
7
|
+
message: ReactNode;
|
|
7
8
|
status?: NotificationVariant;
|
|
8
9
|
title?: string;
|
|
9
10
|
};
|
|
10
11
|
declare const BitkitNoteCard: import('react').ForwardRefExoticComponent<Omit<BoxProps, "title" | "children"> & {
|
|
11
12
|
action?: NotificationAction;
|
|
12
|
-
message:
|
|
13
|
+
message: ReactNode;
|
|
13
14
|
status?: NotificationVariant;
|
|
14
15
|
title?: string;
|
|
15
16
|
} & import('react').RefAttributes<HTMLDivElement>>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"BitkitNoteCard.js","names":[],"sources":["../../../lib/components/BitkitNoteCard/BitkitNoteCard.tsx"],"sourcesContent":["import { Box, type BoxProps } from '@chakra-ui/react/box';\nimport { useSlotRecipe } from '@chakra-ui/react/styled-system';\nimport { Text } from '@chakra-ui/react/text';\nimport { type ElementType, forwardRef } from 'react';\n\nimport { type NotificationVariant } from '../../theme/common/AlertAndToast.common';\nimport BitkitButton from '../BitkitButton/BitkitButton';\nimport { ICON_COMPONENTS_MAP, type NotificationAction } from '../common/notificationMaps';\n\n// ----- Props -----\n\nexport type BitkitNoteCardProps = Omit<BoxProps, 'children' | 'title'> & {\n action?: NotificationAction;\n message:
|
|
1
|
+
{"version":3,"file":"BitkitNoteCard.js","names":[],"sources":["../../../lib/components/BitkitNoteCard/BitkitNoteCard.tsx"],"sourcesContent":["import { Box, type BoxProps } from '@chakra-ui/react/box';\nimport { useSlotRecipe } from '@chakra-ui/react/styled-system';\nimport { Text } from '@chakra-ui/react/text';\nimport { type ElementType, forwardRef, type ReactNode } from 'react';\n\nimport { type NotificationVariant } from '../../theme/common/AlertAndToast.common';\nimport BitkitButton from '../BitkitButton/BitkitButton';\nimport { ICON_COMPONENTS_MAP, type NotificationAction } from '../common/notificationMaps';\n\n// ----- Props -----\n\nexport type BitkitNoteCardProps = Omit<BoxProps, 'children' | 'title'> & {\n action?: NotificationAction;\n message: ReactNode;\n status?: NotificationVariant;\n title?: string;\n};\n\n// ----- Component -----\n\nconst BitkitNoteCard = forwardRef<HTMLDivElement, BitkitNoteCardProps>((props, ref) => {\n const { action, message, status = 'info', title, ...rest } = props;\n\n const recipe = useSlotRecipe({ key: 'noteCard' });\n const styles = recipe({ status });\n\n const IconComponent: ElementType = ICON_COMPONENTS_MAP[status];\n const isProgress = status === 'progress';\n\n return (\n <Box ref={ref} css={styles.root} {...rest}>\n <Box css={styles.iconBar}>\n <Box css={styles.iconWrapper}>{isProgress ? <IconComponent size=\"lg\" /> : <IconComponent size=\"24\" />}</Box>\n </Box>\n <Box css={styles.content}>\n <Box css={styles.messageBlock}>\n {title && <Text css={styles.title}>{title}</Text>}\n <Text css={title ? styles.message : styles.messageSolo}>{message}</Text>\n </Box>\n {action && (\n <BitkitButton\n css={styles.actionArea}\n size=\"sm\"\n variant=\"tertiary\"\n {...(action.href && {\n as: 'a' as const,\n href: action.href,\n rel: action.target === '_blank' ? 'noopener noreferrer' : undefined,\n target: action.target,\n })}\n onClick={action.onClick}\n >\n {action.label}\n </BitkitButton>\n )}\n </Box>\n </Box>\n );\n});\n\nBitkitNoteCard.displayName = 'BitkitNoteCard';\n\nexport default BitkitNoteCard;\n"],"mappings":";;;;;;;;AAoBA,IAAM,iBAAiB,YAAiD,OAAO,QAAQ;CACrF,MAAM,EAAE,QAAQ,SAAS,SAAS,QAAQ,OAAO,GAAG,SAAS;CAG7D,MAAM,SADS,cAAc,EAAE,KAAK,YAAY,CACjC,CAAO,EAAE,QAAQ,CAAC;CAEjC,MAAM,gBAA6B,oBAAoB;CACvD,MAAM,aAAa,WAAW;AAE9B,QACE,qBAAC,KAAD;EAAU;EAAK,KAAK,OAAO;EAAM,GAAI;YAArC,CACE,oBAAC,KAAD;GAAK,KAAK,OAAO;aACf,oBAAC,KAAD;IAAK,KAAK,OAAO;cAAc,aAAa,oBAAC,eAAD,EAAe,MAAK,MAAO,CAAA,GAAG,oBAAC,eAAD,EAAe,MAAK,MAAO,CAAA;IAAO,CAAA;GACxG,CAAA,EACN,qBAAC,KAAD;GAAK,KAAK,OAAO;aAAjB,CACE,qBAAC,KAAD;IAAK,KAAK,OAAO;cAAjB,CACG,SAAS,oBAAC,MAAD;KAAM,KAAK,OAAO;eAAQ;KAAa,CAAA,EACjD,oBAAC,MAAD;KAAM,KAAK,QAAQ,OAAO,UAAU,OAAO;eAAc;KAAe,CAAA,CACpE;OACL,UACC,oBAAC,cAAD;IACE,KAAK,OAAO;IACZ,MAAK;IACL,SAAQ;IACR,GAAK,OAAO,QAAQ;KAClB,IAAI;KACJ,MAAM,OAAO;KACb,KAAK,OAAO,WAAW,WAAW,wBAAwB,KAAA;KAC1D,QAAQ,OAAO;KAChB;IACD,SAAS,OAAO;cAEf,OAAO;IACK,CAAA,CAEb;KACF;;EAER;AAEF,eAAe,cAAc"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bitrise/bitkit-v2",
|
|
3
3
|
"private": false,
|
|
4
|
-
"version": "0.3.
|
|
4
|
+
"version": "0.3.214",
|
|
5
5
|
"description": "Bitrise Design System Components built with Chakra UI V3",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"react",
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
"dist",
|
|
16
16
|
"docs",
|
|
17
17
|
"scripts/postinstall.cjs",
|
|
18
|
+
"AGENTS.md",
|
|
18
19
|
"README.md",
|
|
19
20
|
"package.json"
|
|
20
21
|
],
|
|
@@ -43,6 +44,7 @@
|
|
|
43
44
|
"theme:watch": "chakra typegen lib/theme/index.ts --watch",
|
|
44
45
|
"lint": "eslint .",
|
|
45
46
|
"lint:fix": "eslint . --fix",
|
|
47
|
+
"check:agents-drift": "node ./scripts/check-agents-drift.cjs",
|
|
46
48
|
"start": "npm run storybook",
|
|
47
49
|
"type-check": "tsc --noEmit",
|
|
48
50
|
"release": "release-it patch --ci",
|
|
@@ -65,6 +67,7 @@
|
|
|
65
67
|
"@google-cloud/storage": "^7.19.0",
|
|
66
68
|
"@storybook/addon-docs": "10.3.5",
|
|
67
69
|
"@storybook/addon-mcp": "^0.6.0",
|
|
70
|
+
"@storybook/mcp": "^0.7.0",
|
|
68
71
|
"@storybook/react-vite": "10.3.5",
|
|
69
72
|
"@svgr/plugin-jsx": "^8.1.0",
|
|
70
73
|
"@types/node": "^25.6.0",
|