@staffbase/design-mcp 19.0.0

package/dist/data/meta.json

@@ -0,0 +1,4 @@
+{
+  "generatedAt": "2026-07-01T08:41:27.535Z",
+  "designVersion": "19.0.0"
+}

package/dist/data/package_instructions.md

@@ -0,0 +1,187 @@
+# @staffbase/design — AI Agent Reference
+
+> This file helps AI coding agents (Claude, Cursor, Copilot, etc.) use the Staffbase Design System correctly.
+> Last verified: 2026-05-19
+
+## Package overview
+
+`@staffbase/design` is a React component library providing UI components, icons, and design tokens for Staffbase products. ESM (with CJS fallback). Explicit CSS imports required.
+
+## When the MCP is available — use it for discovery
+
+The MCP returns ground truth, kept in lockstep with this package. Don't re-derive from training data; ask the tools:
+
+| Need                                                                         | Call                       |
+| ---------------------------------------------------------------------------- | -------------------------- |
+| What components exist, which are deprecated, what to use instead             | `list_components`          |
+| One component's full API — props interface, anatomy, examples, required a11y | `get_component`            |
+| One curated example, by default or by named variant                          | `get_component_example`    |
+| Tokens by layer/category; resolve a semantic token to its primitive          | `list_tokens`, `get_token` |
+| Find an icon by category, name, or synonym tag                               | `list_icons`, `get_icon`   |
+| Any published doc page (getting-started, foundation, components)             | `get_doc_page`             |
+| Fuzzy search across everything                                               | `search_design_system`     |
+
+The rest of this file covers the cross-cutting conventions and anti-patterns the tools don't surface. **The MCP is the source of truth for any list (components, tokens, icons, props, examples).**
+
+## Setup — required CSS imports
+
+In your application entry point, in this order:
+
+```ts
+import '@staffbase/design/tokens/semantic.css'; // required — CSS custom properties
+import '@staffbase/design/components.css'; // required — component styles
+import '@staffbase/design/theme.css'; // required if using Tailwind v4
+import '@staffbase/design/fonts/inter.css'; // optional
+import '@staffbase/design/fonts/epilogue.css'; // optional
+```
+
+Additional token layers if you need them: `@staffbase/design/tokens/primitive.css`, `@staffbase/design/tokens/component.css`.
+
+Public entry points: components, types, and icons from `@staffbase/design`; hooks from `@staffbase/design/hooks`.
+
+## Compound component pattern
+
+Many components are compound — they export an object with capitalized subcomponent properties, accessed via dot notation:
+
+```tsx
+<Dialog.Root>
+  <Dialog.Trigger>
+    <Button>Open</Button>
+  </Dialog.Trigger>
+  <Dialog.Popup>
+    <Dialog.Header>
+      <Dialog.Title>Title</Dialog.Title>
+      <Dialog.Close />
+    </Dialog.Header>
+    <Dialog.Body>Content</Dialog.Body>
+    <Dialog.Footer>Actions</Dialog.Footer>
+  </Dialog.Popup>
+</Dialog.Root>
+```
+
+If you don't know whether a given component is compound, call `get_component` — its `compoundMembers` field lists the subcomponents.
+
+### Trigger subcomponents take an element as `children`
+
+`Trigger` subcomponents in `Dialog`, `AlertDialog`, `Menu`, and `Tooltip` accept an element as `children`. Do **NOT** use a `render` prop — the design system wraps the underlying base library's render prop internally:
+
+```tsx
+// ✅ Correct
+<Dialog.Trigger><Button>Open</Button></Dialog.Trigger>
+
+// ❌ Wrong
+<Dialog.Trigger render={<Button />}>Open</Dialog.Trigger>
+```
+
+### Portal containers
+
+Overlay subcomponents (`Dialog.Popup`, `Menu.Popup`, `Select.Popup`, `Popover.Content`, `Tooltip.Content`) accept a `container` prop to control the portal target DOM node.
+
+## Astro component docs — two-tab pages
+
+Component docs in the Astro site now use a two-tab pattern directly below the page title and description:
+
+- **Overview** contains the existing component documentation body, examples, and API reference.
+- **Guidelines** contains the usability, visual design, and UX copy guidance for that component.
+
+When authoring or editing component docs, keep the page content organized so the heading hierarchy in each tab remains semantic and readable. The Guidelines tab content should follow the corresponding Figma frame for that component once available.
+
+## Customizability — `data-c13y-*` attributes
+
+The library exposes a stable CSS-selector surface for customer customizability ("c13y") via `data-c13y-*` attributes. Two axes:
+
+- **`data-c13y-component`** — _structural_ identity (what the element is: `button`, `dialog-popover`, `menu-item`). **The library emits this for you** on every primitive (including compound sub-part values). **Do NOT set `data-c13y-component` on a design primitive** — it already emits the correct value.
+- **`data-c13y-purpose`** — _feature intent_ (what the element does for the user: `join`, `save`, `sort`). The library sets this only on its own internal controls (e.g. a Dialog's close button). For your feature's intent, **pass `data-c13y-purpose` yourself**; it forwards to the primitive's root element.
+- **`data-c13y-id`** — an addressable instance id; pass it to mark individual instances. Prefer it over `data-testid` for logically-identified instances.
+
+```tsx
+// ✅ Design primitive — set purpose only; the library emits component
+<GhostButton onClick={onJoin} data-c13y-purpose="join">Join</GhostButton>
+
+// ❌ Don't override component on a design primitive
+<GhostButton data-c13y-component="button" data-c13y-purpose="join">Join</GhostButton>
+
+// ✅ A native element you render yourself — set BOTH (no library emits it for you)
+<button type="button" data-c13y-component="button" data-c13y-purpose="sort"><SortIcon /></button>
+```
+
+**Values must be runtime-static and kebab-case** (`[a-z0-9][a-z0-9-]*`): no interpolation, no locale/translation-derived strings, no state-dependent values. Use one stable purpose for a toggle regardless of state.
+
+**Regions on portalled overlays.** Portalled overlays (`Menu.Popup`, `Select.Popup`, `Tooltip.Content`, `SearchableSingleSelect.Popup`, `SearchableMultiSelect.Popup`) render outside the trigger's DOM subtree, so they don't inherit the trigger's `data-c13y-region`. To scope them into the same region, pass `data-c13y-region` (and any `data-c13y-purpose` / `data-c13y-id`) directly to the overlay's `Popup`/`Content` — it lands on the visible popup element alongside `data-c13y-component`:
+
+```tsx
+<Menu.Popup data-c13y-region="my-groups" data-c13y-purpose="filter">
+  …
+</Menu.Popup>
+```
+
+## Design tokens — three layers, prefer the most semantic
+
+| Layer     | Naming pattern                            | When to use                                                      |
+| --------- | ----------------------------------------- | ---------------------------------------------------------------- |
+| Primitive | `--sb-color-{hue}-{shade}`                | Never in component code. Raw values; do not theme against these. |
+| Semantic  | `--sb-{category}-color-{intent}-{weight}` | **Default.** Adapts to dark mode/theming.                        |
+| Component | `--sb-{component}-{property}`             | Per-component overrides only.                                    |
+
+Use `list_tokens` / `get_token` to discover and resolve specific names. The rule is: pick the most semantic layer that does the job.
+
+## Form error states — two patterns
+
+Different components handle errors differently. Check the props interface (via `get_component`) before choosing:
+
+**Pattern A — self-contained error props.** Used when the component's props include `errorMessage` and/or `hasError`:
+
+```tsx
+<Checkbox label="Accept terms" hasError errorMessage="Required" errorAriaLive="polite" />
+<TextArea label="Comment" errorMessage="Cannot be empty" />
+```
+
+**Pattern B — `Field` wrapper.** Used when the component has no built-in error props (e.g. `TextField`, `Select`):
+
+```tsx
+<Field.Root>
+  <Field.Label>Name</Field.Label>
+  <TextField />
+  <Field.Error>Name is required</Field.Error>
+</Field.Root>
+```
+
+Rule of thumb: if `errorMessage` or `hasError` appears in the props interface, use Pattern A. Otherwise wrap in `Field`.
+
+## Accessibility
+
+Several components have **required** a11y props that TypeScript enforces — `aria-label` on `SegmentedControl.Root` / `Banner.CloseButton` / `LoadingSpinner` / `Button` (when `iconOnly`), `a11yDescription` on `Badge`, `title` on `Popover.Close` / `HelpButton`, `is` on `Tooltip.Content`. Don't suppress these with type assertions; provide real values. `get_component` shows them on the props interface.
+
+## Conventions
+
+- **CSS classes** use the `ds-` prefix and BEM (`ds-button`, `ds-button__content`, `ds-button--primary`). Don't override them directly — use the `className` prop to layer on custom styles.
+- **RTL by default.** Use CSS logical properties (`margin-inline-start`, `padding-inline-end`) and Tailwind `start`/`end` utilities. Never `margin-left` / `padding-right` in component or consumer code.
+- **Icon slot props are `leadingIcon` / `trailingIcon`** — never `leftIcon` / `rightIcon`.
+
+## Common mistakes — do NOT do these
+
+- **Don't use deprecated components.** Call `list_components` to see which are deprecated and what to use instead. Never introduce new usages even if you find them in existing code — flag and suggest migration. Key migrations: `ButtonDeprecated` → `Button`; `GhostButton` → `Button variant="ghost"`; `IconButton` / `IconGhostButton` → `Button iconOnly`.
+- **Don't use a `render` prop on Trigger components** — pass the element as `children`.
+- **Don't use `margin-left` / `padding-right`** — use `margin-inline-start` / `padding-inline-end`.
+- **Don't import individual component CSS files** — only `@staffbase/design/components.css`.
+- **Don't use primitive tokens (`--sb-color-blue-500`) for theming** — use semantic tokens; they adapt to dark mode.
+- **Don't override `ds-` prefixed classes directly** — use `className` to add custom styles alongside.
+- **Don't set `data-c13y-component` on a design primitive** — the library emits it. Pass only `data-c13y-purpose` / `data-c13y-id`, and `data-c13y-region` on portalled overlays.
+
+## Testing
+
+Vitest + `@testing-library/react`. Query by accessible role, not class name or test id:
+
+```tsx
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {Button} from '@staffbase/design';
+
+test('button click', async () => {
+  const user = userEvent.setup();
+  const onClick = vi.fn();
+  render(<Button onClick={onClick}>Save</Button>);
+  await user.click(screen.getByRole('button', {name: 'Save'}));
+  expect(onClick).toHaveBeenCalled();
+});
+```