@botiverse/raft-ui 0.0.0-stage → 0.7.0

package/skills/raft-ui-guide/rules/lookup.md

@@ -0,0 +1,78 @@
+---
+name: lookup
+description: "Where to find props, variant values, and tokens for the installed raft-ui version — declarations, stylesheet, and monorepo source. Read before guessing any name."
+---
+
+# Looking things up
+
+## Order to try
+
+1. **Editor types** — if you are editing TypeScript in a typed project, hover or autocomplete on the component. Fastest and always matches the installed version.
+   The component's docs page, `https://raft-design.botiverse.build/components/<component>.md`, has the same props in its API section, generated from the latest release.
+2. **The bundled declarations** — `node_modules/@botiverse/raft-ui/dist/index.d.mts`. Authoritative for the version actually installed.
+3. **The token stylesheet** — `node_modules/@botiverse/raft-ui/dist/foundation.css` for colors, shadows, and the light and dark scopes; `styles.css` for Tailwind mappings.
+4. **The recipe source** — only available when working inside the raft-ui monorepo, see below.
+
+## What ships in the package
+
+The published package contains **no `src/`**. Do not look for `.tsx` files in a consumer's `node_modules`.
+
+```
+node_modules/@botiverse/raft-ui/
+├── CHANGELOG.md
+├── package.json
+├── README.md
+├── dist/
+│   ├── index.d.mts     every stable component, part, and prop type
+│   ├── index.mjs       stable runtime
+│   ├── cn.d.mts        the cn helper
+│   ├── cn.mjs
+│   ├── wip.d.mts       unstable surface
+│   ├── wip.mjs
+│   ├── foundation.css  native CSS token contract
+│   ├── styles.css      Tailwind mappings
+│   └── fonts.css
+└── skills/             bundled raft-ui agent skills
+```
+
+## Finding a prop type
+
+```bash
+rg -n -A6 "^type ButtonProps =" node_modules/@botiverse/raft-ui/dist/index.d.mts
+```
+
+Adapt the pattern to how the declarations actually read. The last line of `index.d.mts` is one `export { … }` statement that lists the whole stable surface:
+
+```bash
+tail -n 1 node_modules/@botiverse/raft-ui/dist/index.d.mts | tr ',' '\n'
+```
+
+If a name is absent from `index.d.mts`, treat it as unavailable on the stable surface. Check `wip.d.mts` only when the user explicitly asks to consider unstable APIs.
+
+## Finding a variant's allowed values
+
+Variant unions come through `VariantProps<typeof <recipe>>`. Read the variant keys in the declared `TVReturnType` above the component props; the bundled declarations preserve those keys.
+
+Do not infer a variant value from another component — the names are not consistent. See the note on intent names in [SKILL.md](../SKILL.md#override-your-priors-first).
+
+## Finding a token
+
+```bash
+rg -o -- "--color-[a-z0-9-]+" node_modules/@botiverse/raft-ui/dist/styles.css | sort -u
+```
+
+Use this before writing any color class. If a token is not in that list, it does not exist. What each token is for is on https://raft-design.botiverse.build/foundations/color.md.
+
+## Inside the raft-ui monorepo
+
+When `packages/ui/src/` is present you are working on the library itself, not consuming it. There the `tv()` recipe is the source of truth:
+
+```
+packages/ui/src/components/<component>/<component>.recipe.ts   (or <component>.tsx when there is no recipe file)
+```
+
+Read the `variants` block for the exact option names and the `compoundVariants` block for behavior that depends on a combination of variants. The docs compositions under `apps/doc/src/modules/<component>/compositions/` show canonical usage.
+
+## When the answer is not there
+
+Say so and ask, or read the declarations again. Do not invent a prop name that "should" exist because another library has it. A guessed prop is silently dropped onto the DOM or ignored, and the bug surfaces much later as a styling problem.

package/skills/raft-ui-guide/rules/overlays.md

@@ -0,0 +1,13 @@
+---
+name: overlays
+description: "Moved to the Raft Design System docs: dialogs, drawers, popovers, menus and tooltips."
+---
+
+# Overlays
+
+This guidance is part of the Raft Design System docs now, which are its single source. Each page is Markdown; read only the ones the task needs.
+
+- Choosing a component: overlays: https://raft-design.botiverse.build/patterns/choosing-components.md#overlays
+- Elevation: which things float, and how popups are positioned: https://raft-design.botiverse.build/foundations/elevation.md
+
+Check every prop, part and token you use against [lookup.md](./lookup.md).

package/skills/raft-ui-guide/rules/overview.md

@@ -0,0 +1,30 @@
+---
+name: overview
+description: "What raft-ui is and where to start."
+---
+
+# Overview
+
+raft-ui is the React implementation of the Raft Design System, the design system used to build Raft. The `raft-ui` package includes CSS foundations, composable React components, and light and dark modes.
+
+## Start with your agent
+
+Copy this prompt and add your task:
+
+```text
+Use raft-ui, the React implementation of the Raft Design System, for this project. Use its shared tokens and components where they fit the project. Plain HTML can use foundation.css without React or Tailwind.
+
+Read https://raft-design.botiverse.build/llms.txt and the pages relevant to the task; every page is Markdown. https://raft-design.botiverse.build/components.json lists every component. Match the existing project setup. For version-specific APIs, use node_modules/@botiverse/raft-ui/dist/index.d.mts.
+
+Skills are optional. Only install them when requested.
+```
+
+## Rules in this skill
+
+| Task                                    | Read                                          |
+| --------------------------------------- | --------------------------------------------- |
+| Adopting raft-ui in an existing project | [Adoption](./adoption.md)                     |
+| Package contents, styles and providers  | [Technical overview](./technical-overview.md) |
+| Exact component APIs and tokens         | [API lookup](./lookup.md)                     |
+
+Everything else (which component, how to compose, styling) is in the design system docs; see [SKILL.md](../SKILL.md#where-the-guidance-moved).

package/skills/raft-ui-guide/rules/styling.md

@@ -0,0 +1,17 @@
+---
+name: styling
+description: "Moved to the Raft Design System docs: tokens, classes and recipes."
+---
+
+# Styling
+
+This guidance is part of the Raft Design System docs now, which are its single source. Each page is Markdown; read only the ones the task needs.
+
+- Color: https://raft-design.botiverse.build/foundations/color.md
+- Typography: https://raft-design.botiverse.build/foundations/typography.md
+- Spacing and sizing: https://raft-design.botiverse.build/foundations/spacing.md
+- Shape: https://raft-design.botiverse.build/foundations/shape.md
+- Elevation: https://raft-design.botiverse.build/foundations/elevation.md
+- States: https://raft-design.botiverse.build/foundations/states.md
+
+Check every prop, part and token you use against [lookup.md](./lookup.md).

package/skills/raft-ui-guide/rules/technical-overview.md

@@ -0,0 +1,80 @@
+---
+name: technical-overview
+description: "raft-ui's technical foundations, package contents, and integration contracts."
+---
+
+# Technical overview
+
+## Foundations
+
+`raft-ui` provides shared CSS foundations and a React 19 component library built on Base UI, Tailwind CSS v4, and tailwind-variants; the foundation also works with plain HTML and CSS. It has one visual language, Raft, with light, dark, and system modes.
+
+## Package contents
+
+| Entry                               | Contents                                |
+| ----------------------------------- | --------------------------------------- |
+| `raft-ui`                           | Stable components, providers, and hooks |
+| `@botiverse/raft-ui/cn`             | Class merger                            |
+| `@botiverse/raft-ui/wip`            | Experimental exports                    |
+| `@botiverse/raft-ui/foundation.css` | Native CSS theme variables              |
+| `@botiverse/raft-ui/styles.css`     | Tailwind integration                    |
+| `@botiverse/raft-ui/fonts.css`      | Optional web fonts                      |
+
+Component declarations live in `dist/index.d.mts` (see [API lookup](./lookup.md)). Version-matched Markdown guides and optional `raft-ui-guide` / `raft-ui-critique` skills ship in `skills/`.
+
+## Plain HTML
+
+Link or inline `dist/foundation.css`; no build is required. Optional `fonts.css` supplies web fonts.
+
+```html
+<link rel="stylesheet" href="./foundation.css" />
+<style>
+  body {
+    background: var(--layer-canvas);
+    color: var(--foreground);
+  }
+  article {
+    border: 2px solid var(--line-seam);
+  }
+</style>
+```
+
+`.light` / `.dark` set the mode; otherwise the document follows the system. The foundation defines variables, not component markup or interactions.
+
+## React stylesheet contract
+
+```css
+@import "tailwindcss";
+@import "@botiverse/raft-ui/styles.css";
+@source "../node_modules/@botiverse/raft-ui/dist/**/*.{js,mjs}";
+```
+
+`@source` is relative to this CSS file and must resolve to the installed package for Tailwind to generate its utilities.
+
+Import optional fonts from the app entry, not inside global CSS (`fonts.css` contains a web-font `@import`):
+
+```ts
+import "@botiverse/raft-ui/fonts.css";
+```
+
+Custom fonts use `--heading-font`, `--sans-font`, and `--mono-font`.
+
+## Providers
+
+| Provider          | Responsibility                                                                                                        |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `ThemeProvider`   | Color mode, persistence, and document mode synchronization                                                            |
+| `TooltipProvider` | Shared tooltip behavior when using Tooltip                                                                            |
+| `ToastProvider`   | Toast manager when using the toast API; see the [Toast](https://raft-design.botiverse.build/components/toast.md) page |
+
+`ThemeProvider` defaults to light mode. `mode` / `defaultMode` select `light`, `dark`, or `system`; `onModeChange` reports changes. `storageKey` persists an uncontrolled mode.
+
+`useTheme()` exposes `mode`, `resolvedMode` (`light` or `dark`, with `system` resolved), and `setMode`.
+
+## Mode and portal boundaries
+
+- `ThemeProvider` synchronizes `document.documentElement` by default. Nested scopes need `syncDom={false}` and the matching `light`/`dark` class on their root.
+- Base UI overlays portal to `document.body`. An app root with `isolation: isolate` keeps its stacking contexts below those surfaces. Embedded previews can use `portalProps.container` (toasts: `ToastProvider portalContainer`) to keep overlays inside their scope.
+- SSR apps with persisted mode need to restore it before first paint to avoid a theme flash.
+
+What floats and how popups are positioned is in [Elevation](https://raft-design.botiverse.build/foundations/elevation.md); which overlay to use is in [Choosing a component](https://raft-design.botiverse.build/patterns/choosing-components.md#overlays).