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

package/skills/create-form/SKILL.md

@@ -17,15 +17,15 @@ Do **NOT** hardcode or guess prop names, component options, preset variations, o
 ### Component & Form API Protocol:
 
 ```json
-get_component_api({ "id": "form" })
-get_component_api({ "id": "field" })
-get_component_api({ "id": "dialogform" })
-get_component_api({ "id": "input" })
-get_component_api({ "id": "numberinput" })
-get_component_api({ "id": "select" })
-get_component_api({ "id": "multiselect" })
-get_component_api({ "id": "datepicker" })
-get_component_api({ "id": "fileupload" })
+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:
@@ -83,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/skills/data-table/SKILL.md

@@ -14,13 +14,13 @@ 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({ "id": "datatable" })
-get_component_api({ "id": "exportbutton" })
-get_component_api({ "id": "filtercontainer" })
-get_component_api({ "id": "bulkactionbutton" })
+get_component_api({ "component": "datatable" })
+get_component_api({ "component": "exportbutton" })
+get_component_api({ "component": "filtercontainer" })
+get_component_api({ "component": "bulkactionbutton" })
 ```
 
 ### Read Curated Documentation:
@@ -55,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_component_api({ "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`)**:
@@ -73,4 +73,5 @@ The Wangs UI `DataTable` is built on a modular, headless-first architecture:
 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/skills/dialog-modal/SKILL.md

@@ -14,13 +14,13 @@ 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({ "id": "dialog" })
-get_component_api({ "id": "dialogform" })
-get_component_api({ "id": "modal" })
-get_component_api({ "id": "toast" })
+get_component_api({ "component": "dialog" })
+get_component_api({ "component": "dialogform" })
+get_component_api({ "component": "modal" })
+get_component_api({ "component": "toast" })
 ```
 
 ### Read Curated Overlay Documentation:

package/skills/i18n-usage/SKILL.md

@@ -14,14 +14,14 @@ 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({ "id": "languageswitcher" })
-get_component_api({ "id": "currencyinput" })
-get_component_api({ "id": "datepicker" })
-get_component_api({ "id": "select" })
-get_component_api({ "id": "datatable" })
+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:
@@ -140,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/layout-navigation/SKILL.md

@@ -4,9 +4,10 @@ description: Architecture, navigation hierarchies, and MCP discovery protocol fo
 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`.
+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`.
 
 ---
 
@@ -14,20 +15,23 @@ Use this skill when constructing application shells, multi-level sidebars, page
 
 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:
+### Inspect Layout & Navigation Contracts (`component` parameter):
 
 ```json
-get_component_api({ "id": "applayout" })
-get_component_api({ "id": "sidebar" })
-get_component_api({ "id": "breadcrumb" })
-get_component_api({ "id": "tabs" })
+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:
+
+### Read Curated Layout Documentation (`id` parameter):
 
 ```json
 get_documentation({ "id": "applayout" })
 get_documentation({ "id": "sidebar" })
+get_documentation({ "id": "react-navigation" })
 ```
 
 ### Inspect Live Story Implementations:
@@ -51,20 +55,102 @@ query_graph({ "query": "Sidebar" })
 ## 2. Layout Architecture & Mental Model
 
 1. **Top-Level App Shell (`AppLayout`)**:
-   Provides structured slots for `sidebar`, `header`, and main content view, handling responsive viewport scaling and mobile navigation overlays.
+   - 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`)**:
-   Renders single and nested navigation items, active route indicators, collapsible state, and notification badges.
+   - 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`)**:
-   Maintains clear navigational hierarchy on page headers.
+   - 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`)**:
-   Organizes complex entity detail views or multi-section settings into distinct tabbed panels.
+   - 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. Mandatory Implementation Rules
+## 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>
+  );
+}
+```
+
+---
 
-1. **Query MCP for Current Code Patterns**: Inspect `applayout` and `sidebar` stories via MCP before assembling the layout.
-2. **Strict Subpath Imports**: Import layout blocks via `@wangs-ui/react-core/blocks/*` and primitives via `@wangs-ui/react-core/primitive/*`.
-3. **Consistent Spacing Grid**: Use standard container padding (`p-6` or `p-3xl`) across page contents.
-4. **Page Hierarchy Alignment**: Every page view inside the layout must provide a clear `.heading-1` hierarchy and synchronized breadcrumbs.
-5. **Translate Navigation Labels**: Wrap all sidebar item labels and breadcrumb texts in `t('...')` from `@wangs-ui/react-i18n`.
+## 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`.

package/skills/responsive-design/SKILL.md

@@ -10,7 +10,17 @@ Use this skill when building responsive pages, layouts, or screen adaptations wi
 
 ---
 
-## 1. Breakpoint Reference
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
+
+Do **NOT** guess responsive prop types or breakpoint keys. Query the MCP server dynamically:
+
+```json
+resolve_type_definition({ "types": ["ResponsiveValue", "Breakpoint", "SpacingKey"] })
+```
+
+---
+
+## 2. Breakpoint Reference
 
 Wangs UI uses three standardized breakpoints:
 
@@ -30,14 +40,17 @@ const { breakpoint } = useTheme(); // 'compact' | 'medium' | 'expanded'
 
 ---
 
-## 2. Responsive Props (`ResponsiveValue`)
+## 3. Responsive Props (`ResponsiveValue`)
 
 Visual scale props (`size`, layout `gap`, `columns`, `p`, `m`) accept either a single value or an object mapped by breakpoint:
 
 ```tsx
+import { Button } from '@wangs-ui/react-core/components/button';
+import { Grid, Stack } from '@wangs-ui/foundation/layout';
+
 // Static (identical across all devices)
 <Button size="md" />
-<Stack gap={4} />
+<Stack gap="4" />
 
 // Adaptive (changes across breakpoints)
 <Button size={{ compact: 'lg', expanded: 'sm' }} />
@@ -48,7 +61,7 @@ Visual scale props (`size`, layout `gap`, `columns`, `p`, `m`) accept either a s
 
 ---
 
-## 3. Conditional Rendering (`<Show>`)
+## 4. Conditional Rendering (`<Show>`)
 
 Use `<Show>` when a component should be mounted or unmounted based on the active breakpoint:
 
@@ -78,7 +91,7 @@ import { Show } from '@wangs-ui/foundation/theme';
 
 ---
 
-## 4. Spacing Conventions
+## 5. Spacing Conventions
 
 Spacing tokens are **flat and fixed** (1 unit = 4px):
 
@@ -87,7 +100,7 @@ Spacing tokens are **flat and fixed** (1 unit = 4px):
 
 ---
 
-## 5. Anti-Patterns to Avoid
+## 6. 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.

package/skills/universal-layout/SKILL.md

@@ -18,24 +18,15 @@ Do **NOT** guess layout prop names, spacing scales, or breakpoint keys. Query th
 server dynamically:
 
 ```json
-list_catalog({ "category": "layout" })
-get_component_api({ "id": "layout:box" })
-get_component_api({ "id": "layout:grid" })
-get_documentation({ "id": "layout-stack" })
-```
-
-Resolve shared types before writing responsive props:
-
-```json
-resolve_type_definition({ "name": "ResponsiveValue" })
-resolve_type_definition({ "name": "SpacingKey" })
+list_catalog({ "query": "layout" })
+resolve_type_definition({ "types": ["ResponsiveValue", "SpacingKey", "StackProps", "GridProps", "BoxProps", "ScrollAreaProps"] })
 ```
 
 ---
 
 ## 2. Choosing the Right Primitive
 
-1. **Stack (VStack)** — default for vertical flows (forms, cards, page sections).
+1. **Stack (Vertical)** — default for vertical flows (forms, cards, page sections).
    Fixed `column` direction, uniform `gap`, optional auto-`separator`.
 2. **HStack** — horizontal rows with vertical centering (avatar + label + action,
    toolbar clusters). Fixed `row` direction.
@@ -52,25 +43,26 @@ resolve_type_definition({ "name": "SpacingKey" })
    vertical rhythm (`space: 'sm' | 'md' | 'lg'`, default `'md'`). Never nest
    `Container` inside `Container`.
 7. **ZStack** — overlays (badge on card, status dot on avatar, hero overlay).
-8. **AspectRatio / Bleed / Spacer** — media frames (`ratio`), full-bleed breakouts
+8. **ScrollArea** — styled, accessible scrollable viewports (`orientation: 'vertical' | 'horizontal' | 'both'`, `variant: 'hover' | 'always' | 'scroll'`).
+9. **AspectRatio / Bleed / Spacer** — media frames (`ratio`), full-bleed breakouts
    inside padded containers (`Bleed`), and flexible fillers in stacks (`Spacer`).
 
 ---
 
 ## 3. Mandatory Implementation Rules
 
-1. **ResponsiveValue everywhere**: scalar for static (`gap={4}`), object for
-   adaptive (`gap={{ compact: 2, medium: 4, expanded: 6 }}`,
+1. **ResponsiveValue everywhere**: scalar for static (`gap="4"`), object for
+   adaptive (`gap={{ compact: '2', medium: '4', expanded: '6' }}`,
    `columns={{ compact: 1, medium: 2, expanded: 4 }}`). Breakpoints are
    `compact` (mobile-first base), `medium` (`md:`), `expanded` (`lg:`).
 2. **Separators, not manual dividers**: `<Stack separator={<Divider />}>` inserts
    dividers between children with no trailing element. Never hand-place a divider
    after every child.
-3. **Spacing scale**: `gap`/`p`/`m` use `SpacingKey` (Tailwind numeric scale,
-   1 unit = 4px). Never pass raw pixel strings to spacing props.
+3. **Spacing scale**: `gap`/`p`/`m` use `SpacingKey` (Tailwind numeric scale strings,
+   e.g. `'0'`, `'1'`, `'2'`, `'4'`, `'6'`, `'8'`, `'12'`, `'16'`). Never pass raw pixel strings to spacing props.
 4. **Strict subpath imports**:
    ```tsx
-   import { Stack, HStack, Grid, Container } from '@wangs-ui/foundation/layout';
+   import { Stack, HStack, Grid, Container, Box, Flex, ScrollArea } from '@wangs-ui/foundation/layout';
    ```
 5. **Translate visible labels** inside layout children via `t('...')` from
    `@wangs-ui/react-i18n` (layout props themselves are never translated).