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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wangs-ui/skills",
-  "version": "1.3.0-alpha.2",
+  "version": "1.3.0-alpha.20",
   "description": "CLI to install, update, and manage modular AI agent skills for Wangs UI React applications",
   "keywords": [
     "agents",
@@ -29,7 +29,8 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "rules"
   ],
   "type": "module",
   "sideEffects": false,

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

@@ -0,0 +1,14 @@
+---
+trigger: model_decision
+description: "Apply when deciding whether a prop belongs in global defaultProps config or per-instance JSX."
+owner: wangs-ui
+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/rules/wangs-ui/forms-destructuring-lock.md

@@ -0,0 +1,19 @@
+---
+trigger: model_decision
+description: "Apply when writing a <Field> render-prop callback in a Wangs UI Form/DialogForm."
+owner: wangs-ui
+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/rules/wangs-ui/no-raw-html.md

@@ -0,0 +1,29 @@
+---
+trigger: model_decision
+description: "Apply when writing JSX markup — enforce Wangs UI primitives over raw HTML elements."
+owner: wangs-ui
+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/rules/wangs-ui/no-redundant-wrappers.md

@@ -0,0 +1,56 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing JSX layout for redundant wrapper containers."
+owner: wangs-ui
+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/rules/wangs-ui/react19-checklist-and-reference.md

@@ -0,0 +1,38 @@
+---
+trigger: model_decision
+description: "Apply when doing a final review pass on React 19 component or hook code for compiler-optimization compliance."
+owner: wangs-ui
+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/rules/wangs-ui/react19-compiler-render-patterns.md

@@ -0,0 +1,13 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing render logic in a React 19 component."
+owner: wangs-ui
+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/rules/wangs-ui/react19-naming-conventions.md

@@ -0,0 +1,16 @@
+---
+trigger: model_decision
+description: "Apply when naming a React 19 component, hook, or prop."
+owner: wangs-ui
+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/rules/wangs-ui/react19-no-manual-memoization.md

@@ -0,0 +1,28 @@
+---
+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."
+owner: wangs-ui
+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/rules/wangs-ui/react19-primitives-typing.md

@@ -0,0 +1,85 @@
+---
+trigger: model_decision
+description: "Apply when typing React 19 primitives — ref props, useActionState, useOptimistic, use(), useEffectEvent."
+owner: wangs-ui
+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/rules/wangs-ui/react19-props-typing.md

@@ -0,0 +1,25 @@
+---
+trigger: model_decision
+description: "Apply when defining a component's Props type or interface."
+owner: wangs-ui
+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/rules/wangs-ui/react19-purity-and-immutability.md

@@ -0,0 +1,41 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing a React 19 component or hook body for purity and immutability."
+owner: wangs-ui
+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/rules/wangs-ui/react19-tooling-and-opt-out.md

@@ -0,0 +1,78 @@
+---
+trigger: model_decision
+description: 'Apply when configuring React Compiler tooling or opting a component out via "use no memo".'
+owner: wangs-ui
+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/rules/wangs-ui/theme-variable-override-breaks-engine.md

@@ -0,0 +1,20 @@
+---
+trigger: model_decision
+description: "Apply when tempted to override a Wangs UI theme CSS variable directly."
+owner: wangs-ui
+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/rules/wangs-ui/typescript-assertions-last-resort.md

@@ -0,0 +1,13 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing a type assertion (`as X`) or non-null assertion (`x!`)."
+owner: wangs-ui
+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.

package/rules/wangs-ui/typescript-checklist-and-reference.md

@@ -0,0 +1,34 @@
+---
+trigger: model_decision
+description: "Apply when doing a final TypeScript review pass on a file."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Review Checklist & Quick Reference
+
+## Review Checklist
+
+Before considering TypeScript code "done," verify:
+
+- [ ] No `any` anywhere (including implicit `any` from missing annotations)
+- [ ] External/uncertain data enters as `unknown` and is narrowed before use
+- [ ] Variant state is a discriminated union, not optional fields + booleans
+- [ ] `interface` used for object/entity shapes; `type` used for unions/aliases/intersections
+- [ ] No stray `I` prefixes on interfaces
+- [ ] Naming follows casing conventions consistently
+- [ ] `as` / `!` are rare, justified, and can't be replaced by a guard or null check
+- [ ] Exported functions/methods have explicit return types
+- [ ] Switch statements over unions have an exhaustiveness (`never`) check
+- [ ] `tsconfig.json` includes the strictness baseline
+
+## Quick Reference
+
+| Situation                                      | Use                                                           |
+| ---------------------------------------------- | ------------------------------------------------------------- |
+| External/uncertain data                        | `unknown` + narrowing                                         |
+| "This value is definitely one of these shapes" | Discriminated union (`type`)                                  |
+| Object with identity, may be extended          | `interface`                                                   |
+| Union, intersection, tuple, mapped type        | `type`                                                        |
+| Need to prove a type through logic             | Type guard / narrowing                                        |
+| Tempted to write `any`                         | Stop — use `unknown`, a generic, or a local interface instead |

package/rules/wangs-ui/typescript-discriminated-unions.md

@@ -0,0 +1,40 @@
+---
+trigger: model_decision
+description: "Apply when modeling a variant or multi-shape state in TypeScript."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Discriminated Unions for Variant State
+
+Whenever a value can be one of several distinct "shapes" (loading/success/error states, event types, API response variants), model it as a **discriminated union** with a literal tag field — never as a loose object with optional fields or boolean flags.
+
+```ts
+// ❌ Bad — booleans can contradict each other; unclear which fields are valid together
+interface FetchState {
+  isLoading: boolean;
+  isError: boolean;
+  data?: User;
+  error?: string;
+}
+
+// ✅ Good — only one shape is possible at a time, and the compiler enforces it
+type FetchState =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: User }
+  | { status: 'error'; error: string };
+
+function render(state: FetchState) {
+  switch (state.status) {
+    case 'success':
+      return state.data.name; // `data` is guaranteed to exist here
+    case 'error':
+      return state.error; // `error` is guaranteed to exist here
+    default:
+      return null;
+  }
+}
+```
+
+Use a consistent tag field name across a codebase (`kind`, `type`, or `status` — pick one and stick with it) so narrowing patterns stay predictable.

package/rules/wangs-ui/typescript-explicit-return-types.md

@@ -0,0 +1,22 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing an exported function, class method, or public API surface in TypeScript."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Explicit Return Types on Exported Functions
+
+Inference is fine for local, private helpers, but exported functions, class methods, and anything forming a public API should declare an explicit return type. This prevents an internal implementation change from silently widening/narrowing the public contract.
+
+```ts
+// ❌ Return type is inferred and can silently drift
+export function getActiveUsers(users: User[]) {
+  return users.filter((u) => u.active);
+}
+
+// ✅ Explicit, intentional contract
+export function getActiveUsers(users: User[]): User[] {
+  return users.filter((u) => u.active);
+}
+```

package/rules/wangs-ui/typescript-interface-vs-type.md

@@ -0,0 +1,40 @@
+---
+trigger: model_decision
+description: "Apply when deciding between `interface` and `type` for a new TypeScript declaration."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — `interface` vs `type`
+
+Both can describe object shapes, but they signal different intent. Default rule:
+
+| Use `interface` for...                                                     | Use `type` for...                                                          |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Object / entity shapes (a `User`, a `Product`, a component's `Props`)      | Unions (`"a" \| "b"`) and discriminated unions                             |
+| Public API contracts meant to be `implements`-ed by classes                | Intersections (`A & B`)                                                    |
+| Shapes that consumers may want to **extend/augment** (declaration merging) | Tuples (`[string, number]`)                                                |
+|                                                                            | Function types / callback signatures                                       |
+|                                                                            | Mapped, conditional, or utility-derived types (`Partial<T>`, `Pick<T, K>`) |
+|                                                                            | Aliasing a primitive or another type for readability                       |
+
+```ts
+// ✅ interface — an entity with identity, extendable
+interface User {
+  id: string;
+  email: string;
+  role: UserRole;
+}
+
+interface AdminUser extends User {
+  permissions: Permission[];
+}
+
+// ✅ type — union, alias, derived shape
+type UserRole = 'admin' | 'editor' | 'viewer';
+type UserId = User['id'];
+type PartialUser = Partial<User>;
+type Callback<T> = (value: T) => void;
+```
+
+Don't mix conventions arbitrarily within one file — if a shape is a plain data object that will never need a union/intersection, `interface` is the default; the moment it needs to express "one of several shapes," reach for `type`.