@wangs-ui/skills 1.1.5 → 1.1.9

package/skills/create-form/SKILL.md

@@ -1,176 +1,176 @@
----
-name: create-form
-description: 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.
----
-
-# Skill: Form Architecture & Validation Workflows
-
-Use this skill when building forms, data entry panels, modal forms, settings pages, or multipart forms in Wangs UI applications.
-
----
-
-## 1. MCP Protocol & Component Rules (Mandatory Single Source of Truth)
-
-Do **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:
-
-### Component & Form Documentation Protocol:
-
-```json
-get-documentation({ "id": "form" })
-get-documentation({ "id": "field" })
-get-documentation({ "id": "dialogform" })
-get-documentation({ "id": "input" })
-get-documentation({ "id": "numberinput" })
-get-documentation({ "id": "select" })
-get-documentation({ "id": "multiselect" })
-get-documentation({ "id": "datepicker" })
-get-documentation({ "id": "fileupload" })
-```
-
-### Live Storybook & Interactive Behavior Protocol:
-
-```json
-get-documentation-for-story({ "id": "form", "storyName": "Default" })
-get-documentation-for-story({ "id": "form", "storyName": "AsyncInitialValues" })
-get-documentation-for-story({ "id": "form", "storyName": "ConditionalFields" })
-get-documentation-for-story({ "id": "form", "storyName": "CascadingOptions" })
-get-documentation-for-story({ "id": "dialogform", "storyName": "Default" })
-```
-
-### Knowledge Graph & Symbol Usages:
-
-```json
-query_graph({ "query": "useForm" })
-query_graph({ "query": "useDialogForm" })
-query_graph({ "query": "useWatchField" })
-```
-
----
-
-## 2. Core Form Concepts & Lifecycle Mechanics
-
-### A. Strongly Typed Form Instance (`useForm<TForm>()`)
-
-`useForm<TForm>()` instantiates a `FormControl` natively bound to model type `TForm`.
-
-- `Field`: `name` is strictly typed to `Path<TForm>` dot-paths.
-- `useWatchField`: `name` is strictly typed to `Path<TForm>`.
-- `control`: Provides `setInitialValues`, `setValues`, `setFieldError`, `setErrors`, and `reset`.
-
-### B. Dynamic Initial Values & Baseline Reset (`setInitialValues` vs `setValues`)
-
-1. **Async Initial Values (`control.setInitialValues(values)`)**:
-   - Accepts a `Partial<TForm>` JSON object (e.g. fetched from an API).
-   - Establishes an **immutable baseline** for registered fields. Once set for a field path, subsequent calls to `setInitialValues` for that path are ignored.
-2. **Batch Value Updates (`control.setValues(values)`)**:
-   - Accepts a `Partial<TForm>` JSON object to update current input values without altering the initial baseline.
-3. **Reset Behavior (`control.reset()`)**:
-   - Restores all fields back to their registered initial baseline values (set via `setInitialValues` or field `initialValue`) and clears all field-level validation errors.
-
-### C. Primitive Component Integration Architecture
-
-`Field` serves as the form integration wrapper for primitive UI input components (`Input`, `Select`, `MultiSelect`, `DatePicker`, `NumberInput`, `FileUpload`, `Calendar`, etc.):
-
-- **Children Render Callback**: `Field` yields `{ fieldProps, fieldState }`.
-- **`fieldProps`**: Pass directly to primitive inputs (`<Input {...fieldProps} />`). Contains `name`, `value`, `ref`, `onChange`.
-- **`fieldState`**: Provides `invalid`, `error`, `isDirty`, `isPending`. Pass `invalid={fieldState.invalid}` to primitive components for accessibility and validation styling.
-
----
-
-## 3. High-Level Form Architecture & Usage Patterns
-
-### Pattern 1: Page Forms (`useForm<T>()`)
-
-```tsx
-import Button from '@wangs-ui/react-core/primitive/button';
-import { useForm } from '@wangs-ui/react-core/primitive/form';
-import Input from '@wangs-ui/react-core/primitive/input';
-import { useI18n } from '@wangs-ui/react-i18n';
-import { useEffect } from 'react';
-
-interface UserProfile {
-  name: string;
-  email: string;
-}
-
-export function UserProfilePage({ userId }: { userId: string }) {
-  const { t } = useI18n();
-  const { Form, Field, control } = useForm<UserProfile>();
-
-  useEffect(() => {
-    async function loadData() {
-      const data = await fetchUserData(userId);
-      // Establish immutable initial baseline from async response
-      control.setInitialValues(data);
-    }
-    loadData();
-  }, [userId, control]);
-
-  return (
-    <Form control={control} onSubmit={(values) => saveUserData(values)}>
-      <Field required label={t('Full Name')} name="name">
-        {({ fieldProps, fieldState }) => (
-          <Input {...fieldProps} invalid={fieldState.invalid} placeholder={t('Enter full name')} />
-        )}
-      </Field>
-
-      <div className="flex gap-2">
-        <Button
-          label={t('Reset')}
-          type="button"
-          variant="outlined"
-          onClick={() => control.reset()}
-        />
-        <Button label={t('Save')} type="submit" />
-      </div>
-    </Form>
-  );
-}
-```
-
-### Pattern 2: Modal Forms (`useDialogForm<T>()`)
-
-```tsx
-import Button from '@wangs-ui/react-core/primitive/button';
-import { useDialogForm } from '@wangs-ui/react-core/primitive/dialogform';
-import Input from '@wangs-ui/react-core/primitive/input';
-import { useI18n } from '@wangs-ui/react-i18n';
-import { useState } from 'react';
-
-interface EditUserForm {
-  name: string;
-}
-
-export function EditUserModal() {
-  const { t } = useI18n();
-  const [open, setOpen] = useState(false);
-  const { DialogForm, Field, control } = useDialogForm<EditUserForm>();
-
-  return (
-    <>
-      <Button label={t('Edit')} onClick={() => setOpen(true)} />
-      <DialogForm
-        closeOnSubmit
-        control={control}
-        header={t('Edit User')}
-        open={open}
-        onOpenChange={setOpen}
-        onSubmit={(values) => handleSave(values)}
-      >
-        <Field required label={t('Full Name')} name="name">
-          {({ fieldProps, fieldState }) => <Input {...fieldProps} invalid={fieldState.invalid} />}
-        </Field>
-      </DialogForm>
-    </>
-  );
-}
-```
-
----
-
-## 4. Mandatory Implementation Guidelines
-
-1. **Query MCP First**: Never guess component props or story examples — inspect via MCP tools.
-2. **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`).
-3. **i18n Localization**: Wrap all user-visible labels, placeholders, and error strings in `t('...')` from `@wangs-ui/react-i18n`.
-4. **Server Error Mapping**: Map HTTP validation errors (e.g. 422 response) into the form using `control.setErrors(apiErrors)`.
+---
+name: create-form
+description: 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.
+---
+
+# Skill: Form Architecture & Validation Workflows
+
+Use this skill when building forms, data entry panels, modal forms, settings pages, or multipart forms in Wangs UI applications.
+
+---
+
+## 1. MCP Protocol & Component Rules (Mandatory Single Source of Truth)
+
+Do **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:
+
+### Component & Form Documentation Protocol:
+
+```json
+get-documentation({ "id": "form" })
+get-documentation({ "id": "field" })
+get-documentation({ "id": "dialogform" })
+get-documentation({ "id": "input" })
+get-documentation({ "id": "numberinput" })
+get-documentation({ "id": "select" })
+get-documentation({ "id": "multiselect" })
+get-documentation({ "id": "datepicker" })
+get-documentation({ "id": "fileupload" })
+```
+
+### Live Storybook & Interactive Behavior Protocol:
+
+```json
+get-documentation-for-story({ "id": "form", "storyName": "Default" })
+get-documentation-for-story({ "id": "form", "storyName": "AsyncInitialValues" })
+get-documentation-for-story({ "id": "form", "storyName": "ConditionalFields" })
+get-documentation-for-story({ "id": "form", "storyName": "CascadingOptions" })
+get-documentation-for-story({ "id": "dialogform", "storyName": "Default" })
+```
+
+### Knowledge Graph & Symbol Usages:
+
+```json
+query_graph({ "query": "useForm" })
+query_graph({ "query": "useDialogForm" })
+query_graph({ "query": "useWatchField" })
+```
+
+---
+
+## 2. Core Form Concepts & Lifecycle Mechanics
+
+### A. Strongly Typed Form Instance (`useForm<TForm>()`)
+
+`useForm<TForm>()` instantiates a `FormControl` natively bound to model type `TForm`.
+
+- `Field`: `name` is strictly typed to `Path<TForm>` dot-paths.
+- `useWatchField`: `name` is strictly typed to `Path<TForm>`.
+- `control`: Provides `setInitialValues`, `setValues`, `setFieldError`, `setErrors`, and `reset`.
+
+### B. Dynamic Initial Values & Baseline Reset (`setInitialValues` vs `setValues`)
+
+1. **Async Initial Values (`control.setInitialValues(values)`)**:
+   - Accepts a `Partial<TForm>` JSON object (e.g. fetched from an API).
+   - Establishes an **immutable baseline** for registered fields. Once set for a field path, subsequent calls to `setInitialValues` for that path are ignored.
+2. **Batch Value Updates (`control.setValues(values)`)**:
+   - Accepts a `Partial<TForm>` JSON object to update current input values without altering the initial baseline.
+3. **Reset Behavior (`control.reset()`)**:
+   - Restores all fields back to their registered initial baseline values (set via `setInitialValues` or field `initialValue`) and clears all field-level validation errors.
+
+### C. Primitive Component Integration Architecture
+
+`Field` serves as the form integration wrapper for primitive UI input components (`Input`, `Select`, `MultiSelect`, `DatePicker`, `NumberInput`, `FileUpload`, `Calendar`, etc.):
+
+- **Children Render Callback**: `Field` yields `{ fieldProps, fieldState }`.
+- **`fieldProps`**: Pass directly to primitive inputs (`<Input {...fieldProps} />`). Contains `name`, `value`, `ref`, `onChange`.
+- **`fieldState`**: Provides `invalid`, `error`, `isDirty`, `isPending`. Pass `invalid={fieldState.invalid}` to primitive components for accessibility and validation styling.
+
+---
+
+## 3. High-Level Form Architecture & Usage Patterns
+
+### Pattern 1: Page Forms (`useForm<T>()`)
+
+```tsx
+import Button from '@wangs-ui/react-core/primitive/button';
+import { useForm } from '@wangs-ui/react-core/primitive/form';
+import Input from '@wangs-ui/react-core/primitive/input';
+import { useI18n } from '@wangs-ui/react-i18n';
+import { useEffect } from 'react';
+
+interface UserProfile {
+  name: string;
+  email: string;
+}
+
+export function UserProfilePage({ userId }: { userId: string }) {
+  const { t } = useI18n();
+  const { Form, Field, control } = useForm<UserProfile>();
+
+  useEffect(() => {
+    async function loadData() {
+      const data = await fetchUserData(userId);
+      // Establish immutable initial baseline from async response
+      control.setInitialValues(data);
+    }
+    loadData();
+  }, [userId, control]);
+
+  return (
+    <Form control={control} onSubmit={(values) => saveUserData(values)}>
+      <Field required label={t('Full Name')} name="name">
+        {({ fieldProps, fieldState }) => (
+          <Input {...fieldProps} invalid={fieldState.invalid} placeholder={t('Enter full name')} />
+        )}
+      </Field>
+
+      <div className="flex gap-2">
+        <Button
+          label={t('Reset')}
+          type="button"
+          variant="outlined"
+          onClick={() => control.reset()}
+        />
+        <Button label={t('Save')} type="submit" />
+      </div>
+    </Form>
+  );
+}
+```
+
+### Pattern 2: Modal Forms (`useDialogForm<T>()`)
+
+```tsx
+import Button from '@wangs-ui/react-core/primitive/button';
+import { useDialogForm } from '@wangs-ui/react-core/primitive/dialogform';
+import Input from '@wangs-ui/react-core/primitive/input';
+import { useI18n } from '@wangs-ui/react-i18n';
+import { useState } from 'react';
+
+interface EditUserForm {
+  name: string;
+}
+
+export function EditUserModal() {
+  const { t } = useI18n();
+  const [open, setOpen] = useState(false);
+  const { DialogForm, Field, control } = useDialogForm<EditUserForm>();
+
+  return (
+    <>
+      <Button label={t('Edit')} onClick={() => setOpen(true)} />
+      <DialogForm
+        closeOnSubmit
+        control={control}
+        header={t('Edit User')}
+        open={open}
+        onOpenChange={setOpen}
+        onSubmit={(values) => handleSave(values)}
+      >
+        <Field required label={t('Full Name')} name="name">
+          {({ fieldProps, fieldState }) => <Input {...fieldProps} invalid={fieldState.invalid} />}
+        </Field>
+      </DialogForm>
+    </>
+  );
+}
+```
+
+---
+
+## 4. Mandatory Implementation Guidelines
+
+1. **Query MCP First**: Never guess component props or story examples — inspect via MCP tools.
+2. **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`).
+3. **i18n Localization**: Wrap all user-visible labels, placeholders, and error strings in `t('...')` from `@wangs-ui/react-i18n`.
+4. **Server Error Mapping**: Map HTTP validation errors (e.g. 422 response) into the form using `control.setErrors(apiErrors)`.

package/skills/data-table/SKILL.md

@@ -1,68 +1,68 @@
----
-name: data-table
-description: Architecture, workflows, and MCP discovery protocol for building DataTables with sorting, pagination, filtering, selection, and export.
----
-
-# Skill: DataTable Architecture & Integration Workflows
-
-Use this skill when implementing data grids, server-paginated tables, filterable listing views, or batch management interfaces with `@wangs-ui/react-core`.
-
----
-
-## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
-
-Do **NOT** guess table prop names or hardcode table structures. Query the MCP server dynamically to inspect exact TypeScript signatures, live story implementations, and companion controls:
-
-### Inspect Component Contracts:
-
-```json
-get-documentation({ "id": "datatable" })
-get-documentation({ "id": "exportbutton" })
-get-documentation({ "id": "filtercontainer" })
-get-documentation({ "id": "bulkactionbutton" })
-```
-
-### Inspect Live Story Implementations:
-
-```json
-get-documentation-for-story({ "id": "datatable", "storyName": "Basic" })
-get-documentation-for-story({ "id": "datatable", "storyName": "ServerPagination" })
-get-documentation-for-story({ "id": "datatable", "storyName": "Sortable" })
-get-documentation-for-story({ "id": "datatable", "storyName": "MultipleSelection" })
-get-documentation-for-story({ "id": "datatable", "storyName": "CustomColumn" })
-get-documentation-for-story({ "id": "exportbutton", "storyName": "WithTable" })
-```
-
-### Inspect Knowledge Graph & Usages:
-
-```json
-query_graph({ "query": "DataTable" })
-query_graph({ "query": "useDataTableFetch" })
-```
-
----
-
-## 2. Core Architecture & Mental Model
-
-The Wangs UI `DataTable` is built on a modular, headless-first architecture:
-
-1. **Declarative Column Definitions (`TableColumn<T>[]`)**:
-   Columns are configured as typed array objects, not as JSX children. Check `get-documentation({ "id": "datatable" })` for column field types.
-2. **Table Instance Hook (`useDataTable`)**:
-   Coordinates table state (sorting, pagination, selection, column ordering, pinning, visibility).
-3. **Data Fetching Hook (`useDataTableFetch`)**:
-   Feeds server-side data, handles loading indicators, manages query parameters (`search`, `filter`, `sort`, `page`, `limit`), and debounces requests automatically.
-4. **Ecosystem Companions**:
-   - `FilterContainer` & `FilterToggleButton`: Filter popovers and faceted search.
-   - `ExportButton`: Client/server export to Excel, CSV, PDF, or Print.
-   - `BulkActionButton`: Contextual batch actions triggered when rows are selected.
-   - `CustomColumn`: User-controlled column ordering, visibility toggling, and pinning.
-
----
-
-## 3. Mandatory Implementation Rules
-
-1. **Query MCP for Current Code Patterns**: Always run `get-documentation-for-story` for `datatable` before drafting code.
-2. **Strict Subpath Imports**: Import via `@wangs-ui/react-core/primitive/datatable` and companion primitive paths.
-3. **Always Translate Visible Copy**: All column header labels, empty state messages, and action button labels must be wrapped in `t('...')` from `@wangs-ui/react-i18n`.
-4. **Stable Row Identity**: Always configure a unique key identifier for stable selection and row identity.
+---
+name: data-table
+description: Architecture, workflows, and MCP discovery protocol for building DataTables with sorting, pagination, filtering, selection, and export.
+---
+
+# Skill: DataTable Architecture & Integration Workflows
+
+Use this skill when implementing data grids, server-paginated tables, filterable listing views, or batch management interfaces with `@wangs-ui/react-core`.
+
+---
+
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
+
+Do **NOT** guess table prop names or hardcode table structures. Query the MCP server dynamically to inspect exact TypeScript signatures, live story implementations, and companion controls:
+
+### Inspect Component Contracts:
+
+```json
+get-documentation({ "id": "datatable" })
+get-documentation({ "id": "exportbutton" })
+get-documentation({ "id": "filtercontainer" })
+get-documentation({ "id": "bulkactionbutton" })
+```
+
+### Inspect Live Story Implementations:
+
+```json
+get-documentation-for-story({ "id": "datatable", "storyName": "Basic" })
+get-documentation-for-story({ "id": "datatable", "storyName": "ServerPagination" })
+get-documentation-for-story({ "id": "datatable", "storyName": "Sortable" })
+get-documentation-for-story({ "id": "datatable", "storyName": "MultipleSelection" })
+get-documentation-for-story({ "id": "datatable", "storyName": "CustomColumn" })
+get-documentation-for-story({ "id": "exportbutton", "storyName": "WithTable" })
+```
+
+### Inspect Knowledge Graph & Usages:
+
+```json
+query_graph({ "query": "DataTable" })
+query_graph({ "query": "useDataTableFetch" })
+```
+
+---
+
+## 2. Core Architecture & Mental Model
+
+The Wangs UI `DataTable` is built on a modular, headless-first architecture:
+
+1. **Declarative Column Definitions (`TableColumn<T>[]`)**:
+   Columns are configured as typed array objects, not as JSX children. Check `get-documentation({ "id": "datatable" })` for column field types.
+2. **Table Instance Hook (`useDataTable`)**:
+   Coordinates table state (sorting, pagination, selection, column ordering, pinning, visibility).
+3. **Data Fetching Hook (`useDataTableFetch`)**:
+   Feeds server-side data, handles loading indicators, manages query parameters (`search`, `filter`, `sort`, `page`, `limit`), and debounces requests automatically.
+4. **Ecosystem Companions**:
+   - `FilterContainer` & `FilterToggleButton`: Filter popovers and faceted search.
+   - `ExportButton`: Client/server export to Excel, CSV, PDF, or Print.
+   - `BulkActionButton`: Contextual batch actions triggered when rows are selected.
+   - `CustomColumn`: User-controlled column ordering, visibility toggling, and pinning.
+
+---
+
+## 3. Mandatory Implementation Rules
+
+1. **Query MCP for Current Code Patterns**: Always run `get-documentation-for-story` for `datatable` before drafting code.
+2. **Strict Subpath Imports**: Import via `@wangs-ui/react-core/primitive/datatable` and companion primitive paths.
+3. **Always Translate Visible Copy**: All column header labels, empty state messages, and action button labels must be wrapped in `t('...')` from `@wangs-ui/react-i18n`.
+4. **Stable Row Identity**: Always configure a unique key identifier for stable selection and row identity.

package/skills/dialog-modal/SKILL.md

@@ -1,58 +1,58 @@
----
-name: dialog-modal
-description: Patterns, overlay selection criteria, and MCP discovery protocol for Dialog, Modal, and DialogForm components in Wangs UI.
----
-
-# Skill: Dialog, Modal & Overlay Workflows
-
-Use this skill when building interactive modals, create/edit dialog forms, destructive action confirmations, or slide-in overlay panels.
-
----
-
-## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
-
-Do **NOT** guess overlay props, event names, or footer slots. Query the MCP server dynamically to inspect exact contracts and live story implementations:
-
-### Inspect Overlay Contracts:
-
-```json
-get-documentation({ "id": "dialog" })
-get-documentation({ "id": "dialogform" })
-get-documentation({ "id": "modal" })
-get-documentation({ "id": "toast" })
-```
-
-### Inspect Live Story Implementations:
-
-```json
-get-documentation-for-story({ "id": "dialog", "storyName": "Confirmation" })
-get-documentation-for-story({ "id": "dialogform", "storyName": "Default" })
-get-documentation-for-story({ "id": "modal", "storyName": "Default" })
-```
-
-### Inspect Knowledge Graph & Usages:
-
-```json
-query_graph({ "query": "Dialog" })
-query_graph({ "query": "DialogForm" })
-```
-
----
-
-## 2. Overlay Selection Matrix
-
-| Component        | Primary Use Case                              | Key Characteristics                                                                   |
-| :--------------- | :-------------------------------------------- | :------------------------------------------------------------------------------------ |
-| **`Dialog`**     | Confirmations, alerts, simple detail previews | Standard `header`, `footer`, and body layout; built-in backdrop dimming.              |
-| **`DialogForm`** | Create/Edit forms embedded inside a dialog    | Built-in form submit/cancel action bar, dirty state tracking, and submit lifecycle.   |
-| **`Modal`**      | Slide-in drawers, complex custom viewports    | Headless overlay primitive with flexible animations, size variants, and drawer modes. |
-
----
-
-## 3. Mandatory Implementation Rules
-
-1. **Query MCP for Current Code Patterns**: Always inspect `dialog`, `dialogform`, or `modal` stories via MCP before writing overlay code.
-2. **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`.
-3. **Prevent Dismissal During Async Mutations**: Guard the close handler so users cannot accidentally dismiss the dialog while a mutation request is in-flight.
-4. **Coordinate with Toast Notifications**: Trigger feedback toasts on successful creation, update, or deletion actions.
-5. **Translate All Overlay Copy**: All dialog titles, confirmation descriptions, and button labels must be localized using `t('...')` from `@wangs-ui/react-i18n`.
+---
+name: dialog-modal
+description: Patterns, overlay selection criteria, and MCP discovery protocol for Dialog, Modal, and DialogForm components in Wangs UI.
+---
+
+# Skill: Dialog, Modal & Overlay Workflows
+
+Use this skill when building interactive modals, create/edit dialog forms, destructive action confirmations, or slide-in overlay panels.
+
+---
+
+## 1. MCP Inspection Protocol (Mandatory Single Source of Truth)
+
+Do **NOT** guess overlay props, event names, or footer slots. Query the MCP server dynamically to inspect exact contracts and live story implementations:
+
+### Inspect Overlay Contracts:
+
+```json
+get-documentation({ "id": "dialog" })
+get-documentation({ "id": "dialogform" })
+get-documentation({ "id": "modal" })
+get-documentation({ "id": "toast" })
+```
+
+### Inspect Live Story Implementations:
+
+```json
+get-documentation-for-story({ "id": "dialog", "storyName": "Confirmation" })
+get-documentation-for-story({ "id": "dialogform", "storyName": "Default" })
+get-documentation-for-story({ "id": "modal", "storyName": "Default" })
+```
+
+### Inspect Knowledge Graph & Usages:
+
+```json
+query_graph({ "query": "Dialog" })
+query_graph({ "query": "DialogForm" })
+```
+
+---
+
+## 2. Overlay Selection Matrix
+
+| Component        | Primary Use Case                              | Key Characteristics                                                                   |
+| :--------------- | :-------------------------------------------- | :------------------------------------------------------------------------------------ |
+| **`Dialog`**     | Confirmations, alerts, simple detail previews | Standard `header`, `footer`, and body layout; built-in backdrop dimming.              |
+| **`DialogForm`** | Create/Edit forms embedded inside a dialog    | Built-in form submit/cancel action bar, dirty state tracking, and submit lifecycle.   |
+| **`Modal`**      | Slide-in drawers, complex custom viewports    | Headless overlay primitive with flexible animations, size variants, and drawer modes. |
+
+---
+
+## 3. Mandatory Implementation Rules
+
+1. **Query MCP for Current Code Patterns**: Always inspect `dialog`, `dialogform`, or `modal` stories via MCP before writing overlay code.
+2. **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`.
+3. **Prevent Dismissal During Async Mutations**: Guard the close handler so users cannot accidentally dismiss the dialog while a mutation request is in-flight.
+4. **Coordinate with Toast Notifications**: Trigger feedback toasts on successful creation, update, or deletion actions.
+5. **Translate All Overlay Copy**: All dialog titles, confirmation descriptions, and button labels must be localized using `t('...')` from `@wangs-ui/react-i18n`.