@wangs-ui/skills 1.3.0-alpha.12 → 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.
Files changed (22) hide show
  1. package/dist/bin.js +2 -2
  2. package/dist/index.js +1 -1
  3. package/dist/skills/craft-theme/SKILL.md +1 -1
  4. package/dist/skills/create-form/SKILL.md +11 -9
  5. package/dist/skills/data-table/SKILL.md +8 -7
  6. package/dist/skills/dialog-modal/SKILL.md +5 -5
  7. package/dist/skills/i18n-usage/SKILL.md +7 -7
  8. package/dist/skills/layout-navigation/SKILL.md +103 -17
  9. package/dist/skills/responsive-design/SKILL.md +19 -6
  10. package/dist/skills/universal-layout/SKILL.md +10 -18
  11. package/dist/skills/wangs-ui-components/SKILL.md +132 -47
  12. package/dist/{src-DwQOnl9b.js → src-ilzo-M7u.js} +10 -10
  13. package/package.json +1 -1
  14. package/skills/craft-theme/SKILL.md +1 -1
  15. package/skills/create-form/SKILL.md +11 -9
  16. package/skills/data-table/SKILL.md +8 -7
  17. package/skills/dialog-modal/SKILL.md +5 -5
  18. package/skills/i18n-usage/SKILL.md +7 -7
  19. package/skills/layout-navigation/SKILL.md +103 -17
  20. package/skills/responsive-design/SKILL.md +19 -6
  21. package/skills/universal-layout/SKILL.md +10 -18
  22. package/skills/wangs-ui-components/SKILL.md +132 -47
package/skills/wangs-ui-components/SKILL.md CHANGED
@@ -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/foundation`).
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 the id]
20
- B --> C[get_component_api for the typed contract]
21
- C --> D{Need live story / variant code?}
22
- D -->|Yes| E[get_component_examples]
23
- D -->|No| F[get_documentation for curated guidance]
24
- E --> G[Check Graphify: query_graph]
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. **Inspect Component Contract & Props**:
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({ "id": "button" })
34
- get_component_api({ "id": "input" })
35
- get_component_api({ "id": "datatable" })
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
- 2. **Inspect Curated Documentation**:
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
- 3. **Inspect Live Usage & Story Variants**:
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
- 4. **Inspect Relationships & Real Usages in Graph**:
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 Modular Imports (Mandatory)
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
- // Blocks (@wangs-ui/react-core/blocks/*)
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 elements when a Wangs UI primitive exists:
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
- | Forbidden Raw HTML | Mandatory Wangs UI Component | Subpath Import | MCP Documentation ID |
88
- | :------------------------ | :--------------------------- | :------------------------------------------- | :------------------- |
89
- | `<button>` | `Button` | `@wangs-ui/react-core/primitive/button` | `button` |
90
- | `<input type="text">` | `Input` | `@wangs-ui/react-core/primitive/input` | `input` |
91
- | `<input type="number">` | `NumberInput` | `@wangs-ui/react-core/primitive/numberinput` | `numberinput` |
92
- | `<input type="checkbox">` | `Checkbox` | `@wangs-ui/react-core/primitive/checkbox` | `checkbox` |
93
- | `<select>` | `Select` | `@wangs-ui/react-core/primitive/select` | `select` |
94
- | `<dialog>` / modal | `Dialog` / `Modal` | `@wangs-ui/react-core/primitive/dialog` | `dialog`, `modal` |
95
- | `<table>` | `DataTable` | `@wangs-ui/react-core/primitive/datatable` | `datatable` |
96
- | Container box | `Card` | `@wangs-ui/react-core/primitive/card` | `card` |
97
- | Pill badge / status | `Badge` | `@wangs-ui/react-core/primitive/badge` | `badge` |
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
- ## 4. Typography Scale & 4px Spacing Tokens
179
+ ## 5. Spacing Scale & Theming Invariants
102
180
 
103
- ### Typography Helper Classes
181
+ ### Flat 4px Spacing Scale
104
182
 
105
- - `.heading-1` — Page title (22px, 600)
106
- - `.heading-2` — Section / Card title (18px, 600)
107
- - `.heading-3` — Sub-header (16px, 500)
108
- - `.heading-4` — Field label (14px, 500)
109
- - `.heading-5` — Small group header (12px, 600)
110
- - `.p` — Body copy (12px, 500)
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
- ### Spacing Tokens
198
+ ## 6. Layout Governance & Redundant Wrapper Rule
113
199
 
114
- - 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)
115
- - Web: use numeric utilities directly — Gap: `gap-4`, Padding: `px-4 py-1.5`
116
- - Native: read pixel values via `useTheme().spacing` (e.g. `spacing[4] === 16`)
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.