@wangs-ui/skills 1.3.0-alpha.2 → 1.3.0-alpha.21

package/README.md

@@ -1,31 +1,33 @@
 # @wangs-ui/skills
 
-Modular AI agent skills installer and manager for **Wangs UI** React components and design patterns.
+Modular AI agent skills and guardrail rules installer and manager for **Wangs UI** React components and design patterns.
 
----
-
-## 📚 Dedicated Storybook Guide
-
-For a step-by-step guide on using `@wangs-ui/skills` independently with any Storybook project, see the [Dedicated Storybook Guide](../../docs/storybook-mcp-skills.md).
+Skills and rules are standalone: they work in any Storybook or React project without requiring project scaffolding tools. They pair with [`@wangs-ui/mcp`](../mcp/README.md), which supplies the live component catalog, typed APIs, and story implementations the skills tell agents to verify against.
 
 ---
 
 ## ⚡ Quick Start
 
 ```bash
-# List available skills
+# List available skills & rules
 npx @wangs-ui/skills list
 
-# Install skills (opens interactive multiselect menu with skill descriptions)
+# Interactive installer (select skills and rules via multiselect menu)
 npx @wangs-ui/skills add
 
+# Install all rules (Wangs UI invariants, React 19 compiler-first, TypeScript strict)
+npx @wangs-ui/skills add --rules
+
 # Install specific skills directly by name
 npx @wangs-ui/skills add wangs-ui-components data-table create-form
 
-# Update installed skills
+# Install specific rules directly by name
+npx @wangs-ui/skills add forms-destructuring-lock no-raw-html
+
+# Update installed skills and rules
 npx @wangs-ui/skills update
 
-# Remove a skill
+# Remove a skill or rule
 npx @wangs-ui/skills remove create-form
 ```
 
@@ -33,6 +35,8 @@ npx @wangs-ui/skills remove create-form
 
 ## 🛠️ Features
 
-- **Modular UI Skills**: Installs specialized guidelines, component patterns, and rules into your AI agent environment.
+- **Procedural Skills**: Installs specialized step-by-step guidelines and workflows into your agent environment (`.agents/skills/`, `.claude/skills/`, etc.).
+- **Declarative Guardrail Rules**: Installs high-signal invariants and pitfalls (`.agents/rules/`, `.claude/rules/`) covering Wangs UI core facts, React 19 compiler patterns, and strict TypeScript discipline.
+- **MCP-Verified Guidance**: Skills mandate querying the MCP server for live contracts instead of hardcoding props, so guidance never drifts from the installed package version.
 - **Cross-Platform & Multi-Agent**: Supports Antigravity IDE, Claude Code, OpenCode, Kilo, and universal agent directories on Mac and Windows.
 - **Independent Usage**: Works in any Storybook or React project without requiring project scaffolding tools.

package/dist/bin.js

@@ -1,21 +1,22 @@
 #!/usr/bin/env node
-import { i as listSkills, n as updateSkills, r as addSkills, t as removeSkills } from "./src-DDi-O7tk.js";
+import { i as listSkills, n as updateSkills, r as addSkills, t as removeSkills } from "./src-BFwMaU8I.js";
 import path from "node:path";
 import { parseArgs } from "node:util";
 //#region bin.ts
+var VERSION = "1.3.0-alpha.20";
 var HELP_TEXT = `
-\x1b[1m\x1b[36m🚀 Wangs UI Skills CLI\x1b[0m
-Install, update, and manage modular AI agent skills for Wangs UI React applications.
+\x1b[1m\x1b[36m🚀 Wangs UI Skills & Rules CLI\x1b[0m
+Install, update, and manage modular AI agent skills and rules for Wangs UI React applications.
 
 \x1b[1mUsage:\x1b[0m
   npx @wangs-ui/skills [command] [options]
   wangs-ui-skills [command] [options]
 
 \x1b[1mCommands:\x1b[0m
-  \x1b[36mlist\x1b[0m                      List all available and installed skills
-  \x1b[36madd\x1b[0m [skills...]           Install specified skills (interactive if none provided)
-  \x1b[36mupdate\x1b[0m [skills...]        Update installed skills to latest versions
-  \x1b[36mremove\x1b[0m <skills...>        Remove specified skills from agent environment
+  \x1b[36mlist\x1b[0m                      List all available and installed skills & rules
+  \x1b[36madd\x1b[0m [items...]            Install specified skills or rules (interactive if none provided)
+  \x1b[36mupdate\x1b[0m [items...]         Update installed skills and rules to latest versions
+  \x1b[36mremove\x1b[0m <items...>         Remove specified skills or rules from agent environment
 
 \x1b[1mOptions:\x1b[0m
   --target <dir>            Target directory (default: current working directory)
@@ -24,8 +25,9 @@ Install, update, and manage modular AI agent skills for Wangs UI React applicati
 
 \x1b[1mExamples:\x1b[0m
   npx @wangs-ui/skills list
-  npx @wangs-ui/skills add create-form
-  npx @wangs-ui/skills add wangs-ui-components data-table dialog-modal
+  npx @wangs-ui/skills add --rules
+  npx @wangs-ui/skills add forms-destructuring-lock
+  npx @wangs-ui/skills add create-form data-table
   npx @wangs-ui/skills update
   npx @wangs-ui/skills remove create-form
 `;
@@ -36,7 +38,7 @@ async function main() {
 		return;
 	}
 	if (args.includes("--version") || args.includes("-v")) {
-		console.log("1.0.0");
+		console.log(VERSION);
 		return;
 	}
 	const parsed = parseArgs({
@@ -45,10 +47,13 @@ async function main() {
 		allowPositionals: true,
 		strict: false
 	});
-	const baseDir = parsed.values.target ? path.resolve(parsed.values.target) : process.cwd();
+	const targetVal = parsed.values.target;
+	const baseDir = typeof targetVal === "string" ? path.resolve(targetVal) : process.cwd();
 	const { positionals } = parsed;
 	const command = positionals[0] || "list";
-	const skillArgs = positionals.slice(1);
+	const itemArgs = positionals.slice(1);
+	if (args.includes("--rules")) itemArgs.push("--rules");
+	if (args.includes("--skills")) itemArgs.push("--skills");
 	switch (command) {
 		case "list":
 		case "ls":
@@ -57,16 +62,16 @@ async function main() {
 		case "add":
 		case "install":
 		case "i":
-			await addSkills(skillArgs, baseDir);
+			await addSkills(itemArgs, baseDir);
 			break;
 		case "update":
 		case "up":
-			updateSkills(skillArgs, baseDir);
+			updateSkills(itemArgs, baseDir);
 			break;
 		case "remove":
 		case "rm":
 		case "delete":
-			removeSkills(skillArgs, baseDir);
+			removeSkills(itemArgs, baseDir);
 			break;
 		default:
 			console.log(`\x1b[31mUnknown command: "${command}"\x1b[0m`);

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as getAgentSkillDirs, c as isSkillInstalled, d as loadAllSkills, i as listSkills, l as removeSkill, n as updateSkills, o as getInstalledSkills, r as addSkills, s as installSkill, t as removeSkills, u as getSkill } from "./src-DDi-O7tk.js";
-export { addSkills, getAgentSkillDirs, getInstalledSkills, getSkill, installSkill, isSkillInstalled, listSkills, loadAllSkills, removeSkill, removeSkills, updateSkills };
+import { _ as loadAllRules, a as getAgentRuleDirs, c as getInstalledSkills, d as isRuleInstalled, f as isSkillInstalled, g as getSkill, h as getRule, i as listSkills, l as installRule, m as removeSkill, n as updateSkills, o as getAgentSkillDirs, p as removeRule, r as addSkills, s as getInstalledRules, t as removeSkills, u as installSkill, v as loadAllSkills } from "./src-BFwMaU8I.js";
+export { addSkills, getAgentRuleDirs, getAgentSkillDirs, getInstalledRules, getInstalledSkills, getRule, getSkill, installRule, installSkill, isRuleInstalled, isSkillInstalled, listSkills, loadAllRules, loadAllSkills, removeRule, removeSkill, removeSkills, updateSkills };

package/dist/rules/wangs-ui/default-props-precedence.md

@@ -0,0 +1,13 @@
+---
+trigger: model_decision
+description: "Apply when deciding whether a prop belongs in global defaultProps config or per-instance JSX."
+metadata:
+  owner: wangs-ui
+---
+# Wangs UI Fact: `configOptions.defaultProps` Precedence
+
+`WangsUiProvider.configOptions.defaultProps` lets any project set global
+default prop values per component. Per-instance JSX props always win over
+that global default — the merge order is global-default-then-instance, never
+the reverse. This is a `WangsUiProvider` mechanism, true in any project that
+uses it, independent of what values a given project actually configures.

package/dist/rules/wangs-ui/forms-destructuring-lock.md

@@ -0,0 +1,18 @@
+---
+trigger: model_decision
+description: "Apply when writing a <Field> render-prop callback in a Wangs UI Form/DialogForm."
+metadata:
+  owner: wangs-ui
+---
+# Wangs UI Fact: `<Field>` Render-Prop Must Destructure `{ fieldProps, fieldState }`
+
+`<Field>`'s callback render prop must destructure as `{({ fieldProps, fieldState })}`.
+Passing a single parameter instead (`{(field) => ...}`) produces `undefined`
+`value`/`onChange` and permanently locks the input — the field never becomes
+interactive, even on initial render. This is a real `@wangs-ui/form` quirk,
+not a project convention; it reproduces the same way in any consumer.
+
+`<Field>` is generic — `fieldProps.onChange` is already typed to the field's
+actual value type. Pass it straight through (`fieldProps.onChange`); don't
+wrap it in a defensive `typeof`/`e?.target?.value` extraction, that's fighting
+a type the field already guarantees.

package/dist/rules/wangs-ui/no-raw-html.md

@@ -0,0 +1,28 @@
+---
+trigger: model_decision
+description: "Apply when writing JSX markup — enforce Wangs UI primitives over raw HTML elements."
+metadata:
+  owner: wangs-ui
+---
+# Rule: No Raw HTML Controls
+
+Zero raw HTML elements. Use Wangs UI primitives and Foundation theme typography.
+
+## Prohibitions
+
+- No `<button>`, `<input>`, `<select>`, `<textarea>`, `<form>`, `<table>`, `<dialog>`.
+- No `<h1>`-`<h6>`, `<p>`, `<span>` for text typography without Wangs UI theme primitives.
+
+## Mandatory Imports
+
+- Primitives via subpath:
+  - `@wangs-ui/react-core/primitive/button`
+  - `@wangs-ui/react-core/primitive/input`
+  - `@wangs-ui/react-core/primitive/datatable`
+  - `@wangs-ui/react-core/primitive/modal`
+  - `@wangs-ui/react-core/primitive/dialogform`
+  - `@wangs-ui/react-core/primitive/card`
+  - `@wangs-ui/react-core/primitive/badge`
+- Typography via Foundation theme:
+  - `@wangs-ui/foundation/theme` (`Text`, `Code`, `Kbd`, `Link`, `Mark`, `Blockquote`, `List`)
+  - Use variants: `display*`, `headline*`, `title*`, `body*`, `label*`.

package/dist/rules/wangs-ui/no-redundant-wrappers.md

@@ -0,0 +1,55 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing JSX layout for redundant wrapper containers."
+metadata:
+  owner: wangs-ui
+---
+# Rule: No Redundant Layout & Container Wrappers
+
+> **Severity**: **ARCHITECTURAL CODE SMELL / LINT FAILURE**.
+
+Components must not be wrapped in an unnecessary layout element. A `<div>` (or `Box`/`Stack`) wrapping a single component without active layout coordination is strictly prohibited — see `.agents/skills/universal-layout` and `.agents/rules/no-inline-component-styling.md` §2 for which primitive replaces a raw `<div>` when layout coordination is genuinely needed.
+
+---
+
+## 1. Prohibited Anti-Patterns
+
+1. **Single-Child Wrapper `<div>`**:
+   Never wrap a single component (e.g. `<DataTable />`, `<Card />`, `<Tabs />`, `<Input />`, `<Button />`) inside an isolated `<div>` that has no layout siblings.
+2. **Intermediate Tab/Card Wrappers**:
+   Do not insert pass-through `<div>` wrappers between `<Card>`/`<Tabs>` and feature content:
+   ```tsx
+   // ❌ Bad — Redundant intermediate div wrapping a single tab component
+   function TabbedPage() {
+     return (
+       <Card>
+         <Tabs ... />
+         <div>
+           {activeTab === 'general' ? <GeneralTab /> : <AdvancedTab />}
+         </div>
+       </Card>
+     );
+   }
+
+   // ✅ Good — Render active tab directly as Card child
+   function TabbedPage() {
+     return (
+       <Card>
+         <Tabs ... />
+         {activeTab === 'general' ? <GeneralTab /> : <AdvancedTab />}
+       </Card>
+     );
+   }
+   ```
+3. **Redundant Table Wrappers**:
+   Never wrap `<DataTable />` in a `Box`/`div` solely to set width or margin. Wangs UI DataTable manages its own container scroll and dimensions out of the box.
+
+---
+
+## 2. When a Layout Wrapper Is Permitted
+
+A layout wrapper is **ONLY** warranted when coordinating **2 or more siblings** in a structural layout — and even then it's a `universal-layout` primitive, not a raw `<div>`:
+
+1. **Alignment bars**: header title + search + action buttons → `<HStack justify="between">`.
+2. **Multi-column/card grids**: responsive multi-card or multi-field layouts → `<Grid columns={{ compact: 1, medium: 2, expanded: 3 }}>`.
+3. **Fragment Alternative**: when returning multiple adjacent elements without layout coordination, use React Fragment (`<>...</>`) — not an empty wrapper.

package/dist/rules/wangs-ui/react19-checklist-and-reference.md

@@ -0,0 +1,37 @@
+---
+trigger: model_decision
+description: "Apply when doing a final review pass on React 19 component or hook code for compiler-optimization compliance."
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Review Checklist & Quick Reference
+
+## Checking Compiler Optimization
+
+- **Build output** — compiled files import `react/compiler-runtime` and contain `Symbol.for("react.memo_cache_sentinel")`; if absent, the compiler never ran.
+- **ESLint / Oxlint** — compiler's recommended rules flag Rules-of-React violations at lint time.
+
+## Review Checklist
+
+- [ ] Compiler is wired up and confirmed active — set it up if missing (see `react19-tooling-and-opt-out.md`); never treat a missing compiler as licence to hand-roll memoization
+- [ ] Compiler confirmed active (build output imports `react/compiler-runtime`) before removing any _existing_ manual memoization
+- [ ] No new `useMemo`/`useCallback`/`React.memo` added without documented reason (confirmed bail-out, or external boundary)
+- [ ] No prop/state/context mutation anywhere in render
+- [ ] All hooks called unconditionally at top level, same order every render
+- [ ] Side effects live in `useEffect`/event handlers, never during render
+- [ ] Components are `PascalCase`; hooks are `camelCase` and prefixed `use`
+- [ ] `ref` accepted as normal prop instead of `forwardRef`
+- [ ] Action/optimistic-update state modeled as discriminated union, not optional fields
+- [ ] Mutually exclusive prop combinations modeled as discriminated union `Props` type
+- [ ] Any `"use no memo"` usage has a comment explaining why
+
+## Quick Reference
+
+| Situation                                                   | Do                                                            |
+| ----------------------------------------------------------- | ------------------------------------------------------------- |
+| Tempted to write `useMemo`/`useCallback`                    | Don't — write plain expression, let compiler decide           |
+| Need a ref on a function component                          | Accept `ref` as a prop, skip `forwardRef`                     |
+| Form/async state with distinct outcomes                     | Discriminated union via `useActionState`, not optional fields |
+| Callback needs latest props/state without re-running effect | `useEffectEvent`                                              |
+| A hook/library is known-incompatible with compiler          | `"use no memo"` at top of that function, with comment         |
+| Checking if optimization is happening                       | Build output imports `react/compiler-runtime` (has `react.memo_cache_sentinel`) + compiler lint rules |

package/dist/rules/wangs-ui/react19-compiler-render-patterns.md

@@ -0,0 +1,12 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing render logic in a React 19 component."
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Compiler-Friendly Render Patterns
+
+- Creating new object/array/function literals inline in render (`style={{ color }}`, `onClick={() => ...}`) is fine — stop manually hoisting or `useMemo`-wrapping these preemptively; the compiler memoizes them if it determines it's worthwhile.
+- Avoid module-level mutable variables read or written during render — that state is invisible to the compiler and breaks idempotence.
+- Don't use `useRef` to store a value that should trigger a re-render when it changes — refs are an imperative escape hatch, not state, and the compiler treats them as such.
+- Keep components small and composable. The compiler optimizes per component/hook boundary, so a single 300-line component gives it far less to work with than several focused ones.

package/dist/rules/wangs-ui/react19-naming-conventions.md

@@ -0,0 +1,15 @@
+---
+trigger: model_decision
+description: "Apply when naming a React 19 component, hook, or prop."
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Naming Conventions
+
+The compiler identifies what to optimize by naming heuristics, same as the Rules of Hooks linter:
+
+| Kind                                                                     | Convention                      | Notes                                                                         |
+| ------------------------------------------------------------------------ | ------------------------------- | ----------------------------------------------------------------------------- |
+| Components                                                               | `PascalCase`, returns JSX       | Compiler treats it as a component to optimize                                 |
+| Custom hooks                                                             | `camelCase`, prefixed `use`     | Required for both Rules-of-Hooks lint and compiler analysis                   |
+| Plain helper functions that return JSX-like values but aren't components | Avoid `PascalCase`/`use` naming | Prevents the compiler (and other devs) from mistaking it for a component/hook |

package/dist/rules/wangs-ui/react19-no-manual-memoization.md

@@ -0,0 +1,27 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing a React 19 component or hook that uses or is tempted to use useMemo/useCallback/React.memo."
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Stop Hand-Rolling Memoization
+
+> **Prerequisite:** this rule holds only once the React Compiler is enabled. If the project isn't wired up yet, set it up first (see `react19-tooling-and-opt-out.md`) — the absence of the compiler is never a reason to hand-roll memoization.
+
+Don't reach for `useMemo`, `useCallback`, or `React.memo` — the compiler adds this automatically wherever it determines it helps. This is a requirement, not a stylistic preference: manual memoization is the exception and must be justified.
+
+```tsx
+// ❌ Old habit — noisy, and a mismatched dependency array is a whole class of bugs
+const filteredUsers = useMemo(() => users.filter((u) => u.isActive), [users]);
+const handleClick = useCallback(() => onSelect(user.id), [onSelect, user.id]);
+
+// ✅ New default — just write the logic; the compiler memoizes what's worth memoizing
+const filteredUsers = users.filter((u) => u.isActive);
+const handleClick = () => onSelect(user.id);
+```
+
+## When manual memoization is still justified:
+
+- You've **confirmed a compiler bail-out** on a genuine hot path via profiling, and fixing the underlying Rules-of-React violation isn't possible right now.
+- A value must have **stable referential identity across a boundary the compiler can't see** — e.g. passed into a non-React library, a WebSocket subscription, or a third-party hook incompatible with the compiler (`react-hook-form`'s `useForm`, `@tanstack/react-table`'s `useReactTable` are known cases).
+- Keep any manual memoization it produces isolated and commented with _why_, so it doesn't silently rot into a bail-out later when the code around it changes.

package/dist/rules/wangs-ui/react19-primitives-typing.md

@@ -0,0 +1,84 @@
+---
+trigger: model_decision
+description: "Apply when typing React 19 primitives — ref props, useActionState, useOptimistic, use(), useEffectEvent."
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Typing React 19 Primitives
+
+## `ref` as a Normal Prop
+
+`forwardRef` is no longer required for most cases; function components accept `ref` directly.
+
+```tsx
+type InputProps = {
+  ref?: React.Ref<HTMLInputElement>;
+  placeholder?: string;
+};
+
+function TextInput({ ref, placeholder }: InputProps) {
+  return <input ref={ref} placeholder={placeholder} />;
+}
+```
+
+## Actions with `useActionState`
+
+Type the state and payload as generics; model the result as a discriminated union rather than optional fields.
+
+```tsx
+type FormState = { status: 'idle' } | { status: 'error'; message: string } | { status: 'success' };
+
+const [state, formAction, isPending] = useActionState<FormState, FormData>(
+  async (_previous, formData) => {
+    const email = formData.get('email');
+    if (typeof email !== 'string' || !email.includes('@')) {
+      return { status: 'error', message: 'Invalid email' };
+    }
+    await submit(email);
+    return { status: 'success' };
+  },
+  { status: 'idle' },
+);
+```
+
+## Optimistic Updates with `useOptimistic`
+
+Type both the state and the update shape.
+
+```tsx
+const [optimisticTodos, addOptimisticTodo] = useOptimistic<Todo[], Todo>(
+  todos,
+  (state, newTodo) => [...state, newTodo],
+);
+```
+
+## Reading Promises or Context with `use()`
+
+Type the resolved value, not the promise wrapper; `use()` is not a hook and may be called conditionally.
+
+```tsx
+function Comments({ commentsPromise }: { commentsPromise: Promise<Comment[]> }) {
+  const comments = use(commentsPromise); // suspends until resolved
+  return (
+    <ul>
+      {comments.map((c) => (
+        <li key={c.id}>{c.text}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Stable Event Callbacks with `useEffectEvent` (React 19.2+)
+
+Separates "event" logic from "reactive" effect logic so the callback always sees latest props/state without being listed as an effect dependency.
+
+```tsx
+const onVisit = useEffectEvent((url: string) => {
+  logVisit(url, theme); // always fresh `theme`, never re-triggers the effect
+});
+
+useEffect(() => {
+  onVisit(url);
+}, [url]); // `theme` intentionally omitted — onVisit is stable
+```

package/dist/rules/wangs-ui/react19-props-typing.md

@@ -0,0 +1,24 @@
+---
+trigger: model_decision
+description: "Apply when defining a component's Props type or interface."
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Typing Props
+
+- `interface` for a component's `Props` — it's an entity shape, often extended.
+- A discriminated union when a component has mutually exclusive prop combinations, instead of a pile of optional props that can contradict each other.
+
+```tsx
+// ❌ Bad — nothing stops passing both `href` and `onClick` incoherently
+interface ButtonProps {
+  label: string;
+  href?: string;
+  onClick?: () => void;
+}
+
+// ✅ Good — the two variants can't be mixed
+type ButtonProps =
+  | { variant: 'link'; label: string; href: string }
+  | { variant: 'action'; label: string; onClick: () => void };
+```

package/dist/rules/wangs-ui/react19-purity-and-immutability.md

@@ -0,0 +1,40 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing a React 19 component or hook body for purity and immutability."
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Purity and Immutability (Load-Bearing)
+
+The compiler assumes your components and hooks are pure. Violating these rules causes the compiler to silently skip optimizing that component:
+
+- **Idempotent renders** — given the same props/state/context, a component must return the same output. No random values, no `Date.now()`, no side effects during render.
+- **Immutability** — never mutate props, state, or context directly. Always create new objects/arrays for changes.
+- **Side effects only in effects or event handlers** — never during render.
+- **Hooks called unconditionally, top-level, same order every render** — no hooks inside conditionals, loops, or nested functions.
+
+```tsx
+// ❌ Mutates a prop — breaks purity and the compiler can't safely memoize this
+function TodoList({ todos }: { todos: Todo[] }) {
+  todos.sort((a, b) => a.priority - b.priority); // mutates caller's array
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.title}</li>
+      ))}
+    </ul>
+  );
+}
+
+// ✅ Creates a new array — pure, compiler-safe
+function TodoList({ todos }: { todos: Todo[] }) {
+  const sorted = [...todos].sort((a, b) => a.priority - b.priority);
+  return (
+    <ul>
+      {sorted.map((t) => (
+        <li key={t.id}>{t.title}</li>
+      ))}
+    </ul>
+  );
+}
+```

package/dist/rules/wangs-ui/react19-tooling-and-opt-out.md

@@ -0,0 +1,77 @@
+---
+trigger: model_decision
+description: 'Apply when configuring React Compiler tooling or opting a component out via "use no memo".'
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Tooling Setup & Compiler Opt-Out
+
+## Compiler Setup Is Mandatory
+
+**The compiler is required, not opt-in.** Every Wangs UI project must run it. The entire "write plain code, no manual memoization" rule set only holds once the compiler is actually active, so wiring it up is a prerequisite — not an optional enhancement.
+
+Plain `@vitejs/plugin-react` (`react()`), plain Next.js, plain Babel/webpack config, etc. do **not** run the compiler on their own. **Verify it is active before assuming manual memoization can be dropped — and if it isn't wired up, set it up first** instead of falling back to hand-rolled `useMemo`/`useCallback`/`React.memo`.
+
+### Verify it's active
+
+- The build passes the compiler preset through Babel, and `babel-plugin-react-compiler` is installed (e.g. `@vitejs/plugin-react`'s `reactCompilerPreset()` via `@rolldown/plugin-babel`).
+- The build output actually contains compiler artifacts — `import { c as _c } from "react/compiler-runtime"` and `Symbol.for("react.memo_cache_sentinel")` in `dist`. Config being present is **not** proof it ran; the emitted output is.
+- The `react/react-compiler` lint rule is enabled.
+
+### Setup (when missing)
+
+```bash
+# Compiler (build-time transform)
+pnpm add -D --save-exact babel-plugin-react-compiler@latest
+```
+
+### Lint rules — oxlint
+
+Oxlint ships a **native, Rust-based** `react/react-compiler` rule:
+
+```json
+// .oxlintrc.json
+{
+  "plugins": ["react"],
+  "rules": {
+    "react/react-compiler": "error"
+  }
+}
+```
+
+This single rule reports:
+
+- **Rules-of-React violations** (conditional hooks, reading a ref during render, mutating props) — must-fix bugs.
+- **Compiler bail-outs** — places compiler declined to optimize without rule violation.
+
+### Wiring into Vite 8
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react, { reactCompilerPreset } from '@vitejs/plugin-react';
+import babel from '@rolldown/plugin-babel';
+
+export default defineConfig({
+  plugins: [
+    babel({ presets: [reactCompilerPreset()] }), // must run before react()
+    react(),
+  ],
+});
+```
+
+```bash
+pnpm add -D @rolldown/plugin-babel @babel/core babel-plugin-react-compiler
+```
+
+## Incompatibility Escape Hatch (`"use no memo"`)
+
+If a specific function is genuinely incompatible with compiler (e.g. calls `useForm` from `react-hook-form`), opt out with `"use no memo"` directive as **first line of function body** — leave a comment explaining why:
+
+```tsx
+function LegacyForm() {
+  'use no memo';
+  const form = useForm(); // incompatible with the compiler today
+  // ...
+}
+```

package/dist/rules/wangs-ui/theme-variable-override-breaks-engine.md

@@ -0,0 +1,19 @@
+---
+trigger: model_decision
+description: "Apply when tempted to override a Wangs UI theme CSS variable directly."
+metadata:
+  owner: wangs-ui
+---
+# Wangs UI Fact: Theme Variables Are Engine-Internal, Never Override Directly
+
+Manually defining or overriding `:root`, `[data-mode='dark']`, or `.dark` custom
+properties owned by `@wangs-ui/foundation/theme` (`--color-*`, `--z-index-*`,
+`--spacing-*`, `--size-*`, `--shadow-*`, `--radius-*`) breaks the theme token
+engine: it destroys automatic light/dark mode transitions, corrupts sub-tree
+density overrides made via `<ThemeProvider>`, and causes cross-module visual
+bugs that don't reproduce consistently. This is true for any project consuming
+`@wangs-ui/foundation`, not specific to one app's setup.
+
+The supported customization surface is `WangsUiProvider.configOptions.preset`
+— discover it via the `design-system`/`wangs-ui-components` skills' MCP calls,
+never by reading or guessing the CSS variable names.

package/dist/rules/wangs-ui/typescript-assertions-last-resort.md

@@ -0,0 +1,12 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing a type assertion (`as X`) or non-null assertion (`x!`)."
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Type Assertions & Non-Null Assertions are a Last Resort
+
+- `as X` and `x!` tell the compiler "trust me" — they produce zero runtime safety and actively hide bugs if wrong.
+- Acceptable only when the compiler genuinely cannot know something you do (e.g. a DOM query you've already null-checked, or narrowing a third-party type at a well-tested boundary) — and even then, prefer a type guard or a runtime check over a bare assertion.
+- Never use `as any` or `as unknown as X` to force an incompatible cast — that's `any` wearing a disguise.
+- `x!` should almost always be replaceable by an actual null check or optional chaining (`x?.y`) plus a real fallback.