@botiverse/raft-ui 0.0.0-stage → 0.7.1

package/package.json

@@ -1,6 +1,95 @@
 {
   "name": "@botiverse/raft-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.1",
+  "description": "React components and CSS foundations for the Raft Design System.",
+  "keywords": [
+    "agent-skills",
+    "base-ui",
+    "components",
+    "design-system",
+    "react",
+    "tailwindcss",
+    "tanstack-intent"
+  ],
+  "homepage": "https://raft-design.botiverse.build",
+  "bugs": "https://github.com/botiverse/raft-design/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/botiverse/raft-design.git",
+    "directory": "packages/ui"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "codemods",
+    "dist",
+    "skills"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./cn": {
+      "types": "./dist/cn.d.mts",
+      "default": "./dist/cn.mjs"
+    },
+    "./wip": {
+      "types": "./dist/wip.d.mts",
+      "default": "./dist/wip.mjs"
+    },
+    "./fonts.css": "./dist/fonts.css",
+    "./styles.css": "./dist/styles.css",
+    "./package.json": "./package.json",
+    "./foundation.css": "./dist/foundation.css",
+    "./tokens.json": "./dist/tokens.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.8.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@tanstack/react-hotkeys": "^0.11.0",
+    "cnfast": "^0.2.0",
+    "foxact": "^0.3.12",
+    "lucide-react": "^1.48.0",
+    "react-resizable-panels": "^4.13.2",
+    "tailwind-merge": "^3.7.0",
+    "tailwind-variants": "^3.3.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^26.6.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@vitejs/plugin-react": "^6.1.1",
+    "@vitest/browser-playwright": "5.0.1",
+    "jsdom": "^30.1.1",
+    "playwright": "^1.63.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
+    "vite-plus": "1.0.0",
+    "vitest": "5.0.1"
+  },
+  "peerDependencies": {
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "scripts": {
+    "build:tokens": "node scripts/build-tokens.mjs",
+    "build": "vp pack",
+    "check": "vp check",
+    "dev": "vp pack --watch",
+    "test": "vp test"
+  }
 }

package/skills/raft-ui-critique/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: raft-ui-critique
+description: "Critique raft-ui components and product surfaces from screenshots, live renders, or code evidence in Light and Dark modes. Use when reviewing, auditing, polishing, comparing, or validating visual hierarchy, Raft fidelity, interaction feedback, accessibility, consistency, and user experience in packages/ui, docs compositions, or Playground."
+---
+
+# Raft UI Critique
+
+Review the rendered experience, not only implementation compliance. Produce specific, evidence-based findings for each color mode and for the relationships between them.
+
+Use [theme-lenses.md](./references/theme-lenses.md) for every review. Read active repository instructions when they are available, but keep this skill usable from the published `raft-ui` package without requiring sibling skills or repository-only files.
+
+## Theme model
+
+Raft is the only visual language. Treat its two color modes as independent critique presets:
+
+| Critique preset | Runtime configuration |
+| --------------- | --------------------- |
+| Light           | `mode="light"`        |
+| Dark            | `mode="dark"`         |
+
+Do not invent a theme family or a `theme` prop; `mode="system"` resolves to one of these two. Dark still requires its own evidence and verdict because dark surfaces, contrast, elevation, and interaction states fail independently.
+
+## Evidence boundary
+
+Use the strongest evidence available for the claim being made:
+
+1. For visual hierarchy and preset comparison, prefer matched screenshots or renders of both presets.
+2. For interaction, focus, responsive behavior, overlays, or motion, prefer a live page when the user and host environment authorize interaction.
+3. Use partial screenshots or renders for local observed findings only.
+4. Use component code and recipes to trace likely causes, never to claim a rendered result.
+
+Follow the host repository's tool and browser policy. Do not infer permission from this skill. When live interaction is unavailable, continue with supplied evidence and mark unexercised behavior as a coverage gap.
+
+When evidence is incomplete:
+
+- Critique what is visible without blocking useful work.
+- Name every missing preset, state, or viewport in `Coverage gaps`.
+- Do not issue a cross-mode pass verdict without matched evidence for both presets.
+- Label code-only conclusions as inferred. Do not claim pixel accuracy, visual parity, contrast compliance, or interaction quality from static code alone.
+
+## Package evidence lookup
+
+Use the first available evidence source; do not require a source checkout:
+
+1. In the raft-ui repository, inspect `packages/ui/src/foundation.css`, `packages/ui/src/fonts.css`, the component recipe, and its real consumers.
+2. In an installed application, inspect `node_modules/@botiverse/raft-ui/dist/foundation.css`, `node_modules/@botiverse/raft-ui/dist/fonts.css`, `node_modules/@botiverse/raft-ui/dist/index.d.mts`, and the application's component usage.
+3. If neither code surface is available, rely on supplied screenshots or renders and state that implementation ownership is unverified.
+
+Treat declarations as API evidence and compiled CSS as token evidence.
+
+## Review workflow
+
+Follow this sequence without merging the lenses.
+
+### 1. Establish context
+
+State what the surface is, who uses it, its primary task, and the likely user state of mind. Distinguish an isolated primitive, a canonical composition, and a product workflow; each has a different appropriate density and level of context.
+
+### 2. Normalize the evidence
+
+Compare like for like:
+
+- Use the same component, content, state, viewport dimensions, zoom, and motion frame.
+- Keep surrounding context equivalent. A fragment without its normal shell cannot prove page hierarchy.
+- Record which interaction states are shown: default, hover, pressed, focus-visible, disabled, selected, open, checked, invalid, loading, or empty, as applicable.
+- Separate the live primitive, docs composition, and Playground wrapper. Never treat one as proof for another.
+
+Record an evidence manifest with the route or artifact, preset, exact viewport, browser/platform when known, zoom, font-loading status, UI state, and reduced-motion setting when motion is relevant. For a full product-surface review, include a representative wide and narrow viewport when the layout is responsive; a single isolated primitive may need only its relevant size.
+
+If mismatched evidence prevents a fair comparison, report that before critiquing the modes.
+
+### 3. Exercise interaction when live evidence is available
+
+Use both pointer and keyboard for applicable controls:
+
+1. Observe the resting state and identify the expected action.
+2. Exercise hover, pressed, and keyboard focus-visible independently.
+3. Open, select, check, expand, drag, validate, load, or disable the control when those states belong to the surface.
+4. Inspect overlay placement, clipping, focus return, and preset inheritance.
+5. Repeat the material states in both presets; do not assume behavior verified in one preset survives the other.
+
+Capture or record the exact state that supports each interaction finding. If a state cannot be reached safely, mark it `Not exercised`; do not issue a pass or failure verdict for that state.
+
+### 4. Give a first impression
+
+Write one direct paragraph about the overall hierarchy and emotional tone. Identify the visual entry point, the heaviest element, and the most obvious source of friction. Do not pad the critique with generic praise.
+
+### 5. Review the shared interface
+
+Audit the dimensions that should work in every preset:
+
+- Visual hierarchy: color intentionality, typography, weight versus importance, spacing, alignment, density, icons, and media.
+- Interface design: focusing mechanism, progressive disclosure, information load, expectation setting, feedback, redundancy, and platform conventions.
+- Interaction: visible affordances and distinguishable hover, pressed, focus-visible, disabled, selected, open, checked, invalid, and loading states when relevant.
+- User context: emotional burden, time pressure, recoverability, clarity of the next action, and moments where uncommon care is missing.
+- Accessibility visible from the evidence: focus visibility, target clarity, state communication, text legibility, and reliance on color alone. Do not claim keyboard behavior without exercising it or a contrast ratio without measured colors.
+
+Count and name what is visible. Prefer "four surfaces compete with equal weight" over "the hierarchy feels off."
+
+### 6. Review each preset independently
+
+Apply the lenses in [theme-lenses.md](./references/theme-lenses.md):
+
+1. Raft, in Light and in Dark
+2. Dark mode, in Dark
+
+Dark is not an inverted Light screenshot. Judge whether each preset expresses the same semantic hierarchy through the Raft visual language.
+
+### 7. Compare across presets
+
+Check the cross-mode invariants in [theme-lenses.md](./references/theme-lenses.md).
+
+A shared defect belongs under `Cross-mode`. A defect visible in only one preset belongs under that preset even when the root cause is shared code.
+
+### 8. Trace likely ownership
+
+When code is available, connect each visual issue to the most likely owner without turning the critique into an implementation plan:
+
+- Reusable appearance or interaction styling: `packages/ui` component recipe or semantic tokens.
+- Canonical example structure: docs module composition.
+- Product state or workflow coordination: Playground or application consumer.
+- Global token and font material: `foundation.css` / `fonts.css` (see Package evidence lookup).
+
+State whether the cause is observed, code-verified, or inferred. Do not prescribe a new token for a one-off correction, and do not patch a consumer to compensate for a broken reusable component contract.
+
+### 9. Prioritize findings
+
+Use these severities:
+
+- `P1` — Blocks understanding or task completion; hides focus/state; creates a serious accessibility problem; or breaks structure in a preset.
+- `P2` — Material hierarchy, readability, interaction, consistency, or cross-mode defect that should be fixed.
+- `P3` — Local polish issue with limited user impact.
+
+Order structural and behavioral problems before visual polish. Do not invent a finding for every preset.
+
+## Finding format
+
+Write every finding as:
+
+`[P2][Dark][Surface separation] — factual observation. User impact. Direction for improvement. Evidence: screenshot, state, or file.`
+
+Keep observation, impact, and direction distinct. If the cause is inferred, say so explicitly.
+
+## Output format
+
+Always include:
+
+```markdown
+## Context and evidence
+
+## Overall verdict
+
+## Findings
+
+## Top opportunities
+
+## Coverage gaps
+```
+
+Under `Findings`, add `Cross-mode`, `Light`, `Dark`, or `Interaction and user context` subsections only when evidence supports them. Do not create empty preset sections for a partial review. Under `Top opportunities`, rank one to five supported changes and name which presets they affect; there is no minimum finding count.
+
+## Hard boundaries
+
+- Keep review-only requests read-only.
+- Do not conflate critique with functional validation, static checks, or test results.
+- Do not recommend making Light and Dark visually identical; require equivalent usability and semantic hierarchy.
+- Do not let mode-specific polish change component meaning, public API, or business structure.

package/skills/raft-ui-critique/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Raft UI Critique"
+  short_description: "Review raft-ui in Light and Dark modes"
+  default_prompt: "Use $raft-ui-critique to review the supplied interface evidence in Light and Dark modes. State coverage, exercise interactions only when authorized, and do not infer unseen states."

package/skills/raft-ui-critique/references/theme-lenses.md

@@ -0,0 +1,69 @@
+# Theme Lenses
+
+Use all three lenses for a full review: the cross-mode lens, the Raft lens in each preset, and the dark-mode lens for Dark. Verify token- or typography-specific claims against `foundation.css` and `fonts.css` (see Package evidence lookup in SKILL.md).
+
+## Cross-mode lens
+
+Check whether Light and Dark preserve:
+
+- The same component identity, content, reading order, and interaction model.
+- Equivalent importance for primary actions, destructive actions, status, metadata, and secondary controls.
+- Usable geometry: no mode-only clipping, wrapping, crowding, overlay collision, or target shrinkage.
+- Component ownership: a mode may restyle structure but must not add, remove, or replace business DOM.
+- Semantic color roles: primary is interactive expression and hints; accent is core or important action; state colors communicate state rather than decoration.
+- Contextual fit: the component still belongs in the surrounding shell instead of looking like a pasted demo.
+
+Use a comparison matrix when several states are present:
+
+| State or relationship   | Light    | Dark     | Verdict      |
+| ----------------------- | -------- | -------- | ------------ |
+| Resting hierarchy       | observed | observed | pass/finding |
+| Hover and pressed       | observed | observed | pass/finding |
+| Focus-visible           | observed | observed | pass/finding |
+| Disabled or unavailable | observed | observed | pass/finding |
+| Selected/open/checked   | observed | observed | pass/finding |
+| Error/loading/empty     | observed | observed | pass/finding |
+
+Include only applicable rows. `Not shown` is evidence status, not a pass.
+
+## Raft lens
+
+Judge whether the surface speaks Raft's material language:
+
+- Every color block is a sticker: an ink edge and ink type on the color. Flag colored fills without the edge, light type on a sticker, and edges that double up with an adjacent border.
+- Lines carry roles: ink lines say "control", seams split regions, hairlines sit inside content. Flag a hairline used as a control edge or an ink line used as a region divider.
+- Controls cast no shadow; only overlays float, and `--elevation-sticker` is a hard offset under a sticker. Flag soft shadows on controls, cards, or rows, and floating surfaces without the overlay shadow.
+- Corners follow the shape scale in `styles.css`: sticker, chip, control, container, dialog; fully round only for switches and radios. Flag corners off the scale or mixed within one group.
+- Space Grotesk is what people say; Space Mono is what machines write (ids, times, counts, events, code). Flag machine output set in sans and prose set in mono.
+- Yellow and pink must carry semantic roles. Flag decorative yellow/pink fields that compete with primary actions or status.
+- Hover and pressed keep a control's resting color under an ink wash; focus-visible is the ink ring. Flag a state that swaps a sticker's color or that is indistinguishable from rest.
+- Stickers, ink edges, and bold type create high baseline intensity. Require a clear entry point and quieter secondary information so the surface does not shout uniformly.
+
+Ask: does every sticker, line, and shadow carry a role, or is the surface merely loud?
+
+## Dark-mode lens
+
+Review this independently rather than treating it as color inversion:
+
+- Content stays lighter than the frame and sidebar, and card, popover, and inset surfaces step lighter again. Flag panels, cards, fields, and popovers that collapse into one black plane.
+- Preserve the neutral material and text hierarchy. Flag pure-black patches, mismatched neutrals, glowing white text, and muted text that becomes either dominant or unreadable.
+- Stickers keep their colors and ink type and gain a die-cut edge. Flag stickers that lose the edge or switch to light type.
+- Seams, hairlines, and the overlay shadow must separate adjacent dark surfaces without creating halos, dirty seams, or black fog.
+- Semantic colors and translucent state washes must composite cleanly over page, panel, and popover surfaces. Flag oversaturation, muddy status colors, and color-only state communication.
+- Hover, pressed, focus-visible, selected, checked, invalid, and disabled states need distinct luminance or structure; a slight color shift that disappears on dark is not enough.
+- Overlays and portals must inherit Dark correctly. Check popovers, menus, dialogs, tooltips, native controls, and backdrops for light-mode leakage.
+- Media, avatars, icons, and illustrations must retain intended contrast without accidental dimming, inversion, or bright edge artifacts.
+
+Ask: does this feel dimensional and composed, or flat, glowing, and fatiguing?
+
+## User-context lens
+
+For every preset, ask:
+
+- Where does the eye land first, and is that the right place for the task?
+- What emotion does the visual language add: confidence, urgency, playfulness, calm, pressure, or confusion?
+- Does the density suit the user's likely time pressure and expertise?
+- Are loading, empty, error, success, and destructive moments handled with appropriate care?
+- Does switching presets preserve confidence, or make the product appear to change behavior?
+
+Tie every emotional judgment to visible evidence. Do not substitute taste words for observations.

package/skills/raft-ui-guide/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: raft-ui-guide
+description: "Build with raft-ui, the React implementation of the Raft Design System: where the guidelines and each component's API are, the API facts that differ from other libraries, and how to check props. Use when choosing, composing or styling raft-ui components."
+---
+
+# raft-ui
+
+The package is `@botiverse/raft-ui`. Plain HTML can use `foundation.css` directly; the components are React, built on **Base UI** (`@base-ui/react`), **Tailwind CSS v4** and **tailwind-variants**.
+
+The design guidance (which component to use, how components combine into screens, what each color and size means) lives in the Raft Design System docs, not in this skill. Every page is Markdown:
+
+- **Index:** https://raft-design.botiverse.build/llms.txt lists every page with a one-line summary.
+- **Components:** https://raft-design.botiverse.build/components.json lists every component with its status, other names and doc URLs. Each component page, `https://raft-design.botiverse.build/components/<component>.md`, has when to use it, its parts, rules and an API generated from the code.
+- **Choosing a component:** https://raft-design.botiverse.build/components/overview.md#how-to-choose-a-component.
+
+This skill keeps what is specific to the code: the [adoption](./rules/adoption.md) order, [looking up](./rules/lookup.md) props and tokens, and the [technical overview](./rules/technical-overview.md) (package contents, stylesheets, providers). Do not register or install skills in a consumer project unless requested.
+
+## Working sequence
+
+1. Find the component in `components.json` or on the choosing page; read only the pages the task needs.
+2. Verify every prop, part, variant and token you use with [rules/lookup.md](./rules/lookup.md). The page's API section and `node_modules/@botiverse/raft-ui/dist/index.d.mts` agree; the declarations win for the installed version.
+3. Implement the smallest composition that keeps native semantics and uses raft-ui where its behavior or look is needed.
+4. Apply the review checklist below after implementation.
+
+When this skill is loaded through TanStack Intent, run `intent load @botiverse/raft-ui#raft-ui-guide --path` before opening a linked rule file, then resolve the link relative to the returned `SKILL.md` directory.
+
+## Override your priors first
+
+raft-ui is not shadcn/ui, not Radix, not MUI. These defaults are wrong here:
+
+| Your instinct                                                    | Reality in raft-ui                                                                                            |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `<Button variant="destructive">`                                 | `variant="danger"`, and only on the confirm button of an `AlertDialog`. See the Button page for every variant |
+| `<Button size="icon">`                                           | `size="icon-md"` or `size="icon-lg"`                                                                          |
+| `className="text-gray-500 bg-slate-50"`                          | Don't use Tailwind's default palette. Use the semantic tokens: `text-foreground-muted`, `bg-fill-muted`       |
+| Flat props: `<Dialog title="x" description="y">`                 | Compound parts: `<Dialog><DialogContent><DialogHeader><DialogTitle>…`; `DialogContent` portals itself         |
+| Radix API (`asChild`)                                            | Base UI API: the `render` prop                                                                                |
+| Add a `kind`/`state`/`emphasis` prop for a structural difference | Use the dedicated part or component instead                                                                   |
+| `<Button loading>` doesn't exist, roll a spinner                 | `loading` and `loadingLabel` are real props on `Button`                                                       |
+
+**Never guess a prop or variant name.** See [rules/lookup.md](./rules/lookup.md).
+
+Intent names are **not** consistent across components: negative is `danger` on `Button`, `Badge`, `Status` and `Progress`, `destructive` on `Banner`, and `error` on toast objects and `NotificationCenterItemIcon`. Never carry a variant value from one component to another.
+
+## Principles
+
+- Composition over configuration. Visible structure lives in `children` and named parts, never in a prop that switches layouts.
+- Use semantic tokens, never raw color. Each color has one meaning (yellow is "you", pink is the one primary action); see https://raft-design.botiverse.build/foundations/color.md.
+- Base UI owns headless behavior (open state, focus, keyboard, collections). Product state (upload lifecycle, permissions, workflow) belongs in your app, not in a component prop.
+- Raft is the only visual language, in light and dark modes; `ThemeProvider` switches the mode globally. Components adapt themselves.
+
+## Common mistakes
+
+| Mistake                                            | Fix                                                                     |
+| -------------------------------------------------- | ----------------------------------------------------------------------- |
+| `asChild` on a trigger or close part               | Base UI: `render={<Button … />}`                                        |
+| Actions menu built out of `Select`                 | `DropdownMenu`                                                          |
+| Persistent condition announced with `toast.info()` | `Banner`: toasts expire, conditions don't                               |
+| Buttons or links inside a `Tooltip`                | `Popover`: tooltip content is unreachable                               |
+| Destructive confirm as a styled `Dialog`           | `AlertDialog` with `AlertDialogAction` / `AlertDialogCancel`            |
+| Validation copy disconnected from its control      | `Field` + `FieldError`                                                  |
+| `PanelHeader` where you meant the bare frame       | `PanelHeaderRoot`: `PanelHeader` is the composed identity chrome        |
+| Re-created raft-ui divider, badge, or type styling | `Separator`, `Badge`, or `Text`; keep native semantics when intentional |
+
+## Where the guidance moved
+
+The guideline rules this skill used to carry are pages of the design system now. Each file in `rules/` that is not listed above points to them.
+
+| For                                               | Read                                                                                                                       |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Which component, which feedback, which overlay    | https://raft-design.botiverse.build/components/overview.md#how-to-choose-a-component                                       |
+| Combining parts, things built from existing parts | https://raft-design.botiverse.build/components/overview.md#built-from-existing-parts                                       |
+| Forms and settings                                | https://raft-design.botiverse.build/patterns/forms.md                                                                      |
+| Feedback, loading, empty and error states         | https://raft-design.botiverse.build/patterns/feedback.md                                                                   |
+| Shell, panels, headers, navigation                | https://raft-design.botiverse.build/patterns/page-structure.md, https://raft-design.botiverse.build/patterns/navigation.md |
+| Chat, threads, composer, agents                   | https://raft-design.botiverse.build/patterns/conversation.md, https://raft-design.botiverse.build/patterns/agents.md       |
+| Color, type, spacing, shape, elevation            | https://raft-design.botiverse.build/foundations/color.md and the other pages under `/foundations/`                         |
+| One component's parts, rules and API              | https://raft-design.botiverse.build/components/<component>.md                                                              |
+
+## Review checklist
+
+When reviewing or editing code that uses raft-ui, check:
+
+- [ ] No variant value carried across components; verify against the declarations
+- [ ] Controls with raft-ui label, description, or validation treatment use `Field`; simpler native associations remain explicit and accessible
+- [ ] No Tailwind default palette (`gray-*`, `slate-*`, …), hex, `rgb()`, or `hsl()`: semantic tokens, raw `oklch()` only for one-offs
+- [ ] No `asChild`: element substitution uses `render`
+- [ ] Do not recreate a raft-ui component's visual or behavioral contract with ad hoc markup; native semantic elements remain valid when no library contract is needed
+- [ ] Every `Avatar` with an `AvatarImage` also has an `AvatarFallback`; every blocking overlay has a `Title`
+- [ ] Menu rows are `…Item` parts, not raw `<button>`s; raw buttons drop out of keyboard navigation
+- [ ] Product state (upload, permissions, read/unread) lives in the app; the component renders parts, not a `state` prop
+- [ ] No shadow written as `shadow-[var(--…)]`: named utility or fully literal
+
+## Stability
+
+`raft-ui` is the stable surface; `@botiverse/raft-ui/wip` is experimental. Import `cn` from `@botiverse/raft-ui/cn`.

package/skills/raft-ui-guide/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Raft UI Guide"
+  short_description: "Build correctly with raft-ui components and tokens"
+  default_prompt: "Use $raft-ui-guide to choose and compose the correct stable raft-ui components for this interface."

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

@@ -0,0 +1,55 @@
+---
+name: adoption
+description: "Adopting raft-ui in an existing project: inventory before changing, the order that prevents locally-correct/globally-wrong results, and what acceptance means beyond 'it renders'."
+---
+
+# Adopting raft-ui in an existing project
+
+## Inventory before you change anything
+
+Classify every hand-rolled control first. Do not read-and-replace file by file: you
+will convert the easy ones, leave the hard ones, and end with a surface that is
+half one system and half another.
+
+| Bucket | Meaning                                                 | Action                  |
+| ------ | ------------------------------------------------------- | ----------------------- |
+| A      | raft-ui has an equivalent                               | Replace                 |
+| B1     | raft-ui has no such primitive                           | Out of scope; report it |
+| B2     | raft-ui has it only bound to a domain, no generic layer | Out of scope; report it |
+| C      | Must stay hand-rolled (example code, product-specific)  | Leave, and say why      |
+
+Report B1 (new primitive) and B2 (extract a generic layer from existing code, far
+cheaper) separately.
+
+Count what you are not converting. A migration that reports only its A bucket
+reads as complete when it is not.
+
+## Work in this order
+
+```
+tokens -> primitives -> composition -> layout
+```
+
+Jumping levels is what produces a screen where every control is individually
+correct and the screen is wrong. Finish one level across the whole surface before
+starting the next.
+
+## Acceptance is hierarchy, not rendering
+
+Checking that a screen renders, fits, and does not overflow does not test the thing
+most likely to be wrong. For each surface, read it and answer:
+
+- Which control is the primary action? If more than one answer is defensible, the
+  hierarchy is wrong — see the action-group rule in [composition.md](./composition.md).
+- Do controls at the same level look like the same kind of thing?
+- Does any single element carry a treatment nothing else on the page shares?
+- Do status colors track the value they report, or are they one color regardless?
+
+Swapping a component is not finishing a design. The variant being individually
+valid says nothing about whether the row it sits in is coherent.
+
+## Report what you had to read the source for
+
+If you had to open `dist/index.d.mts`, a recipe, or a comment to learn a rule, that
+rule is not documented. Record it and report it with the migration so it can land
+in these guides.

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

@@ -0,0 +1,14 @@
+---
+name: composition
+description: "Moved to the Raft Design System docs: combining compound parts, overlay containers, business actions and wrappers."
+---
+
+# Composition
+
+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.
+
+- Built from existing parts: https://raft-design.botiverse.build/components/overview.md#built-from-existing-parts
+- Choosing a component: https://raft-design.botiverse.build/components/overview.md#how-to-choose-a-component
+- The component's own page, for its parts: https://raft-design.botiverse.build/components/<component>.md
+
+Check every prop, part and token you use against [lookup.md](./lookup.md).

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

@@ -0,0 +1,15 @@
+---
+name: conversation
+description: "Moved to the Raft Design System docs: chat, threads, the composer, the sidebar, the activity inbox and workspace search."
+---
+
+# Conversation surfaces
+
+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.
+
+- Conversation: https://raft-design.botiverse.build/patterns/conversation.md
+- Agents: https://raft-design.botiverse.build/patterns/agents.md
+- Navigation: https://raft-design.botiverse.build/patterns/navigation.md
+- Raft Chat: https://raft-design.botiverse.build/products/raft-chat.md
+
+Check every prop, part and token you use against [lookup.md](./lookup.md).

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

@@ -0,0 +1,14 @@
+---
+name: display
+description: "Moved to the Raft Design System docs: typography, code, avatars, files and keyboard hints."
+---
+
+# Text and display
+
+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.
+
+- Typography: https://raft-design.botiverse.build/foundations/typography.md
+- Iconography: https://raft-design.botiverse.build/foundations/iconography.md
+- Text, InlineCode, CodeBlock, Avatar, Kbd and the other content components: https://raft-design.botiverse.build/components.json
+
+Check every prop, part and token you use against [lookup.md](./lookup.md).

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

@@ -0,0 +1,13 @@
+---
+name: feedback
+description: "Moved to the Raft Design System docs: banners, toasts, loading, empty states and badges."
+---
+
+# Feedback and status
+
+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.
+
+- Feedback: https://raft-design.botiverse.build/patterns/feedback.md
+- Choosing a component: telling people something, and waiting: https://raft-design.botiverse.build/components/overview.md#telling-people-something
+
+Check every prop, part and token you use against [lookup.md](./lookup.md).

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

@@ -0,0 +1,13 @@
+---
+name: forms
+description: "Moved to the Raft Design System docs: choosing and composing form controls and wiring them with Field."
+---
+
+# Form controls
+
+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.
+
+- Forms and settings: https://raft-design.botiverse.build/patterns/forms.md
+- Choosing a component: picking something: https://raft-design.botiverse.build/components/overview.md#picking-something
+
+Check every prop, part and token you use against [lookup.md](./lookup.md).

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

@@ -0,0 +1,15 @@
+---
+name: layout
+description: "Moved to the Raft Design System docs: the shell, panels, headers, navigation, resizing and task surfaces."
+---
+
+# Layout and shell
+
+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.
+
+- Page structure: https://raft-design.botiverse.build/patterns/page-structure.md
+- Navigation: https://raft-design.botiverse.build/patterns/navigation.md
+- Wide and narrow: https://raft-design.botiverse.build/patterns/responsive.md
+- Tasks: https://raft-design.botiverse.build/patterns/tasks.md
+
+Check every prop, part and token you use against [lookup.md](./lookup.md).