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

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).

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

@@ -4,9 +4,10 @@ description: Foundational rules, subpath imports, design tokens, and the MCP Dis
 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/react-icons`, `@wangs-ui/react-presets`, `@wangs-ui/foundation`).
+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`).
 
 ---
 
@@ -16,34 +17,42 @@ Do **NOT** guess component props, Pass-Through (`pt`) slots, or event names. Alw
 
 ```mermaid
 graph TD
-    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]
+    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
-    G --> H[Implement Component with Subpath Imports]
 ```
 
 ### Discovery Steps:
 
-1. **Inspect Component Contract & Props**:
+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({ "id": "button" })
-   get_component_api({ "id": "input" })
-   get_component_api({ "id": "datatable" })
+   get_component_api({ "component": "button" })
+   get_component_api({ "component": "input" })
+   get_component_api({ "component": "datatable" })
+   get_component_api({ "component": "modal" })
    ```
-2. **Inspect Curated Documentation**:
+3. **Inspect Curated Documentation** (`id` parameter):
    ```json
+   get_documentation({ "id": "foundation" })
    get_documentation({ "id": "button" })
+   get_documentation({ "id": "form" })
    ```
-3. **Inspect Live Usage & Story Variants**:
+4. **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**:
+5. **Query Knowledge Graph & Symbol Relationships**:
    ```json
    query_graph({ "query": "DataTable" })
    query_graph({ "query": "usePT" })
@@ -51,30 +60,55 @@ graph TD
 
 ---
 
-## 2. Subpath Modular Imports (Mandatory)
+## 2. Modular Subpath Imports (Mandatory)
 
 Always import via specific subpaths to guarantee tree-shaking and avoid bundling entire packages:
 
 ```tsx
-// Primitives (@wangs-ui/react-core/primitive/*)
+// 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';
-
-// Blocks (@wangs-ui/react-core/blocks/*)
+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';
 
-// Providers & System Hooks
+// 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';
-import { useTheme } from '@wangs-ui/foundation/theme';
 
-// Icons (@wangs-ui/react-icons)
+// 6. Vector Icons (@wangs-ui/react-icons)
 import { SearchLine, AddLine, DeleteBin6Line, CheckLine } from '@wangs-ui/react-icons';
 ```
 
@@ -82,36 +116,87 @@ import { SearchLine, AddLine, DeleteBin6Line, CheckLine } from '@wangs-ui/react-
 
 ## 3. Strict Primitive Substitution Rule
 
-Never write raw HTML elements when a Wangs UI primitive exists:
+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';
 
-| Forbidden Raw HTML        | Mandatory Wangs UI Component | Subpath Import                               | MCP Documentation 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`                     | `@wangs-ui/react-core/primitive/select`      | `select`             |
-| `<dialog>` / modal        | `Dialog` / `Modal`           | `@wangs-ui/react-core/primitive/dialog`      | `dialog`, `modal`    |
-| `<table>`                 | `DataTable`                  | `@wangs-ui/react-core/primitive/datatable`   | `datatable`          |
-| Container box             | `Card`                       | `@wangs-ui/react-core/primitive/card`        | `card`               |
-| Pill badge / status       | `Badge`                      | `@wangs-ui/react-core/primitive/badge`       | `badge`              |
+// 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`).
 
 ---
 
-## 4. Typography Scale & 4px Spacing Tokens
+## 5. Spacing Scale & Theming Invariants
 
-### Typography Helper Classes
+### Flat 4px Spacing Scale
 
-- `.heading-1` — Page title (22px, 600)
-- `.heading-2` — Section / Card title (18px, 600)
-- `.heading-3` — Sub-header (16px, 500)
-- `.heading-4` — Field label (14px, 500)
-- `.heading-5` — Small group header (12px, 600)
-- `.p` — Body copy (12px, 500)
+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`.
+
+---
 
-### Spacing Tokens
+## 6. Layout Governance & Redundant Wrapper Rule
 
-- 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
+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.