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

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/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