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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wangs-ui/skills",
-  "version": "1.3.0-alpha.14",
+  "version": "1.3.0-alpha.16",
   "description": "CLI to install, update, and manage modular AI agent skills for Wangs UI React applications",
   "keywords": [
     "agents",

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

@@ -0,0 +1,104 @@
+---
+name: wangs-ui-components
+description: MCP Discovery Protocol, modular subpath import map, and primitive substitution map for Wangs UI applications.
+metadata:
+  owner: wangs-ui
+---
+
+# Skill: Wangs UI Component Fundamentals & MCP Protocol
+
+Use this skill to navigate the Wangs UI ecosystem. **MCP is the single source of truth** for all component APIs, props, variants, slots, and examples. Do not hardcode or assume props — always query MCP dynamically.
+
+---
+
+## 1. The MCP Discovery Protocol (Single Source of Truth)
+
+Do **NOT** guess component props, Pass-Through (`pt`) slots, or event names. Always query the MCP server dynamically:
+
+```mermaid
+graph TD
+    A[Identify Component / Primitive Needed] --> B[list_catalog to confirm name/id]
+    B --> C[get_component_api for typed contract]
+    B --> D[get_documentation for curated guidance]
+    C --> E{Need live story / variant code?}
+    D --> E
+    E -->|Yes| F[get_component_examples]
+    E -->|No| G[Implement with Subpath Import Map]
+    F --> G
+```
+
+### Discovery Steps:
+
+1. **Discover Catalog Entries**:
+   ```json
+   list_catalog({ "query": "button" })
+   list_catalog({ "category": "component" })
+   ```
+2. **Inspect Typed Contracts & Props** (`component` parameter):
+   ```json
+   get_component_api({ "component": "button" })
+   get_component_api({ "component": "datatable" })
+   get_component_api({ "component": "field" })
+   ```
+3. **Read Curated Narrative Documentation** (`id` parameter):
+   ```json
+   get_documentation({ "id": "button" })
+   get_documentation({ "id": "foundation" })
+   get_documentation({ "id": "form" })
+   ```
+4. **Fetch Live Storybook TSX Examples**:
+   ```json
+   get_component_examples({ "component": "button", "variant": "Sizes" })
+   get_component_examples({ "component": "datatable", "variant": "Basic" })
+   ```
+5. **Explore Knowledge Graph Relationships**:
+   ```json
+   query_graph({ "query": "DataTable" })
+   query_graph({ "query": "useForm" })
+   ```
+
+---
+
+## 2. Modular Subpath Import Map
+
+Always import via specific subpath modules to guarantee tree-shaking and avoid bundling entire packages:
+
+| Ecosystem Layer | Subpath Pattern | Example Imports |
+| :--- | :--- | :--- |
+| **Core Primitives** | `@wangs-ui/react-core/primitive/<name>` | `Button`, `Input`, `Select`, `DataTable`, `Dialog`, `Modal`, `Field`, `Form`, `Card`, `Badge` |
+| **Layout Primitives** | `@wangs-ui/foundation/layout` | `Stack`, `HStack`, `VStack`, `Flex`, `Grid`, `Box`, `Container`, `Section`, `ScrollArea` |
+| **Typography Primitives** | `@wangs-ui/foundation/theme` | `Text`, `Code`, `Kbd`, `Link`, `Blockquote`, `List`, `Mark` |
+| **Blocks & Shells** | `@wangs-ui/react-core/blocks/<name>` | `AppLayout`, `Sidebar`, `TableToolbar` |
+| **Form Engine** | `@wangs-ui/form/core`, `@wangs-ui/form/react` | Headless form state, hooks, validation adapters |
+| **Universal Navigation** | `@wangs-ui/react-navigation/web`, `@wangs-ui/react-navigation/native` | `buildGraph`, `paramRoute`, platform router bridges |
+| **Theme & Providers** | `@wangs-ui/react-core/api`, `@wangs-ui/foundation/theme` | `WangsUiProvider`, `ThemeProvider`, `useTheme` |
+| **Vector Icons** | `@wangs-ui/react-icons` | `SearchLine`, `AddLine`, `DeleteBin6Line`, `CheckLine` |
+| **i18n & Localization** | `@wangs-ui/react-i18n` | `useI18n`, `t`, `WangsUiI18nProvider` |
+
+---
+
+## 3. Primitive Substitution Map
+
+Zero raw HTML elements. Never write raw HTML tags when a Wangs UI primitive exists:
+
+| Forbidden Raw HTML | Mandatory Wangs UI Primitive | Import Path | MCP Catalog / Doc ID |
+| :--- | :--- | :--- | :--- |
+| `<button>` | `Button` | `@wangs-ui/react-core/primitive/button` | `button` |
+| `<input type="text">` | `Input` | `@wangs-ui/react-core/primitive/input` | `input` |
+| `<input type="number">` | `NumberInput` | `@wangs-ui/react-core/primitive/numberinput` | `numberinput` |
+| `<input type="checkbox">` | `Checkbox` | `@wangs-ui/react-core/primitive/checkbox` | `checkbox` |
+| `<select>` | `Select` / `MultiSelect` | `@wangs-ui/react-core/primitive/select` | `select`, `multiselect` |
+| `<textarea>` | `Textarea` | `@wangs-ui/react-core/primitive/textarea` | `textarea` |
+| `<form>` | `Form` / `DialogForm` | `@wangs-ui/react-core/primitive/form` | `form`, `dialogform` |
+| `<dialog>` / alert modal | `Modal` / `Dialog` | `@wangs-ui/react-core/primitive/modal` | `modal`, `dialog` |
+| `<table>` | `DataTable` | `@wangs-ui/react-core/primitive/datatable` | `datatable` |
+| `<div>` (layout / flex / grid) | `Stack`, `HStack`, `Flex`, `Grid`, `Box` | `@wangs-ui/foundation/layout` | `universal-layout` |
+| `<div>` (surface card) | `Card` | `@wangs-ui/react-core/primitive/card` | `card` |
+| Pill / status chip | `Badge` | `@wangs-ui/react-core/primitive/badge` | `badge` |
+| `<h1>` - `<h6>` | `<Text variant="...">` | `@wangs-ui/foundation/theme` | `foundation` |
+| `<p>`, `<span>` (body text) | `<Text variant="...">` | `@wangs-ui/foundation/theme` | `foundation` |
+| `<a>` | `Link` | `@wangs-ui/foundation/theme` | `foundation` |
+| `<code>` | `Code` | `@wangs-ui/foundation/theme` | `foundation` |
+| `<kbd>` | `Kbd` | `@wangs-ui/foundation/theme` | `foundation` |
+| `<blockquote>` | `Blockquote` | `@wangs-ui/foundation/theme` | `foundation` |
+| `<ul>`, `<ol>` | `List` | `@wangs-ui/foundation/theme` | `foundation` |

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

@@ -1,202 +0,0 @@
----
-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/foundation`, `@wangs-ui/react-icons`, `@wangs-ui/react-presets`, `@wangs-ui/form`).
-
----
-
-## 1. The MCP Discovery Protocol (Mandatory Single Source of Truth)
-
-Do **NOT** guess component props, Pass-Through (`pt`) slots, or event names. Always query the MCP server dynamically to retrieve the current API signatures and live story implementations:
-
-```mermaid
-graph TD
-    A[Identify Component / Token Needed] --> B[list_catalog to confirm name/id]
-    B --> C[get_component_api for typed contract]
-    B --> D[get_documentation for curated guidance]
-    C --> E{Need live story / variant code?}
-    D --> E
-    E -->|Yes| F[get_component_examples]
-    E -->|No| G[Implement with Modular Subpaths]
-    F --> G
-```
-
-### Discovery Steps:
-
-1. **Confirm Available Components & Blocks**:
-   ```json
-   list_catalog({ "query": "button" })
-   list_catalog({ "category": "component" })
-   ```
-2. **Inspect Component Contract & Props** (`component` parameter):
-   ```json
-   get_component_api({ "component": "button" })
-   get_component_api({ "component": "input" })
-   get_component_api({ "component": "datatable" })
-   get_component_api({ "component": "modal" })
-   ```
-3. **Inspect Curated Documentation** (`id` parameter):
-   ```json
-   get_documentation({ "id": "foundation" })
-   get_documentation({ "id": "button" })
-   get_documentation({ "id": "form" })
-   ```
-4. **Inspect Live Usage & Story Variants**:
-   ```json
-   get_component_examples({ "component": "button", "variant": "Sizes" })
-   get_component_examples({ "component": "datatable", "variant": "CursorPagination" })
-   ```
-5. **Query Knowledge Graph & Symbol Relationships**:
-   ```json
-   query_graph({ "query": "DataTable" })
-   query_graph({ "query": "usePT" })
-   ```
-
----
-
-## 2. Modular Subpath Imports (Mandatory)
-
-Always import via specific subpaths to guarantee tree-shaking and avoid bundling entire packages:
-
-```tsx
-// 1. Core Primitives (@wangs-ui/react-core/primitive/*)
-import Button from '@wangs-ui/react-core/primitive/button';
-import Input from '@wangs-ui/react-core/primitive/input';
-import NumberInput from '@wangs-ui/react-core/primitive/numberinput';
-import Textarea from '@wangs-ui/react-core/primitive/textarea';
-import Select from '@wangs-ui/react-core/primitive/select';
-import MultiSelect from '@wangs-ui/react-core/primitive/multiselect';
-import Checkbox from '@wangs-ui/react-core/primitive/checkbox';
-import Badge from '@wangs-ui/react-core/primitive/badge';
-import Card from '@wangs-ui/react-core/primitive/card';
-import DataTable from '@wangs-ui/react-core/primitive/datatable';
-import Modal from '@wangs-ui/react-core/primitive/modal';
-import Dialog from '@wangs-ui/react-core/primitive/dialog';
-import DialogForm from '@wangs-ui/react-core/primitive/dialogform';
-import { useForm, Form } from '@wangs-ui/react-core/primitive/form';
-import Field from '@wangs-ui/react-core/primitive/field';
-
-// 2. Layout Primitives (@wangs-ui/foundation/layout)
-import {
-  Box,
-  Flex,
-  Stack,
-  HStack,
-  VStack,
-  Grid,
-  Container,
-  Section,
-  Show,
-} from '@wangs-ui/foundation/layout';
-
-// 3. Typography Primitives (@wangs-ui/foundation/theme)
-import { Text, Code, Kbd, Link, Mark, Blockquote, List } from '@wangs-ui/foundation/theme';
-
-// 4. Blocks & Navigation (@wangs-ui/react-core/blocks/*)
-import AppLayout from '@wangs-ui/react-core/blocks/applayout';
-import Sidebar from '@wangs-ui/react-core/blocks/sidebar';
-import TableToolbar from '@wangs-ui/react-core/blocks/tabletoolbar';
-
-// 5. Providers & System Hooks
-import { WangsUiProvider } from '@wangs-ui/react-core/api';
-import { ThemeProvider, useTheme } from '@wangs-ui/foundation/theme';
-import { useI18n } from '@wangs-ui/react-i18n';
-
-// 6. Vector Icons (@wangs-ui/react-icons)
-import { SearchLine, AddLine, DeleteBin6Line, CheckLine } from '@wangs-ui/react-icons';
-```
-
----
-
-## 3. Strict Primitive Substitution Rule
-
-Zero raw HTML elements. Never write raw HTML tags when a Wangs UI primitive exists:
-
-| Forbidden Raw HTML             | Mandatory Wangs UI Primitive                         | Import Path                                  | MCP Doc / Catalog ID    |
-|:-------------------------------|:-----------------------------------------------------|:---------------------------------------------|:------------------------|
-| `<button>`                     | `Button`                                             | `@wangs-ui/react-core/primitive/button`      | `button`                |
-| `<input type="text">`          | `Input`                                              | `@wangs-ui/react-core/primitive/input`       | `input`                 |
-| `<input type="number">`        | `NumberInput`                                        | `@wangs-ui/react-core/primitive/numberinput` | `numberinput`           |
-| `<input type="checkbox">`      | `Checkbox`                                           | `@wangs-ui/react-core/primitive/checkbox`    | `checkbox`              |
-| `<select>`                     | `Select` / `MultiSelect`                             | `@wangs-ui/react-core/primitive/select`      | `select`, `multiselect` |
-| `<textarea>`                   | `Textarea`                                           | `@wangs-ui/react-core/primitive/textarea`    | `textarea`              |
-| `<form>`                       | `Form` / `DialogForm`                                | `@wangs-ui/react-core/primitive/form`        | `form`, `dialogform`    |
-| `<dialog>` / alert modal       | `Modal` / `Dialog`                                   | `@wangs-ui/react-core/primitive/modal`       | `modal`, `dialog`       |
-| `<table>`                      | `DataTable`                                          | `@wangs-ui/react-core/primitive/datatable`   | `datatable`             |
-| `<div>` (layout / flex / grid) | `Stack`, `HStack`, `Flex`, `Grid`, `Box`             | `@wangs-ui/foundation/layout`                | `universal-layout`      |
-| `<div>` (surface card)         | `Card`                                               | `@wangs-ui/react-core/primitive/card`        | `card`                  |
-| Pill / status chip             | `Badge`                                              | `@wangs-ui/react-core/primitive/badge`       | `badge`                 |
-| `<h1>` - `<h6>`                | `<Text variant="headline*">` / `display*` / `title*` | `@wangs-ui/foundation/theme`                 | `foundation`            |
-| `<p>`, `<span>` (body text)    | `<Text variant="body*">` / `label*`                  | `@wangs-ui/foundation/theme`                 | `foundation`            |
-| `<a>`                          | `Link`                                               | `@wangs-ui/foundation/theme`                 | `foundation`            |
-| `<code>`                       | `Code`                                               | `@wangs-ui/foundation/theme`                 | `foundation`            |
-| `<kbd>`                        | `Kbd`                                                | `@wangs-ui/foundation/theme`                 | `foundation`            |
-| `<blockquote>`                 | `Blockquote`                                         | `@wangs-ui/foundation/theme`                 | `foundation`            |
-| `<ul>`, `<ol>`                 | `List`                                               | `@wangs-ui/foundation/theme`                 | `foundation`            |
-
----
-
-## 4. Typography System & `<Text>` Primitive
-
-Wangs UI uses a unified typography token system with standard and emphasized variants. Do **NOT** use arbitrary text utilities (`text-[16px]`, `text-lg`) or obsolete `.heading-*` classes.
-
-### Primary Typography Primitive: `<Text>`
-
-```tsx
-import { Text } from '@wangs-ui/foundation/theme';
-
-// Headings & Displays
-<Text variant="displayMedium">Hero Title</Text>
-<Text variant="headlineLarge">Page Header</Text>
-<Text variant="titleMedium">Card Section Header</Text>
-
-// Body & Labels
-<Text variant="bodyMedium">Standard reading paragraph text.</Text>
-<Text variant="bodySmall" color="secondary">Helper caption text.</Text>
-<Text variant="labelLarge" weight="bold">Interactive button or badge label</Text>
-
-// Polymorphic HTML Tag Override (default maps automatically: display/headline -> h1/h2, body -> p, label -> span)
-<Text variant="titleMedium" as="h3">Custom Tag Title</Text>
-```
-
-### Typography Roles:
-
-- **Display**: Page heroes (`displayLarge`, `displayMedium`, `displaySmall`)
-- **Headline**: Screen and page titles (`headlineLarge`, `headlineMedium`, `headlineSmall`)
-- **Title**: Card and modal section headers (`titleLarge`, `titleMedium`, `titleSmall`)
-- **Body**: Main copy and paragraphs (`bodyLarge`, `bodyMedium`, `bodySmall`)
-- **Label**: Buttons, inputs, and badges (`labelLarge`, `labelMedium`, `labelSmall`)
-- Append `Emphasized` for high-emphasis weights (e.g. `headlineMediumEmphasized`, `titleLargeEmphasized`).
-
----
-
-## 5. Spacing Scale & Theming Invariants
-
-### Flat 4px Spacing Scale
-
-Keys follow the flat numeric Tailwind step (`1` unit `= 4px`):
-`0`, `0.5` (2px), `1` (4px), `1.5` (6px), `2` (8px), `2.5` (10px), `3` (12px), `3.5` (14px), `4` (16px), `5` (20px), `6` (24px), `8` (32px), `10` (40px), `12` (48px), `16` (64px).
-
-- **In Layout Primitives**: Pass keys directly: `<HStack gap="3" p="4">`
-- **In Tailwind Utilities**: Use standard numeric utilities: `p-4`, `gap-3`, `px-6`
-- **In React Native**: Read pixels via `useTheme().spacing`: `spacing[4] === 16`
-
-### Theming & Dark Mode Invariants
-
-- **Theme Provider**: Wrap app root with `<ThemeProvider defaultPalette="blue" defaultMode="light">`.
-- **Engine Invariant**: **NEVER** override `:root`, `[data-mode='dark']`, or `--color-*` variables in custom CSS. Always customize themes via `ThemeProvider` or `WangsUiProvider.configOptions.preset`.
-- **Dark Mode**: Toggle only via `useTheme().setMode('dark' | 'light')` — never mutate `document.documentElement.classList`.
-
----
-
-## 6. Layout Governance & Redundant Wrapper Rule
-
-1. **Use Layout Primitives**: Arrange layouts using `Stack`, `HStack`, `VStack`, `Flex`, `Grid`, and `Box` from `@wangs-ui/foundation/layout`.
-2. **Zero Redundant Wrappers**: Never wrap a single component in an unnecessary `<div>` or `<Box>` (e.g. `<div><DataTable /></div>` or `<Box><Card /></Box>`).
-3. **No Inline Styling Overrides**: Component visual styling lives in global presets. Do not pass ad-hoc utility classes (`className="h-5 w-5"`, `rounded-lg`) directly to primitives or icons unless documented as an MCP exception.

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

@@ -1,202 +0,0 @@
----
-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/foundation`, `@wangs-ui/react-icons`, `@wangs-ui/react-presets`, `@wangs-ui/form`).
-
----
-
-## 1. The MCP Discovery Protocol (Mandatory Single Source of Truth)
-
-Do **NOT** guess component props, Pass-Through (`pt`) slots, or event names. Always query the MCP server dynamically to retrieve the current API signatures and live story implementations:
-
-```mermaid
-graph TD
-    A[Identify Component / Token Needed] --> B[list_catalog to confirm name/id]
-    B --> C[get_component_api for typed contract]
-    B --> D[get_documentation for curated guidance]
-    C --> E{Need live story / variant code?}
-    D --> E
-    E -->|Yes| F[get_component_examples]
-    E -->|No| G[Implement with Modular Subpaths]
-    F --> G
-```
-
-### Discovery Steps:
-
-1. **Confirm Available Components & Blocks**:
-   ```json
-   list_catalog({ "query": "button" })
-   list_catalog({ "category": "component" })
-   ```
-2. **Inspect Component Contract & Props** (`component` parameter):
-   ```json
-   get_component_api({ "component": "button" })
-   get_component_api({ "component": "input" })
-   get_component_api({ "component": "datatable" })
-   get_component_api({ "component": "modal" })
-   ```
-3. **Inspect Curated Documentation** (`id` parameter):
-   ```json
-   get_documentation({ "id": "foundation" })
-   get_documentation({ "id": "button" })
-   get_documentation({ "id": "form" })
-   ```
-4. **Inspect Live Usage & Story Variants**:
-   ```json
-   get_component_examples({ "component": "button", "variant": "Sizes" })
-   get_component_examples({ "component": "datatable", "variant": "CursorPagination" })
-   ```
-5. **Query Knowledge Graph & Symbol Relationships**:
-   ```json
-   query_graph({ "query": "DataTable" })
-   query_graph({ "query": "usePT" })
-   ```
-
----
-
-## 2. Modular Subpath Imports (Mandatory)
-
-Always import via specific subpaths to guarantee tree-shaking and avoid bundling entire packages:
-
-```tsx
-// 1. Core Primitives (@wangs-ui/react-core/primitive/*)
-import Button from '@wangs-ui/react-core/primitive/button';
-import Input from '@wangs-ui/react-core/primitive/input';
-import NumberInput from '@wangs-ui/react-core/primitive/numberinput';
-import Textarea from '@wangs-ui/react-core/primitive/textarea';
-import Select from '@wangs-ui/react-core/primitive/select';
-import MultiSelect from '@wangs-ui/react-core/primitive/multiselect';
-import Checkbox from '@wangs-ui/react-core/primitive/checkbox';
-import Badge from '@wangs-ui/react-core/primitive/badge';
-import Card from '@wangs-ui/react-core/primitive/card';
-import DataTable from '@wangs-ui/react-core/primitive/datatable';
-import Modal from '@wangs-ui/react-core/primitive/modal';
-import Dialog from '@wangs-ui/react-core/primitive/dialog';
-import DialogForm from '@wangs-ui/react-core/primitive/dialogform';
-import { useForm, Form } from '@wangs-ui/react-core/primitive/form';
-import Field from '@wangs-ui/react-core/primitive/field';
-
-// 2. Layout Primitives (@wangs-ui/foundation/layout)
-import {
-  Box,
-  Flex,
-  Stack,
-  HStack,
-  VStack,
-  Grid,
-  Container,
-  Section,
-  Show,
-} from '@wangs-ui/foundation/layout';
-
-// 3. Typography Primitives (@wangs-ui/foundation/theme)
-import { Text, Code, Kbd, Link, Mark, Blockquote, List } from '@wangs-ui/foundation/theme';
-
-// 4. Blocks & Navigation (@wangs-ui/react-core/blocks/*)
-import AppLayout from '@wangs-ui/react-core/blocks/applayout';
-import Sidebar from '@wangs-ui/react-core/blocks/sidebar';
-import TableToolbar from '@wangs-ui/react-core/blocks/tabletoolbar';
-
-// 5. Providers & System Hooks
-import { WangsUiProvider } from '@wangs-ui/react-core/api';
-import { ThemeProvider, useTheme } from '@wangs-ui/foundation/theme';
-import { useI18n } from '@wangs-ui/react-i18n';
-
-// 6. Vector Icons (@wangs-ui/react-icons)
-import { SearchLine, AddLine, DeleteBin6Line, CheckLine } from '@wangs-ui/react-icons';
-```
-
----
-
-## 3. Strict Primitive Substitution Rule
-
-Zero raw HTML elements. Never write raw HTML tags when a Wangs UI primitive exists:
-
-| Forbidden Raw HTML             | Mandatory Wangs UI Primitive                         | Import Path                                  | MCP Doc / Catalog ID    |
-|:-------------------------------|:-----------------------------------------------------|:---------------------------------------------|:------------------------|
-| `<button>`                     | `Button`                                             | `@wangs-ui/react-core/primitive/button`      | `button`                |
-| `<input type="text">`          | `Input`                                              | `@wangs-ui/react-core/primitive/input`       | `input`                 |
-| `<input type="number">`        | `NumberInput`                                        | `@wangs-ui/react-core/primitive/numberinput` | `numberinput`           |
-| `<input type="checkbox">`      | `Checkbox`                                           | `@wangs-ui/react-core/primitive/checkbox`    | `checkbox`              |
-| `<select>`                     | `Select` / `MultiSelect`                             | `@wangs-ui/react-core/primitive/select`      | `select`, `multiselect` |
-| `<textarea>`                   | `Textarea`                                           | `@wangs-ui/react-core/primitive/textarea`    | `textarea`              |
-| `<form>`                       | `Form` / `DialogForm`                                | `@wangs-ui/react-core/primitive/form`        | `form`, `dialogform`    |
-| `<dialog>` / alert modal       | `Modal` / `Dialog`                                   | `@wangs-ui/react-core/primitive/modal`       | `modal`, `dialog`       |
-| `<table>`                      | `DataTable`                                          | `@wangs-ui/react-core/primitive/datatable`   | `datatable`             |
-| `<div>` (layout / flex / grid) | `Stack`, `HStack`, `Flex`, `Grid`, `Box`             | `@wangs-ui/foundation/layout`                | `universal-layout`      |
-| `<div>` (surface card)         | `Card`                                               | `@wangs-ui/react-core/primitive/card`        | `card`                  |
-| Pill / status chip             | `Badge`                                              | `@wangs-ui/react-core/primitive/badge`       | `badge`                 |
-| `<h1>` - `<h6>`                | `<Text variant="headline*">` / `display*` / `title*` | `@wangs-ui/foundation/theme`                 | `foundation`            |
-| `<p>`, `<span>` (body text)    | `<Text variant="body*">` / `label*`                  | `@wangs-ui/foundation/theme`                 | `foundation`            |
-| `<a>`                          | `Link`                                               | `@wangs-ui/foundation/theme`                 | `foundation`            |
-| `<code>`                       | `Code`                                               | `@wangs-ui/foundation/theme`                 | `foundation`            |
-| `<kbd>`                        | `Kbd`                                                | `@wangs-ui/foundation/theme`                 | `foundation`            |
-| `<blockquote>`                 | `Blockquote`                                         | `@wangs-ui/foundation/theme`                 | `foundation`            |
-| `<ul>`, `<ol>`                 | `List`                                               | `@wangs-ui/foundation/theme`                 | `foundation`            |
-
----
-
-## 4. Typography System & `<Text>` Primitive
-
-Wangs UI uses a unified typography token system with standard and emphasized variants. Do **NOT** use arbitrary text utilities (`text-[16px]`, `text-lg`) or obsolete `.heading-*` classes.
-
-### Primary Typography Primitive: `<Text>`
-
-```tsx
-import { Text } from '@wangs-ui/foundation/theme';
-
-// Headings & Displays
-<Text variant="displayMedium">Hero Title</Text>
-<Text variant="headlineLarge">Page Header</Text>
-<Text variant="titleMedium">Card Section Header</Text>
-
-// Body & Labels
-<Text variant="bodyMedium">Standard reading paragraph text.</Text>
-<Text variant="bodySmall" color="secondary">Helper caption text.</Text>
-<Text variant="labelLarge" weight="bold">Interactive button or badge label</Text>
-
-// Polymorphic HTML Tag Override (default maps automatically: display/headline -> h1/h2, body -> p, label -> span)
-<Text variant="titleMedium" as="h3">Custom Tag Title</Text>
-```
-
-### Typography Roles:
-
-- **Display**: Page heroes (`displayLarge`, `displayMedium`, `displaySmall`)
-- **Headline**: Screen and page titles (`headlineLarge`, `headlineMedium`, `headlineSmall`)
-- **Title**: Card and modal section headers (`titleLarge`, `titleMedium`, `titleSmall`)
-- **Body**: Main copy and paragraphs (`bodyLarge`, `bodyMedium`, `bodySmall`)
-- **Label**: Buttons, inputs, and badges (`labelLarge`, `labelMedium`, `labelSmall`)
-- Append `Emphasized` for high-emphasis weights (e.g. `headlineMediumEmphasized`, `titleLargeEmphasized`).
-
----
-
-## 5. Spacing Scale & Theming Invariants
-
-### Flat 4px Spacing Scale
-
-Keys follow the flat numeric Tailwind step (`1` unit `= 4px`):
-`0`, `0.5` (2px), `1` (4px), `1.5` (6px), `2` (8px), `2.5` (10px), `3` (12px), `3.5` (14px), `4` (16px), `5` (20px), `6` (24px), `8` (32px), `10` (40px), `12` (48px), `16` (64px).
-
-- **In Layout Primitives**: Pass keys directly: `<HStack gap="3" p="4">`
-- **In Tailwind Utilities**: Use standard numeric utilities: `p-4`, `gap-3`, `px-6`
-- **In React Native**: Read pixels via `useTheme().spacing`: `spacing[4] === 16`
-
-### Theming & Dark Mode Invariants
-
-- **Theme Provider**: Wrap app root with `<ThemeProvider defaultPalette="blue" defaultMode="light">`.
-- **Engine Invariant**: **NEVER** override `:root`, `[data-mode='dark']`, or `--color-*` variables in custom CSS. Always customize themes via `ThemeProvider` or `WangsUiProvider.configOptions.preset`.
-- **Dark Mode**: Toggle only via `useTheme().setMode('dark' | 'light')` — never mutate `document.documentElement.classList`.
-
----
-
-## 6. Layout Governance & Redundant Wrapper Rule
-
-1. **Use Layout Primitives**: Arrange layouts using `Stack`, `HStack`, `VStack`, `Flex`, `Grid`, and `Box` from `@wangs-ui/foundation/layout`.
-2. **Zero Redundant Wrappers**: Never wrap a single component in an unnecessary `<div>` or `<Box>` (e.g. `<div><DataTable /></div>` or `<Box><Card /></Box>`).
-3. **No Inline Styling Overrides**: Component visual styling lives in global presets. Do not pass ad-hoc utility classes (`className="h-5 w-5"`, `rounded-lg`) directly to primitives or icons unless documented as an MCP exception.