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

package/skills/data-table/SKILL.md

@@ -16,21 +16,28 @@ Do **NOT** guess table prop names or hardcode table structures. Query the MCP se
 ### Inspect Component Contracts:
 
 ```json
-get-documentation({ "id": "datatable" })
-get-documentation({ "id": "exportbutton" })
-get-documentation({ "id": "filtercontainer" })
-get-documentation({ "id": "bulkactionbutton" })
+get_component_api({ "id": "datatable" })
+get_component_api({ "id": "exportbutton" })
+get_component_api({ "id": "filtercontainer" })
+get_component_api({ "id": "bulkactionbutton" })
+```
+
+### Read Curated Documentation:
+
+```json
+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 +54,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({ "id": "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 +69,7 @@ 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.

package/skills/dialog-modal/SKILL.md

@@ -16,18 +16,26 @@ Do **NOT** guess overlay props, event names, or footer slots. Query the MCP serv
 ### Inspect Overlay Contracts:
 
 ```json
-get-documentation({ "id": "dialog" })
-get-documentation({ "id": "dialogform" })
-get-documentation({ "id": "modal" })
-get-documentation({ "id": "toast" })
+get_component_api({ "id": "dialog" })
+get_component_api({ "id": "dialogform" })
+get_component_api({ "id": "modal" })
+get_component_api({ "id": "toast" })
+```
+
+### Read Curated Overlay Documentation:
+
+```json
+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/skills/i18n-usage/SKILL.md

@@ -16,19 +16,26 @@ Do **NOT** guess component localization contracts, language switcher variants, o
 ### Inspect Localized Component Contracts:
 
 ```json
-get-documentation({ "id": "languageswitcher" })
-get-documentation({ "id": "currencyinput" })
-get-documentation({ "id": "datepicker" })
-get-documentation({ "id": "select" })
-get-documentation({ "id": "datatable" })
+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" })
+```
+
+### Read Curated Localization Documentation:
+
+```json
+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" })
 ```
 
 ---

package/skills/layout-navigation/SKILL.md

@@ -16,19 +16,26 @@ Do **NOT** guess layout block slots, sidebar item interfaces, or breadcrumb prop
 ### Inspect Layout & Navigation Contracts:
 
 ```json
-get-documentation({ "id": "applayout" })
-get-documentation({ "id": "sidebar" })
-get-documentation({ "id": "breadcrumb" })
-get-documentation({ "id": "tabs" })
+get_component_api({ "id": "applayout" })
+get_component_api({ "id": "sidebar" })
+get_component_api({ "id": "breadcrumb" })
+get_component_api({ "id": "tabs" })
+```
+
+### Read Curated Layout Documentation:
+
+```json
+get_documentation({ "id": "applayout" })
+get_documentation({ "id": "sidebar" })
 ```
 
 ### Inspect Live Story Implementations:
 
 ```json
-get-documentation-for-story({ "id": "applayout", "storyName": "Default" })
-get-documentation-for-story({ "id": "sidebar", "storyName": "Default" })
-get-documentation-for-story({ "id": "breadcrumb", "storyName": "Default" })
-get-documentation-for-story({ "id": "tabs", "storyName": "Default" })
+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:

package/skills/responsive-design/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: responsive-design
+description: Guidelines for implementing responsive UIs with Wangs UI — covering Breakpoint tiers, responsive props (ResponsiveValue), <Show> conditional rendering, and spacing conventions.
+---
+
+# 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/skills/universal-layout/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: universal-layout
+description: Universal layout primitives (Box, Flex, Stack, Grid, Container, Section) with ResponsiveValue patterns for Web and React Native in Wangs UI.
+---
+
+# Skill: Universal Layout Primitives
+
+Use this skill when arranging page structure, spacing, or responsive grids with
+`@wangs-ui/foundation/layout`.
+For app shells (sidebar, breadcrumb, tabs), see the `layout-navigation` skill instead.
+
+---
+
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
+
+Do **NOT** guess layout prop names, spacing scales, or breakpoint keys. Query the MCP
+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" })
+```
+
+---
+
+## 2. Choosing the Right Primitive
+
+1. **Stack (VStack)** — 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.
+3. **Flex** — only when you need explicit `direction`, `wrap`, `align`, or `justify`
+   control beyond what Stack/HStack fix. Prefer Stack/HStack otherwise.
+4. **Grid** — two-dimensional placement or multi-column flows:
+   - explicit `columns={{ compact: 1, medium: 2, expanded: 4 }}` for fixed column counts;
+   - `minItemWidth` for auto-fit (columns grow/shrink with container width, no media query);
+   - `GridItem` with `colSpan` / `rowSpan` for featured tiles.
+5. **Box** — leaf-level spacing/sizing wrapper (`p`, `m`, `radius`, `overflow`), or
+   polymorphic `as="section" | "main" | "article"` for landmarks.
+6. **Container / Section** — page-level rhythm only: `Container` bounds max-width
+   (`size`, default `'xl'`) with consistent horizontal padding; `Section` sets
+   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
+   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 }}`,
+   `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.
+4. **Strict subpath imports**:
+   ```tsx
+   import { Stack, HStack, Grid, Container } 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).
+
+---
+
+## 4. Anti-Patterns (Forbidden)
+
+1. **Gap vs margin**: NEVER hardcode `marginBottom`/`mb-*` on children inside a
+   Stack/Flex/Grid to fake spacing — always use the parent's `gap`/`gapX`/`gapY`.
+   Margins collapse unpredictably and break `separator` insertion.
+2. **No nested Containers** and no `Container` for non-page content (cards, modals).
+3. **No `Flex` with hardcoded `flexDirection` styles** when `Stack`/`HStack` express it.
+4. **No raw media queries** for `direction`/`gap`/`columns` — use `ResponsiveValue`.
+5. **No `Grid` for one-dimensional lists** — that is `Stack`/`HStack` territory.

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

@@ -15,28 +15,34 @@ Do **NOT** guess component props, Pass-Through (`pt`) slots, or event names. Alw
 
 ```mermaid
 graph TD
-    A[Identify Component Needed] --> B[Call get-documentation id]
-    B --> C{Need live story / variant code?}
-    C -->|Yes| D[Call get-documentation-for-story]
-    C -->|No| E[Check Graphify: query_graph]
-    D --> E
-    E --> F[Implement Component with Subpath Imports]
+    A[Identify Component Needed] --> B[list_catalog to confirm the id]
+    B --> C[get_component_api for the typed contract]
+    C --> D{Need live story / variant code?}
+    D -->|Yes| E[get_component_examples]
+    D -->|No| F[get_documentation for curated guidance]
+    E --> G[Check Graphify: query_graph]
+    F --> G
+    G --> H[Implement Component with Subpath Imports]
 ```
 
 ### Discovery Steps:
 
 1. **Inspect Component Contract & Props**:
    ```json
-   get-documentation({ "id": "button" })
-   get-documentation({ "id": "input" })
-   get-documentation({ "id": "datatable" })
+   get_component_api({ "id": "button" })
+   get_component_api({ "id": "input" })
+   get_component_api({ "id": "datatable" })
    ```
-2. **Inspect Live Usage & Story Variants**:
+2. **Inspect Curated Documentation**:
    ```json
-   get-documentation-for-story({ "id": "button", "storyName": "Default" })
-   get-documentation-for-story({ "id": "datatable", "storyName": "ServerPagination" })
+   get_documentation({ "id": "button" })
    ```
-3. **Inspect Relationships & Real Usages in Graph**:
+3. **Inspect Live Usage & Story Variants**:
+   ```json
+   get_component_examples({ "component": "button", "variant": "Sizes" })
+   get_component_examples({ "component": "datatable", "variant": "CursorPagination" })
+   ```
+4. **Inspect Relationships & Real Usages in Graph**:
    ```json
    query_graph({ "query": "DataTable" })
    query_graph({ "query": "usePT" })
@@ -104,5 +110,7 @@ Never write raw HTML elements when a Wangs UI primitive exists:
 
 ### Spacing Tokens
 
-- Gap: `gap-xs`, `gap-sm`, `gap-md`, `gap-lg`, `gap-xl`, `gap-2xl`, `gap-3xl`
-- Padding: `p-xs`, `p-sm`, `p-md`, `p-lg`, `p-xl`, `p-2xl`, `p-3xl`
+- Flat numeric scale, Tailwind-aligned (1 unit = 4px): `0`, `0.5`, `1`, `1.5`, `2`, `2.5`, `3`, `3.5`, `4`…`16` (e.g. `4` = 16px)
+- Web: use numeric utilities directly — Gap: `gap-4`, Padding: `px-4 py-1.5`
+- Native: read pixel values via `useTheme().spacing` (e.g. `spacing[4] === 16`)
+- Responsiveness via `ResponsiveValue<T>` size props and `<Show>`, not per-density spacing tokens