@wangs-ui/skills 1.3.0-alpha.13 → 1.3.0-alpha.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin.js +1 -1
- package/dist/index.js +1 -1
- package/dist/skills/craft-theme/SKILL.md +1 -1
- package/dist/skills/create-form/SKILL.md +11 -9
- package/dist/skills/data-table/SKILL.md +8 -7
- package/dist/skills/dialog-modal/SKILL.md +5 -5
- package/dist/skills/i18n-usage/SKILL.md +7 -7
- package/dist/skills/layout-navigation/SKILL.md +103 -17
- package/dist/skills/responsive-design/SKILL.md +19 -6
- package/dist/skills/universal-layout/SKILL.md +10 -18
- package/dist/skills/wangs-ui-components/SKILL.md +132 -47
- package/dist/{src-DChgYbFi.js → src-ilzo-M7u.js} +9 -9
- package/package.json +1 -1
- package/skills/craft-theme/SKILL.md +1 -1
- package/skills/create-form/SKILL.md +11 -9
- package/skills/data-table/SKILL.md +8 -7
- package/skills/dialog-modal/SKILL.md +5 -5
- package/skills/i18n-usage/SKILL.md +7 -7
- package/skills/layout-navigation/SKILL.md +103 -17
- package/skills/responsive-design/SKILL.md +19 -6
- package/skills/universal-layout/SKILL.md +10 -18
- package/skills/wangs-ui-components/SKILL.md +132 -47
|
@@ -4,9 +4,10 @@ description: Foundational rules, subpath imports, design tokens, and the MCP Dis
|
|
|
4
4
|
metadata:
|
|
5
5
|
owner: wangs-ui
|
|
6
6
|
---
|
|
7
|
+
|
|
7
8
|
# Skill: Wangs UI Component Fundamentals & MCP Protocol
|
|
8
9
|
|
|
9
|
-
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/
|
|
10
|
+
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`).
|
|
10
11
|
|
|
11
12
|
---
|
|
12
13
|
|
|
@@ -16,34 +17,42 @@ Do **NOT** guess component props, Pass-Through (`pt`) slots, or event names. Alw
|
|
|
16
17
|
|
|
17
18
|
```mermaid
|
|
18
19
|
graph TD
|
|
19
|
-
A[Identify Component Needed] --> B[list_catalog to confirm
|
|
20
|
-
B --> C[get_component_api for
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
D
|
|
24
|
-
E
|
|
20
|
+
A[Identify Component / Token Needed] --> B[list_catalog to confirm name/id]
|
|
21
|
+
B --> C[get_component_api for typed contract]
|
|
22
|
+
B --> D[get_documentation for curated guidance]
|
|
23
|
+
C --> E{Need live story / variant code?}
|
|
24
|
+
D --> E
|
|
25
|
+
E -->|Yes| F[get_component_examples]
|
|
26
|
+
E -->|No| G[Implement with Modular Subpaths]
|
|
25
27
|
F --> G
|
|
26
|
-
G --> H[Implement Component with Subpath Imports]
|
|
27
28
|
```
|
|
28
29
|
|
|
29
30
|
### Discovery Steps:
|
|
30
31
|
|
|
31
|
-
1. **
|
|
32
|
+
1. **Confirm Available Components & Blocks**:
|
|
33
|
+
```json
|
|
34
|
+
list_catalog({ "query": "button" })
|
|
35
|
+
list_catalog({ "category": "component" })
|
|
36
|
+
```
|
|
37
|
+
2. **Inspect Component Contract & Props** (`component` parameter):
|
|
32
38
|
```json
|
|
33
|
-
get_component_api({ "
|
|
34
|
-
get_component_api({ "
|
|
35
|
-
get_component_api({ "
|
|
39
|
+
get_component_api({ "component": "button" })
|
|
40
|
+
get_component_api({ "component": "input" })
|
|
41
|
+
get_component_api({ "component": "datatable" })
|
|
42
|
+
get_component_api({ "component": "modal" })
|
|
36
43
|
```
|
|
37
|
-
|
|
44
|
+
3. **Inspect Curated Documentation** (`id` parameter):
|
|
38
45
|
```json
|
|
46
|
+
get_documentation({ "id": "foundation" })
|
|
39
47
|
get_documentation({ "id": "button" })
|
|
48
|
+
get_documentation({ "id": "form" })
|
|
40
49
|
```
|
|
41
|
-
|
|
50
|
+
4. **Inspect Live Usage & Story Variants**:
|
|
42
51
|
```json
|
|
43
52
|
get_component_examples({ "component": "button", "variant": "Sizes" })
|
|
44
53
|
get_component_examples({ "component": "datatable", "variant": "CursorPagination" })
|
|
45
54
|
```
|
|
46
|
-
|
|
55
|
+
5. **Query Knowledge Graph & Symbol Relationships**:
|
|
47
56
|
```json
|
|
48
57
|
query_graph({ "query": "DataTable" })
|
|
49
58
|
query_graph({ "query": "usePT" })
|
|
@@ -51,30 +60,55 @@ graph TD
|
|
|
51
60
|
|
|
52
61
|
---
|
|
53
62
|
|
|
54
|
-
## 2. Subpath
|
|
63
|
+
## 2. Modular Subpath Imports (Mandatory)
|
|
55
64
|
|
|
56
65
|
Always import via specific subpaths to guarantee tree-shaking and avoid bundling entire packages:
|
|
57
66
|
|
|
58
67
|
```tsx
|
|
59
|
-
// Primitives (@wangs-ui/react-core/primitive/*)
|
|
68
|
+
// 1. Core Primitives (@wangs-ui/react-core/primitive/*)
|
|
60
69
|
import Button from '@wangs-ui/react-core/primitive/button';
|
|
61
70
|
import Input from '@wangs-ui/react-core/primitive/input';
|
|
62
71
|
import NumberInput from '@wangs-ui/react-core/primitive/numberinput';
|
|
72
|
+
import Textarea from '@wangs-ui/react-core/primitive/textarea';
|
|
63
73
|
import Select from '@wangs-ui/react-core/primitive/select';
|
|
74
|
+
import MultiSelect from '@wangs-ui/react-core/primitive/multiselect';
|
|
75
|
+
import Checkbox from '@wangs-ui/react-core/primitive/checkbox';
|
|
64
76
|
import Badge from '@wangs-ui/react-core/primitive/badge';
|
|
65
77
|
import Card from '@wangs-ui/react-core/primitive/card';
|
|
66
78
|
import DataTable from '@wangs-ui/react-core/primitive/datatable';
|
|
67
|
-
|
|
68
|
-
|
|
79
|
+
import Modal from '@wangs-ui/react-core/primitive/modal';
|
|
80
|
+
import Dialog from '@wangs-ui/react-core/primitive/dialog';
|
|
81
|
+
import DialogForm from '@wangs-ui/react-core/primitive/dialogform';
|
|
82
|
+
import { useForm, Form } from '@wangs-ui/react-core/primitive/form';
|
|
83
|
+
import Field from '@wangs-ui/react-core/primitive/field';
|
|
84
|
+
|
|
85
|
+
// 2. Layout Primitives (@wangs-ui/foundation/layout)
|
|
86
|
+
import {
|
|
87
|
+
Box,
|
|
88
|
+
Flex,
|
|
89
|
+
Stack,
|
|
90
|
+
HStack,
|
|
91
|
+
VStack,
|
|
92
|
+
Grid,
|
|
93
|
+
Container,
|
|
94
|
+
Section,
|
|
95
|
+
Show,
|
|
96
|
+
} from '@wangs-ui/foundation/layout';
|
|
97
|
+
|
|
98
|
+
// 3. Typography Primitives (@wangs-ui/foundation/theme)
|
|
99
|
+
import { Text, Code, Kbd, Link, Mark, Blockquote, List } from '@wangs-ui/foundation/theme';
|
|
100
|
+
|
|
101
|
+
// 4. Blocks & Navigation (@wangs-ui/react-core/blocks/*)
|
|
69
102
|
import AppLayout from '@wangs-ui/react-core/blocks/applayout';
|
|
70
103
|
import Sidebar from '@wangs-ui/react-core/blocks/sidebar';
|
|
104
|
+
import TableToolbar from '@wangs-ui/react-core/blocks/tabletoolbar';
|
|
71
105
|
|
|
72
|
-
// Providers & System Hooks
|
|
106
|
+
// 5. Providers & System Hooks
|
|
73
107
|
import { WangsUiProvider } from '@wangs-ui/react-core/api';
|
|
108
|
+
import { ThemeProvider, useTheme } from '@wangs-ui/foundation/theme';
|
|
74
109
|
import { useI18n } from '@wangs-ui/react-i18n';
|
|
75
|
-
import { useTheme } from '@wangs-ui/foundation/theme';
|
|
76
110
|
|
|
77
|
-
// Icons (@wangs-ui/react-icons)
|
|
111
|
+
// 6. Vector Icons (@wangs-ui/react-icons)
|
|
78
112
|
import { SearchLine, AddLine, DeleteBin6Line, CheckLine } from '@wangs-ui/react-icons';
|
|
79
113
|
```
|
|
80
114
|
|
|
@@ -82,36 +116,87 @@ import { SearchLine, AddLine, DeleteBin6Line, CheckLine } from '@wangs-ui/react-
|
|
|
82
116
|
|
|
83
117
|
## 3. Strict Primitive Substitution Rule
|
|
84
118
|
|
|
85
|
-
Never write raw HTML
|
|
119
|
+
Zero raw HTML elements. Never write raw HTML tags when a Wangs UI primitive exists:
|
|
120
|
+
|
|
121
|
+
| Forbidden Raw HTML | Mandatory Wangs UI Primitive | Import Path | MCP Doc / Catalog ID |
|
|
122
|
+
|:-------------------------------|:-----------------------------------------------------|:---------------------------------------------|:------------------------|
|
|
123
|
+
| `<button>` | `Button` | `@wangs-ui/react-core/primitive/button` | `button` |
|
|
124
|
+
| `<input type="text">` | `Input` | `@wangs-ui/react-core/primitive/input` | `input` |
|
|
125
|
+
| `<input type="number">` | `NumberInput` | `@wangs-ui/react-core/primitive/numberinput` | `numberinput` |
|
|
126
|
+
| `<input type="checkbox">` | `Checkbox` | `@wangs-ui/react-core/primitive/checkbox` | `checkbox` |
|
|
127
|
+
| `<select>` | `Select` / `MultiSelect` | `@wangs-ui/react-core/primitive/select` | `select`, `multiselect` |
|
|
128
|
+
| `<textarea>` | `Textarea` | `@wangs-ui/react-core/primitive/textarea` | `textarea` |
|
|
129
|
+
| `<form>` | `Form` / `DialogForm` | `@wangs-ui/react-core/primitive/form` | `form`, `dialogform` |
|
|
130
|
+
| `<dialog>` / alert modal | `Modal` / `Dialog` | `@wangs-ui/react-core/primitive/modal` | `modal`, `dialog` |
|
|
131
|
+
| `<table>` | `DataTable` | `@wangs-ui/react-core/primitive/datatable` | `datatable` |
|
|
132
|
+
| `<div>` (layout / flex / grid) | `Stack`, `HStack`, `Flex`, `Grid`, `Box` | `@wangs-ui/foundation/layout` | `universal-layout` |
|
|
133
|
+
| `<div>` (surface card) | `Card` | `@wangs-ui/react-core/primitive/card` | `card` |
|
|
134
|
+
| Pill / status chip | `Badge` | `@wangs-ui/react-core/primitive/badge` | `badge` |
|
|
135
|
+
| `<h1>` - `<h6>` | `<Text variant="headline*">` / `display*` / `title*` | `@wangs-ui/foundation/theme` | `foundation` |
|
|
136
|
+
| `<p>`, `<span>` (body text) | `<Text variant="body*">` / `label*` | `@wangs-ui/foundation/theme` | `foundation` |
|
|
137
|
+
| `<a>` | `Link` | `@wangs-ui/foundation/theme` | `foundation` |
|
|
138
|
+
| `<code>` | `Code` | `@wangs-ui/foundation/theme` | `foundation` |
|
|
139
|
+
| `<kbd>` | `Kbd` | `@wangs-ui/foundation/theme` | `foundation` |
|
|
140
|
+
| `<blockquote>` | `Blockquote` | `@wangs-ui/foundation/theme` | `foundation` |
|
|
141
|
+
| `<ul>`, `<ol>` | `List` | `@wangs-ui/foundation/theme` | `foundation` |
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## 4. Typography System & `<Text>` Primitive
|
|
146
|
+
|
|
147
|
+
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.
|
|
148
|
+
|
|
149
|
+
### Primary Typography Primitive: `<Text>`
|
|
150
|
+
|
|
151
|
+
```tsx
|
|
152
|
+
import { Text } from '@wangs-ui/foundation/theme';
|
|
86
153
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
154
|
+
// Headings & Displays
|
|
155
|
+
<Text variant="displayMedium">Hero Title</Text>
|
|
156
|
+
<Text variant="headlineLarge">Page Header</Text>
|
|
157
|
+
<Text variant="titleMedium">Card Section Header</Text>
|
|
158
|
+
|
|
159
|
+
// Body & Labels
|
|
160
|
+
<Text variant="bodyMedium">Standard reading paragraph text.</Text>
|
|
161
|
+
<Text variant="bodySmall" color="secondary">Helper caption text.</Text>
|
|
162
|
+
<Text variant="labelLarge" weight="bold">Interactive button or badge label</Text>
|
|
163
|
+
|
|
164
|
+
// Polymorphic HTML Tag Override (default maps automatically: display/headline -> h1/h2, body -> p, label -> span)
|
|
165
|
+
<Text variant="titleMedium" as="h3">Custom Tag Title</Text>
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### Typography Roles:
|
|
169
|
+
|
|
170
|
+
- **Display**: Page heroes (`displayLarge`, `displayMedium`, `displaySmall`)
|
|
171
|
+
- **Headline**: Screen and page titles (`headlineLarge`, `headlineMedium`, `headlineSmall`)
|
|
172
|
+
- **Title**: Card and modal section headers (`titleLarge`, `titleMedium`, `titleSmall`)
|
|
173
|
+
- **Body**: Main copy and paragraphs (`bodyLarge`, `bodyMedium`, `bodySmall`)
|
|
174
|
+
- **Label**: Buttons, inputs, and badges (`labelLarge`, `labelMedium`, `labelSmall`)
|
|
175
|
+
- Append `Emphasized` for high-emphasis weights (e.g. `headlineMediumEmphasized`, `titleLargeEmphasized`).
|
|
98
176
|
|
|
99
177
|
---
|
|
100
178
|
|
|
101
|
-
##
|
|
179
|
+
## 5. Spacing Scale & Theming Invariants
|
|
102
180
|
|
|
103
|
-
###
|
|
181
|
+
### Flat 4px Spacing Scale
|
|
104
182
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
-
|
|
109
|
-
-
|
|
110
|
-
-
|
|
183
|
+
Keys follow the flat numeric Tailwind step (`1` unit `= 4px`):
|
|
184
|
+
`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).
|
|
185
|
+
|
|
186
|
+
- **In Layout Primitives**: Pass keys directly: `<HStack gap="3" p="4">`
|
|
187
|
+
- **In Tailwind Utilities**: Use standard numeric utilities: `p-4`, `gap-3`, `px-6`
|
|
188
|
+
- **In React Native**: Read pixels via `useTheme().spacing`: `spacing[4] === 16`
|
|
189
|
+
|
|
190
|
+
### Theming & Dark Mode Invariants
|
|
191
|
+
|
|
192
|
+
- **Theme Provider**: Wrap app root with `<ThemeProvider defaultPalette="blue" defaultMode="light">`.
|
|
193
|
+
- **Engine Invariant**: **NEVER** override `:root`, `[data-mode='dark']`, or `--color-*` variables in custom CSS. Always customize themes via `ThemeProvider` or `WangsUiProvider.configOptions.preset`.
|
|
194
|
+
- **Dark Mode**: Toggle only via `useTheme().setMode('dark' | 'light')` — never mutate `document.documentElement.classList`.
|
|
195
|
+
|
|
196
|
+
---
|
|
111
197
|
|
|
112
|
-
|
|
198
|
+
## 6. Layout Governance & Redundant Wrapper Rule
|
|
113
199
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
- Responsiveness via `ResponsiveValue<T>` size props and `<Show>`, not per-density spacing tokens
|
|
200
|
+
1. **Use Layout Primitives**: Arrange layouts using `Stack`, `HStack`, `VStack`, `Flex`, `Grid`, and `Box` from `@wangs-ui/foundation/layout`.
|
|
201
|
+
2. **Zero Redundant Wrappers**: Never wrap a single component in an unnecessary `<div>` or `<Box>` (e.g. `<div><DataTable /></div>` or `<Box><Card /></Box>`).
|
|
202
|
+
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.
|
|
@@ -4,31 +4,31 @@ import { fileURLToPath } from "node:url";
|
|
|
4
4
|
import os from "node:os";
|
|
5
5
|
import { cancel, intro, isCancel, multiselect, outro } from "@clack/prompts";
|
|
6
6
|
//#region skills/craft-theme/SKILL.md?raw
|
|
7
|
-
var SKILL_default$8 = "---\nname: craft-theme\ndescription: Generate a brand-color theme (13-shade tonal palette +
|
|
7
|
+
var SKILL_default$8 = "---\nname: craft-theme\ndescription: Generate a brand-color theme (13-shade tonal palette + semantic tokens) for a Wangs UI app via the `wangs-ui-generate-palette` CLI — never hand-write hex shade ramps.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Craft Theme\n\nUse this skill whenever the user asks to create, customize, or rebrand the color theme of an app built on `@wangs-ui/react-core` / `@wangs-ui/foundation` — \"make the app's theme orange\", \"use our brand color #ff6b35\", \"add a new palette called sunset\", etc.\n\n## The rule this skill exists to enforce\n\n**Never hand-write a 13-shade tonal ramp, and never hand-pick which shade pairs with which as a text/foreground color.** Wangs UI's own design system shipped with exactly that mistake for a while: hand-tuned palette files drifted from what the perceptual (OKLCH) generator would produce, which caused white text to render at 2.54:1 contrast on one brand's primary color — invisible-adjacent, and only caught by a dedicated audit. The generator and the contrast math it's paired with exist specifically so this class of bug can't happen again. Always reach for the CLI below instead of writing hex values yourself.\n\n## 1. Generate the palette\n\n```bash\nnpx wangs-ui-generate-palette --name=<id> --primary=<#hex> [options] --out=<path>\n```\n\n- `--name` (required): identifier for the palette, e.g. `sunset`. Used for the exported const name (`sunsetPalette`) and, unless `--out` is given, the output filename (`sunset.ts`).\n- `--primary` (required): the brand/key hex color, e.g. `#ff6b35`.\n- Optional per-family overrides — omit any of these to let the generator harmoniously auto-derive it from `--primary` (secondary: boosted-lightness variant of primary's hue; tertiary: +60° hue rotation; general: near-neutral variant of primary's hue) or fall back to the generator's calibrated defaults (success/danger/warning/info):\n `--secondary=#hex --tertiary=#hex --general=#hex --success=#hex --danger=#hex --warning=#hex --info=#hex`\n- `--out=<path>` (optional): where to write the file. Defaults to `./<name>.ts` in the current working directory — always pass an explicit `--out` pointing into the consumer app's own theme directory (e.g. `src/theme/sunset.ts`), don't rely on the default.\n\nIf `@wangs-ui/foundation` isn't already a dependency of the project you're working in, install it first (`pnpm add @wangs-ui/foundation` or the project's equivalent) — the CLI ships as its `bin`.\n\n**The written file is chmod'd read-only (0o444) and headed with an AUTO-GENERATED / DO NOT EDIT BY HAND comment.** If a color needs to change, re-run the command (it clears the read-only bit, rewrites, and re-locks it) — never hand-edit a shade in the output, and never `chmod` it writable to bypass this. Note the read-only bit is a local filesystem attribute only; it is not preserved by git across clones, so it is a deterrent for the person/agent working in this checkout right now, not a hard guarantee for every future contributor.\n\n## 2. Wire it into the app\n\nThe generated file exports a plain `Palette` object — pass it directly to `WangsUiProvider`'s `theme.palette` (or `theme.defaultPalette` for uncontrolled mode):\n\n```tsx\nimport { WangsUiProvider } from '@wangs-ui/react-core/api';\nimport preset from '@wangs-ui/react-presets/fixedasset'; // or whichever preset the app uses\nimport { sunsetPalette } from './theme/sunset';\n\nconst App = () => (\n <WangsUiProvider configOptions={{ preset }} theme={{ palette: sunsetPalette, mode: 'light' }}>\n <YourApp />\n </WangsUiProvider>\n);\n```\n\n`theme.palette` also accepts a built-in palette name (`'blue' | 'emerald' | 'crimson' | 'carbon' | 'gold'`) or a raw hex string — a generated `Palette` object is the right choice once you have brand-specific secondary/tertiary/status colors to preserve, not just a single key color.\n\n## 3. Regenerating / evolving an existing custom palette\n\nTo change a color, re-run the same command with a new hex for the family that changed — **always pass every family you want to keep**, not just the one changing, since each run is a full regeneration from the anchors you give it:\n\n```bash\nnpx wangs-ui-generate-palette --name=sunset --primary=#ff6b35 --tertiary=#2a9d8f --out=src/theme/sunset.ts\n```\n\n## 4. If you're extending Wangs UI itself (contributing a new official palette)\n\nThis is a different, rarer case than theming a consumer app — only relevant if you're working inside the `wangs-ui-react` monorepo itself and adding a 6th built-in palette alongside blue/emerald/crimson/carbon/gold:\n\n1. Run the generator with `--out` pointing at `packages/foundation/theme/tokens/palettes/<name>.ts`.\n2. Register it: add `'<name>'` to the `PaletteName` union and `paletteLoaders` map in `packages/foundation/theme/context/ThemeContext.tsx`, and re-export it from `packages/foundation/theme/tokens/palettes/index.ts`.\n3. Run the contrast regression suite before considering it done: `pnpm exec vitest run --config packages/foundation/vitest.config.ts` — it checks every semantic token pairing (including the new palette) against WCAG AA across both light and dark mode. See `packages/foundation/theme/tokens/COLOR_TOKEN_CONTRACT.md` for the full rule set this is checked against.\n";
|
|
8
8
|
//#endregion
|
|
9
9
|
//#region skills/create-form/SKILL.md?raw
|
|
10
|
-
var SKILL_default$7 = "---\nname: create-form\ndescription: Form architecture, validation workflows, strongly-typed forms (useForm, useDialogForm, useWatchField), initialValues/reset lifecycle, and MCP discovery protocol for building forms and input controls with @wangs-ui/react-core.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Form Architecture & Validation Workflows\n\nUse this skill when building forms, data entry panels, modal forms, settings pages, or multipart forms in Wangs UI applications.\n\n---\n\n## 1. MCP Protocol & Component Rules (Mandatory Single Source of Truth)\n\nDo **NOT** hardcode or guess prop names, component options, preset variations, or Storybook patterns in this document. Always retrieve component definitions, active props, and live Storybook implementations directly via MCP:\n\n### Component & Form API Protocol:\n\n```json\nget_component_api({ \"
|
|
10
|
+
var SKILL_default$7 = "---\nname: create-form\ndescription: Form architecture, validation workflows, strongly-typed forms (useForm, useDialogForm, useWatchField), initialValues/reset lifecycle, and MCP discovery protocol for building forms and input controls with @wangs-ui/react-core.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Form Architecture & Validation Workflows\n\nUse this skill when building forms, data entry panels, modal forms, settings pages, or multipart forms in Wangs UI applications.\n\n---\n\n## 1. MCP Protocol & Component Rules (Mandatory Single Source of Truth)\n\nDo **NOT** hardcode or guess prop names, component options, preset variations, or Storybook patterns in this document. Always retrieve component definitions, active props, and live Storybook implementations directly via MCP:\n\n### Component & Form API Protocol:\n\n```json\nget_component_api({ \"component\": \"form\" })\nget_component_api({ \"component\": \"field\" })\nget_component_api({ \"component\": \"dialogform\" })\nget_component_api({ \"component\": \"input\" })\nget_component_api({ \"component\": \"numberinput\" })\nget_component_api({ \"component\": \"select\" })\nget_component_api({ \"component\": \"multiselect\" })\nget_component_api({ \"component\": \"datepicker\" })\nget_component_api({ \"component\": \"fileupload\" })\n```\n\n### Curated Form Documentation:\n\n```json\nget_documentation({ \"id\": \"form\" })\nget_documentation({ \"id\": \"dialogform\" })\nget_documentation({ \"id\": \"field\" })\n```\n\n### Live Storybook & Interactive Behavior Protocol:\n\n```json\nget_component_examples({ \"component\": \"form\", \"variant\": \"Default\" })\nget_component_examples({ \"component\": \"form\", \"variant\": \"AsyncInitialValues\" })\nget_component_examples({ \"component\": \"form\", \"variant\": \"ConditionalFields\" })\nget_component_examples({ \"component\": \"form\", \"variant\": \"CascadingOptions\" })\nget_component_examples({ \"component\": \"dialogform\", \"variant\": \"Default\" })\n```\n\n### Knowledge Graph & Symbol Usages:\n\n```json\nquery_graph({ \"query\": \"useForm\" })\nquery_graph({ \"query\": \"useDialogForm\" })\nquery_graph({ \"query\": \"useWatchField\" })\n```\n\n---\n\n## 2. Core Form Concepts & Lifecycle Mechanics\n\n### A. Strongly Typed Form Instance (`useForm<TForm>()`)\n\n`useForm<TForm>()` instantiates a `FormControl` natively bound to model type `TForm`.\n\n- `Field`: `name` is strictly typed to `Path<TForm>` dot-paths.\n- `useWatchField`: `name` is strictly typed to `Path<TForm>`.\n- `control`: Provides `setInitialValues`, `setValues`, `setFieldError`, `setErrors`, and `reset`.\n\n### B. Dynamic Initial Values & Baseline Reset (`setInitialValues` vs `setValues`)\n\n1. **Async Initial Values (`control.setInitialValues(values)`)**:\n - Accepts a `Partial<TForm>` JSON object (e.g. fetched from an API).\n - Establishes an **immutable baseline** for registered fields. Once set for a field path, subsequent calls to `setInitialValues` for that path are ignored.\n2. **Batch Value Updates (`control.setValues(values)`)**:\n - Accepts a `Partial<TForm>` JSON object to update current input values without altering the initial baseline.\n3. **Reset Behavior (`control.reset()`)**:\n - Restores all fields back to their registered initial baseline values (set via `setInitialValues` or field `initialValue`) and clears all field-level validation errors.\n\n### C. Primitive Component Integration Architecture\n\n`Field` serves as the form integration wrapper for primitive UI input components (`Input`, `Select`, `MultiSelect`, `DatePicker`, `NumberInput`, `FileUpload`, `Calendar`, etc.):\n\n- **Children Render Callback**: `Field` yields `{ fieldProps, fieldState }`.\n- **`fieldProps`**: Pass directly to primitive inputs (`<Input {...fieldProps} />`). Contains `name`, `value`, `ref`, `onChange`.\n- **`fieldState`**: Provides `invalid`, `error`, `isDirty`, `isPending`. Pass `invalid={fieldState.invalid}` to primitive components for accessibility and validation styling.\n- **⚠️ 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.\n- **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.\n\n---\n\n## 3. High-Level Form Architecture & Usage Patterns\n\n### Pattern 1: Page Forms (`useForm<T>()`)\n\n```tsx\nimport Button from '@wangs-ui/react-core/primitive/button';\nimport { useForm } from '@wangs-ui/react-core/primitive/form';\nimport Input from '@wangs-ui/react-core/primitive/input';\nimport { useI18n } from '@wangs-ui/react-i18n';\nimport { useEffect } from 'react';\n\ninterface UserProfile {\n name: string;\n email: string;\n}\n\nexport function UserProfilePage({ userId }: { userId: string }) {\n const { t } = useI18n();\n const { Form, Field, control } = useForm<UserProfile>();\n\n useEffect(() => {\n async function loadData() {\n const data = await fetchUserData(userId);\n // Establish immutable initial baseline from async response\n control.setInitialValues(data);\n }\n loadData();\n }, [userId, control]);\n\n return (\n <Form control={control} onSubmit={(values) => saveUserData(values)}>\n <Field required label={t('Full Name')} name=\"name\">\n {({ fieldProps, fieldState }) => (\n <Input {...fieldProps} invalid={fieldState.invalid} placeholder={t('Enter full name')} />\n )}\n </Field>\n\n <div className=\"flex gap-2\">\n <Button\n label={t('Reset')}\n type=\"button\"\n variant=\"outlined\"\n onClick={() => control.reset()}\n />\n <Button label={t('Save')} type=\"submit\" />\n </div>\n </Form>\n );\n}\n```\n\n### Pattern 2: Modal Forms (`useDialogForm<T>()`)\n\n```tsx\nimport Button from '@wangs-ui/react-core/primitive/button';\nimport { useDialogForm } from '@wangs-ui/react-core/primitive/dialogform';\nimport Input from '@wangs-ui/react-core/primitive/input';\nimport { useI18n } from '@wangs-ui/react-i18n';\nimport { useState } from 'react';\n\ninterface EditUserForm {\n name: string;\n}\n\nexport function EditUserModal() {\n const { t } = useI18n();\n const [open, setOpen] = useState(false);\n const { DialogForm, Field, control } = useDialogForm<EditUserForm>();\n\n return (\n <>\n <Button label={t('Edit')} onClick={() => setOpen(true)} />\n <DialogForm\n closeOnSubmit\n control={control}\n header={t('Edit User')}\n open={open}\n onOpenChange={setOpen}\n onSubmit={(values) => handleSave(values)}\n >\n <Field required label={t('Full Name')} name=\"name\">\n {({ fieldProps, fieldState }) => <Input {...fieldProps} invalid={fieldState.invalid} />}\n </Field>\n </DialogForm>\n </>\n );\n}\n```\n\n---\n\n## 4. Mandatory Implementation Guidelines\n\n1. **Query MCP First**: Never guess component props or story examples — inspect via MCP tools.\n2. **Granular Primitive Subpaths**: Import primitives via exact subpath modules (`@wangs-ui/react-core/primitive/form`, `@wangs-ui/react-core/primitive/dialogform`, `@wangs-ui/react-core/primitive/input`).\n3. **i18n Localization**: Wrap all user-visible labels, placeholders, and error strings in `t('...')` from `@wangs-ui/react-i18n`.\n4. **Server Error Mapping**: Map HTTP validation errors (e.g. 422 response) into the form using `control.setErrors(apiErrors)`.\n";
|
|
11
11
|
//#endregion
|
|
12
12
|
//#region skills/data-table/SKILL.md?raw
|
|
13
|
-
var SKILL_default$6 = "---\nname: data-table\ndescription: Architecture, workflows, and MCP discovery protocol for building DataTables with sorting, pagination, filtering, selection, and export.\nmetadata:\n owner: wangs-ui\n---\n# Skill: DataTable Architecture & Integration Workflows\n\nUse this skill when implementing data grids, server-paginated tables, filterable listing views, or batch management interfaces with `@wangs-ui/react-core`.\n\n---\n\n## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)\n\nDo **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:\n\n### Inspect Component Contracts:\n\n```json\nget_component_api({ \"
|
|
13
|
+
var SKILL_default$6 = "---\nname: data-table\ndescription: Architecture, workflows, and MCP discovery protocol for building DataTables with sorting, pagination, filtering, selection, and export.\nmetadata:\n owner: wangs-ui\n---\n# Skill: DataTable Architecture & Integration Workflows\n\nUse this skill when implementing data grids, server-paginated tables, filterable listing views, or batch management interfaces with `@wangs-ui/react-core`.\n\n---\n\n## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)\n\nDo **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:\n\n### Inspect Component Contracts (`component` parameter):\n\n```json\nget_component_api({ \"component\": \"datatable\" })\nget_component_api({ \"component\": \"exportbutton\" })\nget_component_api({ \"component\": \"filtercontainer\" })\nget_component_api({ \"component\": \"bulkactionbutton\" })\n```\n\n### Read Curated Documentation:\n\n```json\nget_documentation({ \"id\": \"datatable\" })\nget_documentation({ \"id\": \"exportbutton\" })\n```\n\n### Inspect Live Story Implementations:\n\n```json\nget_component_examples({ \"component\": \"datatable\", \"variant\": \"Basic\" })\nget_component_examples({ \"component\": \"datatable\", \"variant\": \"CursorPagination\" })\nget_component_examples({ \"component\": \"datatable\", \"variant\": \"Sortable\" })\nget_component_examples({ \"component\": \"datatable\", \"variant\": \"MultipleSelection\" })\nget_component_examples({ \"component\": \"datatable\", \"variant\": \"CustomColumn\" })\nget_component_examples({ \"component\": \"exportbutton\", \"variant\": \"WithTable\" })\n```\n\n### Inspect Knowledge Graph & Usages:\n\n```json\nquery_graph({ \"query\": \"DataTable\" })\nquery_graph({ \"query\": \"useDataTableFetch\" })\n```\n\n---\n\n## 2. Core Architecture & Mental Model\n\nThe Wangs UI `DataTable` is built on a modular, headless-first architecture:\n\n1. **Declarative Column Definitions (`TableColumn<T>[]`)**:\n Columns are configured as typed array objects, not as JSX children. Check `get_component_api({ \"component\": \"datatable\" })` for column field types.\n2. **Table Instance Hook (`useDataTable`)**:\n Coordinates table state (sorting, pagination, selection, column ordering, pinning, visibility).\n3. **Data Fetching Hook (`useDataTableFetch`)**:\n Feeds server-side data, handles loading indicators, manages query parameters (`search`, `filter`, `sort`, `page`, `limit`), and debounces requests automatically.\n4. **Ecosystem Companions**:\n - `FilterContainer` & `FilterToggleButton`: Filter popovers and faceted search.\n - `ExportButton`: Client/server export to Excel, CSV, PDF, or Print.\n - `BulkActionButton`: Contextual batch actions triggered when rows are selected.\n - `CustomColumn`: User-controlled column ordering, visibility toggling, and pinning.\n\n---\n\n## 3. Mandatory Implementation Rules\n\n1. **Query MCP for Current Code Patterns**: Always run `get_component_examples` for `datatable` before drafting code.\n2. **Strict Subpath Imports**: Import via `@wangs-ui/react-core/primitive/datatable` and companion primitive paths.\n3. **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`.\n4. **Stable Row Identity**: Always configure a unique key identifier (`dataKey` / `rowId`) for stable selection and row identity.\n5. **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.\n";
|
|
14
14
|
//#endregion
|
|
15
15
|
//#region skills/dialog-modal/SKILL.md?raw
|
|
16
|
-
var SKILL_default$5 = "---\nname: dialog-modal\ndescription: Patterns, overlay selection criteria, and MCP discovery protocol for Dialog, Modal, and DialogForm components in Wangs UI.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Dialog, Modal & Overlay Workflows\n\nUse this skill when building interactive modals, create/edit dialog forms, destructive action confirmations, or slide-in overlay panels.\n\n---\n\n## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)\n\nDo **NOT** guess overlay props, event names, or footer slots. Query the MCP server dynamically to inspect exact contracts and live story implementations:\n\n### Inspect Overlay Contracts:\n\n```json\nget_component_api({ \"
|
|
16
|
+
var SKILL_default$5 = "---\nname: dialog-modal\ndescription: Patterns, overlay selection criteria, and MCP discovery protocol for Dialog, Modal, and DialogForm components in Wangs UI.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Dialog, Modal & Overlay Workflows\n\nUse this skill when building interactive modals, create/edit dialog forms, destructive action confirmations, or slide-in overlay panels.\n\n---\n\n## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)\n\nDo **NOT** guess overlay props, event names, or footer slots. Query the MCP server dynamically to inspect exact contracts and live story implementations:\n\n### Inspect Overlay Contracts (`component` parameter):\n\n```json\nget_component_api({ \"component\": \"dialog\" })\nget_component_api({ \"component\": \"dialogform\" })\nget_component_api({ \"component\": \"modal\" })\nget_component_api({ \"component\": \"toast\" })\n```\n\n### Read Curated Overlay Documentation:\n\n```json\nget_documentation({ \"id\": \"dialog\" })\nget_documentation({ \"id\": \"dialogform\" })\nget_documentation({ \"id\": \"modal\" })\n```\n\n### Inspect Live Story Implementations:\n\n```json\nget_component_examples({ \"component\": \"dialog\", \"variant\": \"RichHeaderFooter\" })\nget_component_examples({ \"component\": \"dialogform\", \"variant\": \"Default\" })\nget_component_examples({ \"component\": \"modal\", \"variant\": \"Default\" })\n```\n\n### Inspect Knowledge Graph & Usages:\n\n```json\nquery_graph({ \"query\": \"Dialog\" })\nquery_graph({ \"query\": \"DialogForm\" })\n```\n\n---\n\n## 2. Overlay Selection Matrix\n\n| Component | Primary Use Case | Key Characteristics |\n| :--------------- | :-------------------------------------------- | :------------------------------------------------------------------------------------ |\n| **`Dialog`** | Confirmations, alerts, simple detail previews | Standard `header`, `footer`, and body layout; built-in backdrop dimming. |\n| **`DialogForm`** | Create/Edit forms embedded inside a dialog | Built-in form submit/cancel action bar, dirty state tracking, and submit lifecycle. |\n| **`Modal`** | Slide-in drawers, complex custom viewports | Headless overlay primitive with flexible animations, size variants, and drawer modes. |\n\n---\n\n## 3. Mandatory Implementation Rules\n\n1. **Query MCP for Current Code Patterns**: Always inspect `dialog`, `dialogform`, or `modal` stories via MCP before writing overlay code.\n2. **Strict Subpath Imports**: Import via `@wangs-ui/react-core/primitive/dialog`, `@wangs-ui/react-core/primitive/dialogform`, `@wangs-ui/react-core/primitive/modal`, or `@wangs-ui/react-core/primitive/toast`.\n3. **Prevent Dismissal During Async Mutations**: Guard the close handler so users cannot accidentally dismiss the dialog while a mutation request is in-flight.\n4. **Coordinate with Toast Notifications**: Trigger feedback toasts on successful creation, update, or deletion actions.\n5. **Translate All Overlay Copy**: All dialog titles, confirmation descriptions, and button labels must be localized using `t('...')` from `@wangs-ui/react-i18n`.\n";
|
|
17
17
|
//#endregion
|
|
18
18
|
//#region skills/i18n-usage/SKILL.md?raw
|
|
19
|
-
var SKILL_default$4 = "---\nname: i18n-usage\ndescription: Comprehensive guidelines for application internationalization, JIT translations (t), ICU formatting, and locale-aware formatting with @wangs-ui/react-i18n.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Application Internationalization & Formatting Protocol\n\nUse this skill when implementing multi-language interfaces, translating user-facing text, formatting dates, times, currencies, or numbers in React applications built with Wangs UI and `@wangs-ui/react-i18n`.\n\n---\n\n## 1. The MCP Discovery Protocol (Single Source of Truth)\n\nDo **NOT** guess component localization contracts, language switcher variants, or datepicker props. Query the MCP server dynamically to inspect exact props and live story implementations:\n\n### Inspect Localized Component Contracts:\n\n```json\nget_component_api({ \"
|
|
19
|
+
var SKILL_default$4 = "---\nname: i18n-usage\ndescription: Comprehensive guidelines for application internationalization, JIT translations (t), ICU formatting, and locale-aware formatting with @wangs-ui/react-i18n.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Application Internationalization & Formatting Protocol\n\nUse this skill when implementing multi-language interfaces, translating user-facing text, formatting dates, times, currencies, or numbers in React applications built with Wangs UI and `@wangs-ui/react-i18n`.\n\n---\n\n## 1. The MCP Discovery Protocol (Single Source of Truth)\n\nDo **NOT** guess component localization contracts, language switcher variants, or datepicker props. Query the MCP server dynamically to inspect exact props and live story implementations:\n\n### Inspect Localized Component Contracts (`component` parameter):\n\n```json\nget_component_api({ \"component\": \"languageswitcher\" })\nget_component_api({ \"component\": \"currencyinput\" })\nget_component_api({ \"component\": \"datepicker\" })\nget_component_api({ \"component\": \"select\" })\nget_component_api({ \"component\": \"datatable\" })\n```\n\n### Read Curated Localization Documentation:\n\n```json\nget_documentation({ \"id\": \"languageswitcher\" })\nget_documentation({ \"id\": \"currencyinput\" })\n```\n\n### Inspect Live Story Implementations:\n\n```json\nget_component_examples({ \"component\": \"languageswitcher\", \"variant\": \"Default\" })\nget_component_examples({ \"component\": \"currencyinput\", \"variant\": \"Default\" })\nget_component_examples({ \"component\": \"datepicker\", \"variant\": \"Default\" })\n```\n\n---\n\n## 2. Root Provider Setup (`WangsUiI18nProvider`)\n\nWrap the application root with `WangsUiI18nProvider` from `@wangs-ui/react-i18n` to enable dynamic JIT translations, versioned cache invalidation, and locale context:\n\n```tsx\nimport { WangsUiI18nProvider } from '@wangs-ui/react-i18n';\nimport React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport App from './App';\n\nReactDOM.createRoot(document.getElementById('root')!).render(\n <React.StrictMode>\n <WangsUiI18nProvider defaultLocale=\"en\" baseUrl={import.meta.env.VITE_API_URL || ''}>\n <App />\n </WangsUiI18nProvider>\n </React.StrictMode>,\n);\n```\n\n---\n\n## 3. Translation Protocol with `useI18n()`\n\nThe `@wangs-ui/react-i18n` package uses a Just-In-Time (JIT) translation architecture where natural English text strings serve as database keys.\n\n### A. Consumer-Level Translation for `ReactNode` Props (Mandatory)\n\nAll user-facing text props in Wangs UI components (`placeholder`, `label`, `emptyMessage`, `header`, `tooltip`, etc.) are typed as `ReactNode` and rendered as-is. Components do **NOT** automatically translate custom strings. Translation **MUST** be called at the application/consumer level:\n\n```tsx\nimport { useI18n } from '@wangs-ui/react-i18n';\nimport Button from '@wangs-ui/react-core/primitive/button';\nimport DataTable from '@wangs-ui/react-core/primitive/datatable';\nimport Select from '@wangs-ui/react-core/primitive/select';\n\nexport function OrderList() {\n const { t } = useI18n();\n\n return (\n <div>\n <Select placeholder={t('Search category...')} />\n <DataTable emptyMessage={t('No orders found')} />\n <Button label={t('Create new order')} />\n </div>\n );\n}\n```\n\n### B. Natural English Sentence Keys\n\nAlways write full, natural English sentences as translation keys. Never use artificial dotted namespace keys:\n\n```tsx\n// ✅ Good — Natural English\nt('Invoice Summary');\nt('Are you sure you want to delete this customer?');\n\n// ❌ Bad — Artificial dotted keys\nt('invoice.summary.title');\nt('dialog.delete.customer.confirm');\n```\n\n### C. Named Variable Interpolation (Single Braces `{var}`)\n\nPass interpolation values inside a plain object using descriptive named variables. This provides crucial semantic context for AI translation engines:\n\n```tsx\n// ✅ Good — Named variables provide context\nt('Upload {count} files to {groupName}', { count: 5, groupName: 'Marketing' });\nt('Welcome back, {userName}!', { userName: user.name });\n\n// ❌ Bad — Concatenation or positional arguments\nt('Welcome back, ' + user.name);\nt('Upload {0} files to {1}', 5, 'Marketing');\n```\n\n### D. ICU Pluralization & Zero-State (`=0`)\n\nAlways handle singular, plural, and zero states directly within ICU MessageFormat strings. Do **NOT** use JavaScript ternary operators:\n\n```tsx\n// ✅ Good — Clean ICU pluralization with zero-state handling\nt('{count, plural, =0 {No items selected} one {1 item selected} other {{count} items selected}}', {\n count: selectedCount,\n});\n\n// ❌ Bad — Manual JS branching\nselectedCount === 0\n ? t('No items selected')\n : selectedCount === 1\n ? t('1 item selected')\n : t('{count} items selected', { count: selectedCount });\n```\n\n### E. Rich Text / Annotated Strings\n\nUse 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:\n\n```tsx\nimport { Link } from '@wangs-ui/foundation/theme';\n\nt('You have selected <b>{count} items</b>. Click <a>here</a> to review.', {\n count: selectedCount,\n a: (chunks) => <Link href=\"/review\">{chunks}</Link>,\n});\n```\n\n---\n\n## 4. Locale Formatting Protocol with `useLocaleFormatter()`\n\nFor locale-aware formatting of dates, relative times, currencies, numbers, and display names, use the dedicated `useLocaleFormatter()` hook. All functions automatically adapt to the active locale without triggering backend database requests:\n\n```tsx\nimport { useLocaleFormatter } from '@wangs-ui/react-i18n';\n\nexport function SummaryCard({ updatedAt, amount, count }: Props) {\n const {\n formatDate,\n formatRelativeTime,\n formatCurrency,\n formatNumber,\n formatDisplayName,\n formatList,\n truncateText,\n } = useLocaleFormatter();\n\n return (\n <div>\n {/* Date formatting with Go tokens or date-fns tokens, and timezone */}\n <p>{formatDate(new Date(), 'dd MMMM yyyy, HH:mm', 'Asia/Jakarta')}</p>\n\n {/* Relative time */}\n <p>{formatRelativeTime(updatedAt)}</p>\n\n {/* Currency formatting */}\n <p>{formatCurrency(amount, 'IDR')}</p>\n\n {/* Number formatting with locale grouping */}\n <p>{formatNumber(count)}</p>\n\n {/* ISO code to localized name */}\n <p>{formatDisplayName('id', 'language')}</p>\n\n {/* Localized list */}\n <p>{formatList(['Finance', 'Operations', 'IT'])}</p>\n\n {/* Emoji & multi-byte safe text truncation */}\n <p>{truncateText('Long product description with emojis 🚀', 20)}</p>\n </div>\n );\n}\n```\n\n> [!NOTE]\n> Formatters MUST NOT be called as standalone `t()` keys (e.g. `t(formatRelativeTime(date))`). Instead, pass the formatted result as a named variable:\n>\n> ```tsx\n> const { t } = useI18n();\n> const { formatRelativeTime } = useLocaleFormatter();\n> const label = t('Updated {time}', { time: formatRelativeTime(updatedAt) });\n> ```\n\n---\n\n## 5. Language Switching UI Integration\n\nConnect the Wangs UI `LanguageSwitcher` primitive directly with `useI18n()` state:\n\n```tsx\nimport LanguageSwitcher from '@wangs-ui/react-core/primitive/languageswitcher';\nimport { useI18n } from '@wangs-ui/react-i18n';\n\nexport function HeaderLanguageSwitcher() {\n const { locale, setLocale, languageOptions } = useI18n();\n\n return (\n <LanguageSwitcher\n options={languageOptions}\n value={locale}\n onChange={(code) => setLocale(code)}\n />\n );\n}\n```\n\n---\n\n## 6. Strict Behavioral Constraints (MUST NOT)\n\n- **NO Formatters Destructured from `useI18n()`:** Formatters are isolated in `useLocaleFormatter()`. Never attempt to import `formatDate` or `formatCurrency` from `useI18n()`.\n- **NO String Concatenation in `t()` Keys:** Never concatenate strings or use dynamic template literals (e.g. `t('Hello ' + user.name)` or ``t(`Hello ${user.name}`)``). This creates infinite distinct keys in the translation database and prevents caching.\n- **NO Manual Zero-State JavaScript Branching:** Always use ICU `=0` syntax inside a single plural key.\n- **NO Dotted Artificial Translation Keys:** Never use dotted keys like `t('app.header.title')`. Use natural English sentences.\n- **NO Custom Markdown Formatting Symbols:** Do not use `*bold*` or `_italic_` in translation keys. Use valid HTML tags like `<b>bold</b>`.\n- **NO Hardcoded Static Translation Dictionaries:** Do not bundle static translation files (`id.json`, `zh.json`). The JIT backend broker manages translations dynamically.\n- **NO Unnecessary English Key Modifications:** Minor typos or punctuation changes in keys create orphaned entries in the translation backend and trigger new AI translation costs.\n";
|
|
20
20
|
//#endregion
|
|
21
21
|
//#region skills/layout-navigation/SKILL.md?raw
|
|
22
|
-
var SKILL_default$3 = "---\nname: layout-navigation\ndescription: Architecture, navigation hierarchies, and MCP discovery protocol for AppLayout, Sidebar, Breadcrumb, and Tabs in Wangs UI.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Application Layout & Navigation Hierarchy\n\nUse this skill when constructing application shells, multi-level sidebars, page headers, breadcrumbs,
|
|
22
|
+
var SKILL_default$3 = "---\nname: layout-navigation\ndescription: Architecture, navigation hierarchies, and MCP discovery protocol for AppLayout, Sidebar, Breadcrumb, and Tabs in Wangs UI.\nmetadata:\n owner: wangs-ui\n---\n\n# Skill: Application Layout & Navigation Hierarchy\n\nUse 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`.\n\n---\n\n## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)\n\nDo **NOT** guess layout block slots, sidebar item interfaces, or breadcrumb props. Query the MCP server dynamically to inspect exact contracts and live story implementations:\n\n### Inspect Layout & Navigation Contracts (`component` parameter):\n\n```json\nget_component_api({ \"component\": \"applayout\" })\nget_component_api({ \"component\": \"sidebar\" })\nget_component_api({ \"component\": \"tabletoolbar\" })\nget_component_api({ \"component\": \"breadcrumb\" })\nget_component_api({ \"component\": \"tabs\" })\n```\n\n\n### Read Curated Layout Documentation (`id` parameter):\n\n```json\nget_documentation({ \"id\": \"applayout\" })\nget_documentation({ \"id\": \"sidebar\" })\nget_documentation({ \"id\": \"react-navigation\" })\n```\n\n### Inspect Live Story Implementations:\n\n```json\nget_component_examples({ \"component\": \"applayout\", \"variant\": \"TopNavbar\" })\nget_component_examples({ \"component\": \"sidebar\", \"variant\": \"WithSubMenu\" })\nget_component_examples({ \"component\": \"breadcrumb\", \"variant\": \"Default\" })\nget_component_examples({ \"component\": \"tabs\", \"variant\": \"Default\" })\n```\n\n### Inspect Knowledge Graph & Usages:\n\n```json\nquery_graph({ \"query\": \"AppLayout\" })\nquery_graph({ \"query\": \"Sidebar\" })\n```\n\n---\n\n## 2. Layout Architecture & Mental Model\n\n1. **Top-Level App Shell (`AppLayout`)**:\n - Subpath: `@wangs-ui/react-core/blocks/applayout`\n - Outer responsive shell arranging navigation, navbar, sidebars, main viewport, and footer. Inspect slots and layout variants via `get_component_api({ \"component\": \"applayout\" })`.\n2. **Hierarchical Menu (`Sidebar`)**:\n - Subpath: `@wangs-ui/react-core/blocks/sidebar`\n - Primary app navigation drawer/rail supporting nested menus, badges, and collapse states. Inspect items and events via `get_component_api({ \"component\": \"sidebar\" })`.\n3. **Breadcrumb Trail (`Breadcrumb`)**:\n - Subpath: `@wangs-ui/react-core/primitive/breadcrumb`\n - Secondary hierarchy navigation displaying screen depth. Inspect item structure via `get_component_api({ \"component\": \"breadcrumb\" })`.\n4. **Tabbed Sub-Views (`Tabs`)**:\n - Subpath: `@wangs-ui/react-core/primitive/tabs`\n - In-page view switcher for partitioning entity details into distinct panels. Inspect via `get_component_api({ \"component\": \"tabs\" })`.\n5. **Universal Routing (`@wangs-ui/react-navigation`)**:\n - Platform-agnostic route graph abstraction (`buildGraph`, `paramRoute`).\n - Web router bridge: `@wangs-ui/react-navigation/web` (React Router).\n - Native router bridge: `@wangs-ui/react-navigation/native` (React Navigation / Expo).\n\n---\n\n## 3. Structural Page Blueprint (Standard Pattern)\n\n```tsx\nimport AppLayout from '@wangs-ui/react-core/blocks/applayout';\nimport Sidebar from '@wangs-ui/react-core/blocks/sidebar';\nimport Breadcrumb from '@wangs-ui/react-core/primitive/breadcrumb';\nimport { Container, Section, Stack, HStack } from '@wangs-ui/foundation/layout';\nimport { Text } from '@wangs-ui/foundation/theme';\nimport { useI18n } from '@wangs-ui/react-i18n';\nimport { HomeLine, Settings4Line } from '@wangs-ui/react-icons';\nimport { useState } from 'react';\n\nexport function ApplicationShell({ children }: { children: React.ReactNode }) {\n const { t } = useI18n();\n const [activeRoute, setActiveRoute] = useState('dashboard');\n const [collapsed, setCollapsed] = useState(false);\n\n const sidebarItems = [\n { value: 'dashboard', label: t('Dashboard'), icon: HomeLine, to: '/' },\n { value: 'settings', label: t('Settings'), icon: Settings4Line, to: '/settings' },\n ];\n\n return (\n <AppLayout\n variant=\"full-sidebar\"\n sidebar={\n <Sidebar\n items={sidebarItems}\n value={activeRoute}\n onValueChange={setActiveRoute}\n collapsed={collapsed}\n onCollapsedChange={setCollapsed}\n collapseMode=\"rail\"\n />\n }\n >\n <Container size=\"xl\">\n <Section space=\"md\">\n <Stack gap=\"4\">\n <Breadcrumb\n items={[\n { label: t('Home'), href: '/' },\n { label: t('Dashboard') },\n ]}\n />\n <Text variant=\"headlineLarge\">{t('Overview')}</Text>\n {children}\n </Stack>\n </Section>\n </Container>\n </AppLayout>\n );\n}\n```\n\n---\n\n## 4. Mandatory Implementation Rules\n\n1. **Query MCP First**: Always inspect `applayout` and `sidebar` stories via MCP before assembling the layout.\n2. **Strict Subpath Imports**:\n - Blocks: `@wangs-ui/react-core/blocks/*` (`applayout`, `sidebar`, `tabletoolbar`)\n - Primitives: `@wangs-ui/react-core/primitive/*` (`breadcrumb`, `tabs`)\n - Layout Primitives: `@wangs-ui/foundation/layout` (`Container`, `Section`, `Stack`, `HStack`, `Box`, `Grid`)\n - Typography: `@wangs-ui/foundation/theme` (`Text`)\n3. **Standard Layout Containers & Spacing**:\n - Use `Container` (max-width rhythm) and `Section` (vertical rhythm) for page boundaries.\n - Use flat numeric Tailwind spacing (`gap=\"4\"`, `p=\"6\"`). Never use legacy named tokens like `p-3xl` or `gap-md`.\n4. **Typography Scale**:\n - Use `<Text variant=\"headlineLarge\">` or `display*` / `title*` for page headers. Never use obsolete `.heading-*` helper classes or raw HTML heading tags without primitives.\n5. **No Redundant Layout Wrappers**:\n - Do NOT insert intermediate pass-through `<div>` or `<Box>` wrappers between `<Card>`/`<Tabs>` and tab contents.\n - Render active tab content directly as a child of the container:\n ```tsx\n // ✅ Good\n <Card>\n <Tabs items={tabItems} value={activeTab} onValueChange={setActiveTab} />\n {activeTab === 'general' ? <GeneralTab /> : <SecurityTab />}\n </Card>\n ```\n6. **Translate Navigation Labels**: Wrap all sidebar item labels, breadcrumb text, and page headings in `t('...')` from `@wangs-ui/react-i18n`.\n";
|
|
23
23
|
//#endregion
|
|
24
24
|
//#region skills/responsive-design/SKILL.md?raw
|
|
25
|
-
var SKILL_default$2 = "---\nname: responsive-design\ndescription: Guidelines for implementing responsive UIs with Wangs UI — covering Breakpoint tiers, responsive props (ResponsiveValue), <Show> conditional rendering, and spacing conventions.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Responsive Design (Consumer Guide)\n\nUse this skill when building responsive pages, layouts, or screen adaptations with Wangs UI components.\n\n---\n\n## 1. Breakpoint Reference\n\nWangs UI uses three standardized breakpoints:\n\n| Breakpoint | Viewport Range | Typical Target |\n| :------------- | :------------- | :------------------------- |\n| **`compact`** | `< 600px` | Mobile phones |\n| **`medium`** | `600–839px` | Tablet portrait |\n| **`expanded`** | `≥ 840px` | Tablet landscape & Desktop |\n\n### Reading the Current Breakpoint in Code\n\n```tsx\nimport { useTheme } from '@wangs-ui/foundation/theme';\n\nconst { breakpoint } = useTheme(); // 'compact' | 'medium' | 'expanded'\n```\n\n---\n\n##
|
|
25
|
+
var SKILL_default$2 = "---\nname: responsive-design\ndescription: Guidelines for implementing responsive UIs with Wangs UI — covering Breakpoint tiers, responsive props (ResponsiveValue), <Show> conditional rendering, and spacing conventions.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Responsive Design (Consumer Guide)\n\nUse this skill when building responsive pages, layouts, or screen adaptations with Wangs UI components.\n\n---\n\n## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)\n\nDo **NOT** guess responsive prop types or breakpoint keys. Query the MCP server dynamically:\n\n```json\nresolve_type_definition({ \"types\": [\"ResponsiveValue\", \"Breakpoint\", \"SpacingKey\"] })\n```\n\n---\n\n## 2. Breakpoint Reference\n\nWangs UI uses three standardized breakpoints:\n\n| Breakpoint | Viewport Range | Typical Target |\n| :------------- | :------------- | :------------------------- |\n| **`compact`** | `< 600px` | Mobile phones |\n| **`medium`** | `600–839px` | Tablet portrait |\n| **`expanded`** | `≥ 840px` | Tablet landscape & Desktop |\n\n### Reading the Current Breakpoint in Code\n\n```tsx\nimport { useTheme } from '@wangs-ui/foundation/theme';\n\nconst { breakpoint } = useTheme(); // 'compact' | 'medium' | 'expanded'\n```\n\n---\n\n## 3. Responsive Props (`ResponsiveValue`)\n\nVisual scale props (`size`, layout `gap`, `columns`, `p`, `m`) accept either a single value or an object mapped by breakpoint:\n\n```tsx\nimport { Button } from '@wangs-ui/react-core/components/button';\nimport { Grid, Stack } from '@wangs-ui/foundation/layout';\n\n// Static (identical across all devices)\n<Button size=\"md\" />\n<Stack gap=\"4\" />\n\n// Adaptive (changes across breakpoints)\n<Button size={{ compact: 'lg', expanded: 'sm' }} />\n<Grid columns={{ compact: 1, medium: 2, expanded: 4 }} />\n```\n\n> **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.\n\n---\n\n## 4. Conditional Rendering (`<Show>`)\n\nUse `<Show>` when a component should be mounted or unmounted based on the active breakpoint:\n\n```tsx\nimport { Show } from '@wangs-ui/foundation/theme';\n\n// Render only on tablet & desktop\n<Show above=\"medium\">\n <SidebarNav />\n</Show>\n\n// Render only on mobile\n<Show below=\"medium\">\n <MobileNavbar />\n</Show>\n\n// Swap component with a fallback\n<Show at=\"compact\" fallback={<DesktopTable />}>\n <MobileCardList />\n</Show>\n```\n\n### When to use `<Show>` vs CSS `hidden`:\n\n- **Use `<Show>`**: If the hidden component has expensive network fetches, subscriptions, or animations (unmounts completely).\n- **Use CSS Tailwind (`hidden md:block`)**: If it's just a visual styling toggle with no side effects.\n\n---\n\n## 5. Spacing Conventions\n\nSpacing tokens are **flat and fixed** (1 unit = 4px):\n\n- **Web**: Use standard Tailwind numeric classes (`gap-2`, `px-4`, `py-3`). **Never** use legacy named classes like `gap-md` or `px-sm`.\n- **Native**: Use `const { spacing } = useTheme();` (`spacing[4]` = 16px).\n\n---\n\n## 6. Anti-Patterns to Avoid\n\n1. **Avoid `hidden md:block` for stateful/heavy trees**: Always prefer `<Show>` so unused components cleanly unmount.\n2. **Never pass responsive objects to behavioral props**: `<Button disabled={{ compact: true }} />` is invalid.\n3. **No manual pixel calculations**: Use Tailwind numeric tokens (`gap-4`, `p-6`) or `ResponsiveValue`.\n";
|
|
26
26
|
//#endregion
|
|
27
27
|
//#region skills/universal-layout/SKILL.md?raw
|
|
28
|
-
var SKILL_default$1 = "---\nname: universal-layout\ndescription: Universal layout primitives (Box, Flex, Stack, Grid, Container, Section) with ResponsiveValue patterns for Web and React Native in Wangs UI.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Universal Layout Primitives\n\nUse this skill when arranging page structure, spacing, or responsive grids with\n`@wangs-ui/foundation/layout`.\nFor app shells (sidebar, breadcrumb, tabs), see the `layout-navigation` skill instead.\n\n---\n\n## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)\n\nDo **NOT** guess layout prop names, spacing scales, or breakpoint keys. Query the MCP\nserver dynamically:\n\n```json\nlist_catalog({ \"
|
|
28
|
+
var SKILL_default$1 = "---\nname: universal-layout\ndescription: Universal layout primitives (Box, Flex, Stack, Grid, Container, Section) with ResponsiveValue patterns for Web and React Native in Wangs UI.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Universal Layout Primitives\n\nUse this skill when arranging page structure, spacing, or responsive grids with\n`@wangs-ui/foundation/layout`.\nFor app shells (sidebar, breadcrumb, tabs), see the `layout-navigation` skill instead.\n\n---\n\n## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)\n\nDo **NOT** guess layout prop names, spacing scales, or breakpoint keys. Query the MCP\nserver dynamically:\n\n```json\nlist_catalog({ \"query\": \"layout\" })\nresolve_type_definition({ \"types\": [\"ResponsiveValue\", \"SpacingKey\", \"StackProps\", \"GridProps\", \"BoxProps\", \"ScrollAreaProps\"] })\n```\n\n---\n\n## 2. Choosing the Right Primitive\n\n1. **Stack (Vertical)** — default for vertical flows (forms, cards, page sections).\n Fixed `column` direction, uniform `gap`, optional auto-`separator`.\n2. **HStack** — horizontal rows with vertical centering (avatar + label + action,\n toolbar clusters). Fixed `row` direction.\n3. **Flex** — only when you need explicit `direction`, `wrap`, `align`, or `justify`\n control beyond what Stack/HStack fix. Prefer Stack/HStack otherwise.\n4. **Grid** — two-dimensional placement or multi-column flows:\n - explicit `columns={{ compact: 1, medium: 2, expanded: 4 }}` for fixed column counts;\n - `minItemWidth` for auto-fit (columns grow/shrink with container width, no media query);\n - `GridItem` with `colSpan` / `rowSpan` for featured tiles.\n5. **Box** — leaf-level spacing/sizing wrapper (`p`, `m`, `radius`, `overflow`), or\n polymorphic `as=\"section\" | \"main\" | \"article\"` for landmarks.\n6. **Container / Section** — page-level rhythm only: `Container` bounds max-width\n (`size`, default `'xl'`) with consistent horizontal padding; `Section` sets\n vertical rhythm (`space: 'sm' | 'md' | 'lg'`, default `'md'`). Never nest\n `Container` inside `Container`.\n7. **ZStack** — overlays (badge on card, status dot on avatar, hero overlay).\n8. **ScrollArea** — styled, accessible scrollable viewports (`orientation: 'vertical' | 'horizontal' | 'both'`, `variant: 'hover' | 'always' | 'scroll'`).\n9. **AspectRatio / Bleed / Spacer** — media frames (`ratio`), full-bleed breakouts\n inside padded containers (`Bleed`), and flexible fillers in stacks (`Spacer`).\n\n---\n\n## 3. Mandatory Implementation Rules\n\n1. **ResponsiveValue everywhere**: scalar for static (`gap=\"4\"`), object for\n adaptive (`gap={{ compact: '2', medium: '4', expanded: '6' }}`,\n `columns={{ compact: 1, medium: 2, expanded: 4 }}`). Breakpoints are\n `compact` (mobile-first base), `medium` (`md:`), `expanded` (`lg:`).\n2. **Separators, not manual dividers**: `<Stack separator={<Divider />}>` inserts\n dividers between children with no trailing element. Never hand-place a divider\n after every child.\n3. **Spacing scale**: `gap`/`p`/`m` use `SpacingKey` (Tailwind numeric scale strings,\n e.g. `'0'`, `'1'`, `'2'`, `'4'`, `'6'`, `'8'`, `'12'`, `'16'`). Never pass raw pixel strings to spacing props.\n4. **Strict subpath imports**:\n ```tsx\n import { Stack, HStack, Grid, Container, Box, Flex, ScrollArea } from '@wangs-ui/foundation/layout';\n ```\n5. **Translate visible labels** inside layout children via `t('...')` from\n `@wangs-ui/react-i18n` (layout props themselves are never translated).\n\n---\n\n## 4. Anti-Patterns (Forbidden)\n\n1. **Gap vs margin**: NEVER hardcode `marginBottom`/`mb-*` on children inside a\n Stack/Flex/Grid to fake spacing — always use the parent's `gap`/`gapX`/`gapY`.\n Margins collapse unpredictably and break `separator` insertion.\n2. **No nested Containers** and no `Container` for non-page content (cards, modals).\n3. **No `Flex` with hardcoded `flexDirection` styles** when `Stack`/`HStack` express it.\n4. **No raw media queries** for `direction`/`gap`/`columns` — use `ResponsiveValue`.\n5. **No `Grid` for one-dimensional lists** — that is `Stack`/`HStack` territory.\n";
|
|
29
29
|
//#endregion
|
|
30
30
|
//#region skills/wangs-ui-components/SKILL.md?raw
|
|
31
|
-
var SKILL_default = "---\nname: wangs-ui-components\ndescription: Foundational rules, subpath imports, design tokens, and the MCP Discovery Protocol for building React apps with Wangs UI.\nmetadata:\n owner: wangs-ui\n---\n# Skill: Wangs UI Component Fundamentals & MCP Protocol\n\nUse 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`).\n\n---\n\n## 1. The MCP Discovery Protocol (Mandatory Single Source of Truth)\n\nDo **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:\n\n```mermaid\ngraph TD\n A[Identify Component Needed] --> B[list_catalog to confirm the id]\n B --> C[get_component_api for the typed contract]\n C --> D{Need live story / variant code?}\n D -->|Yes| E[get_component_examples]\n D -->|No| F[get_documentation for curated guidance]\n E --> G[Check Graphify: query_graph]\n F --> G\n G --> H[Implement Component with Subpath Imports]\n```\n\n### Discovery Steps:\n\n1. **Inspect Component Contract & Props**:\n ```json\n get_component_api({ \"id\": \"button\" })\n get_component_api({ \"id\": \"input\" })\n get_component_api({ \"id\": \"datatable\" })\n ```\n2. **Inspect Curated Documentation**:\n ```json\n get_documentation({ \"id\": \"button\" })\n ```\n3. **Inspect Live Usage & Story Variants**:\n ```json\n get_component_examples({ \"component\": \"button\", \"variant\": \"Sizes\" })\n get_component_examples({ \"component\": \"datatable\", \"variant\": \"CursorPagination\" })\n ```\n4. **Inspect Relationships & Real Usages in Graph**:\n ```json\n query_graph({ \"query\": \"DataTable\" })\n query_graph({ \"query\": \"usePT\" })\n ```\n\n---\n\n## 2. Subpath Modular Imports (Mandatory)\n\nAlways import via specific subpaths to guarantee tree-shaking and avoid bundling entire packages:\n\n```tsx\n// Primitives (@wangs-ui/react-core/primitive/*)\nimport Button from '@wangs-ui/react-core/primitive/button';\nimport Input from '@wangs-ui/react-core/primitive/input';\nimport NumberInput from '@wangs-ui/react-core/primitive/numberinput';\nimport Select from '@wangs-ui/react-core/primitive/select';\nimport Badge from '@wangs-ui/react-core/primitive/badge';\nimport Card from '@wangs-ui/react-core/primitive/card';\nimport DataTable from '@wangs-ui/react-core/primitive/datatable';\n\n// Blocks (@wangs-ui/react-core/blocks/*)\nimport AppLayout from '@wangs-ui/react-core/blocks/applayout';\nimport Sidebar from '@wangs-ui/react-core/blocks/sidebar';\n\n// Providers & System Hooks\nimport { WangsUiProvider } from '@wangs-ui/react-core/api';\nimport { useI18n } from '@wangs-ui/react-i18n';\nimport { useTheme } from '@wangs-ui/foundation/theme';\n\n// Icons (@wangs-ui/react-icons)\nimport { SearchLine, AddLine, DeleteBin6Line, CheckLine } from '@wangs-ui/react-icons';\n```\n\n---\n\n## 3. Strict Primitive Substitution Rule\n\nNever write raw HTML elements when a Wangs UI primitive exists:\n\n| Forbidden Raw HTML | Mandatory Wangs UI Component | Subpath Import | MCP Documentation ID |\n| :------------------------ | :--------------------------- | :------------------------------------------- | :------------------- |\n| `<button>` | `Button` | `@wangs-ui/react-core/primitive/button` | `button` |\n| `<input type=\"text\">` | `Input` | `@wangs-ui/react-core/primitive/input` | `input` |\n| `<input type=\"number\">` | `NumberInput` | `@wangs-ui/react-core/primitive/numberinput` | `numberinput` |\n| `<input type=\"checkbox\">` | `Checkbox` | `@wangs-ui/react-core/primitive/checkbox` | `checkbox` |\n| `<select>` | `Select` | `@wangs-ui/react-core/primitive/select` | `select` |\n| `<dialog>` / modal | `Dialog` / `Modal` | `@wangs-ui/react-core/primitive/dialog` | `dialog`, `modal` |\n| `<table>` | `DataTable` | `@wangs-ui/react-core/primitive/datatable` | `datatable` |\n| Container box | `Card` | `@wangs-ui/react-core/primitive/card` | `card` |\n| Pill badge / status | `Badge` | `@wangs-ui/react-core/primitive/badge` | `badge` |\n\n---\n\n## 4. Typography Scale & 4px Spacing Tokens\n\n### Typography Helper Classes\n\n- `.heading-1` — Page title (22px, 600)\n- `.heading-2` — Section / Card title (18px, 600)\n- `.heading-3` — Sub-header (16px, 500)\n- `.heading-4` — Field label (14px, 500)\n- `.heading-5` — Small group header (12px, 600)\n- `.p` — Body copy (12px, 500)\n\n### Spacing Tokens\n\n- 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)\n- Web: use numeric utilities directly — Gap: `gap-4`, Padding: `px-4 py-1.5`\n- Native: read pixel values via `useTheme().spacing` (e.g. `spacing[4] === 16`)\n- Responsiveness via `ResponsiveValue<T>` size props and `<Show>`, not per-density spacing tokens\n";
|
|
31
|
+
var SKILL_default = "---\nname: wangs-ui-components\ndescription: Foundational rules, subpath imports, design tokens, and the MCP Discovery Protocol for building React apps with Wangs UI.\nmetadata:\n owner: wangs-ui\n---\n\n# Skill: Wangs UI Component Fundamentals & MCP Protocol\n\nUse 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`).\n\n---\n\n## 1. The MCP Discovery Protocol (Mandatory Single Source of Truth)\n\nDo **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:\n\n```mermaid\ngraph TD\n A[Identify Component / Token Needed] --> B[list_catalog to confirm name/id]\n B --> C[get_component_api for typed contract]\n B --> D[get_documentation for curated guidance]\n C --> E{Need live story / variant code?}\n D --> E\n E -->|Yes| F[get_component_examples]\n E -->|No| G[Implement with Modular Subpaths]\n F --> G\n```\n\n### Discovery Steps:\n\n1. **Confirm Available Components & Blocks**:\n ```json\n list_catalog({ \"query\": \"button\" })\n list_catalog({ \"category\": \"component\" })\n ```\n2. **Inspect Component Contract & Props** (`component` parameter):\n ```json\n get_component_api({ \"component\": \"button\" })\n get_component_api({ \"component\": \"input\" })\n get_component_api({ \"component\": \"datatable\" })\n get_component_api({ \"component\": \"modal\" })\n ```\n3. **Inspect Curated Documentation** (`id` parameter):\n ```json\n get_documentation({ \"id\": \"foundation\" })\n get_documentation({ \"id\": \"button\" })\n get_documentation({ \"id\": \"form\" })\n ```\n4. **Inspect Live Usage & Story Variants**:\n ```json\n get_component_examples({ \"component\": \"button\", \"variant\": \"Sizes\" })\n get_component_examples({ \"component\": \"datatable\", \"variant\": \"CursorPagination\" })\n ```\n5. **Query Knowledge Graph & Symbol Relationships**:\n ```json\n query_graph({ \"query\": \"DataTable\" })\n query_graph({ \"query\": \"usePT\" })\n ```\n\n---\n\n## 2. Modular Subpath Imports (Mandatory)\n\nAlways import via specific subpaths to guarantee tree-shaking and avoid bundling entire packages:\n\n```tsx\n// 1. Core Primitives (@wangs-ui/react-core/primitive/*)\nimport Button from '@wangs-ui/react-core/primitive/button';\nimport Input from '@wangs-ui/react-core/primitive/input';\nimport NumberInput from '@wangs-ui/react-core/primitive/numberinput';\nimport Textarea from '@wangs-ui/react-core/primitive/textarea';\nimport Select from '@wangs-ui/react-core/primitive/select';\nimport MultiSelect from '@wangs-ui/react-core/primitive/multiselect';\nimport Checkbox from '@wangs-ui/react-core/primitive/checkbox';\nimport Badge from '@wangs-ui/react-core/primitive/badge';\nimport Card from '@wangs-ui/react-core/primitive/card';\nimport DataTable from '@wangs-ui/react-core/primitive/datatable';\nimport Modal from '@wangs-ui/react-core/primitive/modal';\nimport Dialog from '@wangs-ui/react-core/primitive/dialog';\nimport DialogForm from '@wangs-ui/react-core/primitive/dialogform';\nimport { useForm, Form } from '@wangs-ui/react-core/primitive/form';\nimport Field from '@wangs-ui/react-core/primitive/field';\n\n// 2. Layout Primitives (@wangs-ui/foundation/layout)\nimport {\n Box,\n Flex,\n Stack,\n HStack,\n VStack,\n Grid,\n Container,\n Section,\n Show,\n} from '@wangs-ui/foundation/layout';\n\n// 3. Typography Primitives (@wangs-ui/foundation/theme)\nimport { Text, Code, Kbd, Link, Mark, Blockquote, List } from '@wangs-ui/foundation/theme';\n\n// 4. Blocks & Navigation (@wangs-ui/react-core/blocks/*)\nimport AppLayout from '@wangs-ui/react-core/blocks/applayout';\nimport Sidebar from '@wangs-ui/react-core/blocks/sidebar';\nimport TableToolbar from '@wangs-ui/react-core/blocks/tabletoolbar';\n\n// 5. Providers & System Hooks\nimport { WangsUiProvider } from '@wangs-ui/react-core/api';\nimport { ThemeProvider, useTheme } from '@wangs-ui/foundation/theme';\nimport { useI18n } from '@wangs-ui/react-i18n';\n\n// 6. Vector Icons (@wangs-ui/react-icons)\nimport { SearchLine, AddLine, DeleteBin6Line, CheckLine } from '@wangs-ui/react-icons';\n```\n\n---\n\n## 3. Strict Primitive Substitution Rule\n\nZero raw HTML elements. Never write raw HTML tags when a Wangs UI primitive exists:\n\n| Forbidden Raw HTML | Mandatory Wangs UI Primitive | Import Path | MCP Doc / Catalog ID |\n|:-------------------------------|:-----------------------------------------------------|:---------------------------------------------|:------------------------|\n| `<button>` | `Button` | `@wangs-ui/react-core/primitive/button` | `button` |\n| `<input type=\"text\">` | `Input` | `@wangs-ui/react-core/primitive/input` | `input` |\n| `<input type=\"number\">` | `NumberInput` | `@wangs-ui/react-core/primitive/numberinput` | `numberinput` |\n| `<input type=\"checkbox\">` | `Checkbox` | `@wangs-ui/react-core/primitive/checkbox` | `checkbox` |\n| `<select>` | `Select` / `MultiSelect` | `@wangs-ui/react-core/primitive/select` | `select`, `multiselect` |\n| `<textarea>` | `Textarea` | `@wangs-ui/react-core/primitive/textarea` | `textarea` |\n| `<form>` | `Form` / `DialogForm` | `@wangs-ui/react-core/primitive/form` | `form`, `dialogform` |\n| `<dialog>` / alert modal | `Modal` / `Dialog` | `@wangs-ui/react-core/primitive/modal` | `modal`, `dialog` |\n| `<table>` | `DataTable` | `@wangs-ui/react-core/primitive/datatable` | `datatable` |\n| `<div>` (layout / flex / grid) | `Stack`, `HStack`, `Flex`, `Grid`, `Box` | `@wangs-ui/foundation/layout` | `universal-layout` |\n| `<div>` (surface card) | `Card` | `@wangs-ui/react-core/primitive/card` | `card` |\n| Pill / status chip | `Badge` | `@wangs-ui/react-core/primitive/badge` | `badge` |\n| `<h1>` - `<h6>` | `<Text variant=\"headline*\">` / `display*` / `title*` | `@wangs-ui/foundation/theme` | `foundation` |\n| `<p>`, `<span>` (body text) | `<Text variant=\"body*\">` / `label*` | `@wangs-ui/foundation/theme` | `foundation` |\n| `<a>` | `Link` | `@wangs-ui/foundation/theme` | `foundation` |\n| `<code>` | `Code` | `@wangs-ui/foundation/theme` | `foundation` |\n| `<kbd>` | `Kbd` | `@wangs-ui/foundation/theme` | `foundation` |\n| `<blockquote>` | `Blockquote` | `@wangs-ui/foundation/theme` | `foundation` |\n| `<ul>`, `<ol>` | `List` | `@wangs-ui/foundation/theme` | `foundation` |\n\n---\n\n## 4. Typography System & `<Text>` Primitive\n\nWangs 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.\n\n### Primary Typography Primitive: `<Text>`\n\n```tsx\nimport { Text } from '@wangs-ui/foundation/theme';\n\n// Headings & Displays\n<Text variant=\"displayMedium\">Hero Title</Text>\n<Text variant=\"headlineLarge\">Page Header</Text>\n<Text variant=\"titleMedium\">Card Section Header</Text>\n\n// Body & Labels\n<Text variant=\"bodyMedium\">Standard reading paragraph text.</Text>\n<Text variant=\"bodySmall\" color=\"secondary\">Helper caption text.</Text>\n<Text variant=\"labelLarge\" weight=\"bold\">Interactive button or badge label</Text>\n\n// Polymorphic HTML Tag Override (default maps automatically: display/headline -> h1/h2, body -> p, label -> span)\n<Text variant=\"titleMedium\" as=\"h3\">Custom Tag Title</Text>\n```\n\n### Typography Roles:\n\n- **Display**: Page heroes (`displayLarge`, `displayMedium`, `displaySmall`)\n- **Headline**: Screen and page titles (`headlineLarge`, `headlineMedium`, `headlineSmall`)\n- **Title**: Card and modal section headers (`titleLarge`, `titleMedium`, `titleSmall`)\n- **Body**: Main copy and paragraphs (`bodyLarge`, `bodyMedium`, `bodySmall`)\n- **Label**: Buttons, inputs, and badges (`labelLarge`, `labelMedium`, `labelSmall`)\n- Append `Emphasized` for high-emphasis weights (e.g. `headlineMediumEmphasized`, `titleLargeEmphasized`).\n\n---\n\n## 5. Spacing Scale & Theming Invariants\n\n### Flat 4px Spacing Scale\n\nKeys follow the flat numeric Tailwind step (`1` unit `= 4px`):\n`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).\n\n- **In Layout Primitives**: Pass keys directly: `<HStack gap=\"3\" p=\"4\">`\n- **In Tailwind Utilities**: Use standard numeric utilities: `p-4`, `gap-3`, `px-6`\n- **In React Native**: Read pixels via `useTheme().spacing`: `spacing[4] === 16`\n\n### Theming & Dark Mode Invariants\n\n- **Theme Provider**: Wrap app root with `<ThemeProvider defaultPalette=\"blue\" defaultMode=\"light\">`.\n- **Engine Invariant**: **NEVER** override `:root`, `[data-mode='dark']`, or `--color-*` variables in custom CSS. Always customize themes via `ThemeProvider` or `WangsUiProvider.configOptions.preset`.\n- **Dark Mode**: Toggle only via `useTheme().setMode('dark' | 'light')` — never mutate `document.documentElement.classList`.\n\n---\n\n## 6. Layout Governance & Redundant Wrapper Rule\n\n1. **Use Layout Primitives**: Arrange layouts using `Stack`, `HStack`, `VStack`, `Flex`, `Grid`, and `Box` from `@wangs-ui/foundation/layout`.\n2. **Zero Redundant Wrappers**: Never wrap a single component in an unnecessary `<div>` or `<Box>` (e.g. `<div><DataTable /></div>` or `<Box><Card /></Box>`).\n3. **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.\n";
|
|
32
32
|
//#endregion
|
|
33
33
|
//#region rules/react19-checklist-and-reference.md?raw
|
|
34
34
|
var react19_checklist_and_reference_default = "---\ntrigger: model_decision\ndescription: \"Apply when doing a final review pass on React 19 component or hook code for compiler-optimization compliance.\"\nowner: wangs-ui\nmetadata:\n owner: wangs-ui\n---\n# Rule: React 19 — Review Checklist & Quick Reference\n\n## Checking Compiler Optimization\n\n- **React DevTools** — an optimized component shows a \"Memo ✨\" badge next to its name in the component tree.\n- **ESLint / Oxlint** — compiler's recommended rules flag Rules-of-React violations at lint time.\n\n## Review Checklist\n\n- [ ] Compiler confirmed active (\"Memo ✨\" badge) before removing any _existing_ manual memoization\n- [ ] No new `useMemo`/`useCallback`/`React.memo` added without documented reason (confirmed bail-out, or external boundary)\n- [ ] No prop/state/context mutation anywhere in render\n- [ ] All hooks called unconditionally at top level, same order every render\n- [ ] Side effects live in `useEffect`/event handlers, never during render\n- [ ] Components are `PascalCase`; hooks are `camelCase` and prefixed `use`\n- [ ] `ref` accepted as normal prop instead of `forwardRef`\n- [ ] Action/optimistic-update state modeled as discriminated union, not optional fields\n- [ ] Mutually exclusive prop combinations modeled as discriminated union `Props` type\n- [ ] Any `\"use no memo\"` usage has a comment explaining why\n\n## Quick Reference\n\n| Situation | Do |\n| ----------------------------------------------------------- | ------------------------------------------------------------- |\n| Tempted to write `useMemo`/`useCallback` | Don't — write plain expression, let compiler decide |\n| Need a ref on a function component | Accept `ref` as a prop, skip `forwardRef` |\n| Form/async state with distinct outcomes | Discriminated union via `useActionState`, not optional fields |\n| Callback needs latest props/state without re-running effect | `useEffectEvent` |\n| A hook/library is known-incompatible with compiler | `\"use no memo\"` at top of that function, with comment |\n| Checking if optimization is happening | React DevTools \"Memo ✨\" badge + compiler lint rules |\n";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: craft-theme
|
|
3
|
-
description: Generate a brand-color theme (13-shade tonal palette +
|
|
3
|
+
description: Generate a brand-color theme (13-shade tonal palette + semantic tokens) for a Wangs UI app via the `wangs-ui-generate-palette` CLI — never hand-write hex shade ramps.
|
|
4
4
|
metadata:
|
|
5
5
|
owner: wangs-ui
|
|
6
6
|
---
|
|
@@ -17,15 +17,15 @@ Do **NOT** hardcode or guess prop names, component options, preset variations, o
|
|
|
17
17
|
### Component & Form API Protocol:
|
|
18
18
|
|
|
19
19
|
```json
|
|
20
|
-
get_component_api({ "
|
|
21
|
-
get_component_api({ "
|
|
22
|
-
get_component_api({ "
|
|
23
|
-
get_component_api({ "
|
|
24
|
-
get_component_api({ "
|
|
25
|
-
get_component_api({ "
|
|
26
|
-
get_component_api({ "
|
|
27
|
-
get_component_api({ "
|
|
28
|
-
get_component_api({ "
|
|
20
|
+
get_component_api({ "component": "form" })
|
|
21
|
+
get_component_api({ "component": "field" })
|
|
22
|
+
get_component_api({ "component": "dialogform" })
|
|
23
|
+
get_component_api({ "component": "input" })
|
|
24
|
+
get_component_api({ "component": "numberinput" })
|
|
25
|
+
get_component_api({ "component": "select" })
|
|
26
|
+
get_component_api({ "component": "multiselect" })
|
|
27
|
+
get_component_api({ "component": "datepicker" })
|
|
28
|
+
get_component_api({ "component": "fileupload" })
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
### Curated Form Documentation:
|
|
@@ -83,6 +83,8 @@ query_graph({ "query": "useWatchField" })
|
|
|
83
83
|
- **Children Render Callback**: `Field` yields `{ fieldProps, fieldState }`.
|
|
84
84
|
- **`fieldProps`**: Pass directly to primitive inputs (`<Input {...fieldProps} />`). Contains `name`, `value`, `ref`, `onChange`.
|
|
85
85
|
- **`fieldState`**: Provides `invalid`, `error`, `isDirty`, `isPending`. Pass `invalid={fieldState.invalid}` to primitive components for accessibility and validation styling.
|
|
86
|
+
- **⚠️ 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.
|
|
87
|
+
- **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.
|
|
86
88
|
|
|
87
89
|
---
|
|
88
90
|
|