@wangs-ui/skills 1.3.0-alpha.10 → 1.3.0-alpha.12

package/dist/rules/typescript-naming-conventions.md

@@ -0,0 +1,24 @@
+---
+trigger: model_decision
+description: "Apply when naming a TypeScript type, variable, or constant."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Naming Conventions
+
+| Kind                                                       | Convention                                  | Example                             |
+| ---------------------------------------------------------- | ------------------------------------------- | ----------------------------------- |
+| Types, interfaces, classes, enums                          | `PascalCase`                                | `UserProfile`, `OrderStatus`        |
+| Interfaces                                                 | `PascalCase`, **no `I` prefix**             | `User`, not `IUser`                 |
+| Type aliases                                               | `PascalCase`                                | `type ApiResponse<T> = ...`         |
+| Variables, functions, methods, properties                  | `camelCase`                                 | `getUserById`, `isValid`            |
+| Booleans                                                   | `camelCase` with `is/has/should/can` prefix | `isLoading`, `hasPermission`        |
+| True constants (module-level, never reassigned, primitive) | `UPPER_SNAKE_CASE`                          | `MAX_RETRIES`, `DEFAULT_TIMEOUT_MS` |
+| Enum members                                               | `PascalCase`                                | `enum Status { Active, Archived }`  |
+| Generic type parameters (simple, single-purpose)           | Single uppercase letter                     | `T`, `K`, `V`, `E` for errors       |
+| Generic type parameters (multiple / non-obvious)           | Descriptive, prefixed with `T`              | `TInput`, `TOutput`, `TContext`     |
+| Discriminated union tag field                              | Consistent across the codebase              | `kind`, `type`, or `status`         |
+| Files with a single exported entity                        | Match the entity name                       | `UserProfile.ts`, `useAuth.ts`      |
+
+Naming should describe **intent**, not implementation — `fetchUser` not `getUserFromApiEndpoint`; `retryCount` not `numRetries2`.

package/dist/rules/typescript-narrowing-over-casting.md

@@ -0,0 +1,44 @@
+---
+trigger: model_decision
+description: "Apply when narrowing an `unknown` or union-typed value in TypeScript."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — `unknown` + Narrowing, Not Casting
+
+Prefer proving a type through control flow over asserting it with `as`.
+
+## Narrowing techniques, in order of preference:
+
+1. **`typeof`** — primitives (`string`, `number`, `boolean`, `undefined`, `function`)
+2. **`instanceof`** — class instances, `Error`, `Date`, custom classes
+3. **`in`** — checking a property exists before accessing it on a union/unknown
+4. **User-defined type guards** — `function isUser(x: unknown): x is User`
+5. **Discriminated union tag checks** — `switch (value.kind) { ... }`
+6. **Exhaustiveness checks** — a `never`-typed default branch so adding a new variant is a compile error until every switch/if-chain handles it
+
+```ts
+// ✅ Type guard
+function isUser(value: unknown): value is User {
+  return typeof value === 'object' && value !== null && 'id' in value && 'email' in value;
+}
+
+// ✅ Exhaustiveness check
+function assertNever(x: never): never {
+  throw new Error(`Unhandled case: ${JSON.stringify(x)}`);
+}
+
+function area(shape: Shape): number {
+  switch (shape.kind) {
+    case 'circle':
+      return Math.PI * shape.radius ** 2;
+    case 'square':
+      return shape.side ** 2;
+    default:
+      return assertNever(shape); // compile error if a variant is missed
+  }
+}
+```
+
+Type assertions (`as X`) and the non-null assertion (`!`) bypass this entirely — treat them as a last resort, not a shortcut.

package/dist/rules/typescript-readonly-by-default.md

@@ -0,0 +1,24 @@
+---
+trigger: model_decision
+description: "Apply when declaring a TypeScript collection or object shape."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Readonly by Default
+
+Prefer immutable shapes unless mutation is intentional and localized.
+
+```ts
+interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+function config(values: readonly string[]) {
+  /* ... */
+}
+
+const ROLES = ['admin', 'editor', 'viewer'] as const;
+type UserRole = (typeof ROLES)[number];
+```

package/dist/rules/typescript-tsconfig-strictness.md

@@ -0,0 +1,31 @@
+---
+trigger: model_decision
+description: "Apply when configuring or reviewing tsconfig.json compiler strictness options."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Baseline `tsconfig.json` Strictness
+
+Treat these as the non-negotiable floor for any project this rule touches:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictPropertyInitialization": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}
+```
+
+`strict: true` alone enables the core group (`noImplicitAny`, `strictNullChecks`, etc.), but `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` are commonly missed and close real gaps (array/object index access returning `T` instead of `T | undefined`; optional properties silently accepting `undefined` as an explicit value).

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/skills/responsive-design/SKILL.md

@@ -0,0 +1,94 @@
+---
+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.
+
+---
+
+## 1. Breakpoint Reference
+
+Wangs UI uses three standardized breakpoints:
+
+| Breakpoint     | Viewport Range | Typical Target             |
+| :------------- | :------------- | :------------------------- |
+| **`compact`**  | `< 600px`      | Mobile phones              |
+| **`medium`**   | `600–839px`    | Tablet portrait            |
+| **`expanded`** | `≥ 840px`      | Tablet landscape & Desktop |
+
+### Reading the Current Breakpoint in Code
+
+```tsx
+import { useTheme } from '@wangs-ui/foundation/theme';
+
+const { breakpoint } = useTheme(); // 'compact' | 'medium' | 'expanded'
+```
+
+---
+
+## 2. Responsive Props (`ResponsiveValue`)
+
+Visual scale props (`size`, layout `gap`, `columns`, `p`, `m`) accept either a single value or an object mapped by breakpoint:
+
+```tsx
+// Static (identical across all devices)
+<Button size="md" />
+<Stack gap={4} />
+
+// Adaptive (changes across breakpoints)
+<Button size={{ compact: 'lg', expanded: 'sm' }} />
+<Grid columns={{ compact: 1, medium: 2, expanded: 4 }} />
+```
+
+> **Rule**: Do **NOT** attempt to use responsive objects on event handlers or boolean flags (e.g. `disabled`, `onClick`). Only visual scale props support responsive objects.
+
+---
+
+## 3. Conditional Rendering (`<Show>`)
+
+Use `<Show>` when a component should be mounted or unmounted based on the active breakpoint:
+
+```tsx
+import { Show } from '@wangs-ui/foundation/theme';
+
+// Render only on tablet & desktop
+<Show above="medium">
+  <SidebarNav />
+</Show>
+
+// Render only on mobile
+<Show below="medium">
+  <MobileNavbar />
+</Show>
+
+// Swap component with a fallback
+<Show at="compact" fallback={<DesktopTable />}>
+  <MobileCardList />
+</Show>
+```
+
+### When to use `<Show>` vs CSS `hidden`:
+
+- **Use `<Show>`**: If the hidden component has expensive network fetches, subscriptions, or animations (unmounts completely).
+- **Use CSS Tailwind (`hidden md:block`)**: If it's just a visual styling toggle with no side effects.
+
+---
+
+## 4. Spacing Conventions
+
+Spacing tokens are **flat and fixed** (1 unit = 4px):
+
+- **Web**: Use standard Tailwind numeric classes (`gap-2`, `px-4`, `py-3`). **Never** use legacy named classes like `gap-md` or `px-sm`.
+- **Native**: Use `const { spacing } = useTheme();` (`spacing[4]` = 16px).
+
+---
+
+## 5. Anti-Patterns to Avoid
+
+1. **Avoid `hidden md:block` for stateful/heavy trees**: Always prefer `<Show>` so unused components cleanly unmount.
+2. **Never pass responsive objects to behavioral props**: `<Button disabled={{ compact: true }} />` is invalid.
+3. **No manual pixel calculations**: Use Tailwind numeric tokens (`gap-4`, `p-6`) or `ResponsiveValue`.

package/dist/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/dist/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`).