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

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

@@ -15,6 +15,7 @@ This project uses the **Red Sift Design System** (`@redsift/*` packages). The de
 1. Configure the MCP server in `.vscode/mcp.json` — see [MCP Server docs](https://design-system.redsift.io/introduction/mcp-server)
 2. Copy this file to `.github/instructions/` in your project
 3. Verify: ask the AI _"What props does Button accept?"_ — it should call `get_component_props`, not answer from memory
+4. **For automated code generation (Software Factory / agent workflows):** also load the `design-system://prompts/ds-advisor` MCP resource into the system prompt — it contains the component selection cheat sheet, anti-patterns, and disambiguation rules
 
 ## Rule 1 — Mandatory Prop Lookup
 
@@ -54,9 +55,43 @@ When adopting `@redsift/*` components in a new project or migrating from raw HTM
 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.
 
+## Rule 6 — Semantic Colors Only
+
+When setting colors on DS components:
+
+1. **Never use hex/rgb literals** (`#22c55e`, `rgb(34, 197, 94)`) on DS component color props.
+2. **Never use CSS variable fallbacks** like `color="var(--rs-color-green-500, #22c55e)"`.
+3. **Always use semantic color values:** `"success"`, `"warning"`, `"error"`, `"info"`, `"no-data"`, `"question"`, or palette names from `NeutralColorPalette` / `PresentationColorPalette`.
+4. If asked which hex color to use, **refuse** — return the semantic token name instead.
+
+## Rule 7 — Icons from @redsift/icons Only
+
+1. **Never use unicode glyphs** (✓, ✕, ⚠, ›, •) as visual indicators — import the equivalent `mdi*` icon from `@redsift/icons`.
+2. **Never import from `@mdi/js`** — always use `@redsift/icons` (the DS re-exports the mdi icon set).
+3. Render icons with the `<Icon>` component from `@redsift/design-system`, e.g. `<Icon path={mdiCheck} />`.
+
+## Rule 8 — Component Selection
+
+When choosing which component to use, follow this cheat sheet:
+
+| UI Intent                | Correct Component                      | Package                  | Common Mistake                                    |
+| ------------------------ | -------------------------------------- | ------------------------ | ------------------------------------------------- |
+| KPI / metric tile        | `DataCard` + `DataRow`                 | `@redsift/dashboard`     | Using `Card` with inline styles                   |
+| Status badge             | `<Pill color="success">Label</Pill>`   | `@redsift/design-system` | `<Pill label="..." />` (label prop doesn't exist) |
+| Loading placeholder      | `Skeleton` / `SkeletonText`            | `@redsift/design-system` | `Skeleton` from `@mui/material`                   |
+| Collapsible detail panel | `DetailedCard` + `DetailedCardSection` | `@redsift/design-system` | Custom accordion with Card                        |
+| Generic container        | `Card`                                 | `@redsift/design-system` | Using Card for KPI tiles (use DataCard)           |
+| Modal / dialog           | `Dialog` compound component            | `@redsift/popovers`      | Building custom overlay                           |
+
+## Rule 9 — Refusal Rules
+
+1. If asked to provide a hex color for a DS component → **refuse** and return the semantic token name.
+2. If asked to wrap a DS component in `styled-components` to change its visual appearance → **refuse** and propose using the component's built-in props, composition, or filing a DS feature request.
+3. If the requested component does not exist in any `@redsift/*` package → say so and propose the closest existing primitive or composition.
+
 ## NEVER Do This
 
-These are concrete examples of wrong code. **Every single one will fail:**
+These are concrete examples of wrong code. **Every single one will fail or produce incorrect results:**
 
 ```tsx
 // ❌ WRONG — Button has NO size prop
@@ -72,6 +107,46 @@ These are concrete examples of wrong code. **Every single one will fail:**
 
 // ❌ WRONG — wrong package
 import { Select } from '@redsift/design-system';
+
+// ❌ WRONG — Use DataCard for KPI tiles, not Card with inline styles
+<Card style={{ borderLeft: '4px solid green' }}>
+// ✅ RIGHT
+<DataCard color="success">
+
+// ❌ WRONG — Pill uses children, not label
+<Pill label="Active" />
+// ✅ RIGHT
+<Pill color="success">Active</Pill>
+
+// ❌ WRONG — gap takes a string
+<Flexbox gap={4}>
+// ✅ RIGHT
+<Flexbox gap="4px">
+
+// ❌ WRONG — use mdi icons, not unicode characters
+<Text>✓ Trusted</Text>
+// ✅ RIGHT
+<Icon path={mdiCheck} /> <Text>Trusted</Text>
+
+// ❌ WRONG — use DS Skeleton, not MUI
+import { Skeleton } from '@mui/material';
+// ✅ RIGHT
+import { Skeleton } from '@redsift/design-system';
+
+// ❌ WRONG — hex color on DS component
+<Heading color="#22c55e">Title</Heading>
+// ✅ RIGHT
+<Heading color="success">Title</Heading>
+
+// ❌ WRONG — CSS variable fallback on DS component
+<Text color="var(--rs-color-green-500, #22c55e)">Status</Text>
+// ✅ RIGHT
+<Text color="success">Status</Text>
+
+// ❌ WRONG — import from @mdi/js
+import { mdiPlus } from '@mdi/js';
+// ✅ RIGHT
+import { mdiPlus } from '@redsift/icons';
 ```
 
 ## Common Mistakes
@@ -91,6 +166,12 @@ import { Select } from '@redsift/design-system';
 | 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` |
+| `<Pill label="Active" />`                           | `<Pill color="success">Active</Pill>` (children)            | `get_component_props` for Pill             |
+| `<Flexbox gap={4}>`                                 | `<Flexbox gap="4px">` (string, not number)                  | `get_component_props` for Flexbox          |
+| `<Card>` for KPI tiles                              | `<DataCard>` from `@redsift/dashboard`                      | `get_component_props` for DataCard         |
+| `import { Skeleton } from '@mui/material'`          | `import { Skeleton } from '@redsift/design-system'`         | `get_component_usage` for Skeleton         |
+| Hex/rgb colors on DS components                     | Use semantic colors: `"success"`, `"error"`, etc.           | `get_component_props` for the component    |
+| Unicode glyphs (✓, ✕, ⚠) as indicators              | `<Icon path={mdiCheck} />` from `@redsift/icons`            | `get_component_usage` for Icon             |
 
 ## Verification
 

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

@@ -265,5 +265,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "chart axis",
+    "x axis",
+    "y axis"
+  ]
 }

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

@@ -848,5 +848,11 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "bar graph",
+    "histogram",
+    "column chart",
+    "bar visualization"
+  ]
 }

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

@@ -570,5 +570,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "chart title",
+    "chart heading"
+  ]
 }

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

@@ -506,5 +506,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "chart legend",
+    "color legend",
+    "series legend"
+  ]
 }

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

@@ -749,5 +749,11 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "line graph",
+    "time series",
+    "trend chart",
+    "line visualization"
+  ]
 }

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

@@ -822,5 +822,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "pie graph",
+    "donut chart",
+    "pie visualization"
+  ]
 }

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

@@ -798,5 +798,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "scatter graph",
+    "dot plot",
+    "scatter visualization"
+  ]
 }

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

@@ -38,5 +38,12 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "chart loading",
+    "chart empty",
+    "chart error",
+    "empty chart",
+    "no data chart"
+  ]
 }

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

@@ -22,5 +22,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "dashboard page",
+    "dashboard layout",
+    "dashboard container"
+  ]
 }

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

@@ -301,5 +301,17 @@
     "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."
+  ],
+  "disambiguation": "DataCard is a purpose-built KPI/metric tile from @redsift/dashboard. This is the correct component 9 out of 10 times when building \"a card with a big number\" or \"summary cards above a grid\". Do NOT use Card or DetailedCard for this.",
+  "antiPatterns": [
+    "❌ <Card style={{ borderLeft: \"4px solid green\" }}> for KPI tiles → ✅ <DataCard color=\"success\"> — DataCard is purpose-built for metric tiles."
+  ],
+  "keywords": [
+    "kpi tile",
+    "metric tile",
+    "stat card",
+    "kpi card",
+    "summary card",
+    "metric card"
   ]
 }

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

@@ -439,5 +439,9 @@
   "usageRules": [
     "Must be a direct child of <DataCard>. Do not place DataCard.Listbox or DataCard.Header inside DataCard.Body.",
     "Children should be <DataRow> components."
+  ],
+  "keywords": [
+    "metric body",
+    "kpi body"
   ]
 }

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

@@ -303,5 +303,9 @@
   "tags": {},
   "usageRules": [
     "Must be a direct child of <DataCard>, not nested inside DataCard.Body or DataCard.Listbox."
+  ],
+  "keywords": [
+    "metric header",
+    "kpi header"
   ]
 }

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

@@ -537,5 +537,10 @@
   "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."
+  ],
+  "keywords": [
+    "metric listbox",
+    "kpi listbox",
+    "filter listbox"
   ]
 }

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

@@ -576,5 +576,11 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "kpi row",
+    "metric row",
+    "data row",
+    "summary row"
+  ]
 }

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

@@ -454,5 +454,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "export pdf",
+    "download pdf",
+    "print dashboard"
+  ]
 }

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

@@ -168,5 +168,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "time bar chart",
+    "temporal bar chart",
+    "time series bar"
+  ]
 }

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

@@ -98,5 +98,9 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "filter provider",
+    "crossfilter wrapper"
+  ]
 }

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

@@ -345,5 +345,12 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "banner",
+    "notification",
+    "message bar",
+    "info banner",
+    "error banner"
+  ]
 }

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

@@ -60,5 +60,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "top bar",
+    "header bar",
+    "navigation bar"
+  ]
 }

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

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

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

@@ -86,5 +86,10 @@
   "tags": {},
   "usageRules": [
     "Must be a direct child of <AppContainer>. Houses the side navigation."
+  ],
+  "keywords": [
+    "side nav",
+    "sidebar",
+    "navigation panel"
   ]
 }

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

@@ -289,5 +289,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "counter",
+    "count badge",
+    "notification badge"
+  ]
 }

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

@@ -299,5 +299,9 @@
     "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\")."
+  ],
+  "keywords": [
+    "breadcrumb nav",
+    "path navigation"
   ]
 }

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

@@ -402,5 +402,10 @@
   "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\")."
+  ],
+  "keywords": [
+    "action button",
+    "cta",
+    "submit"
   ]
 }

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

@@ -329,5 +329,14 @@
     "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."
+  ],
+  "disambiguation": "Card is a generic container with Header/Body/Actions. Do NOT use for KPI/metric tiles — use DataCard from @redsift/dashboard instead.",
+  "antiPatterns": [
+    "❌ Using Card with inline styles for KPI tiles → ✅ Use DataCard from @redsift/dashboard for metric/KPI tiles."
+  ],
+  "keywords": [
+    "container",
+    "card panel",
+    "content card"
   ]
 }

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

@@ -430,5 +430,9 @@
   "tags": {},
   "usageRules": [
     "Must be a direct child of <Card>."
+  ],
+  "keywords": [
+    "card footer",
+    "card buttons"
   ]
 }

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

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

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

@@ -427,5 +427,9 @@
   "tags": {},
   "usageRules": [
     "Must be a direct child of <Card>."
+  ],
+  "keywords": [
+    "card title",
+    "card heading"
   ]
 }

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

@@ -402,5 +402,11 @@
     "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."
+  ],
+  "disambiguation": "DetailedCard is a complex card with collapsible sections. Use for rich detail panels, not KPI tiles. For KPI tiles use DataCard from @redsift/dashboard.",
+  "keywords": [
+    "expandable card",
+    "collapsible card",
+    "detail panel"
   ]
 }

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

@@ -519,5 +519,18 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "antiPatterns": [
+    "❌ gap={4} → ✅ gap=\"4px\" — gap is a string prop (CSS value), not a number.",
+    "❌ style={{ display: \"flex\", gap: 4 }} → ✅ <Flexbox gap=\"4px\"> — use the Flexbox component instead of inline styles."
+  ],
+  "keywords": [
+    "flex container",
+    "row",
+    "column",
+    "stack",
+    "box",
+    "hstack",
+    "vstack"
+  ]
 }

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

@@ -539,5 +539,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "keywords": [
+    "grid layout",
+    "css grid",
+    "grid container"
+  ]
 }

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

@@ -390,5 +390,16 @@
   "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."
+  ],
+  "antiPatterns": [
+    "❌ color=\"#22c55e\" or color=\"var(--rs-color-green-500)\" → ✅ color=\"success\" — use semantic color values from NeutralColorPalette / NotificationsColorPalette."
+  ],
+  "keywords": [
+    "title",
+    "header text",
+    "section heading",
+    "h1",
+    "h2",
+    "h3"
   ]
 }

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

@@ -321,5 +321,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "disambiguation": "Icon renders an SVG icon from a path string. Always import mdi* icons from @redsift/icons. NEVER use unicode glyphs (✓, ✕, ⚠, ›) and NEVER import from @mdi/js.",
+  "antiPatterns": [
+    "❌ Unicode characters (✓, ✕, ⚠, ›) → ✅ <Icon path={mdiCheck} /> from @redsift/icons.",
+    "❌ import { mdiPlus } from \"@mdi/js\" → ✅ import { mdiPlus } from \"@redsift/icons\"."
+  ]
 }

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

@@ -371,5 +371,14 @@
   "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."
+  ],
+  "disambiguation": "IconButton renders a clickable icon. Requires icon prop (SVG path string). Import icons from @redsift/icons, not @mdi/js.",
+  "antiPatterns": [
+    "❌ Unicode characters as icon content → ✅ icon={mdiPlus} prop with mdi imports from @redsift/icons.",
+    "❌ import { mdiPlus } from \"@mdi/js\" → ✅ import { mdiPlus } from \"@redsift/icons\"."
+  ],
+  "keywords": [
+    "icon action",
+    "toolbar button"
   ]
 }

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

@@ -378,5 +378,15 @@
   "usageRules": [
     "Content via `children`, NOT a `label` prop. Usage: `<Pill color=\"blue\" size=\"small\">Active</Pill>`",
     "The `theme` prop is optional — inherited from context."
+  ],
+  "antiPatterns": [
+    "❌ <Pill label=\"Active\" /> → ✅ <Pill color=\"success\">Active</Pill> — Pill uses children for content, NOT a label prop."
+  ],
+  "keywords": [
+    "chip",
+    "tag",
+    "badge",
+    "label",
+    "status pill"
   ]
 }

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

@@ -334,5 +334,14 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "disambiguation": "Always use Skeleton from @redsift/design-system. NEVER import Skeleton from @mui/material — it will not match the DS theme.",
+  "antiPatterns": [
+    "❌ import { Skeleton } from \"@mui/material\" → ✅ import { Skeleton } from \"@redsift/design-system\" — always use the DS Skeleton."
+  ],
+  "keywords": [
+    "loading placeholder",
+    "shimmer",
+    "skeleton loader"
+  ]
 }

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

@@ -334,5 +334,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "disambiguation": "Use SkeletonCircle from @redsift/design-system for avatar/icon-shaped loading placeholders.",
+  "keywords": [
+    "avatar placeholder",
+    "circle skeleton"
+  ]
 }

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

@@ -367,5 +367,10 @@
     }
   ],
   "examples": [],
-  "tags": {}
+  "tags": {},
+  "disambiguation": "Use SkeletonText from @redsift/design-system for paragraph-shaped loading placeholders.",
+  "keywords": [
+    "text placeholder",
+    "paragraph skeleton"
+  ]
 }

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

@@ -529,5 +529,9 @@
   "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."
+  ],
+  "keywords": [
+    "tab item",
+    "tab button"
   ]
 }

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

@@ -296,5 +296,9 @@
     "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)."
+  ],
+  "keywords": [
+    "tab content",
+    "tab panel"
   ]
 }