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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/consumer-instructions/.cursorrules +14 -0
  2. package/consumer-instructions/.windsurfrules +18 -4
  3. package/consumer-instructions/CLAUDE.md +25 -11
  4. package/consumer-instructions/redsift-design-system.instructions.md +107 -12
  5. package/data/docs/components/charts/Axis.json +6 -1
  6. package/data/docs/components/charts/BarChart.json +7 -1
  7. package/data/docs/components/charts/BaseBarChart.json +1 -1
  8. package/data/docs/components/charts/ChartContainerTitle.json +5 -1
  9. package/data/docs/components/charts/Legend.json +6 -1
  10. package/data/docs/components/charts/LineChart.json +8 -2
  11. package/data/docs/components/charts/PieChart.json +6 -1
  12. package/data/docs/components/charts/ScatterPlot.json +6 -1
  13. package/data/docs/components/dashboard/ChartEmptyState.json +8 -1
  14. package/data/docs/components/dashboard/Dashboard.json +6 -1
  15. package/data/docs/components/dashboard/DataCard.json +18 -1
  16. package/data/docs/components/dashboard/DataCardBody.json +9 -1
  17. package/data/docs/components/dashboard/DataCardHeader.json +8 -1
  18. package/data/docs/components/dashboard/DataCardListbox.json +10 -1
  19. package/data/docs/components/dashboard/DataRow.json +7 -1
  20. package/data/docs/components/dashboard/PdfExportButton.json +6 -1
  21. package/data/docs/components/dashboard/TimeSeriesBarChart.json +6 -1
  22. package/data/docs/components/dashboard/WithFilters.json +5 -1
  23. package/data/docs/components/design-system/Alert.json +8 -1
  24. package/data/docs/components/design-system/AppBar.json +6 -1
  25. package/data/docs/components/design-system/AppContent.json +8 -1
  26. package/data/docs/components/design-system/AppSidePanel.json +9 -1
  27. package/data/docs/components/design-system/Badge.json +6 -1
  28. package/data/docs/components/design-system/Breadcrumbs.json +10 -1
  29. package/data/docs/components/design-system/Button.json +10 -1
  30. package/data/docs/components/design-system/Card.json +15 -1
  31. package/data/docs/components/design-system/CardActions.json +8 -1
  32. package/data/docs/components/design-system/CardBody.json +7 -1
  33. package/data/docs/components/design-system/CardHeader.json +8 -1
  34. package/data/docs/components/design-system/DetailedCard.json +12 -1
  35. package/data/docs/components/design-system/DetailedCardHeader.json +4 -1
  36. package/data/docs/components/design-system/DetailedCardSection.json +4 -1
  37. package/data/docs/components/design-system/Flexbox.json +14 -1
  38. package/data/docs/components/design-system/Grid.json +6 -1
  39. package/data/docs/components/design-system/Heading.json +16 -1
  40. package/data/docs/components/design-system/Icon.json +6 -1
  41. package/data/docs/components/design-system/IconButton.json +14 -1
  42. package/data/docs/components/design-system/Pill.json +15 -1
  43. package/data/docs/components/design-system/Skeleton.json +10 -1
  44. package/data/docs/components/design-system/SkeletonCircle.json +6 -1
  45. package/data/docs/components/design-system/SkeletonText.json +6 -1
  46. package/data/docs/components/design-system/Tab.json +9 -1
  47. package/data/docs/components/design-system/TabPanel.json +10 -1
  48. package/data/docs/components/design-system/Tabs.json +12 -1
  49. package/data/docs/components/design-system/Text.json +14 -1
  50. package/data/docs/components/design-system/TextField.json +6 -1
  51. package/data/docs/components/pickers/Combobox.json +12 -1
  52. package/data/docs/components/pickers/ComboboxContent.json +6 -1
  53. package/data/docs/components/pickers/MenuButton.json +10 -1
  54. package/data/docs/components/pickers/MenuButtonContent.json +5 -1
  55. package/data/docs/components/pickers/Select.json +11 -1
  56. package/data/docs/components/popovers/Dialog.json +10 -1
  57. package/data/docs/components/popovers/Toggletip.json +11 -1
  58. package/data/docs/components/popovers/Tooltip.json +9 -1
  59. package/data/docs/components/table/DataGrid.json +9 -1
  60. package/data/docs/components/table/StatefulDataGrid.json +6 -1
  61. package/data/docs/components-index.json +341 -555
  62. package/data/docs/components.json +7945 -24342
  63. package/data/docs/llms-full.txt +879 -2546
  64. package/data/docs/llms.txt +55 -77
  65. package/data/docs/patterns-catalog.md +191 -0
  66. package/data/docs/patterns.json +365 -27
  67. package/data/metadata.json +2 -2
  68. package/data/patterns/drilldowned-datagrid-server-side.mdx +19 -0
  69. package/data/prompts/ds-advisor.md +103 -0
  70. package/dist/data-store.d.ts +23 -1
  71. package/dist/data-store.d.ts.map +1 -1
  72. package/dist/data-store.js +69 -15
  73. package/dist/data-store.js.map +1 -1
  74. package/dist/pattern-store.d.ts +23 -1
  75. package/dist/pattern-store.d.ts.map +1 -1
  76. package/dist/pattern-store.js +94 -22
  77. package/dist/pattern-store.js.map +1 -1
  78. package/dist/prompts.d.ts.map +1 -1
  79. package/dist/prompts.js +56 -27
  80. package/dist/prompts.js.map +1 -1
  81. package/dist/resources.d.ts.map +1 -1
  82. package/dist/resources.js +60 -6
  83. package/dist/resources.js.map +1 -1
  84. package/dist/tools.d.ts.map +1 -1
  85. package/dist/tools.js +12 -0
  86. package/dist/tools.js.map +1 -1
  87. package/dist/types.d.ts +11 -0
  88. package/dist/types.d.ts.map +1 -1
  89. package/dist/types.js.map +1 -1
  90. package/package.json +4 -2
@@ -12,22 +12,40 @@ The Red Sift Design System provides reusable UI components including forms, navi
12
12
 
13
13
  ## Packages
14
14
 
15
- - **@redsift/design-system** (63 components): Core UI components (buttons, forms, navigation, layout)
16
- - **@redsift/popovers** (28 components): Popover, tooltip, dialog, and toast components
15
+ - **@redsift/design-system** (61 components): Core UI components (buttons, forms, navigation, layout)
16
+ - **@redsift/popovers** (22 components): Popover, tooltip, dialog, and toast components
17
17
  - **@redsift/pickers** (21 components): Selection components (combobox, menu button, select)
18
- - **@redsift/charts** (32 components): D3.js-based chart components (bar, line, pie, scatter)
18
+ - **@redsift/charts** (14 components): D3.js-based chart components (bar, line, pie, scatter)
19
19
  - **@redsift/table** (8 components): DataGrid components built on MUI X Data Grid
20
- - **@redsift/dashboard** (18 components): Dashboard components with crossfilter integration
21
- - **@redsift/products** (58 components): Product-specific component implementations
20
+ - **@redsift/dashboard** (10 components): Dashboard components with crossfilter integration
21
+ - **@redsift/products** (20 components): Product-specific component implementations
22
22
 
23
23
  ## Components
24
24
 
25
+ > **⚠️ Do NOT import from @mui/material, @mui/icons-material, or @mui/x-data-grid directly.**
26
+ > The Design System wraps or replaces every MUI component you need. Use these DS equivalents:
27
+ >
28
+ > | MUI component | DS equivalent | Package |
29
+ > |---------------|---------------|---------|
30
+ > | `Chip` | `Pill` | @redsift/design-system |
31
+ > | `Tabs` / `Tab` | `Tabs` / `Tab` | @redsift/design-system |
32
+ > | `Skeleton` | `Skeleton` | @redsift/design-system |
33
+ > | `Box` / `Stack` | `Flexbox` | @redsift/design-system |
34
+ > | `Typography` | `Heading` / `Text` | @redsift/design-system |
35
+ > | `Button` | `Button` | @redsift/design-system |
36
+ > | `Alert` | `Alert` | @redsift/design-system |
37
+ > | `Dialog` | `Dialog` | @redsift/popovers |
38
+ > | `Tooltip` | `Tooltip` | @redsift/popovers |
39
+ > | `Select` / `Autocomplete` | `Select` / `Combobox` | @redsift/pickers |
40
+ > | `Card` | `Card` (or `DataCard` for KPIs) | @redsift/design-system / @redsift/dashboard |
41
+ > | `DataGrid` / `DataGridPro` / `DataGridPremium` | `DataGrid` / `StatefulDataGrid` | @redsift/table |
42
+
43
+
25
44
  ### design-system
26
45
 
27
46
  - **ActiveDescendantListbox** (19 props)
28
47
  - **Alert** (7 props): Alert displays a short, important message that attracts the user's attention
29
48
  - **AppBar** (6 props): AppBar is the top navigation bar of the application. It displays the page title
30
- - **AppContainer** (5 props): The AppContainer component.
31
49
  - **AppContent** (11 props): AppContent is the main content area of a Red Sift application. It automatically
32
50
  - **AppSidePanel** (8 props): AppSidePanel is the collapsible side navigation panel of a Red Sift application.
33
51
  - **Badge** (5 props): Badge displays a small status indicator or count. Badges have two variants:
@@ -45,7 +63,6 @@ The Red Sift Design System provides reusable UI components including forms, navi
45
63
  - **CardHeader** (6 props): CardHeader displays the title and optional subtitle of a Card.
46
64
  - **Checkbox** (15 props): Checkbox allows users to select one or more items from a set, or to mark an
47
65
  - **CheckboxGroup** (11 props): CheckboxGroup manages a group of related Checkbox components. It handles
48
- - **ConditionalWrapper** (3 props): ConditionalWrapper conditionally wraps children in a wrapper component.
49
66
  - **DetailedCard** (10 props)
50
67
  - **DetailedCardCollapsibleSectionItems** (2 props): The DetailedCardCollapsibleSectionItems Section component.
51
68
  - **DetailedCardHeader** (3 props): The DetailedCardHeader component.
@@ -95,18 +112,12 @@ The Red Sift Design System provides reusable UI components including forms, navi
95
112
  - **BasePopover** (15 props): Popover displays contextual content anchored to a trigger element.
96
113
  - **BaseToggletip** (17 props): Toggletip displays supplementary content toggled by click/tap.
97
114
  - **BaseTooltip** (11 props): Tooltip displays brief informational text on hover or focus.
98
- - **Button** (12 props)
99
- - **ButtonLink** (11 props)
100
115
  - **Dialog** (10 props)
101
116
  - **DialogContent** (1 props)
102
117
  - **DialogContentActions** (11 props): The DialogContentActions component.
103
118
  - **DialogContentBody** (11 props): The DialogContentBody component.
104
119
  - **DialogContentHeader** (7 props): The DialogContentHeader component.
105
120
  - **DialogTrigger** (0 props): The DialogTrigger component.
106
- - **IconButton** (9 props)
107
- - **IconButtonLink** (13 props)
108
- - **Link** (8 props)
109
- - **LinkButton** (10 props)
110
121
  - **Popover** (15 props)
111
122
  - **PopoverContent** (11 props): The PopoverContent component.
112
123
  - **PopoverTrigger** (0 props): The PopoverTrigger component.
@@ -150,32 +161,14 @@ The Red Sift Design System provides reusable UI components including forms, navi
150
161
  - **Axis** (28 props)
151
162
  - **Bar** (26 props)
152
163
  - **BarChart** (54 props)
153
- - **BarChartBars** (1 props)
154
- - **BarChartGroupedTooltip** (0 props)
155
- - **BarChartOverlay** (3 props)
156
- - **BarChartSection** (9 props)
157
164
  - **BaseBarChart** (54 props): BarChart visualizes categorical data with rectangular bars.
158
165
  - **ChartContainerTitle** (26 props)
159
166
  - **DataPoint** (17 props)
160
167
  - **Dot** (20 props)
161
- - **EmptyBarChart** (54 props)
162
- - **EmptyLineChart** (44 props)
163
- - **EmptyPieChart** (50 props)
164
- - **EmptyScatterPlot** (49 props)
165
168
  - **Legend** (18 props)
166
- - **LegendItem** (13 props)
167
169
  - **Line** (6 props)
168
170
  - **LineChart** (44 props): LineChart displays trends over time or continuous data.
169
- - **LoadingBarChart** (54 props)
170
- - **LoadingLineChart** (44 props)
171
- - **LoadingPieChart** (50 props)
172
- - **LoadingScatterPlot** (49 props)
173
171
  - **PieChart** (50 props): PieChart displays proportional data as slices of a circle.
174
- - **RenderedLinearBarChart** (51 props)
175
- - **RenderedLineChart** (44 props)
176
- - **RenderedOrdinalBarChart** (54 props)
177
- - **RenderedPieChart** (50 props)
178
- - **RenderedScatterPlot** (49 props)
179
172
  - **ScatterPlot** (49 props): ScatterPlot displays relationships between two numeric variables.
180
173
 
181
174
  ### table
@@ -192,84 +185,38 @@ The Red Sift Design System provides reusable UI components including forms, navi
192
185
  ### dashboard
193
186
 
194
187
  - **ChartEmptyState** (4 props)
195
- - **CrossfilteredDashboard.Card** (2 props): CrossfilteredDashboard with attached sub-components.
196
188
  - **Dashboard** (2 props): Dashboard provides a context for connected, filterable visualizations.
197
189
  - **DataCard** (2 props)
198
190
  - **DataCardBody** (11 props): DataCardBody is the main content area of a DataCard.
199
191
  - **DataCardHeader** (3 props): DataCardHeader displays an icon and title that floats on top of
200
192
  - **DataCardListbox** (21 props): DataCardListbox is a styled Listbox for use inside a DataCard.
201
193
  - **DataRow** (13 props): DataRow displays a formatted number alongside a legend label.
202
- - **DrilldownDashboard.Card** (3 props): DrilldownDashboard with attached sub-components.
203
- - **FilterableBarChart** (10 props)
204
- - **FilterableDataCard** (10 props)
205
- - **FilterableDataGrid** (10 props)
206
- - **FilterablePieChart** (10 props)
207
- - **FilterableScatterPlot** (10 props)
208
- - **PdfDocument** (6 props)
209
194
  - **PdfExportButton** (19 props)
210
195
  - **TimeSeriesBarChart** (17 props)
211
196
  - **WithFilters** (10 props)
212
197
 
213
198
  ### products
214
199
 
215
- - **ChartSankey** (0 props): Wrapper component that provides a React-friendly unique ID via useId()
216
- - **CheckBox** (0 props)
217
- - **ChecklistContainer** (0 props)
218
- - **ChecklistRenderer** (4 props): ChecklistRenderer - Renders categorized checklists within DetailedCard sections
219
- - **DeliverabilityDescriptionContainer** (0 props)
220
- - **Dialog** (10 props): RadarDialog displays Radar AI interactions in a branded modal dialog.
221
- - **Dialog** (9 props)
222
- - **DmarcPromoBanner** (4 props): Promotional banner for OnDMARC displayed at the top of the DMARC signal card.
223
- - **DmarcSummaryBoxes** (4 props): DmarcSummaryBoxes renders two side-by-side summary boxes for the DMARC card.
224
- - **ExpandableDescription** (10 props): ExpandableDescription - Isolated description component with its own state
225
- - **ExtractedCategoryContent** (0 props)
226
- - **ExtractedItem** (7 props)
227
- - **ExtractionBox** (0 props)
228
- - **GlossaryTag** (0 props)
229
- - **IconContainer** (0 props)
230
- - **InfoItemContainer** (0 props)
231
- - **LazyChartSankey** (3 props): Lazy-loaded Sankey chart that defers D3 bundle loading until render.
232
- - **MemoizedSankeyChart** (9 props)
233
- - **MenuButton** (22 props): The RadarMenuButton component.
234
- - **MenuButton** (21 props): The RadarSimpleMenuButton component.
235
- - **OpenInNewTabIcon** (0 props)
236
- - **Portal** (2 props)
237
- - **PulsedRadarImage** (0 props)
238
200
  - **RadarButton** (12 props): RadarButton is a pre-styled button for Radar AI features.
239
201
  - **RadarItem** (23 props): The RadarItem component.
240
- - **RecommendationsSummary** (4 props)
241
- - **SignalCard** (8 props): SignalCard is the visual wrapper component for signal cards.
242
202
  - **SignalCardAmp** (10 props): SignalCardAmp Component
243
203
  - **SignalCardBimi** (11 props): SignalCardBimi displays BIMI validation results including DMARC compliance,
244
- - **SignalCardButton** (0 props)
245
204
  - **SignalCardDkim** (10 props)
246
205
  - **SignalCardDkimDomainAnalyzer** (10 props): SignalCardDkimDomainAnalyzer Component
247
206
  - **SignalCardDmarc** (11 props): SignalCardDmarc displays DMARC (Domain-based Message Authentication, Reporting & Conformance)
248
207
  - **SignalCardDmarcDomain** (10 props)
249
208
  - **SignalCardDnssec** (11 props): SignalCardDnssec Component
250
- - **SignalCardErrorBoundary** (5 props): Error boundary component for Signal Cards.
251
- - **SignalCardExtractedItems** (5 props)
252
209
  - **SignalCardFcrdns** (11 props): SignalCardFcrdns Component
253
210
  - **SignalCardGoogleYahooCompliance** (12 props): SignalCardGoogleYahooCompliance Component
254
- - **SignalCardInfoBox** (0 props)
255
211
  - **SignalCardList** (23 props)
256
212
  - **SignalCardMtaSts** (11 props): SignalCardMtaSts displays MTA-STS validation results including TLS-RPT records,
257
- - **SignalCardNormal** (37 props): SignalCardNormal is the base component for all signal cards in the Investigate tool.
258
- - **SignalCardSection** (0 props)
259
213
  - **SignalCardSpf** (10 props)
260
214
  - **SignalCardSpfDomain** (10 props): SignalCardSpfDomain Component
261
215
  - **SignalCardSpfDomainAnalyzer** (10 props): SignalCardSpfDomainAnalyzer Component
262
216
  - **SignalCardSubdo** (10 props): SignalCardSubdo Component
263
217
  - **SignalCardThreatInv** (11 props)
264
218
  - **SignalCardTls** (10 props)
265
- - **SignalCardTlsProps** (0 props): Component props.
266
219
  - **SignalCardUrls** (10 props): SignalCardUrls Component
267
- - **StatusType** (0 props): Status values matching signal-logic's CardStatus union.
268
- - **SVGLogo** (1 props)
269
- - **Tooltip** (6 props)
270
- - **TooltipInPortal** (7 props)
271
- - **TooltipInPortalWrapper** (6 props): Wraps children in a container that will show the tooltip on mouse enter and hide it on mouse leave
272
- - **WordHighlighter** (5 props)
273
220
 
274
221
  ## Links
275
222
 
@@ -295,6 +242,11 @@ Proven component groupings for common UI scenarios, extracted from production ap
295
242
  | Tabbed Datagrid Page | DataGrid, TextCell, Tabs, Tab, Flexbox, Pill, Number | @redsift/table, @redsift/design-system |
296
243
  | Server Tabbed Datagrid Page | DataGrid, TextCell, Tabs, Tab, Flexbox, Pill, Number | @redsift/table, @redsift/design-system, @mui/x-data-grid-pro |
297
244
  | Summary Dashboard | DataCard, DataRow, PieChart, BarChart, Flexbox, Icon, Text | @redsift/dashboard, @redsift/charts, @redsift/design-system |
245
+ | KPI Cards Above Charts | DataCard, DataCardHeader, DataCardBody, DataRow, BarChart, PieChart, ChartContainer, Flexbox, Heading, Text, Skeleton | @redsift/dashboard, @redsift/charts, @redsift/design-system |
246
+ | Chart Empty State | ChartEmptyState, DataCard, DataCardHeader, DataCardBody, Skeleton, Alert, Button, Text | @redsift/dashboard, @redsift/design-system |
247
+ | Error Banner with Retry | Alert, Button, Flexbox, Text | @redsift/design-system |
248
+ | Host App Page Registration | AppContainer, AppSidePanel, AppBar, AppContent | @redsift/design-system |
249
+ | Category Tabs Above Table | Tabs, Tab, TabPanel, DataGrid, Pill, Flexbox | @redsift/design-system, @redsift/table |
298
250
 
299
251
  **Datagrid Page** — when to use:
300
252
  - You need a filterable, sortable, paginated table of records
@@ -363,4 +315,30 @@ Proven component groupings for common UI scenarios, extracted from production ap
363
315
  - Navigation is the primary interaction — no inline filtering
364
316
  - No DataGrid needed on this page
365
317
 
318
+ **KPI Cards Above Charts** — when to use:
319
+ - Building an overview or landing page that shows key metrics at a glance
320
+ - Users need to see aggregate KPIs and trend charts without interactive filtering
321
+ - The page is read-only — clicking a DataRow navigates to a detail page
322
+ - You want a standard two-row layout: metrics on top, charts below
323
+
324
+ **Chart Empty State** — when to use:
325
+ - A chart or DataCard needs to show loading, empty, or error states
326
+ - You want a consistent look across all chart tiles for non-happy-path states
327
+ - The error state should include a retry action
328
+
329
+ **Error Banner with Retry** — when to use:
330
+ - A section of the page failed to load and the user can retry
331
+ - You need an inline error message with an action
332
+ - Replacing a hand-rolled error banner with hardcoded styles
333
+
334
+ **Host App Page Registration** — when to use:
335
+ - Adding a new page or view to a Red Sift application
336
+ - The page needs a sidebar navigation entry
337
+ - The page title must be translated across all supported locales
338
+
339
+ **Category Tabs Above Table** — when to use:
340
+ - You have a fixed, small set of mutually exclusive row categories (typically 2–6 tabs)
341
+ - The category filter is the dominant user action on the page
342
+ - Tabs should mirror an enum field on the row (e.g. status, severity)
343
+
366
344
  For detailed pattern documentation with demos, visit: https://design-system.redsift.io/patterns/
@@ -6,6 +6,61 @@ These patterns serve as implementation specs — they give LLMs and developers e
6
6
 
7
7
  ---
8
8
 
9
+ ## Quick Reference — Component Selection Cheat Sheet
10
+
11
+ Before picking a component, consult this table. It maps common UI intents to the correct component and package.
12
+
13
+ | UI Intent | Component(s) | Package | Do NOT Use |
14
+ | ------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
15
+ | KPI / metric tile (number + label + accent) | `DataCard` + `DataCard.Header` + `DataCard.Body` + `DataRow` | `@redsift/dashboard` | `Card` with inline styles |
16
+ | 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 |
17
+ | Status badge (Trusted / Pass / Fail) | `<Pill color="success\|warning\|error">Label</Pill>` | `@redsift/design-system` | `<Pill label="..." />` or unicode glyphs |
18
+ | Icon-only status indicator | `<Icon>` + `<Tooltip>` | `@redsift/design-system` + `@redsift/popovers` | Unicode characters (✓, ✕, ⚠) |
19
+ | Data grid / table | `DataGrid` | `@redsift/table` | Raw HTML table or MUI DataGrid directly |
20
+ | Loading placeholder | `Skeleton` / `SkeletonText` / `SkeletonCircle` | `@redsift/design-system` | `Skeleton` from `@mui/material` |
21
+ | Collapsible detail panel | `DetailedCard` + `DetailedCardSection` | `@redsift/design-system` | Custom accordion or Card |
22
+ | Generic container | `Card` + `Card.Header` + `Card.Body` | `@redsift/design-system` | Card for KPI tiles (use DataCard) |
23
+ | Modal / confirmation dialog | `Dialog` compound component | `@redsift/popovers` | Custom overlay |
24
+ | Tooltip on hover | `Tooltip` + `Tooltip.Trigger` + `Tooltip.Content` | `@redsift/popovers` | HTML `title` attribute |
25
+ | Dropdown selection | `Select` + `Select.Trigger` + `Select.Content` | `@redsift/pickers` | HTML `<select>` |
26
+ | Searchable selection | `Combobox` compound component | `@redsift/pickers` | Custom autocomplete |
27
+
28
+ ## Global Anti-Patterns
29
+
30
+ These mistakes apply across **all** patterns and components. Avoid them everywhere.
31
+
32
+ ### Semantic Colors — No Hex / RGB Literals
33
+
34
+ - **Wrong:** `color="#22c55e"`, `color="var(--rs-color-green-500, #22c55e)"`
35
+ - **Right:** `color="success"`, `color="warning"`, `color="error"`, `color="info"`
36
+ - DS components accept semantic color values. Never hardcode hex or CSS variable fallbacks.
37
+
38
+ ### Icons — mdi Only, No Unicode
39
+
40
+ - **Wrong:** `✓ Trusted`, `⚠ Warning`, `› Details`
41
+ - **Right:** `<Icon path={mdiCheck} />`, `<Icon path={mdiAlert} />`, `<Icon path={mdiChevronRight} />`
42
+ - Always import from `@redsift/icons`, never from `@mdi/js`.
43
+
44
+ ### DS Primitives over MUI Equivalents
45
+
46
+ - **Wrong:** `import { Skeleton } from '@mui/material'`
47
+ - **Right:** `import { Skeleton } from '@redsift/design-system'`
48
+ - The DS wraps or replaces MUI components. Always use the DS export.
49
+
50
+ ### Flexbox — String Props, No Inline Styles
51
+
52
+ - **Wrong:** `gap={4}`, `style={{ display: 'flex', gap: 4 }}`
53
+ - **Right:** `<Flexbox gap="4px" flexDirection="row" alignItems="center">`
54
+ - Use the `Flexbox` component with string props for layout.
55
+
56
+ ### Pill — Children, Not Label
57
+
58
+ - **Wrong:** `<Pill label="Active" />`
59
+ - **Right:** `<Pill color="success">Active</Pill>`
60
+ - Content goes in `children`. There is no `label` prop.
61
+
62
+ ---
63
+
9
64
  ## Datagrid Page
10
65
 
11
66
  **When to use:**
@@ -609,3 +664,139 @@ type FetchResult = {
609
664
  **Variants:** Loading State, Empty State, Error State
610
665
  **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
611
666
  **Demo:** [Summary Dashboard](/patterns/summary-dashboard)
667
+
668
+ ---
669
+
670
+ ## KPI Cards Above Charts
671
+
672
+ A row of metric tiles (DataCards) followed by one or two chart tiles. The standard Overview page shape across Red Sift products.
673
+
674
+ **When to use:**
675
+
676
+ - Building an overview or landing page showing key metrics at a glance
677
+ - The page is read-only — clicking a DataRow navigates to a detail page
678
+ - Standard two-row layout: KPIs on top, charts below
679
+
680
+ **When NOT to use:**
681
+
682
+ - Users need to cross-filter between cards and a DataGrid — use **Cross-filtered Datagrid Page** instead
683
+ - The page is primarily a table with summary KPIs — use **Drilldown Datagrid Page** instead
684
+
685
+ **Key imports:** `DataCard`, `DataRow`, `BarChart`, `PieChart`, `Flexbox` from `@redsift/dashboard`, `@redsift/charts`, `@redsift/design-system`
686
+
687
+ **Anti-patterns:**
688
+
689
+ - styled.div with inline hex colors for tile borders → use `<DataCard color="success">`
690
+ - `<Card>` for KPI tiles → use `<DataCard>`
691
+ - MUI `Box` / `Stack` for the row layout → use `<Flexbox flexDirection="row" gap="16px">`
692
+
693
+ **Demo:** [/patterns/kpi-cards-above-charts](/patterns/kpi-cards-above-charts)
694
+
695
+ ---
696
+
697
+ ## Chart Empty State
698
+
699
+ 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.
700
+
701
+ **When to use:**
702
+
703
+ - A chart or DataCard needs loading / empty / error states
704
+ - The error state should include a retry action
705
+
706
+ **Key imports:** `ChartEmptyState`, `DataCard` from `@redsift/dashboard`; `Skeleton`, `Alert`, `Button` from `@redsift/design-system`
707
+
708
+ **Anti-patterns:**
709
+
710
+ - styled.div with `border-radius: 4px; background: #f9fafb` for empty state → use `<ChartEmptyState>`
711
+ - `Skeleton` from `@mui/material` → use `Skeleton` from `@redsift/design-system`
712
+ - styled.button for retry → use `<Button variant="secondary">`
713
+
714
+ **Demo:** [/patterns/chart-empty-state](/patterns/chart-empty-state)
715
+
716
+ ---
717
+
718
+ ## Error Banner with Retry
719
+
720
+ Section-level error display with retry button. Replaces hand-rolled styled.button + hex colors with the canonical DS pattern.
721
+
722
+ **When to use:**
723
+
724
+ - A section of the page failed to load and the user can retry
725
+ - Inline error message with a single action
726
+
727
+ **When NOT to use:**
728
+
729
+ - Entire page failed — use a full-page error boundary instead
730
+ - Error inside a chart tile — use **Chart Empty State** pattern instead
731
+
732
+ **Key imports:** `Alert`, `Button` from `@redsift/design-system`
733
+
734
+ **Anti-patterns:**
735
+
736
+ - styled.button with `background: rgba(0,0,0,0.04)` → use `<Button variant="secondary">Retry</Button>`
737
+ - Plain `<div>` with hand-rolled error styling → use `<Alert severity="error">`
738
+ - Custom `rgba(0,0,0,0.12)` borders → use DS tokens via Alert's built-in styling
739
+
740
+ **Demo:** [/patterns/error-banner-with-retry](/patterns/error-banner-with-retry)
741
+
742
+ ---
743
+
744
+ ## Host App Page Registration
745
+
746
+ 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.
747
+
748
+ **When to use:**
749
+
750
+ - Adding a new page or view to a Red Sift application
751
+ - The page needs a sidebar navigation entry
752
+ - The page title must be translated across all supported locales
753
+
754
+ **When NOT to use:**
755
+
756
+ - Rendering a modal or dialog — no route needed
757
+ - A sub-tab within an existing page — handled by the page's `Tabs` component
758
+
759
+ **Anatomy:**
760
+
761
+ 1. **Route definition** — maps a URL path to a page component
762
+ 2. **Navigation entry** — adds an item to `AppSidePanel` with icon, label i18n key, and route path
763
+ 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").
764
+ 4. **Page component** — wrapped in `AppContent`, receives route params
765
+
766
+ **Implementation Checklist:**
767
+
768
+ 1. Define the route path and page component in the app's router configuration
769
+ 2. Add a navigation entry to `AppSidePanel` with the route path and an i18n label key
770
+ 3. Register the page title i18n key in ALL locale files (en-US, fr-FR, etc.)
771
+ 4. Verify the title renders correctly by switching locales
772
+ 5. Import `@redsift/design-system/style/index.css` at the app entry if not already done
773
+
774
+ **Demo:** [/patterns/host-app-page-registration](/patterns/host-app-page-registration)
775
+
776
+ ---
777
+
778
+ ## Category Tabs Above Table
779
+
780
+ 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`.
781
+
782
+ **When to use:**
783
+
784
+ - You have a fixed, small set of mutually exclusive row categories (2–6 tabs)
785
+ - The category filter is the dominant user action on the page
786
+ - Tabs mirror an enum field on the row (status, severity, etc.)
787
+
788
+ **When NOT to use:**
789
+
790
+ - The filter values are dynamic or numerous — use the DataGrid's built-in column filter instead
791
+ - Multiple simultaneous filters are required — Tabs are mutually exclusive by design
792
+ - The categories overlap (a row could be in multiple categories at once)
793
+
794
+ **Anti-patterns:**
795
+
796
+ - `@mui/material` Tabs → use `Tabs` / `Tab` from `@redsift/design-system`
797
+ - `styled(Tab)` to fake a segmented control → DS Tabs already supports the visual variant; check `get_component_props('Tabs')`
798
+ - Separate `<DataGrid>` per tab → one DataGrid, swap `filterModel` based on the active tab
799
+ - Hard-coded counts in tab labels → derive from `rows` so they stay in sync
800
+ - Hiding column filters when tabs are added → tab filters and column filters compose; keep both
801
+
802
+ **Demo:** [/patterns/category-tabs-above-table](/patterns/category-tabs-above-table)