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

package/data/docs/components.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "Red Sift Design System",
-  "version": "12.5.3-alpha.5",
-  "generated": "2026-05-11T10:08:07.706Z",
+  "version": "12.5.3-alpha.6",
+  "generated": "2026-05-12T09:42:09.207Z",
   "repository": "https://github.com/redsift/design-system",
   "documentation": "https://design-system.redsift.io",
   "packages": [

package/data/docs/llms-full.txt

@@ -3,7 +3,7 @@
 This file contains comprehensive documentation for all components in the Red Sift Design System.
 It is optimized for LLM consumption and includes props, types, defaults, and usage examples.
 
-Generated: 2026-05-11T10:08:07.700Z
+Generated: 2026-05-12T09:42:09.200Z
 Total Components: 156
 
 ---
@@ -654,6 +654,14 @@ Inherits standard positioning props: `position`, `top`, `bottom`, `left`, `right
 - ⚠️ 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.
+
+#### Common Anti-Patterns
+
+- ❌ Using Card with inline styles for KPI tiles → ✅ Use DataCard from @redsift/dashboard for metric/KPI tiles.
+
 ---
 
 ### CardActions
@@ -927,6 +935,10 @@ Inherits standard positioning props: `position`, `top`, `bottom`, `left`, `right
 - ⚠️ 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.
+
 ---
 
 ### DetailedCardCollapsibleSectionItems
@@ -1063,6 +1075,11 @@ Inherits standard sizing props: `height`, `maxHeight`, `maxWidth`, `minHeight`,
 
 Inherits standard positioning props: `position`, `top`, `bottom`, `left`, `right`, `zIndex`
 
+#### Common Anti-Patterns
+
+- ❌ 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.
+
 ---
 
 ### FocusWithinGroup
@@ -1206,6 +1223,10 @@ Inherits standard positioning props: `position`, `top`, `bottom`, `left`, `right
 - ⚠️ 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.
 
+#### Common Anti-Patterns
+
+- ❌ color="#22c55e" or color="var(--rs-color-green-500)" → ✅ color="success" — use semantic color values from NeutralColorPalette / NotificationsColorPalette.
+
 ---
 
 ### Icon
@@ -1247,6 +1268,15 @@ Inherits standard spacing props: `margin`, `marginBottom`, `marginLeft`, `margin
 
 Inherits standard positioning props: `position`, `top`, `bottom`, `left`, `right`, `zIndex`
 
+#### 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.
+
+#### Common Anti-Patterns
+
+- ❌ Unicode characters (✓, ✕, ⚠, ›) → ✅ <Icon path={mdiCheck} /> from @redsift/icons.
+- ❌ import { mdiPlus } from "@mdi/js" → ✅ import { mdiPlus } from "@redsift/icons".
+
 ---
 
 ### IconButton
@@ -1297,6 +1327,15 @@ Inherits standard positioning props: `position`, `top`, `bottom`, `left`, `right
 - ⚠️ 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.
+
+#### Common Anti-Patterns
+
+- ❌ Unicode characters as icon content → ✅ icon={mdiPlus} prop with mdi imports from @redsift/icons.
+- ❌ import { mdiPlus } from "@mdi/js" → ✅ import { mdiPlus } from "@redsift/icons".
+
 ---
 
 ### IconButtonLink
@@ -1734,6 +1773,10 @@ Inherits standard positioning props: `position`, `top`, `bottom`, `left`, `right
 - ⚠️ Content via `children`, NOT a `label` prop. Usage: `<Pill color="blue" size="small">Active</Pill>`
 - ⚠️ The `theme` prop is optional — inherited from context.
 
+#### Common Anti-Patterns
+
+- ❌ <Pill label="Active" /> → ✅ <Pill color="success">Active</Pill> — Pill uses children for content, NOT a label prop.
+
 ---
 
 ### ProgressBar
@@ -2057,6 +2100,14 @@ Inherits standard sizing props: `height`, `maxHeight`, `maxWidth`, `minHeight`,
 
 Inherits standard positioning props: `position`, `top`, `bottom`, `left`, `right`, `zIndex`
 
+#### Disambiguation
+
+⚠️ Always use Skeleton from @redsift/design-system. NEVER import Skeleton from @mui/material — it will not match the DS theme.
+
+#### Common Anti-Patterns
+
+- ❌ import { Skeleton } from "@mui/material" → ✅ import { Skeleton } from "@redsift/design-system" — always use the DS Skeleton.
+
 ---
 
 ### SkeletonCircle
@@ -2089,6 +2140,10 @@ Inherits standard sizing props: `height`, `maxHeight`, `maxWidth`, `minHeight`,
 
 Inherits standard positioning props: `position`, `top`, `bottom`, `left`, `right`, `zIndex`
 
+#### Disambiguation
+
+⚠️ Use SkeletonCircle from @redsift/design-system for avatar/icon-shaped loading placeholders.
+
 ---
 
 ### SkeletonText
@@ -2124,6 +2179,10 @@ Inherits standard sizing props: `height`, `maxHeight`, `maxWidth`, `minHeight`,
 
 Inherits standard positioning props: `position`, `top`, `bottom`, `left`, `right`, `zIndex`
 
+#### Disambiguation
+
+⚠️ Use SkeletonText from @redsift/design-system for paragraph-shaped loading placeholders.
+
 ---
 
 ### Spinner
@@ -2440,6 +2499,10 @@ Inherits standard positioning props: `position`, `top`, `bottom`, `left`, `right
 - ⚠️ 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.
 
+#### Common Anti-Patterns
+
+- ❌ color="#22c55e" or color="var(--rs-color-green-500)" → ✅ color="success" — use semantic color values from NeutralColorPalette / NotificationsColorPalette.
+
 ---
 
 ### TextArea
@@ -5071,6 +5134,14 @@ Inherits standard positioning props: `position`, `top`, `bottom`, `left`, `right
 - ⚠️ 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.
+
+#### Common Anti-Patterns
+
+- ❌ <Card style={{ borderLeft: "4px solid green" }}> for KPI tiles → ✅ <DataCard color="success"> — DataCard is purpose-built for metric tiles.
+
 ---
 
 ### DataCardBody
@@ -8133,3 +8204,179 @@ export default () => {
 - **drilldown-datagrid-page**: The detail page a summary dashboard typically links to
 - **crossfiltered-datagrid-page**: Interactive version with cross-filtering and a DataGrid
 - **server-crossfiltered-datagrid-page**: Server-driven interactive dashboard
+
+## KPI Cards Above Charts
+**Description:** A row of metric tiles (DataCards) followed by one or two chart tiles, forming a dashboard overview page. Each DataCard shows a key metric; charts visualize trends or distributions. Users scan KPIs then drill into charts. This is the standard layout for 'Overview' pages across Red Sift products.
+**Components:** DataCard, DataCardHeader, DataCardBody, DataRow, BarChart, PieChart, ChartContainer, Flexbox, Heading, Text, Skeleton
+**Packages:** @redsift/dashboard, @redsift/charts, @redsift/design-system
+**Layout:** Flexbox column: top row = Flexbox row wrapping DataCards (flex: 1 each), bottom row = Flexbox row with one or two chart containers. Each DataCard has DataCardHeader + DataCardBody with DataRow children.
+**Tags:** dashboard, kpi, metric, chart, overview, summary, tiles, landing-page
+
+### When to Use
+
+- Building an overview or landing page that shows key metrics at a glance
+- Users need to see aggregate KPIs and trend charts without interactive filtering
+- The page is read-only — clicking a DataRow navigates to a detail page
+- You want a standard two-row layout: metrics on top, charts below
+
+**When NOT to use:**
+
+- Users need to cross-filter between cards and a DataGrid — use Crossfiltered Datagrid Page instead
+- The page is primarily a table with summary KPIs — use Drilldown Datagrid Page instead
+- Only charts, no KPI tiles — use a simple Flexbox of ChartContainers
+
+### Anatomy
+
+1. Heading — Page title
+2. KPI Row — Flexbox row of DataCards, each with DataCardHeader and DataCardBody containing DataRow items
+3. Chart Row — Flexbox row of chart containers (BarChart, PieChart, etc.) wrapped in styled containers with titles
+
+## Chart Empty State
+**Description:** How to render loading, empty, and error states inside a DataCard or ChartContainer. Uses ChartEmptyState from @redsift/dashboard for consistent empty/error messaging, Skeleton for loading shimmer, and Alert + Button for error-with-retry.
+**Components:** ChartEmptyState, DataCard, DataCardHeader, DataCardBody, Skeleton, Alert, Button, Text
+**Packages:** @redsift/dashboard, @redsift/design-system
+**Layout:** DataCard with conditional content: loading (Skeleton), empty (ChartEmptyState), error (Alert + Button), or success (chart content).
+**Tags:** empty-state, loading, error, skeleton, chart, dashboard, retry
+
+### When to Use
+
+- A chart or DataCard needs to show loading, empty, or error states
+- You want a consistent look across all chart tiles for non-happy-path states
+- The error state should include a retry action
+
+**When NOT to use:**
+
+- The component is a DataGrid — DataGrid has its own built-in loading/empty/error overlays
+- You only need a full-page loading spinner — use Spinner instead
+
+### Anatomy
+
+1. DataCard — Container for the chart tile
+2. DataCardHeader — Title of the chart
+3. DataCardBody — Conditional content based on state
+4. Loading: Skeleton components matching the chart shape
+5. Empty: ChartEmptyState with a message and optional illustration
+6. Error: Alert variant='error' + Button variant='secondary' for retry
+
+## Error Banner with Retry
+**Description:** A section-level error display with a retry button, replacing hand-rolled styled.button and hex colors. Uses Alert from @redsift/design-system for the error message and Button variant='secondary' for the retry action. Never use styled.button or hardcoded rgba() values for this pattern.
+**Components:** Alert, Button, Flexbox, Text
+**Packages:** @redsift/design-system
+**Layout:** Flexbox column with Alert at top and optional Button below, or Alert with action prop containing the retry Button.
+**Tags:** error, retry, alert, banner, notification, failure
+
+### When to Use
+
+- A section of the page failed to load and the user can retry
+- You need an inline error message with an action
+- Replacing a hand-rolled error banner with hardcoded styles
+
+**When NOT to use:**
+
+- The entire page failed — use a full-page error boundary instead
+- The error is inside a chart tile — use Chart Empty State pattern instead
+
+### Anatomy
+
+1. Alert — Displays the error message with severity='error'
+2. Button — 'Retry' button with variant='secondary' and onClick handler
+
+## Host App Page Registration
+**Description:** Abstract contract for adding a new page to a Red Sift host application. Every new page requires a routing entry, a navigation entry in the sidebar, and a page title registered as an i18n key in ALL supported locales. Missing any locale mirror causes the page title to show as a raw key string. This is a framework pattern — concrete implementation depends on the host app's router and i18n system.
+**Components:** AppContainer, AppSidePanel, AppBar, AppContent
+**Packages:** @redsift/design-system
+**Layout:** AppContainer > AppSidePanel (nav entry) + AppContent (routed page component). AppBar displays the page title from i18n.
+**Tags:** host-app, page, routing, navigation, i18n, locale, title, setup
+
+### When to Use
+
+- Adding a new page or view to a Red Sift application
+- The page needs a sidebar navigation entry
+- The page title must be translated across all supported locales
+
+**When NOT to use:**
+
+- Rendering a modal or dialog — no route needed
+- A sub-tab within an existing page — handled by the page's Tabs component
+
+### Anatomy
+
+1. Route definition — maps a URL path to a page component
+2. Navigation entry — adds an item to AppSidePanel with icon, label i18n key, and route path
+3. Page title i18n key — registered in EVERY locale file (e.g. en-US.json, fr-FR.json). If any locale is missing the key, the title renders as the raw key string.
+4. Page component — wrapped in AppContent, receives route params
+
+### Implementation Checklist
+
+1. Define the route path and page component in the app's router configuration
+2. Add a navigation entry to AppSidePanel with the route path and an i18n label key
+3. Register the page title i18n key in ALL locale files (en-US, fr-FR, etc.)
+4. Verify the title renders correctly by switching locales
+5. Import @redsift/design-system/style/index.css at the app entry if not already done
+
+## Category Tabs Above Table
+**Description:** A row of Tabs above a DataGrid that filter the grid's rows by a category (e.g. All / Active / Expired / Critical). The selected tab becomes part of the grid's filterModel. Use this pattern when you have a small, well-known set of mutually exclusive row categories — it is a UX shortcut for the most common filter on the page. For arbitrary or many-valued filters, use the DataGrid's built-in column filter UI instead.
+**Components:** Tabs, Tab, TabPanel, DataGrid, Pill, Flexbox
+**Packages:** @redsift/design-system, @redsift/table
+**Layout:** Flexbox column: Tabs row + DataGrid below. Tabs are sticky-positioned above the grid; the active Tab drives a filterModel applied to the DataGrid.
+**Tags:** tabs, datagrid, filter, category, status-filter, segmented-control
+
+### When to Use
+
+- You have a fixed, small set of mutually exclusive row categories (typically 2–6 tabs)
+- The category filter is the dominant user action on the page
+- Tabs should mirror an enum field on the row (e.g. status, severity)
+
+**When NOT to use:**
+
+- The filter values are dynamic or numerous — use the DataGrid's built-in column filter instead
+- Multiple simultaneous filters are required — Tabs are mutually exclusive by design
+- The categories themselves are not orthogonal (overlapping memberships)
+
+### Anatomy
+
+1. Tabs — DS Tabs from @redsift/design-system, one Tab per category plus an 'All' tab
+2. Optional Pill — count badge inside each Tab label (e.g. 'Active (12)')
+3. DataGrid — receives filterModel derived from the active tab
+
+### State Management
+
+| Hook | Type | Initial | Description |
+|------|------|---------|-------------|
+| activeTab | string | 'all' | Slug of the currently selected tab; drives the DataGrid filterModel. |
+
+### Data Contract
+
+```tsx
+type Row = {
+  id: string;
+  status: 'active' | 'warning' | 'critical' | 'expired';
+  // …other fields
+};
+
+// activeTab → filterModel mapping
+const filterModelForTab = (tab: string): GridFilterModel =>
+  tab === 'all'
+    ? { items: [] }
+    : { items: [{ columnField: 'status', operatorValue: 'equals', value: tab }] };
+```
+
+### Implementation Checklist
+
+1. Define the tab list as a const array of { slug, label, filterValue } entries — one per category plus 'all'.
+2. Add useState<string>('all') for activeTab.
+3. Render <Tabs value={activeTab} onChange={setActiveTab}> with one <Tab> per entry. Inside the label, optionally show a count <Pill>.
+4. Compute filterModel from activeTab via a pure helper.
+5. Pass filterModel into <DataGrid filterModel={...} onFilterModelChange={...}>. Keep the DataGrid's own filter UI enabled so users can layer column filters on top.
+6. Sync activeTab to the URL query string (?status=active) for shareable links.
+
+### Keyboard & Accessibility
+
+- Tabs and Tab from @redsift/design-system already wire role="tablist" / role="tab" and arrow-key navigation
+- Use aria-controls to associate each Tab with the DataGrid id
+- Do not hide the DataGrid's built-in column filter — tab filters are a shortcut, not a replacement
+
+### Related Patterns
+
+- **datagrid-page**: The underlying full-page grid. Add tabs on top when one enum field dominates filtering.
+- **tabbed-datagrid-client-side**: Closely related; this pattern is specifically the 'category filter' variant.

package/data/docs/llms.txt

@@ -22,6 +22,25 @@ The Red Sift Design System provides reusable UI components including forms, navi
 
 ## Components
 
+> **⚠️ Do NOT import from @mui/material, @mui/icons-material, or @mui/x-data-grid directly.**
+> The Design System wraps or replaces every MUI component you need. Use these DS equivalents:
+>
+> | MUI component | DS equivalent | Package |
+> |---------------|---------------|---------|
+> | `Chip` | `Pill` | @redsift/design-system |
+> | `Tabs` / `Tab` | `Tabs` / `Tab` | @redsift/design-system |
+> | `Skeleton` | `Skeleton` | @redsift/design-system |
+> | `Box` / `Stack` | `Flexbox` | @redsift/design-system |
+> | `Typography` | `Heading` / `Text` | @redsift/design-system |
+> | `Button` | `Button` | @redsift/design-system |
+> | `Alert` | `Alert` | @redsift/design-system |
+> | `Dialog` | `Dialog` | @redsift/popovers |
+> | `Tooltip` | `Tooltip` | @redsift/popovers |
+> | `Select` / `Autocomplete` | `Select` / `Combobox` | @redsift/pickers |
+> | `Card` | `Card` (or `DataCard` for KPIs) | @redsift/design-system / @redsift/dashboard |
+> | `DataGrid` / `DataGridPro` / `DataGridPremium` | `DataGrid` / `StatefulDataGrid` | @redsift/table |
+
+
 ### design-system
 
 - **ActiveDescendantListbox** (19 props)
@@ -223,6 +242,11 @@ Proven component groupings for common UI scenarios, extracted from production ap
 | Tabbed Datagrid Page | DataGrid, TextCell, Tabs, Tab, Flexbox, Pill, Number | @redsift/table, @redsift/design-system |
 | Server Tabbed Datagrid Page | DataGrid, TextCell, Tabs, Tab, Flexbox, Pill, Number | @redsift/table, @redsift/design-system, @mui/x-data-grid-pro |
 | Summary Dashboard | DataCard, DataRow, PieChart, BarChart, Flexbox, Icon, Text | @redsift/dashboard, @redsift/charts, @redsift/design-system |
+| KPI Cards Above Charts | DataCard, DataCardHeader, DataCardBody, DataRow, BarChart, PieChart, ChartContainer, Flexbox, Heading, Text, Skeleton | @redsift/dashboard, @redsift/charts, @redsift/design-system |
+| Chart Empty State | ChartEmptyState, DataCard, DataCardHeader, DataCardBody, Skeleton, Alert, Button, Text | @redsift/dashboard, @redsift/design-system |
+| Error Banner with Retry | Alert, Button, Flexbox, Text | @redsift/design-system |
+| Host App Page Registration | AppContainer, AppSidePanel, AppBar, AppContent | @redsift/design-system |
+| Category Tabs Above Table | Tabs, Tab, TabPanel, DataGrid, Pill, Flexbox | @redsift/design-system, @redsift/table |
 
 **Datagrid Page** — when to use:
 - You need a filterable, sortable, paginated table of records
@@ -291,4 +315,30 @@ Proven component groupings for common UI scenarios, extracted from production ap
 - Navigation is the primary interaction — no inline filtering
 - No DataGrid needed on this page
 
+**KPI Cards Above Charts** — when to use:
+- Building an overview or landing page that shows key metrics at a glance
+- Users need to see aggregate KPIs and trend charts without interactive filtering
+- The page is read-only — clicking a DataRow navigates to a detail page
+- You want a standard two-row layout: metrics on top, charts below
+
+**Chart Empty State** — when to use:
+- A chart or DataCard needs to show loading, empty, or error states
+- You want a consistent look across all chart tiles for non-happy-path states
+- The error state should include a retry action
+
+**Error Banner with Retry** — when to use:
+- A section of the page failed to load and the user can retry
+- You need an inline error message with an action
+- Replacing a hand-rolled error banner with hardcoded styles
+
+**Host App Page Registration** — when to use:
+- Adding a new page or view to a Red Sift application
+- The page needs a sidebar navigation entry
+- The page title must be translated across all supported locales
+
+**Category Tabs Above Table** — when to use:
+- You have a fixed, small set of mutually exclusive row categories (typically 2–6 tabs)
+- The category filter is the dominant user action on the page
+- Tabs should mirror an enum field on the row (e.g. status, severity)
+
 For detailed pattern documentation with demos, visit: https://design-system.redsift.io/patterns/

package/data/docs/patterns-catalog.md

@@ -6,6 +6,61 @@ These patterns serve as implementation specs — they give LLMs and developers e
 
 ---
 
+## Quick Reference — Component Selection Cheat Sheet
+
+Before picking a component, consult this table. It maps common UI intents to the correct component and package.
+
+| UI Intent                                   | Component(s)                                                                      | Package                                         | Do NOT Use                               |
+| ------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
+| KPI / metric tile (number + label + accent) | `DataCard` + `DataCard.Header` + `DataCard.Body` + `DataRow`                      | `@redsift/dashboard`                            | `Card` with inline styles                |
+| Set of KPI tiles above a grid               | `<Flexbox flexDirection="row" flexWrap="wrap" gap="0">` wrapping `DataCard` tiles | `@redsift/dashboard` + `@redsift/design-system` | CSS Grid or inline flex styles           |
+| Status badge (Trusted / Pass / Fail)        | `<Pill color="success\|warning\|error">Label</Pill>`                              | `@redsift/design-system`                        | `<Pill label="..." />` or unicode glyphs |
+| Icon-only status indicator                  | `<Icon>` + `<Tooltip>`                                                            | `@redsift/design-system` + `@redsift/popovers`  | Unicode characters (✓, ✕, ⚠)             |
+| Data grid / table                           | `DataGrid`                                                                        | `@redsift/table`                                | Raw HTML table or MUI DataGrid directly  |
+| Loading placeholder                         | `Skeleton` / `SkeletonText` / `SkeletonCircle`                                    | `@redsift/design-system`                        | `Skeleton` from `@mui/material`          |
+| Collapsible detail panel                    | `DetailedCard` + `DetailedCardSection`                                            | `@redsift/design-system`                        | Custom accordion or Card                 |
+| Generic container                           | `Card` + `Card.Header` + `Card.Body`                                              | `@redsift/design-system`                        | Card for KPI tiles (use DataCard)        |
+| Modal / confirmation dialog                 | `Dialog` compound component                                                       | `@redsift/popovers`                             | Custom overlay                           |
+| Tooltip on hover                            | `Tooltip` + `Tooltip.Trigger` + `Tooltip.Content`                                 | `@redsift/popovers`                             | HTML `title` attribute                   |
+| Dropdown selection                          | `Select` + `Select.Trigger` + `Select.Content`                                    | `@redsift/pickers`                              | HTML `<select>`                          |
+| Searchable selection                        | `Combobox` compound component                                                     | `@redsift/pickers`                              | Custom autocomplete                      |
+
+## Global Anti-Patterns
+
+These mistakes apply across **all** patterns and components. Avoid them everywhere.
+
+### Semantic Colors — No Hex / RGB Literals
+
+- **Wrong:** `color="#22c55e"`, `color="var(--rs-color-green-500, #22c55e)"`
+- **Right:** `color="success"`, `color="warning"`, `color="error"`, `color="info"`
+- DS components accept semantic color values. Never hardcode hex or CSS variable fallbacks.
+
+### Icons — mdi Only, No Unicode
+
+- **Wrong:** `✓ Trusted`, `⚠ Warning`, `› Details`
+- **Right:** `<Icon path={mdiCheck} />`, `<Icon path={mdiAlert} />`, `<Icon path={mdiChevronRight} />`
+- Always import from `@redsift/icons`, never from `@mdi/js`.
+
+### DS Primitives over MUI Equivalents
+
+- **Wrong:** `import { Skeleton } from '@mui/material'`
+- **Right:** `import { Skeleton } from '@redsift/design-system'`
+- The DS wraps or replaces MUI components. Always use the DS export.
+
+### Flexbox — String Props, No Inline Styles
+
+- **Wrong:** `gap={4}`, `style={{ display: 'flex', gap: 4 }}`
+- **Right:** `<Flexbox gap="4px" flexDirection="row" alignItems="center">`
+- Use the `Flexbox` component with string props for layout.
+
+### Pill — Children, Not Label
+
+- **Wrong:** `<Pill label="Active" />`
+- **Right:** `<Pill color="success">Active</Pill>`
+- Content goes in `children`. There is no `label` prop.
+
+---
+
 ## Datagrid Page
 
 **When to use:**
@@ -609,3 +664,139 @@ type FetchResult = {
 **Variants:** Loading State, Empty State, Error State
 **Related:** Drilldown Datagrid Page — the detail page a summary dashboard typically links to; Cross-filtered Datagrid Page — interactive version with cross-filtering and a DataGrid
 **Demo:** [Summary Dashboard](/patterns/summary-dashboard)
+
+---
+
+## KPI Cards Above Charts
+
+A row of metric tiles (DataCards) followed by one or two chart tiles. The standard Overview page shape across Red Sift products.
+
+**When to use:**
+
+- Building an overview or landing page showing key metrics at a glance
+- The page is read-only — clicking a DataRow navigates to a detail page
+- Standard two-row layout: KPIs on top, charts below
+
+**When NOT to use:**
+
+- Users need to cross-filter between cards and a DataGrid — use **Cross-filtered Datagrid Page** instead
+- The page is primarily a table with summary KPIs — use **Drilldown Datagrid Page** instead
+
+**Key imports:** `DataCard`, `DataRow`, `BarChart`, `PieChart`, `Flexbox` from `@redsift/dashboard`, `@redsift/charts`, `@redsift/design-system`
+
+**Anti-patterns:**
+
+- styled.div with inline hex colors for tile borders → use `<DataCard color="success">`
+- `<Card>` for KPI tiles → use `<DataCard>`
+- MUI `Box` / `Stack` for the row layout → use `<Flexbox flexDirection="row" gap="16px">`
+
+**Demo:** [/patterns/kpi-cards-above-charts](/patterns/kpi-cards-above-charts)
+
+---
+
+## Chart Empty State
+
+Loading, empty, and error states inside a DataCard or ChartContainer. Uses `ChartEmptyState` for consistent messaging, `Skeleton` for loading shimmer, and `Alert` + `Button` for error-with-retry.
+
+**When to use:**
+
+- A chart or DataCard needs loading / empty / error states
+- The error state should include a retry action
+
+**Key imports:** `ChartEmptyState`, `DataCard` from `@redsift/dashboard`; `Skeleton`, `Alert`, `Button` from `@redsift/design-system`
+
+**Anti-patterns:**
+
+- styled.div with `border-radius: 4px; background: #f9fafb` for empty state → use `<ChartEmptyState>`
+- `Skeleton` from `@mui/material` → use `Skeleton` from `@redsift/design-system`
+- styled.button for retry → use `<Button variant="secondary">`
+
+**Demo:** [/patterns/chart-empty-state](/patterns/chart-empty-state)
+
+---
+
+## Error Banner with Retry
+
+Section-level error display with retry button. Replaces hand-rolled styled.button + hex colors with the canonical DS pattern.
+
+**When to use:**
+
+- A section of the page failed to load and the user can retry
+- Inline error message with a single action
+
+**When NOT to use:**
+
+- Entire page failed — use a full-page error boundary instead
+- Error inside a chart tile — use **Chart Empty State** pattern instead
+
+**Key imports:** `Alert`, `Button` from `@redsift/design-system`
+
+**Anti-patterns:**
+
+- styled.button with `background: rgba(0,0,0,0.04)` → use `<Button variant="secondary">Retry</Button>`
+- Plain `<div>` with hand-rolled error styling → use `<Alert severity="error">`
+- Custom `rgba(0,0,0,0.12)` borders → use DS tokens via Alert's built-in styling
+
+**Demo:** [/patterns/error-banner-with-retry](/patterns/error-banner-with-retry)
+
+---
+
+## Host App Page Registration
+
+Abstract contract for adding a new page to a Red Sift host application. Every new page requires three things: a routing entry, a sidebar nav entry, and a page title registered as an i18n key in ALL supported locales.
+
+**When to use:**
+
+- Adding a new page or view to a Red Sift application
+- The page needs a sidebar navigation entry
+- The page title must be translated across all supported locales
+
+**When NOT to use:**
+
+- Rendering a modal or dialog — no route needed
+- A sub-tab within an existing page — handled by the page's `Tabs` component
+
+**Anatomy:**
+
+1. **Route definition** — maps a URL path to a page component
+2. **Navigation entry** — adds an item to `AppSidePanel` with icon, label i18n key, and route path
+3. **Page title i18n key** — registered in EVERY locale file (e.g. `en-US.json`, `fr-FR.json`). **If any locale is missing the key, the title renders as the raw key string** (e.g. "page.dashboard.title" instead of "Dashboard").
+4. **Page component** — wrapped in `AppContent`, receives route params
+
+**Implementation Checklist:**
+
+1. Define the route path and page component in the app's router configuration
+2. Add a navigation entry to `AppSidePanel` with the route path and an i18n label key
+3. Register the page title i18n key in ALL locale files (en-US, fr-FR, etc.)
+4. Verify the title renders correctly by switching locales
+5. Import `@redsift/design-system/style/index.css` at the app entry if not already done
+
+**Demo:** [/patterns/host-app-page-registration](/patterns/host-app-page-registration)
+
+---
+
+## Category Tabs Above Table
+
+A `Tabs` row above a `DataGrid` that filters rows by a category enum (typically All / Active / Warning / Expired). The selected tab becomes part of the grid's `filterModel`.
+
+**When to use:**
+
+- You have a fixed, small set of mutually exclusive row categories (2–6 tabs)
+- The category filter is the dominant user action on the page
+- Tabs mirror an enum field on the row (status, severity, etc.)
+
+**When NOT to use:**
+
+- The filter values are dynamic or numerous — use the DataGrid's built-in column filter instead
+- Multiple simultaneous filters are required — Tabs are mutually exclusive by design
+- The categories overlap (a row could be in multiple categories at once)
+
+**Anti-patterns:**
+
+- `@mui/material` Tabs → use `Tabs` / `Tab` from `@redsift/design-system`
+- `styled(Tab)` to fake a segmented control → DS Tabs already supports the visual variant; check `get_component_props('Tabs')`
+- Separate `<DataGrid>` per tab → one DataGrid, swap `filterModel` based on the active tab
+- Hard-coded counts in tab labels → derive from `rows` so they stay in sync
+- Hiding column filters when tabs are added → tab filters and column filters compose; keep both
+
+**Demo:** [/patterns/category-tabs-above-table](/patterns/category-tabs-above-table)