@wangs-ui/skills 1.3.0-alpha.11 → 1.3.0-alpha.13

package/rules/typescript-zero-any.md

@@ -0,0 +1,37 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing any TypeScript type annotation."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Never Use `any`
+
+`any` is not "unknown type," it's "type checking off." It's contagious — once a value is `any`, everything it touches becomes unchecked too.
+
+- Never write `any` for parameters, return types, variables, or generics.
+- Use `unknown` for genuinely unknown external data (API responses, `JSON.parse`, catch clauses, third-party callbacks) and narrow it before use.
+- Use generics (`<T>`) when a function needs to work across types but preserve the relationship between input and output.
+- If a library ships untyped, write a minimal local type/interface for the surface area you actually use instead of reaching for `any`.
+
+```ts
+// ❌ Bad
+function parseConfig(json: any) {
+  return json.settings.theme; // no safety, no autocomplete, silent runtime crash
+}
+
+// ✅ Good
+function parseConfig(json: unknown): string {
+  if (
+    typeof json === 'object' &&
+    json !== null &&
+    'settings' in json &&
+    typeof (json as { settings: unknown }).settings === 'object'
+  ) {
+    // still narrow further or validate with a schema library (zod, valibot, etc.)
+  }
+  throw new Error('Invalid config shape');
+}
+```
+
+The only acceptable `any` is a well-justified, isolated, and commented one (e.g. interfacing with a genuinely untyped legacy module) — never a default.

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/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/skills/craft-theme/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: craft-theme
 description: Generate a brand-color theme (13-shade tonal palette + M3-style semantic tokens) for a Wangs UI app via the `wangs-ui-generate-palette` CLI — never hand-write hex shade ramps.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: Craft Theme
 
 Use this skill whenever the user asks to create, customize, or rebrand the color theme of an app built on `@wangs-ui/react-core` / `@wangs-ui/foundation` — "make the app's theme orange", "use our brand color #ff6b35", "add a new palette called sunset", etc.

package/skills/create-form/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: create-form
 description: Form architecture, validation workflows, strongly-typed forms (useForm, useDialogForm, useWatchField), initialValues/reset lifecycle, and MCP discovery protocol for building forms and input controls with @wangs-ui/react-core.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: Form Architecture & Validation Workflows
 
 Use this skill when building forms, data entry panels, modal forms, settings pages, or multipart forms in Wangs UI applications.

package/skills/data-table/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: data-table
 description: Architecture, workflows, and MCP discovery protocol for building DataTables with sorting, pagination, filtering, selection, and export.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: DataTable Architecture & Integration Workflows
 
 Use this skill when implementing data grids, server-paginated tables, filterable listing views, or batch management interfaces with `@wangs-ui/react-core`.

package/skills/dialog-modal/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: dialog-modal
 description: Patterns, overlay selection criteria, and MCP discovery protocol for Dialog, Modal, and DialogForm components in Wangs UI.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: Dialog, Modal & Overlay Workflows
 
 Use this skill when building interactive modals, create/edit dialog forms, destructive action confirmations, or slide-in overlay panels.

package/skills/i18n-usage/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: i18n-usage
 description: Comprehensive guidelines for application internationalization, JIT translations (t), ICU formatting, and locale-aware formatting with @wangs-ui/react-i18n.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: Application Internationalization & Formatting Protocol
 
 Use this skill when implementing multi-language interfaces, translating user-facing text, formatting dates, times, currencies, or numbers in React applications built with Wangs UI and `@wangs-ui/react-i18n`.

package/skills/layout-navigation/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: layout-navigation
 description: Architecture, navigation hierarchies, and MCP discovery protocol for AppLayout, Sidebar, Breadcrumb, and Tabs in Wangs UI.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: Application Layout & Navigation Hierarchy
 
 Use this skill when constructing application shells, multi-level sidebars, page headers, breadcrumbs, or tabbed views with `@wangs-ui/react-core`.

package/skills/responsive-design/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: responsive-design
 description: Guidelines for implementing responsive UIs with Wangs UI — covering Breakpoint tiers, responsive props (ResponsiveValue), <Show> conditional rendering, and spacing conventions.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: Responsive Design (Consumer Guide)
 
 Use this skill when building responsive pages, layouts, or screen adaptations with Wangs UI components.

package/skills/universal-layout/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: universal-layout
 description: Universal layout primitives (Box, Flex, Stack, Grid, Container, Section) with ResponsiveValue patterns for Web and React Native in Wangs UI.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: Universal Layout Primitives
 
 Use this skill when arranging page structure, spacing, or responsive grids with

package/skills/wangs-ui-components/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: wangs-ui-components
 description: Foundational rules, subpath imports, design tokens, and the MCP Discovery Protocol for building React apps with Wangs UI.
+metadata:
+  owner: wangs-ui
 ---
-
 # Skill: Wangs UI Component Fundamentals & MCP Protocol
 
 Use this skill whenever you write or modify UI components using Wangs UI (`@wangs-ui/react-core`, `@wangs-ui/react-icons`, `@wangs-ui/react-presets`, `@wangs-ui/foundation`).