@redsift/ds-mcp-server 12.5.3-alpha.4 → 12.5.3-alpha.6

package/consumer-instructions/.cursorrules

@@ -40,6 +40,16 @@ When applying colors, spacing, or typography:
 1. Call `search_design_tokens` to find the correct token names and CSS custom properties.
 2. Do not hardcode color hex values — use the design token CSS variables.
 
+## Rule 5 — Host App Setup (Adopting or Migrating to DS)
+
+When adopting `@redsift/*` components in a new project or migrating from raw HTML/CSS/Tailwind:
+
+1. Read the `design-system://getting-started/host-app` MCP resource FIRST.
+2. Ensure the app entry point imports `@redsift/design-system/style/index.css`.
+3. Wrap the app with `<AppContainer>` (full Red Sift shell) or `<ThemeProvider value={{ theme }}>` (standalone). Do NOT pass `theme` to every individual component — use context at the root.
+4. Import icons from `@redsift/icons`, not `@mdi/js`.
+5. Remove conflicting Tailwind/utility-CSS classes (`bg-*`, `text-*`, `border-*`, `dark:*`) from elements that render or wrap DS components.
+
 ## Common Mistakes
 
 These are real examples of props that do NOT exist in the Red Sift DS:
@@ -52,6 +62,10 @@ These are real examples of props that do NOT exist in the Red Sift DS:
 - `import { Select } from '@redsift/design-system'` → Should be `@redsift/pickers`
 - `import { Dialog } from '@redsift/design-system'` → Should be `@redsift/popovers`
 - `import { DataGrid } from '@redsift/design-system'` → Should be `@redsift/table`
+- Passing `theme` to every component → Wrap app with `<AppContainer>` or `<ThemeProvider>` at root
+- Missing `@redsift/design-system/style/index.css` import → Must import at app entry point
+- `import { mdiPlus } from '@mdi/js'` → Should be `@redsift/icons`
+- Tailwind `bg-*`/`text-*`/`dark:*` on DS wrappers → Use DS tokens or layout primitives
 
 ## NEVER Do This
 

package/consumer-instructions/.windsurfrules

@@ -10,7 +10,7 @@ This project uses the **Red Sift Design System** (`@redsift/*` packages). The de
 
 1. Configure the MCP server — see [MCP Server docs](https://design-system.redsift.io/introduction/mcp-server)
 2. Copy this file to your project root as `.cursorrules`
-3. Verify: ask the AI *"What props does Button accept?"* — it should call `get_component_props`, not answer from memory
+3. Verify: ask the AI _"What props does Button accept?"_ — it should call `get_component_props`, not answer from memory
 
 ## Rule 1 — Mandatory Prop Lookup
 
@@ -40,6 +40,16 @@ When applying colors, spacing, or typography:
 1. Call `search_design_tokens` to find the correct token names and CSS custom properties.
 2. Do not hardcode color hex values — use the design token CSS variables.
 
+## Rule 5 — Host App Setup (Adopting or Migrating to DS)
+
+When adopting `@redsift/*` components in a new project or migrating from raw HTML/CSS/Tailwind:
+
+1. Read the `design-system://getting-started/host-app` MCP resource FIRST.
+2. Ensure the app entry point imports `@redsift/design-system/style/index.css`.
+3. Wrap the app with `<AppContainer>` (full Red Sift shell) or `<ThemeProvider value={{ theme }}>` (standalone). Do NOT pass `theme` to every individual component — use context at the root.
+4. Import icons from `@redsift/icons`, not `@mdi/js`.
+5. Remove conflicting Tailwind/utility-CSS classes (`bg-*`, `text-*`, `border-*`, `dark:*`) from elements that render or wrap DS components.
+
 ## Common Mistakes
 
 These are real examples of props that do NOT exist in the Red Sift DS:
@@ -52,6 +62,10 @@ These are real examples of props that do NOT exist in the Red Sift DS:
 - `import { Select } from '@redsift/design-system'` → Should be `@redsift/pickers`
 - `import { Dialog } from '@redsift/design-system'` → Should be `@redsift/popovers`
 - `import { DataGrid } from '@redsift/design-system'` → Should be `@redsift/table`
+- Passing `theme` to every component → Wrap app with `<AppContainer>` or `<ThemeProvider>` at root
+- Missing `@redsift/design-system/style/index.css` import → Must import at app entry point
+- `import { mdiPlus } from '@mdi/js'` → Should be `@redsift/icons`
+- Tailwind `bg-*`/`text-*`/`dark:*` on DS wrappers → Use DS tokens or layout primitives
 
 ## NEVER Do This
 
@@ -75,6 +89,6 @@ import { Select } from '@redsift/design-system';
 
 Test that your AI assistant is using the MCP server correctly with these prompts:
 
-1. *"What props does Button accept?"* → Should call `get_component_props`, NOT answer from memory
-2. *"Import the Select component"* → Should call `get_component_usage`, return `@redsift/pickers`
-3. *"Create a data table page"* → Should call `search_patterns` first, then follow the pattern spec
+1. _"What props does Button accept?"_ → Should call `get_component_props`, NOT answer from memory
+2. _"Import the Select component"_ → Should call `get_component_usage`, return `@redsift/pickers`
+3. _"Create a data table page"_ → Should call `search_patterns` first, then follow the pattern spec

package/consumer-instructions/CLAUDE.md

@@ -40,6 +40,16 @@ When applying colors, spacing, or typography:
 1. Call `search_design_tokens` to find the correct token names and CSS custom properties.
 2. Do not hardcode color hex values — use the design token CSS variables.
 
+## Rule 5 — Host App Setup (Adopting or Migrating to DS)
+
+When adopting `@redsift/*` components in a new project or migrating from raw HTML/CSS/Tailwind:
+
+1. Read the `design-system://getting-started/host-app` MCP resource FIRST.
+2. Ensure the app entry point imports `@redsift/design-system/style/index.css`.
+3. Wrap the app with `<AppContainer>` (full Red Sift shell) or `<ThemeProvider value={{ theme }}>` (standalone). Do NOT pass `theme` to every individual component — use context at the root.
+4. Import icons from `@redsift/icons`, not `@mdi/js`.
+5. Remove conflicting Tailwind/utility-CSS classes (`bg-*`, `text-*`, `border-*`, `dark:*`) from elements that render or wrap DS components.
+
 ## NEVER Do This
 
 These are concrete examples of wrong code. **Every single one will fail:**
@@ -62,17 +72,21 @@ import { Select } from '@redsift/design-system';
 
 ## Common Mistakes
 
-| Wrong (guessed)                                     | Correct (actual)                             | How to verify                           |
-| --------------------------------------------------- | -------------------------------------------- | --------------------------------------- |
-| `variant="primary"`                                 | Look up actual variants                      | `get_component_props` for the component |
-| `size="sm"` / `size="lg"`                           | Most components have no size prop            | `get_component_props` for the component |
-| `colorScheme="red"`                                 | Does not exist                               | `get_component_props` for the component |
-| `isDisabled`                                        | `disabled`                                   | `get_component_props` for the component |
-| `onPress`                                           | `onClick`                                    | `get_component_props` for the component |
-| `leftIcon` / `rightIcon`                            | Look up actual icon prop names               | `get_component_props` for the component |
-| `import { Select } from '@redsift/design-system'`   | `import { Select } from '@redsift/pickers'`  | `get_component_usage`                   |
-| `import { Dialog } from '@redsift/design-system'`   | `import { Dialog } from '@redsift/popovers'` | `get_component_usage`                   |
-| `import { DataGrid } from '@redsift/design-system'` | `import { DataGrid } from '@redsift/table'`  | `get_component_usage`                   |
+| Wrong (guessed)                                     | Correct (actual)                                            | How to verify                              |
+| --------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------ |
+| `variant="primary"`                                 | Look up actual variants                                     | `get_component_props` for the component    |
+| `size="sm"` / `size="lg"`                           | Most components have no size prop                           | `get_component_props` for the component    |
+| `colorScheme="red"`                                 | Does not exist                                              | `get_component_props` for the component    |
+| `isDisabled`                                        | `disabled`                                                  | `get_component_props` for the component    |
+| `onPress`                                           | `onClick`                                                   | `get_component_props` for the component    |
+| `leftIcon` / `rightIcon`                            | Look up actual icon prop names                              | `get_component_props` for the component    |
+| `import { Select } from '@redsift/design-system'`   | `import { Select } from '@redsift/pickers'`                 | `get_component_usage`                      |
+| `import { Dialog } from '@redsift/design-system'`   | `import { Dialog } from '@redsift/popovers'`                | `get_component_usage`                      |
+| `import { DataGrid } from '@redsift/design-system'` | `import { DataGrid } from '@redsift/table'`                 | `get_component_usage`                      |
+| Passing `theme` to every component                  | Wrap app with `<AppContainer>` or `<ThemeProvider>` at root | `design-system://getting-started/host-app` |
+| Missing `@redsift/design-system/style/index.css`    | Must import at app entry point                              | `design-system://getting-started/host-app` |
+| `import { mdiPlus } from '@mdi/js'`                 | `import { mdiPlus } from '@redsift/icons'`                  | `get_component_usage`                      |
+| Tailwind `bg-*`/`text-*`/`dark:*` on DS wrappers    | Use DS tokens or layout primitives                          | `design-system://getting-started/host-app` |
 
 ## Verification
 

package/consumer-instructions/redsift-design-system.instructions.md

@@ -44,6 +44,16 @@ When applying colors, spacing, or typography:
 1. Call `search_design_tokens` to find the correct token names and CSS custom properties.
 2. Do not hardcode color hex values — use the design token CSS variables.
 
+## Rule 5 — Host App Setup (Adopting or Migrating to DS)
+
+When adopting `@redsift/*` components in a new project or migrating from raw HTML/CSS/Tailwind:
+
+1. Read the `design-system://getting-started/host-app` MCP resource FIRST.
+2. Ensure the app entry point imports `@redsift/design-system/style/index.css`.
+3. Wrap the app with `<AppContainer>` (full Red Sift shell) or `<ThemeProvider value={{ theme }}>` (standalone). Do NOT pass `theme` to every individual component — use context at the root.
+4. Import icons from `@redsift/icons`, not `@mdi/js`.
+5. Remove conflicting Tailwind/utility-CSS classes (`bg-*`, `text-*`, `border-*`, `dark:*`) from elements that render or wrap DS components.
+
 ## NEVER Do This
 
 These are concrete examples of wrong code. **Every single one will fail:**
@@ -66,17 +76,21 @@ import { Select } from '@redsift/design-system';
 
 ## Common Mistakes
 
-| Wrong (guessed)                                     | Correct (actual)                             | How to verify                           |
-| --------------------------------------------------- | -------------------------------------------- | --------------------------------------- |
-| `variant="primary"`                                 | Look up actual variants                      | `get_component_props` for the component |
-| `size="sm"` / `size="lg"`                           | Most components have no size prop            | `get_component_props` for the component |
-| `colorScheme="red"`                                 | Does not exist                               | `get_component_props` for the component |
-| `isDisabled`                                        | `disabled`                                   | `get_component_props` for the component |
-| `onPress`                                           | `onClick`                                    | `get_component_props` for the component |
-| `leftIcon` / `rightIcon`                            | Look up actual icon prop names               | `get_component_props` for the component |
-| `import { Select } from '@redsift/design-system'`   | `import { Select } from '@redsift/pickers'`  | `get_component_usage`                   |
-| `import { Dialog } from '@redsift/design-system'`   | `import { Dialog } from '@redsift/popovers'` | `get_component_usage`                   |
-| `import { DataGrid } from '@redsift/design-system'` | `import { DataGrid } from '@redsift/table'`  | `get_component_usage`                   |
+| Wrong (guessed)                                     | Correct (actual)                                            | How to verify                              |
+| --------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------ |
+| `variant="primary"`                                 | Look up actual variants                                     | `get_component_props` for the component    |
+| `size="sm"` / `size="lg"`                           | Most components have no size prop                           | `get_component_props` for the component    |
+| `colorScheme="red"`                                 | Does not exist                                              | `get_component_props` for the component    |
+| `isDisabled`                                        | `disabled`                                                  | `get_component_props` for the component    |
+| `onPress`                                           | `onClick`                                                   | `get_component_props` for the component    |
+| `leftIcon` / `rightIcon`                            | Look up actual icon prop names                              | `get_component_props` for the component    |
+| `import { Select } from '@redsift/design-system'`   | `import { Select } from '@redsift/pickers'`                 | `get_component_usage`                      |
+| `import { Dialog } from '@redsift/design-system'`   | `import { Dialog } from '@redsift/popovers'`                | `get_component_usage`                      |
+| `import { DataGrid } from '@redsift/design-system'` | `import { DataGrid } from '@redsift/table'`                 | `get_component_usage`                      |
+| Passing `theme` to every component                  | Wrap app with `<AppContainer>` or `<ThemeProvider>` at root | `design-system://getting-started/host-app` |
+| Missing `@redsift/design-system/style/index.css`    | Must import at app entry point                              | `design-system://getting-started/host-app` |
+| `import { mdiPlus } from '@mdi/js'`                 | `import { mdiPlus } from '@redsift/icons'`                  | `get_component_usage`                      |
+| Tailwind `bg-*`/`text-*`/`dark:*` on DS wrappers    | Use DS tokens or layout primitives                          | `design-system://getting-started/host-app` |
 
 ## Verification
 

package/data/docs/components/charts/BaseBarChart.json

@@ -1,6 +1,6 @@
 {
   "name": "BaseBarChart",
-  "description": "BarChart visualizes categorical data with rectangular bars.\nBuilt on D3.js with responsive sizing and interactive tooltips.\n\nSupports horizontal/vertical orientation, stacked/grouped bars,\nand various legend placements.\n\nData format: `CategoryData` `[{ key: string, value: number }]`",
+  "description": "BarChart visualizes categorical data with rectangular bars.\nBuilt on D3.js with responsive sizing and interactive tooltips.\n\nThis is the only public entry point for bar charts. Do not import\n`RenderedLinearBarChart`, `RenderedOrdinalBarChart`, `EmptyBarChart`, or\n`LoadingBarChart` directly — `BarChart` selects the correct renderer\n(linear vs. ordinal scale) automatically based on the data type,\nand manages all loading and empty states internally.\n\nSupports horizontal/vertical orientation, stacked/grouped bars,\nand various legend placements.\n\nData format: `CategoryData` `[{ key: string, value: number }]`",
   "package": "@redsift/charts",
   "filePath": "packages/charts/src/components/BarChart/BarChart.tsx",
   "props": [

package/data/docs/components/charts/LineChart.json

@@ -1,6 +1,6 @@
 {
   "name": "LineChart",
-  "description": "LineChart displays trends over time or continuous data.\nBuilt on D3.js with smooth interpolation and interactive data points.\n\nData format: `LinearData` `[{ key: Date, value: number, label?: string }]`",
+  "description": "LineChart displays trends over time or continuous data.\nBuilt on D3.js with smooth interpolation and interactive data points.\n\nThis is the only public entry point for line charts. Do not import\n`RenderedLineChart`, `EmptyLineChart`, or `LoadingLineChart` directly —\nthose are internal sub-components that `LineChart` selects automatically\nbased on whether `data` is present and non-empty.\n\nData format: `LinearData` `[{ key: Date, value: number, label?: string }]`",
   "package": "@redsift/charts",
   "filePath": "packages/charts/src/components/LineChart/LineChart.tsx",
   "props": [

package/data/docs/components/dashboard/DataCard.json

@@ -296,5 +296,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "DataCard.Header, DataCard.Body, and DataCard.Listbox must be direct children of <DataCard>. Never nest them inside each other (e.g. Listbox inside Body) — nesting doubles margins and breaks layout.",
+    "Use DataCard.Body for static/link DataRow children. Use DataCard.Listbox for interactive filter-selection DataRow children. Do not combine both in one DataCard.",
+    "The `slot` prop is not supported. Do not pass slot=\"heading\" or similar — use the compound sub-component API instead."
+  ]
 }

package/data/docs/components/dashboard/DataCardBody.json

@@ -435,5 +435,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must be a direct child of <DataCard>. Do not place DataCard.Listbox or DataCard.Header inside DataCard.Body.",
+    "Children should be <DataRow> components."
+  ]
 }

package/data/docs/components/dashboard/DataCardHeader.json

@@ -300,5 +300,8 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must be a direct child of <DataCard>, not nested inside DataCard.Body or DataCard.Listbox."
+  ]
 }

package/data/docs/components/dashboard/DataCardListbox.json

@@ -533,5 +533,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must be a direct child of <DataCard>. Do not place DataCard.Body or DataCard.Header inside DataCard.Listbox.",
+    "Children should be <DataRow> components with onClick and hasFilterIcon for drilldown interactions."
+  ]
 }

package/data/docs/components/design-system/AppContent.json

@@ -562,5 +562,8 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must be a direct child of <AppContainer>. This is where page content goes."
+  ]
 }

package/data/docs/components/design-system/AppSidePanel.json

@@ -83,5 +83,8 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must be a direct child of <AppContainer>. Houses the side navigation."
+  ]
 }

package/data/docs/components/design-system/Breadcrumbs.json

@@ -294,5 +294,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Only accepts Breadcrumbs.Item as children. Non-Item children are silently ignored and will not render.",
+    "The last Breadcrumbs.Item is automatically marked as the current page and is not clickable.",
+    "Provide an aria-label for accessibility (e.g. aria-label=\"Breadcrumb navigation\")."
+  ]
 }

package/data/docs/components/design-system/Button.json

@@ -398,5 +398,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "The `theme` prop is optional — components inherit theme from the nearest ThemeProvider or AppContainer ancestor. Do NOT pass `theme` to every component; wrap the app at the root instead.",
+    "Variants: check with get_component_props — they differ from other UI libraries (no \"primary\", no \"secondary\")."
+  ]
 }

package/data/docs/components/design-system/Card.json

@@ -324,5 +324,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Card only accepts Card.Header, Card.Body, and Card.Actions as children. Other elements are silently ignored.",
+    "Card.Header has a fixed design. Use Card.Body for content and Card.Actions for button rows.",
+    "For collapsible cards, pass `isCollapsible` to Card. Use `isCollapsed`/`onCollapse` for controlled mode, or `defaultCollapsed` for uncontrolled."
+  ]
 }

package/data/docs/components/design-system/CardActions.json

@@ -427,5 +427,8 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must be a direct child of <Card>."
+  ]
 }

package/data/docs/components/design-system/CardBody.json

@@ -427,5 +427,8 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must be a direct child of <Card>."
+  ]
 }

package/data/docs/components/design-system/CardHeader.json

@@ -424,5 +424,8 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must be a direct child of <Card>."
+  ]
 }

package/data/docs/components/design-system/DetailedCard.json

@@ -397,5 +397,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Content children (after DetailedCard.Header) must be DetailedCard.Section components. Other elements will not receive collapse/expand state injection via cloneElement.",
+    "DetailedCard.Header is extracted via partitionComponents — it must be a direct child, not wrapped.",
+    "DetailedCard.CollapsibleSectionItems must be a child of DetailedCard.Section for auto-detection of collapsible state."
+  ]
 }

package/data/docs/components/design-system/DetailedCardHeader.json

@@ -33,5 +33,8 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must be a direct child of <DetailedCard>."
+  ]
 }

package/data/docs/components/design-system/DetailedCardSection.json

@@ -86,5 +86,8 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must be a direct child of <DetailedCard>. Do not wrap in a <div> — the parent injects `isCollapsed` and `theme` via cloneElement."
+  ]
 }

package/data/docs/components/design-system/Heading.json

@@ -386,5 +386,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "The `theme` prop is optional — inherited from context. Do NOT pass `theme` to every component.",
+    "Valid `color` values come from NeutralColorPalette (\"black\", \"x-dark-grey\", \"dark-grey\", \"mid-grey\", \"light-grey\", \"x-light-grey\", \"white\") and NotificationsColorPalette (\"error\", \"warning\", \"success\", \"info\", \"question\", \"no-data\"). You can also pass hex/rgb strings."
+  ]
 }

package/data/docs/components/design-system/IconButton.json

@@ -367,5 +367,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "The `theme` prop is optional — inherited from context. Do NOT pass `theme` to every component.",
+    "Requires `icon` prop (SVG path string from @redsift/icons). Import icons from @redsift/icons, not @mdi/js."
+  ]
 }

package/data/docs/components/design-system/Pill.json

@@ -374,5 +374,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Content via `children`, NOT a `label` prop. Usage: `<Pill color=\"blue\" size=\"small\">Active</Pill>`",
+    "The `theme` prop is optional — inherited from context."
+  ]
 }

package/data/docs/components/design-system/Tab.json

@@ -525,5 +525,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must be a child of <Tabs>. Requires TabsContext — rendering outside <Tabs> will silently fail (no selection, no keyboard navigation).",
+    "Always provide a `value` prop that matches a corresponding TabPanel."
+  ]
 }

package/data/docs/components/design-system/TabPanel.json

@@ -291,5 +291,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must be used within a <Tabs> provider. Requires TabsContext — rendering outside <Tabs> will silently fail (panel never shown).",
+    "The `value` prop must match a corresponding Tab `value`.",
+    "Use `keepMounted` to keep panel content in DOM when inactive (useful for preserving form state)."
+  ]
 }

package/data/docs/components/design-system/Tabs.json

@@ -354,5 +354,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Accepts <Tab> and <TabPanel> children. Tabs must have a `value` prop that matches a TabPanel `value`.",
+    "For navigation tabs, use the `as` prop on Tab (e.g. as=\"a\" href=\"/path\") instead of onClick.",
+    "Supports controlled (`value`/`onChange`) and uncontrolled (`defaultValue`) modes."
+  ]
 }

package/data/docs/components/design-system/Text.json

@@ -414,5 +414,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "The `theme` prop is optional — inherited from context. Do NOT pass `theme` to every component.",
+    "The `slot` prop is NOT supported. Do not pass slot=\"heading\" or similar — use Heading component or compound sub-component API instead."
+  ]
 }

package/data/docs/components/pickers/Combobox.json

@@ -316,5 +316,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must use compound sub-components: <Combobox.Trigger> and <Combobox.Content>.",
+    "Combobox.Trigger requires a TextField or TextArea as its child. Custom inputs must forward refs correctly or focus management will break.",
+    "Combobox.Content accepts ComboboxContent.Header, .Listbox, and .Footer as children."
+  ]
 }

package/data/docs/components/pickers/ComboboxContent.json

@@ -449,5 +449,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Only accepts ComboboxContent.Header, ComboboxContent.Listbox, and ComboboxContent.Footer as children. Other elements are silently ignored.",
+    "Children are reordered internally (Header → Listbox → Footer) regardless of JSX order.",
+    "Must be used inside a <Combobox> — requires popover and combobox context."
+  ]
 }

package/data/docs/components/pickers/MenuButton.json

@@ -236,5 +236,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must use compound sub-components: <MenuButton.Trigger> and <MenuButton.Content>.",
+    "MenuButton.Content accepts MenuButtonContent.Header, .Menu, and .Footer or plain Menu items."
+  ]
 }

package/data/docs/components/pickers/MenuButtonContent.json

@@ -438,5 +438,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Only accepts MenuButtonContent.Header, MenuButtonContent.Menu, and MenuButtonContent.Footer as children. If none are provided, all children are wrapped in a Menu automatically.",
+    "Must be used inside a <MenuButton> — requires popover and menu button context."
+  ]
 }

package/data/docs/components/pickers/Select.json

@@ -254,5 +254,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must use compound sub-components: <Select.Trigger> and <Select.Content>.",
+    "Select.Content accepts <Item> components as children for options.",
+    "For searchable/filterable lists, use Combobox instead of Select."
+  ]
 }

package/data/docs/components/popovers/Dialog.json

@@ -110,5 +110,8 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must use compound sub-components: <Dialog.Trigger>, <Dialog.Content>, <Dialog.Title>, etc. Do not pass content as a string prop."
+  ]
 }

package/data/docs/components/popovers/Toggletip.json

@@ -180,5 +180,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must use compound sub-components: <Toggletip.Trigger> and <Toggletip.Content>.",
+    "Trigger and Content sub-components must not be used outside <Toggletip> — they throw if ToggletipContext is missing.",
+    "Use Toggletip instead of Tooltip when content should be triggered by click (not hover) for touch/keyboard accessibility."
+  ]
 }

package/data/docs/components/popovers/Tooltip.json

@@ -117,5 +117,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "usageRules": [
+    "Must use compound sub-components: <Tooltip.Trigger> and <Tooltip.Content>. Do not pass content as a string prop.",
+    "Trigger and Content sub-components must not be used outside <Tooltip> — they throw if TooltipContext is missing."
+  ]
 }