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

package/rules/wangs-ui/typescript-naming-conventions.md

@@ -0,0 +1,23 @@
+---
+trigger: model_decision
+description: "Apply when naming a TypeScript type, variable, or constant."
+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/rules/wangs-ui/typescript-narrowing-over-casting.md

@@ -0,0 +1,43 @@
+---
+trigger: model_decision
+description: "Apply when narrowing an `unknown` or union-typed value in TypeScript."
+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/rules/wangs-ui/typescript-readonly-by-default.md

@@ -0,0 +1,23 @@
+---
+trigger: model_decision
+description: "Apply when declaring a TypeScript collection or object shape."
+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/rules/wangs-ui/typescript-tsconfig-strictness.md

@@ -0,0 +1,30 @@
+---
+trigger: model_decision
+description: "Apply when configuring or reviewing tsconfig.json compiler strictness options."
+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/rules/wangs-ui/typescript-zero-any.md

@@ -0,0 +1,36 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing any TypeScript type annotation."
+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/skills/wangs-ui/craft-theme/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: craft-theme
+description: Generate a brand-color theme (13-shade tonal palette + 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.
+
+## The rule this skill exists to enforce
+
+**Never hand-write a 13-shade tonal ramp, and never hand-pick which shade pairs with which as a text/foreground color.** Wangs UI's own design system shipped with exactly that mistake for a while: hand-tuned palette files drifted from what the perceptual (OKLCH) generator would produce, which caused white text to render at 2.54:1 contrast on one brand's primary color — invisible-adjacent, and only caught by a dedicated audit. The generator and the contrast math it's paired with exist specifically so this class of bug can't happen again. Always reach for the CLI below instead of writing hex values yourself.
+
+## 1. Generate the palette
+
+```bash
+pnpm exec wangs-ui-generate-palette --name=<id> --primary=<#hex> [options] --out=<path>
+```
+
+- `--name` (required): identifier for the palette, e.g. `sunset`. Used for the exported const name (`sunsetPalette`) and, unless `--out` is given, the output filename (`sunset.ts`).
+- `--primary` (required): the brand/key hex color, e.g. `#ff6b35`.
+- Optional per-family overrides — omit any of these to let the generator harmoniously auto-derive it from `--primary` (secondary: boosted-lightness variant of primary's hue; tertiary: +60° hue rotation; general: near-neutral variant of primary's hue) or fall back to the generator's calibrated defaults (success/danger/warning/info):
+  `--secondary=#hex --tertiary=#hex --general=#hex --success=#hex --danger=#hex --warning=#hex --info=#hex`
+- `--out=<path>` (optional): where to write the file. Defaults to `./<name>.ts` in the current working directory — always pass an explicit `--out` pointing into the consumer app's own theme directory (e.g. `src/theme/sunset.ts`), don't rely on the default.
+
+If `@wangs-ui/foundation` isn't already a dependency of the project you're working in, install it first (`pnpm add @wangs-ui/foundation` or the project's equivalent) — the CLI ships as its `bin`.
+
+**The written file is chmod'd read-only (0o444) and headed with an AUTO-GENERATED / DO NOT EDIT BY HAND comment.** If a color needs to change, re-run the command (it clears the read-only bit, rewrites, and re-locks it) — never hand-edit a shade in the output, and never `chmod` it writable to bypass this. Note the read-only bit is a local filesystem attribute only; it is not preserved by git across clones, so it is a deterrent for the person/agent working in this checkout right now, not a hard guarantee for every future contributor.
+
+## 2. Wire it into the app
+
+The generated file exports a plain `Palette` object — pass it directly to `WangsUiProvider`'s `theme.palette` (or `theme.defaultPalette` for uncontrolled mode):
+
+```tsx
+import { WangsUiProvider } from '@wangs-ui/react-core/api';
+import preset from '@wangs-ui/react-presets/fixedasset'; // or whichever preset the app uses
+import { sunsetPalette } from './theme/sunset';
+
+const App = () => (
+  <WangsUiProvider configOptions={{ preset }} theme={{ palette: sunsetPalette, mode: 'light' }}>
+    <YourApp />
+  </WangsUiProvider>
+);
+```
+
+`theme.palette` also accepts a built-in palette name (`'blue' | 'emerald' | 'crimson' | 'carbon' | 'gold'`) or a raw hex string — a generated `Palette` object is the right choice once you have brand-specific secondary/tertiary/status colors to preserve, not just a single key color.
+
+## 3. Regenerating / evolving an existing custom palette
+
+To change a color, re-run the same command with a new hex for the family that changed — **always pass every family you want to keep**, not just the one changing, since each run is a full regeneration from the anchors you give it:
+
+```bash
+pnpm exec wangs-ui-generate-palette --name=sunset --primary=#ff6b35 --tertiary=#2a9d8f --out=src/theme/sunset.ts
+```
+
+## 4. If you're extending Wangs UI itself (contributing a new official palette)
+
+This is a different, rarer case than theming a consumer app — only relevant if you're working inside the `wangs-ui-react` monorepo itself and adding a 6th built-in palette alongside blue/emerald/crimson/carbon/gold:
+
+1. Run the generator with `--out` pointing at `packages/foundation/theme/tokens/palettes/<name>.ts`.
+2. Register it: add `'<name>'` to the `PaletteName` union and `paletteLoaders` map in `packages/foundation/theme/context/ThemeContext.tsx`, and re-export it from `packages/foundation/theme/tokens/palettes/index.ts`.
+3. Run the contrast regression suite before considering it done: `pnpm exec vitest run --config packages/foundation/vitest.config.ts` — it checks every semantic token pairing (including the new palette) against WCAG AA across both light and dark mode. See `packages/foundation/theme/tokens/COLOR_TOKEN_CONTRACT.md` for the full rule set this is checked against.

package/skills/{create-form → wangs-ui/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.
@@ -13,28 +14,36 @@ Use this skill when building forms, data entry panels, modal forms, settings pag
 
 Do **NOT** hardcode or guess prop names, component options, preset variations, or Storybook patterns in this document. Always retrieve component definitions, active props, and live Storybook implementations directly via MCP:
 
-### Component & Form Documentation Protocol:
+### Component & Form API Protocol:
+
+```json
+get_component_api({ "component": "form" })
+get_component_api({ "component": "field" })
+get_component_api({ "component": "dialogform" })
+get_component_api({ "component": "input" })
+get_component_api({ "component": "numberinput" })
+get_component_api({ "component": "select" })
+get_component_api({ "component": "multiselect" })
+get_component_api({ "component": "datepicker" })
+get_component_api({ "component": "fileupload" })
+```
+
+### Curated Form Documentation:
 
 ```json
-get-documentation({ "id": "form" })
-get-documentation({ "id": "field" })
-get-documentation({ "id": "dialogform" })
-get-documentation({ "id": "input" })
-get-documentation({ "id": "numberinput" })
-get-documentation({ "id": "select" })
-get-documentation({ "id": "multiselect" })
-get-documentation({ "id": "datepicker" })
-get-documentation({ "id": "fileupload" })
+get_documentation({ "id": "form" })
+get_documentation({ "id": "dialogform" })
+get_documentation({ "id": "field" })
 ```
 
 ### Live Storybook & Interactive Behavior Protocol:
 
 ```json
-get-documentation-for-story({ "id": "form", "storyName": "Default" })
-get-documentation-for-story({ "id": "form", "storyName": "AsyncInitialValues" })
-get-documentation-for-story({ "id": "form", "storyName": "ConditionalFields" })
-get-documentation-for-story({ "id": "form", "storyName": "CascadingOptions" })
-get-documentation-for-story({ "id": "dialogform", "storyName": "Default" })
+get_component_examples({ "component": "form", "variant": "Default" })
+get_component_examples({ "component": "form", "variant": "AsyncInitialValues" })
+get_component_examples({ "component": "form", "variant": "ConditionalFields" })
+get_component_examples({ "component": "form", "variant": "CascadingOptions" })
+get_component_examples({ "component": "dialogform", "variant": "Default" })
 ```
 
 ### Knowledge Graph & Symbol Usages:
@@ -74,6 +83,8 @@ query_graph({ "query": "useWatchField" })
 - **Children Render Callback**: `Field` yields `{ fieldProps, fieldState }`.
 - **`fieldProps`**: Pass directly to primitive inputs (`<Input {...fieldProps} />`). Contains `name`, `value`, `ref`, `onChange`.
 - **`fieldState`**: Provides `invalid`, `error`, `isDirty`, `isPending`. Pass `invalid={fieldState.invalid}` to primitive components for accessibility and validation styling.
+- **⚠️ Mandatory Destructuring (Never `(field) => ...`)**: `<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.
+- **Pass `fieldProps.onChange` directly**: `<Field>` is generic and `fieldProps.onChange` is already typed to the field's value type. Do not wrap it in unnecessary `e?.target?.value` extractions.
 
 ---
 

package/{dist/skills → skills/wangs-ui}/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`.
@@ -13,24 +14,31 @@ Use this skill when implementing data grids, server-paginated tables, filterable
 
 Do **NOT** guess table prop names or hardcode table structures. Query the MCP server dynamically to inspect exact TypeScript signatures, live story implementations, and companion controls:
 
-### Inspect Component Contracts:
+### Inspect Component Contracts (`component` parameter):
+
+```json
+get_component_api({ "component": "datatable" })
+get_component_api({ "component": "exportbutton" })
+get_component_api({ "component": "filtercontainer" })
+get_component_api({ "component": "bulkactionbutton" })
+```
+
+### Read Curated Documentation:
 
 ```json
-get-documentation({ "id": "datatable" })
-get-documentation({ "id": "exportbutton" })
-get-documentation({ "id": "filtercontainer" })
-get-documentation({ "id": "bulkactionbutton" })
+get_documentation({ "id": "datatable" })
+get_documentation({ "id": "exportbutton" })
 ```
 
 ### Inspect Live Story Implementations:
 
 ```json
-get-documentation-for-story({ "id": "datatable", "storyName": "Basic" })
-get-documentation-for-story({ "id": "datatable", "storyName": "ServerPagination" })
-get-documentation-for-story({ "id": "datatable", "storyName": "Sortable" })
-get-documentation-for-story({ "id": "datatable", "storyName": "MultipleSelection" })
-get-documentation-for-story({ "id": "datatable", "storyName": "CustomColumn" })
-get-documentation-for-story({ "id": "exportbutton", "storyName": "WithTable" })
+get_component_examples({ "component": "datatable", "variant": "Basic" })
+get_component_examples({ "component": "datatable", "variant": "CursorPagination" })
+get_component_examples({ "component": "datatable", "variant": "Sortable" })
+get_component_examples({ "component": "datatable", "variant": "MultipleSelection" })
+get_component_examples({ "component": "datatable", "variant": "CustomColumn" })
+get_component_examples({ "component": "exportbutton", "variant": "WithTable" })
 ```
 
 ### Inspect Knowledge Graph & Usages:
@@ -47,7 +55,7 @@ query_graph({ "query": "useDataTableFetch" })
 The Wangs UI `DataTable` is built on a modular, headless-first architecture:
 
 1. **Declarative Column Definitions (`TableColumn<T>[]`)**:
-   Columns are configured as typed array objects, not as JSX children. Check `get-documentation({ "id": "datatable" })` for column field types.
+   Columns are configured as typed array objects, not as JSX children. Check `get_component_api({ "component": "datatable" })` for column field types.
 2. **Table Instance Hook (`useDataTable`)**:
    Coordinates table state (sorting, pagination, selection, column ordering, pinning, visibility).
 3. **Data Fetching Hook (`useDataTableFetch`)**:
@@ -62,7 +70,8 @@ The Wangs UI `DataTable` is built on a modular, headless-first architecture:
 
 ## 3. Mandatory Implementation Rules
 
-1. **Query MCP for Current Code Patterns**: Always run `get-documentation-for-story` for `datatable` before drafting code.
+1. **Query MCP for Current Code Patterns**: Always run `get_component_examples` for `datatable` before drafting code.
 2. **Strict Subpath Imports**: Import via `@wangs-ui/react-core/primitive/datatable` and companion primitive paths.
 3. **Always Translate Visible Copy**: All column header labels, empty state messages, and action button labels must be wrapped in `t('...')` from `@wangs-ui/react-i18n`.
-4. **Stable Row Identity**: Always configure a unique key identifier for stable selection and row identity.
+4. **Stable Row Identity**: Always configure a unique key identifier (`dataKey` / `rowId`) for stable selection and row identity.
+5. **Zero Redundant Table Wrappers**: Never wrap `<DataTable />` in an isolated `<div>` or `<Box>` solely to set width or margin. Wangs UI DataTable manages its own container scroll and layout dimensions out of the box.

package/{dist/skills → skills/wangs-ui}/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.
@@ -13,21 +14,29 @@ Use this skill when building interactive modals, create/edit dialog forms, destr
 
 Do **NOT** guess overlay props, event names, or footer slots. Query the MCP server dynamically to inspect exact contracts and live story implementations:
 
-### Inspect Overlay Contracts:
+### Inspect Overlay Contracts (`component` parameter):
+
+```json
+get_component_api({ "component": "dialog" })
+get_component_api({ "component": "dialogform" })
+get_component_api({ "component": "modal" })
+get_component_api({ "component": "toast" })
+```
+
+### Read Curated Overlay Documentation:
 
 ```json
-get-documentation({ "id": "dialog" })
-get-documentation({ "id": "dialogform" })
-get-documentation({ "id": "modal" })
-get-documentation({ "id": "toast" })
+get_documentation({ "id": "dialog" })
+get_documentation({ "id": "dialogform" })
+get_documentation({ "id": "modal" })
 ```
 
 ### Inspect Live Story Implementations:
 
 ```json
-get-documentation-for-story({ "id": "dialog", "storyName": "Confirmation" })
-get-documentation-for-story({ "id": "dialogform", "storyName": "Default" })
-get-documentation-for-story({ "id": "modal", "storyName": "Default" })
+get_component_examples({ "component": "dialog", "variant": "RichHeaderFooter" })
+get_component_examples({ "component": "dialogform", "variant": "Default" })
+get_component_examples({ "component": "modal", "variant": "Default" })
 ```
 
 ### Inspect Knowledge Graph & Usages:

package/{dist/skills → skills/wangs-ui}/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`.
@@ -13,22 +14,29 @@ Use this skill when implementing multi-language interfaces, translating user-fac
 
 Do **NOT** guess component localization contracts, language switcher variants, or datepicker props. Query the MCP server dynamically to inspect exact props and live story implementations:
 
-### Inspect Localized Component Contracts:
+### Inspect Localized Component Contracts (`component` parameter):
+
+```json
+get_component_api({ "component": "languageswitcher" })
+get_component_api({ "component": "currencyinput" })
+get_component_api({ "component": "datepicker" })
+get_component_api({ "component": "select" })
+get_component_api({ "component": "datatable" })
+```
+
+### Read Curated Localization Documentation:
 
 ```json
-get-documentation({ "id": "languageswitcher" })
-get-documentation({ "id": "currencyinput" })
-get-documentation({ "id": "datepicker" })
-get-documentation({ "id": "select" })
-get-documentation({ "id": "datatable" })
+get_documentation({ "id": "languageswitcher" })
+get_documentation({ "id": "currencyinput" })
 ```
 
 ### Inspect Live Story Implementations:
 
 ```json
-get-documentation-for-story({ "id": "languageswitcher", "storyName": "Basic" })
-get-documentation-for-story({ "id": "currencyinput", "storyName": "Basic" })
-get-documentation-for-story({ "id": "datepicker", "storyName": "Default" })
+get_component_examples({ "component": "languageswitcher", "variant": "Default" })
+get_component_examples({ "component": "currencyinput", "variant": "Default" })
+get_component_examples({ "component": "datepicker", "variant": "Default" })
 ```
 
 ---
@@ -132,7 +140,7 @@ selectedCount === 0
 Use standard supported HTML tags (`<a>`, `<b>`, `<i>`, `<u>`, `<s>`, `<br/>`, `<sub>`, `<sup>`, `<code>`, `<mark>`) for inline styling. Tags are automatically parsed into React elements without custom regex or string manipulation:
 
 ```tsx
-import Link from '@wangs-ui/foundation/theme/Link';
+import { Link } from '@wangs-ui/foundation/theme';
 
 t('You have selected <b>{count} items</b>. Click <a>here</a> to review.', {
   count: selectedCount,

package/skills/wangs-ui/layout-navigation/SKILL.md

@@ -0,0 +1,156 @@
+---
+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, tabbed views, or feature routing with `@wangs-ui/react-core`, `@wangs-ui/foundation`, and `@wangs-ui/react-navigation`.
+
+---
+
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
+
+Do **NOT** guess layout block slots, sidebar item interfaces, or breadcrumb props. Query the MCP server dynamically to inspect exact contracts and live story implementations:
+
+### Inspect Layout & Navigation Contracts (`component` parameter):
+
+```json
+get_component_api({ "component": "applayout" })
+get_component_api({ "component": "sidebar" })
+get_component_api({ "component": "tabletoolbar" })
+get_component_api({ "component": "breadcrumb" })
+get_component_api({ "component": "tabs" })
+```
+
+
+### Read Curated Layout Documentation (`id` parameter):
+
+```json
+get_documentation({ "id": "applayout" })
+get_documentation({ "id": "sidebar" })
+get_documentation({ "id": "react-navigation" })
+```
+
+### Inspect Live Story Implementations:
+
+```json
+get_component_examples({ "component": "applayout", "variant": "TopNavbar" })
+get_component_examples({ "component": "sidebar", "variant": "WithSubMenu" })
+get_component_examples({ "component": "breadcrumb", "variant": "Default" })
+get_component_examples({ "component": "tabs", "variant": "Default" })
+```
+
+### Inspect Knowledge Graph & Usages:
+
+```json
+query_graph({ "query": "AppLayout" })
+query_graph({ "query": "Sidebar" })
+```
+
+---
+
+## 2. Layout Architecture & Mental Model
+
+1. **Top-Level App Shell (`AppLayout`)**:
+   - Subpath: `@wangs-ui/react-core/blocks/applayout`
+   - Outer responsive shell arranging navigation, navbar, sidebars, main viewport, and footer. Inspect slots and layout variants via `get_component_api({ "component": "applayout" })`.
+2. **Hierarchical Menu (`Sidebar`)**:
+   - Subpath: `@wangs-ui/react-core/blocks/sidebar`
+   - Primary app navigation drawer/rail supporting nested menus, badges, and collapse states. Inspect items and events via `get_component_api({ "component": "sidebar" })`.
+3. **Breadcrumb Trail (`Breadcrumb`)**:
+   - Subpath: `@wangs-ui/react-core/primitive/breadcrumb`
+   - Secondary hierarchy navigation displaying screen depth. Inspect item structure via `get_component_api({ "component": "breadcrumb" })`.
+4. **Tabbed Sub-Views (`Tabs`)**:
+   - Subpath: `@wangs-ui/react-core/primitive/tabs`
+   - In-page view switcher for partitioning entity details into distinct panels. Inspect via `get_component_api({ "component": "tabs" })`.
+5. **Universal Routing (`@wangs-ui/react-navigation`)**:
+   - Platform-agnostic route graph abstraction (`buildGraph`, `paramRoute`).
+   - Web router bridge: `@wangs-ui/react-navigation/web` (React Router).
+   - Native router bridge: `@wangs-ui/react-navigation/native` (React Navigation / Expo).
+
+---
+
+## 3. Structural Page Blueprint (Standard Pattern)
+
+```tsx
+import AppLayout from '@wangs-ui/react-core/blocks/applayout';
+import Sidebar from '@wangs-ui/react-core/blocks/sidebar';
+import Breadcrumb from '@wangs-ui/react-core/primitive/breadcrumb';
+import { Container, Section, Stack, HStack } from '@wangs-ui/foundation/layout';
+import { Text } from '@wangs-ui/foundation/theme';
+import { useI18n } from '@wangs-ui/react-i18n';
+import { HomeLine, Settings4Line } from '@wangs-ui/react-icons';
+import { useState } from 'react';
+
+export function ApplicationShell({ children }: { children: React.ReactNode }) {
+  const { t } = useI18n();
+  const [activeRoute, setActiveRoute] = useState('dashboard');
+  const [collapsed, setCollapsed] = useState(false);
+
+  const sidebarItems = [
+    { value: 'dashboard', label: t('Dashboard'), icon: HomeLine, to: '/' },
+    { value: 'settings', label: t('Settings'), icon: Settings4Line, to: '/settings' },
+  ];
+
+  return (
+    <AppLayout
+      variant="full-sidebar"
+      sidebar={
+        <Sidebar
+          items={sidebarItems}
+          value={activeRoute}
+          onValueChange={setActiveRoute}
+          collapsed={collapsed}
+          onCollapsedChange={setCollapsed}
+          collapseMode="rail"
+        />
+      }
+    >
+      <Container size="xl">
+        <Section space="md">
+          <Stack gap="4">
+            <Breadcrumb
+              items={[
+                { label: t('Home'), href: '/' },
+                { label: t('Dashboard') },
+              ]}
+            />
+            <Text variant="headlineLarge">{t('Overview')}</Text>
+            {children}
+          </Stack>
+        </Section>
+      </Container>
+    </AppLayout>
+  );
+}
+```
+
+---
+
+## 4. Mandatory Implementation Rules
+
+1. **Query MCP First**: Always inspect `applayout` and `sidebar` stories via MCP before assembling the layout.
+2. **Strict Subpath Imports**:
+   - Blocks: `@wangs-ui/react-core/blocks/*` (`applayout`, `sidebar`, `tabletoolbar`)
+   - Primitives: `@wangs-ui/react-core/primitive/*` (`breadcrumb`, `tabs`)
+   - Layout Primitives: `@wangs-ui/foundation/layout` (`Container`, `Section`, `Stack`, `HStack`, `Box`, `Grid`)
+   - Typography: `@wangs-ui/foundation/theme` (`Text`)
+3. **Standard Layout Containers & Spacing**:
+   - Use `Container` (max-width rhythm) and `Section` (vertical rhythm) for page boundaries.
+   - Use flat numeric Tailwind spacing (`gap="4"`, `p="6"`). Never use legacy named tokens like `p-3xl` or `gap-md`.
+4. **Typography Scale**:
+   - Use `<Text variant="headlineLarge">` or `display*` / `title*` for page headers. Never use obsolete `.heading-*` helper classes or raw HTML heading tags without primitives.
+5. **No Redundant Layout Wrappers**:
+   - Do NOT insert intermediate pass-through `<div>` or `<Box>` wrappers between `<Card>`/`<Tabs>` and tab contents.
+   - Render active tab content directly as a child of the container:
+     ```tsx
+     // ✅ Good
+     <Card>
+       <Tabs items={tabItems} value={activeTab} onValueChange={setActiveTab} />
+       {activeTab === 'general' ? <GeneralTab /> : <SecurityTab />}
+     </Card>
+     ```
+6. **Translate Navigation Labels**: Wrap all sidebar item labels, breadcrumb text, and page headings in `t('...')` from `@wangs-ui/react-i18n`.