@peerproblem/sw3-ui 0.0.0-stage → 0.3.0

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 (144) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +109 -2
  3. package/agent/components/accordion.md +95 -0
  4. package/agent/components/action-square.md +106 -0
  5. package/agent/components/agent-bridge.md +87 -0
  6. package/agent/components/agent-console.md +123 -0
  7. package/agent/components/alert-dialog.md +82 -0
  8. package/agent/components/app-shell.md +105 -0
  9. package/agent/components/area-chart.md +56 -0
  10. package/agent/components/async-options.md +47 -0
  11. package/agent/components/autocomplete.md +69 -0
  12. package/agent/components/avatar.md +88 -0
  13. package/agent/components/badge.md +51 -0
  14. package/agent/components/bar-chart.md +56 -0
  15. package/agent/components/bar-list.md +49 -0
  16. package/agent/components/breadcrumbs.md +43 -0
  17. package/agent/components/button.md +109 -0
  18. package/agent/components/calendar.md +114 -0
  19. package/agent/components/canvas.md +105 -0
  20. package/agent/components/card.md +78 -0
  21. package/agent/components/carousel.md +113 -0
  22. package/agent/components/chart-card.md +41 -0
  23. package/agent/components/chart-surface.md +56 -0
  24. package/agent/components/checkbox.md +88 -0
  25. package/agent/components/citation-chip.md +61 -0
  26. package/agent/components/collapsible.md +69 -0
  27. package/agent/components/color-picker.md +82 -0
  28. package/agent/components/combobox.md +104 -0
  29. package/agent/components/command.md +92 -0
  30. package/agent/components/dashboard-grid.md +73 -0
  31. package/agent/components/date-input.md +87 -0
  32. package/agent/components/date-picker.md +122 -0
  33. package/agent/components/dialog.md +97 -0
  34. package/agent/components/donut-chart.md +50 -0
  35. package/agent/components/drawer.md +101 -0
  36. package/agent/components/empty-state.md +52 -0
  37. package/agent/components/field.md +80 -0
  38. package/agent/components/file-input.md +84 -0
  39. package/agent/components/hover-card.md +64 -0
  40. package/agent/components/image-cropper.md +77 -0
  41. package/agent/components/input.md +49 -0
  42. package/agent/components/label.md +53 -0
  43. package/agent/components/line-chart.md +60 -0
  44. package/agent/components/listbox.md +84 -0
  45. package/agent/components/map-view.md +104 -0
  46. package/agent/components/menu.md +117 -0
  47. package/agent/components/menubar.md +67 -0
  48. package/agent/components/meter.md +59 -0
  49. package/agent/components/navigation-menu.md +98 -0
  50. package/agent/components/number-input.md +81 -0
  51. package/agent/components/otp-input.md +67 -0
  52. package/agent/components/pagination.md +80 -0
  53. package/agent/components/password-input.md +67 -0
  54. package/agent/components/pill-button.md +116 -0
  55. package/agent/components/popover.md +85 -0
  56. package/agent/components/poster-card.md +61 -0
  57. package/agent/components/preferences.md +92 -0
  58. package/agent/components/progress.md +63 -0
  59. package/agent/components/provider.md +47 -0
  60. package/agent/components/radio.md +91 -0
  61. package/agent/components/rating.md +66 -0
  62. package/agent/components/reorder.md +61 -0
  63. package/agent/components/resizable.md +87 -0
  64. package/agent/components/scatter-chart.md +49 -0
  65. package/agent/components/scroll-area.md +81 -0
  66. package/agent/components/segmented-control.md +56 -0
  67. package/agent/components/select.md +130 -0
  68. package/agent/components/separator.md +60 -0
  69. package/agent/components/shortcuts.md +50 -0
  70. package/agent/components/sidebar-nav.md +68 -0
  71. package/agent/components/skeleton.md +58 -0
  72. package/agent/components/slider.md +79 -0
  73. package/agent/components/sparkline.md +39 -0
  74. package/agent/components/squircle.md +58 -0
  75. package/agent/components/stat.md +58 -0
  76. package/agent/components/switch.md +48 -0
  77. package/agent/components/table.md +58 -0
  78. package/agent/components/tabs.md +108 -0
  79. package/agent/components/textarea.md +68 -0
  80. package/agent/components/time-input.md +84 -0
  81. package/agent/components/timeline.md +91 -0
  82. package/agent/components/toast.md +85 -0
  83. package/agent/components/toggle.md +76 -0
  84. package/agent/components/token-input.md +66 -0
  85. package/agent/components/toolbar.md +76 -0
  86. package/agent/components/tooltip.md +83 -0
  87. package/agent/components/tracker.md +47 -0
  88. package/agent/components/tree.md +87 -0
  89. package/agent/components/treemap.md +72 -0
  90. package/agent/components/trend-chart.md +80 -0
  91. package/agent/components/trigger-menu.md +67 -0
  92. package/agent/components/typography.md +51 -0
  93. package/agent/components/waterfall.md +78 -0
  94. package/agent/components/week-schedule.md +113 -0
  95. package/agent/llms/actions-and-layout.txt +1749 -0
  96. package/agent/llms/agents.txt +505 -0
  97. package/agent/llms/charts.txt +778 -0
  98. package/agent/llms/dashboards.txt +457 -0
  99. package/agent/llms/extend.txt +132 -0
  100. package/agent/llms/extras.txt +527 -0
  101. package/agent/llms/forms.txt +2152 -0
  102. package/agent/llms/foundations.txt +674 -0
  103. package/agent/llms/hooks.txt +178 -0
  104. package/agent/llms/maps.txt +229 -0
  105. package/agent/llms/overlays-and-navigation.txt +1167 -0
  106. package/agent/llms-full.txt +8717 -0
  107. package/agent/llms.txt +145 -0
  108. package/agent/registry.json +11289 -0
  109. package/agent/tokens.md +66 -0
  110. package/dist/agent/index.d.ts +235 -0
  111. package/dist/agent/index.js +21 -0
  112. package/dist/card-Ipm-Cj5f.d.ts +490 -0
  113. package/dist/charts/index.d.ts +289 -0
  114. package/dist/charts/index.js +815 -0
  115. package/dist/check/cli.d.ts +1 -0
  116. package/dist/check/cli.js +48 -0
  117. package/dist/check/rendered.d.ts +11 -0
  118. package/dist/check/rendered.js +77 -0
  119. package/dist/check/source.d.ts +13 -0
  120. package/dist/check/source.js +182 -0
  121. package/dist/chunk-3DXBM65D.js +65 -0
  122. package/dist/chunk-3H5X4ZP6.js +55 -0
  123. package/dist/chunk-6XC4BC5C.js +92 -0
  124. package/dist/chunk-7H6TEAWD.js +507 -0
  125. package/dist/chunk-I63ZTJOI.js +1089 -0
  126. package/dist/chunk-JCIRUM4W.js +33 -0
  127. package/dist/chunk-LTBEHZ3P.js +25 -0
  128. package/dist/chunk-QDPPLO4U.js +60 -0
  129. package/dist/chunk-U2XFBPU4.js +56 -0
  130. package/dist/chunk-UY2WH5AY.js +681 -0
  131. package/dist/extras.d.ts +203 -0
  132. package/dist/extras.js +904 -0
  133. package/dist/icons-BJiGEAnU.d.ts +68 -0
  134. package/dist/index.d.ts +3737 -0
  135. package/dist/index.js +14477 -0
  136. package/dist/map/index.d.ts +115 -0
  137. package/dist/map/index.js +394 -0
  138. package/dist/meta/index.d.ts +3314 -0
  139. package/dist/meta/index.js +5106 -0
  140. package/dist/rules-1RIZ_JZr.d.ts +38 -0
  141. package/dist/styles.css +4037 -0
  142. package/dist/themes/calm.css +42 -0
  143. package/dist/themes/frost.css +40 -0
  144. package/package.json +142 -4
@@ -0,0 +1,457 @@
1
+ # SW3 UI SDK · Dashboards
2
+
3
+ > AppShell, SidebarNav, DashboardGrid: dashboard frame, density, list interactions and chart choice per tile.
4
+
5
+ Setup: `import "@peerproblem/sw3-ui/styles.css"` once, wrap the app in `<SwProvider>`, add `className="sw-root"` to the page. Charts: `@peerproblem/sw3-ui/charts`. Maps: `@peerproblem/sw3-ui/map`.
6
+ Optional peers: install `@unovis/react@~1.8.1 @unovis/ts@~1.8.1 d3-hierarchy@^3.1.0` for charts or `maplibre-gl@^6.18.0` for maps.
7
+ Index of all topics and components: llms.txt.
8
+
9
+ ---
10
+
11
+ # Dashboards
12
+
13
+ A dashboard is one frame split by lines, not cards scattered across gutters. Only four pieces are dashboard-specific: `AppShell`, `SidebarNav`, `DashboardGrid` (with `DashboardTile` and `DashboardSection`) and `Breadcrumbs`. Everything inside them is the ordinary kit. See the full composition under Blocks (`#/blocks`) in the playground.
14
+
15
+ ## Which component for which job
16
+
17
+ | Job | Use |
18
+ | --- | --- |
19
+ | Dashboard title and navigation | One `AppShellHeader` with the logo and title on the left, and compact dashboard, site and account controls on the right |
20
+ | Tile, side panel, list box | `Card` with `title` (the panel layout: 40px header bar, toolbar, body, footer), or `DashboardTile` inside a grid |
21
+ | A stack of foldable panels (inspector, side column) | `Accordion size="sm" multiple fill` |
22
+ | KPI row | `Tabs variant="metric"` with one `Stat size="sm"` per tab. If the panel needs a chart, choose it for the selected metric's question and data |
23
+ | Data list (select, act, reorder) | `Listbox` with `framed={false}` (automatic inside a Card) plus `meta`, `actions`, `onItemAction`, `onReorder` |
24
+ | Search in a toolbar | `ToolbarInput`, or `Input type="search" size="xs" variant="filled" clearable` |
25
+ | Sort | A `Menu` with radio groups behind an xs ghost `Button`, with state from `useListQuery` |
26
+ | Row and header actions | `Button size="2xs"` or `"xs"`, `variant="ghost" iconOnly`, in a `Tooltip` |
27
+ | Paging inside a tile | `Pagination variant="compact"` in the header, plus a controlled `Carousel controls={false} indicators={false}` |
28
+ | Charts | [Choose a chart for each tile](#choose-a-chart-for-each-tile) from `@peerproblem/sw3-ui/charts` or adapt a gallery example |
29
+ | Row height | The density preference (`data-density`: compact 28, comfortable 32, spacious 40). Set it on the shell or let the user choose |
30
+
31
+ ## Frames: one per group, and the shell is already one
32
+
33
+ The AppShell splits its regions with 1px lines, so **the main region is already a frame**. Inside it, don't draw rounded cards around tiles:
34
+
35
+ - `DashboardGrid` inside `AppShellMain` is `flush` by default. Tiles share the shell's lines out to the region's edges, with no outer frame and no gaps. Use `AppShellMain padding="none"`.
36
+ - `DashboardSection` inside the shell is a 40px band on the same lines, not a floating heading with a rule.
37
+ - Cards and Listboxes inside a tile, an Accordion or a panel Card drop their frame automatically (`FrameContext`).
38
+ - Use `variant="gapped"` (framed cards with gaps) only for galleries of independent items, such as projects or people. Never use it for metrics.
39
+ - Don't repeat a heading: a section titled "Incidents" holding one tile titled "Open incidents" says the same thing twice. Put the tile in a section that adds information, or in none.
40
+ - `checkDesign()` reports `nested-frame` when a framed surface sits inside another frame.
41
+
42
+ ## Anatomy
43
+
44
+ Use one 44px `AppShellHeader` as the dashboard’s top row. Put the linked logo beside the project or page `Heading as="h1" size="sm"` in `start`. Use `center` for an optional dashboard-wide search. Put dashboard actions, site links and the account control in `end`, with a small gap between groups. Use compact SW3 buttons and give icon-only controls an accessible name.
45
+
46
+ Keep the title on one line and let it truncate when space is tight. Group secondary links and actions in a labeled `Menu` or `Popover` when they outgrow the row. Omit `AppShellMain.header` for this layout. Views with their own tabs or filters can use it as a dedicated content toolbar.
47
+
48
+ ```
49
+ ┌─────────────────────── AppShellHeader (44px) ─────────────────────────────┐
50
+ │ Toggle Logo Project title Optional search Actions Account │
51
+ ├──────────┬──────────────────────────────────────────────┬─────────────────┤
52
+ │ Sidebar │ AppShellMain │ Inspector │
53
+ │ 248px │ Metric tabs and selected view │ Accordion fill │
54
+ │ ⌘B → 48 │ ▾ DashboardSection │ ▾ Details │
55
+ │ rail │ ┌ DashboardGrid (joined) ──┬───────────┐ │ ▾ Activity │
56
+ │ │ │ Tile span 8 │ Tile 4 │ │ ▾ Related │
57
+ │ │ └──────────────────────────┴───────────┘ │ │
58
+ └──────────┴──────────────────────────────────────────────┴─────────────────┘
59
+ ```
60
+
61
+ - **Lines, not gutters.** Regions meet at 1px `--sw-divider` lines. Inside the shell, tiles continue the same lines (flush grid). Stacked panels share lines in an `Accordion`.
62
+ - **44px header height.** Use the same height for any side-region header or content toolbar so lines align across columns.
63
+ - **Fold, don't hide.** The sidebar folds to a 48px icon rail (⌘B) and the inspector folds away (⌘⌥B). Both resize from their inner edge and remember their state with `autoSaveId`. Under 768px of container width they become sheets.
64
+ - **Order:** general to specific. Start with the overview, then the tiles, then lists and tables. One question per tile.
65
+
66
+ ## Density
67
+
68
+ | Thing | Size |
69
+ | --- | --- |
70
+ | Shell header and optional main toolbar | 44px |
71
+ | Panel header | 40px (28px controls, 6px around) |
72
+ | List rows | 28 (compact, default), 32, 40 (two lines) |
73
+ | Controls in toolbars (SearchField, SortMenu, toggles) | 28px |
74
+ | Row actions (in 28px rows) | 20px, 4px inset on all sides, 2px apart, radius 4 inside the 8px row |
75
+ | Header and toolbar controls (card bar, tile, accordion, pager) | 28px, 6px from the bar like the title |
76
+ | Icons beside 13px text | 15px |
77
+ | Type | 13 UI, 12 meta, 11 group labels and counts |
78
+
79
+ - **Frames and insets.** Dashboard frames (Panel, PanelGroup, DashboardGrid, StatStrip) use radius `md` (14px). Fills inside them (rows, triggers, the search field, row actions) sit 6px from the frame, and their text and icons start 6px further in. Everything inside a panel starts on the same 12px line: the title, the search icon, row icons, body text and KPI labels.
80
+ - **Concentric corners.** A fill in a frame corner gets frame radius − 6px on that corner (8px), so the gap to the curve stays even. Rows in the middle keep 6px. This is automatic: `data-corner` is set from geometry.
81
+ - Group with spacing and lines, not boxes: rows 1px apart, sidebar groups 12px apart.
82
+ - Counts and changing numbers use tabular figures.
83
+ - Selection is a neutral fill with weight 500. Hover is a lighter fill. Blue (accent) is only for focus and drop lines.
84
+
85
+ ## Row actions are data
86
+
87
+ Give `Listbox` items `actions` and `menu` as data (`{ label, icon, onSelect }`), not markup:
88
+
89
+ - The SDK renders them as 20px ghost Buttons with tooltips, 4px from the row on every side and 2px apart, plus a ⋯ menu. Their curves nest inside the row (8 − 4 = 4).
90
+ - The meta and the actions share one slot. Exactly one of them is visible: actions on hover, keyboard focus, focus inside the actions, or while a row menu is open.
91
+ - Custom action markup gets no automatic ⋯, so you never see two.
92
+ - When the list is reorderable, the menu gains Move to top, Move up and Move down. That is the screen-reader path for reordering.
93
+ - Menu and tooltip events come from portals, but they never select or drag the row.
94
+
95
+ ## Dragging
96
+
97
+ - Rows drag from their whole body with a mouse, after 5px so clicks still select. The grip (which swaps with the icon on hover) is the affordance and the touch target.
98
+ - Tiles drag from their header bar. The grip is a 2xs Button in the header actions (keyboard: Space, arrows, Space).
99
+ - Tiles register with their grid through context, so wrapping a `DashboardTile` in your own component keeps its `id`, `span` and reordering.
100
+
101
+ ## Nothing moves on hover
102
+
103
+ - Hover actions take the place of the count or meta in the same slot. They never push the row.
104
+ - Drag handles keep their space while invisible.
105
+ - On touch (`hover: none`) hover-revealed controls are always shown.
106
+ - Hover actions are shortcuts. Make every action reachable elsewhere too, from the inspector or a menu.
107
+
108
+ ## Folding
109
+
110
+ - Use `Accordion size="sm" multiple fill` for a split side column. A folded item shrinks to its header and keeps its `meta` count visible, and open items share the height. For a single panel, use `Card collapsible`.
111
+ - Use `DashboardSection` for rows of tiles (one per service or area). A folded section unmounts its content, so its charts stop loading.
112
+ - Use `SidebarGroup` for sidebar groups. A folded group shows its count.
113
+
114
+ ## Search, sort and filter
115
+
116
+ ```tsx
117
+ const q = useListQuery({
118
+ items,
119
+ searchKeys: [(i) => i.title, (i) => i.owner],
120
+ sorters: { updated: (i) => i.updatedAt, title: (i) => i.title },
121
+ })
122
+
123
+ <Card
124
+ title="Incidents"
125
+ count={q.results.length}
126
+ padding="none"
127
+ toolbar={
128
+ <Toolbar variant="plain" size="sm" aria-label="Incident controls">
129
+ <ToolbarInput prefix={<Icon name="search" />} aria-label="Search incidents" value={q.query} onChange={(e) => q.setQuery(e.target.value)} />
130
+ <SortMenuRecipe value={q.sort} onValueChange={q.setSort} /> {/* Menu + MenuRadioGroup behind a Button size="xs" */}
131
+ </Toolbar>
132
+ }
133
+ >
134
+ <Listbox aria-label="Incidents" items={q.results} value={selected} onValueChange={setSelected}
135
+ onReorder={save} reorderable={q.reorderable} emptyMessage={`No incidents match “${q.query}”.`} />
136
+ </Card>
137
+ ```
138
+
139
+ - One toolbar row: search grows, then sort, then filters.
140
+ - Reordering is only possible in manual order with no query. `q.reorderable` handles that.
141
+ - Empty results say what happened and why.
142
+
143
+ ## Reordering
144
+
145
+ - Items stay put while you drag. The source dims, a small preview follows the pointer and a 2px line shows the drop point. After the drop the item flashes once.
146
+ - Handles: `handle="hover"` (default; the grip swaps with the row icon) when reordering is secondary, `'always'` when ordering is the list's job, and `'none'` to drag whole rows with a mouse.
147
+ - Keyboard: Alt+↑/↓ on a Listbox. On grips, Space lifts, the arrows move, Space drops and Escape cancels. Every step is announced.
148
+ - Agents: `move(id, toIndex)` on `listbox` and `dashboard-grid`.
149
+ - Save orders as id lists and restore them with `applyOrder(items, ids, getId)`. Missing ids are ignored and new items go last.
150
+
151
+ ## Paging inside a tile
152
+
153
+ - Put `Pagination variant="compact"` (‹ 2 / 5 ›) in the tile header and a controlled `Carousel controls={false} indicators={false}` in the body, sharing one `page` state.
154
+ - Page only between peers of one kind. The carousel row takes the tallest page's height, so the layout never jumps.
155
+ - No dots, no auto-advance. For long lists, scroll or link to a full page.
156
+
157
+ ## Choose a chart for each tile
158
+
159
+ 1. **Start with the dashboard's job.** Write the question each tile answers for its reader. An operations view may need to show which checks failed and when. A product view may need to show which channels bring in sign-ups. If the reader only needs the current value, use `Stat`. If they need to look up exact values across several fields, use a table.
160
+ 2. **Inspect the data at the tile's level of detail.** Identify what each row represents, which values can be compared or added, and whether the order carries meaning. A timestamp can filter a ranking, index a time series, mark the start of an interval, or contribute to an hour-by-weekday heatmap. Choose the chart according to the question the timestamp helps answer.
161
+ 3. **Fit the chart to the tile and the task.** In a compact tile, keep the essential labels and values readable. Give charts with multiple series, axes, or legends more grid space. Check the narrow layout too. Reuse a chart type when several tiles ask the same kind of question, and choose again whenever the question or data shape changes, including when switching metric tabs.
162
+
163
+ | Tile question | Data and chart choice | Example to adapt |
164
+ | --- | --- | --- |
165
+ | How is latency changing? | An ordered numeric series. Use `TrendChart` for one metric at regular intervals. Use `LineChart` for a few comparable series or when actual time spacing matters, with `Date` or numeric x values. | [Compare three time series](https://sw3-ui-sdk.vercel.app/#/charts/multi-line-chart), [TrendChart demo](https://sw3-ui-sdk.vercel.app/#/components/trend-chart) |
166
+ | How many requests came in per hour? | Counts in discrete time buckets. Use `TrendChart variant="bars"` for one series or grouped `BarChart` for side-by-side counts. Use `AreaChart` when changes in total volume over time are the focus. | [Compare counts across periods](https://sw3-ui-sdk.vercel.app/#/charts/basic-grouped-bar), [Compare volume over time](https://sw3-ui-sdk.vercel.app/#/charts/non-stacked-area-chart) |
167
+ | Which endpoints have the most errors? | A short ranking of categories by nonnegative value. Use `BarList` when labels, counts or drill-in links matter. Use horizontal `BarChart` for long category names, signed comparisons or several values per category. | [Top endpoints demo](https://sw3-ui-sdk.vercel.app/#/components/bar-list), [Arrivals and departures by state](https://sw3-ui-sdk.vercel.app/#/charts/state-migration-balance) |
168
+ | What share of traffic came from each channel? | A single total split into 2–6 nonnegative parts that are easy to tell apart. Use `DonutChart` for a share snapshot, `BarChart` for close comparisons, or `Treemap` to show the relative size of many parts within a total. | [Share by category](https://sw3-ui-sdk.vercel.app/#/charts/basic-donut-chart), [Tree species by borough](https://sw3-ui-sdk.vercel.app/#/charts/street-tree-treemap) |
169
+ | How does the mix differ by plan or change over time? | Additive parts in common units. Use `BarChart mode="stacked"` for composition by category, with normalized values if comparing percentage shares. Use `AreaChart stacked` for how a total and its parts change over time. | [Compare percentage mixes](https://sw3-ui-sdk.vercel.app/#/charts/tree-health-bars), [Follow a changing mix](https://sw3-ui-sdk.vercel.app/#/charts/stacked-area-chart) |
170
+ | Did the latest checks pass? | An ordered sequence of discrete statuses. Use `Tracker` for a run or uptime history and a short list for just a few events. | [Uptime tracker demo](https://sw3-ui-sdk.vercel.app/#/components/tracker) |
171
+ | When do incidents start, end or overlap? | One start and end per incident or interval. Use a timeline with `VisTimeline` when duration or overlap matters. | [Compare release support windows](https://sw3-ui-sdk.vercel.app/#/charts/python-release-timeline) |
172
+ | Do cost and latency vary together? | Paired numeric observations. Use `ScatterChart` and add point size only if a third measure such as traffic matters. | [Compare two measures and size points by a third](https://sw3-ui-sdk.vercel.app/#/charts/sized-scatter-plot) |
173
+ | How spread out are response times? | Numeric samples or binned counts. Use a histogram for distribution shape and a box plot with `VisBoxplot` for medians and spread across groups. | [Ride-duration histogram](https://sw3-ui-sdk.vercel.app/#/charts/bike-trip-distributions), [Compare grouped distributions](https://sw3-ui-sdk.vercel.app/#/charts/penguin-distributions) |
174
+ | Which hours and weekdays are busiest? | A numeric value for each pair of buckets. Use a heatmap with `VisHeatmap` to show repeating patterns across both dimensions. | [Demand by weekday and hour](https://sw3-ui-sdk.vercel.app/#/charts/bike-demand-heatmap) |
175
+ | What contributed to the period's net change? | Ordered, signed contributions to a running total. Use a waterfall chart. | [From revenue to net income](https://sw3-ui-sdk.vercel.app/#/charts/waterfall-chart) |
176
+ | Where does the volume go? | Weighted links between stages or categories. Use a Sankey with `VisSankey` when the paths and their relative volume matter. | [Follow flows from source to use](https://sw3-ui-sdk.vercel.app/#/charts/energy-flow-sankey) |
177
+
178
+ For example, an API operations dashboard can use hourly bars for request counts, a `BarList` for top failing endpoints, a `Tracker` for check results, and a histogram for the spread of response times. All four tiles can share the same date range while answering different questions.
179
+
180
+ Open the linked gallery example for source and **Copy prompt**, or look up its slug in [`chart-gallery.json`](https://sw3-ui-sdk.vercel.app/chart-gallery.json) for the source path, Unovis components and build prompt. Use the `@peerproblem/sw3-ui/charts` wrapper when it supports the required encoding. For specialized charts, adapt the gallery's `@unovis/react` implementation inside `ChartSurface` from `@peerproblem/sw3-ui/charts` so it inherits SW3 chart tokens. Use a titled `DashboardTile` in the grid or a `ChartCard` for a standalone plot, and give the chart an `aria-label` with its takeaway.
181
+
182
+ ### Compact chart details
183
+
184
+ - Use `Sparkline` inside a `Stat` only when the direction adds context to the value. Keep the line neutral and use status color on the delta.
185
+ - A `TrendChart` uses sparse ticks, a fading area fill, and a latest-value dot in line and area modes. Set `live` for streaming data to pulse the dot. Use `compare` for the same metric in an aligned previous period, `incomplete` for a bucket still filling, and `threshold` for a target or limit. Use `onScrub` when the tile header should show the active value. Keep the built-in short first-mount animation and align chart heights for side-by-side comparisons.
186
+ - In `Tracker`, let degraded and down states carry the color and keep normal runs quiet.
187
+
188
+ ## Anti-patterns
189
+
190
+ - Cards with 24–32px gaps and individual shadows for every metric.
191
+ - More than 2 levels of navigation in the sidebar, or critical actions at its bottom.
192
+ - Duplicate navigation (sidebar and header tabs listing the same places).
193
+ - A site navbar stacked above the dashboard title row.
194
+ - Header heights that differ between columns.
195
+ - Fixed heights on tiles that aren't charts or maps.
196
+ - Drag as the only way to reorder.
197
+ - Colorful chrome. Color belongs to data and status.
198
+ - Default-looking charts: flat fills, 1.5s draw-ins, tick lines everywhere, a second saturated hue for last week.
199
+
200
+ ---
201
+
202
+ # Components
203
+
204
+ # AppShell
205
+
206
+ > The frame of a dashboard: a header, a sidebar that folds to a rail, a main region and an inspector, all joined by 1px lines.
207
+
208
+ Category: layout · Status: beta · Slug: `app-shell`
209
+
210
+ ```tsx
211
+ import { AppShell, AppShellHeader, AppShellSidebar, AppShellMain, AppShellInspector, ShellToggle, useAppShell } from '@peerproblem/sw3-ui'
212
+ ```
213
+
214
+ ## When to use
215
+ - The outer layout of an app or dashboard with persistent navigation.
216
+ - A master–detail view where a trailing inspector shows the selection.
217
+
218
+ ## Avoid
219
+ - Marketing or document pages — use the normal page layout (guides/05-layout).
220
+ - Spacing regions apart with gutters or giving each region its own card and shadow. Regions meet at hairlines.
221
+ - Nesting a second AppShell. Use Resizable or an Accordion inside AppShellMain.
222
+
223
+ ## Props
224
+
225
+ | Prop | Type | Default | Description |
226
+ | --- | --- | --- | --- |
227
+ | `layout` | `'header-first' \| 'sidebar-first'` | `'header-first'` | header-first: the header spans the full width. sidebar-first: the sidebar runs the full height beside the header. |
228
+ | `sidebarOpen / defaultSidebarOpen / onSidebarOpenChange` | `boolean` | `true` | Sidebar expanded on wide layouts. Folded, it becomes a 48px rail or disappears. |
229
+ | `inspectorOpen / defaultInspectorOpen / onInspectorOpenChange` | `boolean` | `true` | Inspector open on wide layouts. |
230
+ | `collapseBelow` | `number` | `768` | Container width (px) below which the sidebar and inspector become sheets over the content. |
231
+ | `sidebarShortcut` | `string \| null` | `'mod+b'` | Keyboard toggle for the sidebar. |
232
+ | `inspectorShortcut` | `string \| null` | `'mod+alt+b'` | Keyboard toggle for the inspector. |
233
+ | `autoSaveId` | `string` | | Save open state and widths in localStorage under this key. |
234
+ | `height` | `CSS height` | `'100dvh'` | Shell height. Use '100%' inside a sized container. |
235
+ | `AppShellHeader.start / center / end` | `ReactNode` | | Put the linked logo and dashboard title in start, an optional search in center, and compact dashboard, site and account controls in end. |
236
+ | `AppShellSidebar.collapsible` | `'rail' \| 'offcanvas' \| 'none'` | `'rail'` | How the sidebar folds. |
237
+ | `AppShellSidebar / AppShellInspector .label` * | `string` | | Accessible name of the region. |
238
+ | `AppShellSidebar / AppShellInspector .header / footer` | `ReactNode` | | Pinned rows. The header matches the shell header height (44px). |
239
+ | `AppShellSidebar / AppShellInspector .defaultWidth / minWidth / maxWidth` | `number` | | Sidebar 248 (200–400). Inspector 320 (260–480). |
240
+ | `AppShellSidebar / AppShellInspector .resizable` | `boolean` | `true` | Resize from the inner edge. Drag past half the minimum width to fold it. Double-click or Enter toggles it. |
241
+ | `AppShellMain.header` | `ReactNode` | | Optional 44px content toolbar for a separate view title, tabs or filters. Omit it when the shell header holds the dashboard title and controls. |
242
+ | `AppShellMain.padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Padding of the scrolling content. Use 'none' for an edge-to-edge DashboardGrid. |
243
+ | `ShellToggle.side` | `'sidebar' \| 'inspector'` | `'sidebar'` | 28px icon button that toggles a region. Its tooltip shows the shortcut. |
244
+
245
+ ## Examples
246
+
247
+ ### Dashboard frame with one header
248
+
249
+ ```tsx
250
+ <AppShell autoSaveId="acme">
251
+ <AppShellHeader
252
+ start={
253
+ <>
254
+ <ShellToggle />
255
+ <Button href="/" size="xs" variant="ghost" iconOnly aria-label="Acme home" leading={<Icon name="activity" />} />
256
+ <Heading as="h1" size="sm" style={{ minWidth: 0, whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>
257
+ Incident overview
258
+ </Heading>
259
+ </>
260
+ }
261
+ end={
262
+ <>
263
+ <ShellToggle side="inspector" />
264
+ <nav aria-label="Site" style={{ display: 'flex', gap: 'var(--sw-space-1)' }}>
265
+ <Button href="/projects" size="xs" variant="ghost">Projects</Button>
266
+ <Button href="/login" size="xs" variant="outline">Sign in</Button>
267
+ </nav>
268
+ </>
269
+ }
270
+ />
271
+ <AppShellSidebar label="Workspace">
272
+ <SidebarNav>
273
+ <SidebarItem icon={<Icon name="home" />} label="Overview" active href="#/" />
274
+ <SidebarItem icon={<Icon name="alert" />} label="Incidents" count={3} href="#/incidents" />
275
+ </SidebarNav>
276
+ </AppShellSidebar>
277
+ <AppShellMain padding="none">
278
+ <DashboardGrid aria-label="Overview">…</DashboardGrid>
279
+ </AppShellMain>
280
+ <AppShellInspector label="Details">
281
+ <Accordion size="sm" variant="plain" multiple fill defaultValue={['details', 'activity']}>…</Accordion>
282
+ </AppShellInspector>
283
+ </AppShell>
284
+ ```
285
+
286
+ ## Rules
287
+ - Regions meet at 1px lines. Never put gutters, shadows or separate cards between them.
288
+ - All headers share one height (44px), so the lines across columns align.
289
+ - Use one shell header for the dashboard logo, title, dashboard controls and site navigation. Omit the main header unless a view needs a separate content toolbar.
290
+ - Let the title truncate and move secondary controls into a labeled Menu or Popover when space is tight.
291
+ - Keep workspace navigation in the sidebar with at most two levels. Use trailing header links for site destinations.
292
+ - Do not hide the sidebar by default on wide screens. Let people fold it (⌘B) and remember the choice with autoSaveId.
293
+ - Do not put critical actions at the bottom of the sidebar.
294
+
295
+ ## Accessibility
296
+ - The sidebar and inspector are <aside> landmarks named by `label`. The main region is <main>.
297
+ - Resizers are role="separator" with aria-valuenow and keyboard control: ←/→ by 16px, Shift for 64px, Home/End, Enter folds.
298
+ - A folded region is inert. Sheets close with Escape or by clicking the scrim.
299
+ - ShellToggle has aria-expanded and aria-keyshortcuts.
300
+
301
+ ## DOM contract (for agents operating the page)
302
+
303
+ - Selector: `[data-sw="app-shell"]`
304
+ - `data-narrow`: present when the regions are sheets
305
+ - `data-state`: open | rail | closed on [data-sw="app-shell-sidebar"] and [data-sw="app-shell-inspector"]
306
+ - How to operate: Click [data-sw="shell-toggle"][data-side="sidebar|inspector"], or press ⌘B / ⌘⌥B. Agent bridge: toggleSidebar(), toggleInspector(), setSidebarOpen(bool), setInspectorOpen(bool). state = { narrow, sidebarOpen, inspectorOpen }.
307
+
308
+ Related: `sidebar-nav`, `card`, `dashboard-grid`, `accordion`, `breadcrumbs`, `resizable`
309
+
310
+ ---
311
+
312
+ # SidebarNav
313
+
314
+ > Dense sidebar navigation: 28px rows with icons, counts and hover actions, plus groups that fold. In the rail it becomes icon buttons with tooltips.
315
+
316
+ Category: navigation · Status: beta · Slug: `sidebar-nav`
317
+
318
+ ```tsx
319
+ import { SidebarNav, SidebarGroup, SidebarItem } from '@peerproblem/sw3-ui'
320
+ ```
321
+
322
+ ## When to use
323
+ - Primary navigation in an AppShellSidebar.
324
+ - Lists of saved views, projects or teams with counts.
325
+
326
+ ## Avoid
327
+ - More than 2 levels. Use a Tree in a panel, or a drill-in page.
328
+ - Rows without icons in a sidebar that folds to a rail. Rows without an icon are hidden in the rail.
329
+ - Putting the only path to an action in hover-only row actions.
330
+
331
+ ## Props
332
+
333
+ | Prop | Type | Default | Description |
334
+ | --- | --- | --- | --- |
335
+ | `SidebarItem.label` * | `string` | | Row text. In the rail it becomes the tooltip and accessible name. |
336
+ | `SidebarItem.icon` | `ReactNode` | | 15px icon. Required for the row to show in the rail. |
337
+ | `SidebarItem.active` | `boolean` | | Current page: neutral fill, weight 500, aria-current="page". |
338
+ | `SidebarItem.count` | `ReactNode` | | Trailing count (mono, tabular). Hover actions take its place. |
339
+ | `SidebarItem.actions` | `ReactNode` | | One or two `Button size="2xs" variant="ghost" iconOnly` (in a Tooltip), shown on hover or focus and always on touch. |
340
+ | `SidebarItem.level` | `0 \| 1 \| 2` | `0` | Indent to line up under a parent label. |
341
+ | `SidebarItem.href / onClick` | `string / function` | | Renders a link with href, otherwise a button. Choosing an item closes the sheet on narrow layouts. |
342
+ | `SidebarGroup.label` * | `string` | | 11px group label. It is the fold button. |
343
+ | `SidebarGroup.count` | `ReactNode` | | Shown while folded. |
344
+ | `SidebarGroup.actions` | `ReactNode` | | Hover actions on the group row, e.g. "New project". |
345
+ | `SidebarGroup.collapsible / open / defaultOpen / onOpenChange` | `boolean` | `true / – / true` | Fold state. |
346
+
347
+ ## Examples
348
+
349
+ ### Groups, counts and hover actions
350
+
351
+ ```tsx
352
+ <SidebarNav aria-label="Workspace">
353
+ <SidebarItem icon={<Icon name="home" />} label="Overview" active href="#/" />
354
+ <SidebarItem icon={<Icon name="inbox" />} label="Inbox" count={12} href="#/inbox" />
355
+ <SidebarGroup label="Projects" count={3} actions={<Tooltip content="New project"><Button size="2xs" variant="ghost" iconOnly aria-label="New project" leading={<Icon name="plus" />} /></Tooltip>}>
356
+ <SidebarItem icon={<Icon name="folder" />} label="API" href="#/api" />
357
+ <SidebarItem icon={<Icon name="folder" />} label="Billing" href="#/billing" />
358
+ </SidebarGroup>
359
+ </SidebarNav>
360
+ ```
361
+
362
+ ## Rules
363
+ - Rows are 28px with 13px labels. Groups are 12px apart and rows 1px apart.
364
+ - Selection is a neutral fill with weight 500. Never use color or bold alone.
365
+ - Hover actions replace the count in the same slot. Nothing shifts on hover.
366
+
367
+ ## Accessibility
368
+ - Rendered as <nav> with an aria-label. Group labels are buttons with aria-expanded. Folded groups are inert.
369
+ - In the rail each icon button is named by its label.
370
+
371
+ ## DOM contract (for agents operating the page)
372
+
373
+ - Selector: `[data-sw="sidebar-nav"]`
374
+ - `data-active`: on the current [data-sw="sidebar-item"]
375
+ - `data-state`: open | closed on [data-sw="sidebar-group"]
376
+ - `data-collapsed`: on the nav while in the rail
377
+ - How to operate: Click [data-sw="sidebar-item"]. Agent bridge on groups: open(), close(), toggle().
378
+
379
+ Related: `app-shell`, `tree`, `navigation-menu`
380
+
381
+ ---
382
+
383
+ # DashboardGrid
384
+
385
+ > A 12-column grid of DashboardTiles that share 1px lines in one frame, or sit apart as separate cards. Tiles reorder by their header grip, and DashboardSection folds a row.
386
+
387
+ Category: layout · Status: beta · Slug: `dashboard-grid`
388
+
389
+ ```tsx
390
+ import { DashboardGrid, DashboardTile, DashboardSection } from '@peerproblem/sw3-ui'
391
+ ```
392
+
393
+ ## When to use
394
+ - The main area of a dashboard: KPI strip, charts, tables.
395
+ - Grouping related tiles into foldable rows (one row per service or area).
396
+
397
+ ## Avoid
398
+ - Cards scattered with big gaps and their own shadows. The default joined variant shares lines.
399
+ - Fixed heights on tiles, except charts and maps that need one.
400
+ - Tiles that answer more than one question. Split them.
401
+
402
+ ## Props
403
+
404
+ | Prop | Type | Default | Description |
405
+ | --- | --- | --- | --- |
406
+ | `variant` | `'flush' \| 'joined' \| 'gapped'` | `'flush' in AppShellMain, else 'joined'` | flush: tiles share the shell's lines to the edges, with no frame. joined: shared lines in one rounded frame. gapped: separate framed cards 12px apart, only for galleries of independent items. |
407
+ | `minTileWidth` | `number` | `280` | Tiles narrower than this grow to half, then full width. |
408
+ | `columns` | `number` | `12` | Columns on wide containers. |
409
+ | `rowHeight` | `number` | | Fixed row height for tiles with rowSpan. By default rows follow their content. |
410
+ | `order / defaultOrder / onOrderChange` | `string[]` | | Tile ids in order. onOrderChange turns on reordering by the header grip (drag, or Space, arrows, Space). |
411
+ | `DashboardTile.id` | `string` | | Stable id, required for reordering. |
412
+ | `DashboardTile.span` | `number` | `4` | Columns spanned. A tile narrower than `minTileWidth` (280px) grows to half, then full width. Rows never end in a hole: the last tile of a row stretches to its end. |
413
+ | `DashboardTile.rowSpan` | `number` | | Rows spanned when rowHeight is set. |
414
+ | `DashboardTile.*` | `CardProps` | | title, count, actions, toolbar, footer, padding. A tile is a grid cell holding a Card in the panel layout, unframed in a joined grid and framed in a gapped one. |
415
+ | `DashboardSection.title / count / actions` | `ReactNode` | | A foldable row heading with a line to the end. |
416
+ | `DashboardSection.keepMounted` | `boolean` | `false` | A folded section unmounts its content so its charts stop loading. Set true to keep it. |
417
+
418
+ ## Examples
419
+
420
+ ### Sections of joined tiles
421
+
422
+ ```tsx
423
+ const [order, setOrder] = useState(['latency', 'errors', 'throughput'])
424
+
425
+ <DashboardSection title="API" count="3 panels">
426
+ <DashboardGrid aria-label="API" order={order} onOrderChange={setOrder}>
427
+ <DashboardTile id="latency" span={6} title="p95 latency" actions={<Pagination variant="compact" pageCount={3} />}>…</DashboardTile>
428
+ <DashboardTile id="errors" span={3} title="Error rate">…</DashboardTile>
429
+ <DashboardTile id="throughput" span={3} title="Throughput">…</DashboardTile>
430
+ </DashboardGrid>
431
+ </DashboardSection>
432
+ ```
433
+
434
+ ## Rules
435
+ - Order the dashboard from general to specific: metric Tabs over a TrendChart, then tiles, then lists and tables.
436
+ - One question per tile. The title says what it answers.
437
+ - Inside AppShellMain, leave the grid flush (the default) with `AppShellMain padding="none"`: the shell is already the frame.
438
+ - Gapped tiles are for galleries of independent items such as projects. Never use them for metrics.
439
+ - Tiles may sit inside your own wrapper components: they register with the grid through context.
440
+ - Do not wrap a single tile in a section whose title repeats the tile title.
441
+ - Tiles drag from their header bar. The grip is a hover-revealed 2xs Button in the header actions.
442
+
443
+ ## Accessibility
444
+ - Tiles are sections labelled by their title. The grip is a button: Space or Enter lifts, the arrows move, Space drops, Escape cancels. Every step is announced.
445
+ - Section headings are buttons with aria-expanded.
446
+
447
+ ## DOM contract (for agents operating the page)
448
+
449
+ - Selector: `[data-sw="dashboard-grid"]`
450
+ - `data-variant`: joined | gapped
451
+ - `data-tile-id`: on each [data-sw="dashboard-tile"]
452
+ - `data-state`: open | closed on [data-sw="dashboard-section"]
453
+ - How to operate: Agent bridge: move(id, toIndex), setOrder(ids). state = { order, reorderable }. Sections: open(), close(), toggle().
454
+
455
+ Related: `card`, `tabs`, `trend-chart`, `pagination`, `app-shell`
456
+
457
+ ---
@@ -0,0 +1,132 @@
1
+ # SW3 UI SDK · Build and contribute components
2
+
3
+ > Build a new component from SW3 primitives and add it to the SDK.
4
+
5
+ Setup: `import "@peerproblem/sw3-ui/styles.css"` once, wrap the app in `<SwProvider>`, add `className="sw-root"` to the page. Charts: `@peerproblem/sw3-ui/charts`. Maps: `@peerproblem/sw3-ui/map`.
6
+ Optional peers: install `@unovis/react@~1.8.1 @unovis/ts@~1.8.1 d3-hierarchy@^3.1.0` for charts or `maplibre-gl@^6.18.0` for maps.
7
+ Index of all topics and components: llms.txt.
8
+
9
+ ---
10
+
11
+ # Build a component
12
+
13
+ This guide builds a small star **Rating** from scratch to show the full SW3 pattern. (The SDK ships one already. This is for learning the pattern.) Use the same steps for anything the kit doesn't have.
14
+
15
+ ## 1. State: controlled or uncontrolled
16
+
17
+ ```tsx
18
+ import { useControllableState } from '@peerproblem/sw3-ui'
19
+
20
+ export interface StarsProps {
21
+ value?: number
22
+ defaultValue?: number
23
+ onValueChange?(value: number): void
24
+ max?: number
25
+ 'aria-label'?: string
26
+ }
27
+
28
+ export function Stars({ value, defaultValue = 0, onValueChange, max = 5, ...aria }: StarsProps) {
29
+ const [v, setV] = useControllableState({ value, defaultValue, onChange: onValueChange })
30
+ // …
31
+ }
32
+ ```
33
+
34
+ Use the same names as the kit: `value`, `defaultValue`, `onValueChange`. For popups, use `open`, `defaultOpen` and `onOpenChange`.
35
+
36
+ ## 2. Parts and keyboard
37
+
38
+ Render real elements with a WAI-ARIA role:
39
+
40
+ - A rating is a `slider`: Left/Right change the value by 1, and Home/End jump to the ends.
41
+ - For lists, use `useListNavigation`.
42
+ - For popups, use `usePopup` with `PopupPanel`.
43
+
44
+ ```tsx
45
+ const ref = useRef<HTMLDivElement>(null)
46
+ return (
47
+ <div
48
+ ref={ref}
49
+ data-sw="stars"
50
+ role="slider"
51
+ tabIndex={0}
52
+ aria-valuemin={0}
53
+ aria-valuemax={max}
54
+ aria-valuenow={v}
55
+ aria-valuetext={`${v} of ${max} stars`}
56
+ {...aria}
57
+ onKeyDown={(e) => {
58
+ const next = { ArrowRight: v + 1, ArrowUp: v + 1, ArrowLeft: v - 1, ArrowDown: v - 1, Home: 0, End: max }[e.key]
59
+ if (next === undefined) return
60
+ e.preventDefault()
61
+ setV(Math.max(0, Math.min(max, next)))
62
+ }}
63
+ >
64
+ {Array.from({ length: max }, (_, i) => (
65
+ <span key={i} data-sw="stars-star" data-state={i < v ? 'on' : 'off'} onClick={() => setV(i + 1)}>
66
+ <Icon name="star" />
67
+ </span>
68
+ ))}
69
+ </div>
70
+ )
71
+ ```
72
+
73
+ ## 3. Style it with tokens
74
+
75
+ ```css
76
+ .sw-stars { display: inline-flex; gap: 2px; color: var(--sw-border); outline: none; }
77
+ .sw-stars [data-state='on'] { color: var(--sw-foreground); }
78
+ .sw-stars:focus-visible { box-shadow: 0 0 0 2px var(--sw-accent); border-radius: 6px; }
79
+ ```
80
+
81
+ - Rounded surfaces bigger than about 20px use `useSquircle` with `SquircleLayers`, never `border-radius`.
82
+ - Animate with the presets from `motion/react` (`transitions.snappy`).
83
+ - Colors come only from `var(--sw-*)`.
84
+
85
+ ## 4. Let agents operate it
86
+
87
+ ```tsx
88
+ useAgentBinding(ref, { kind: 'stars', state: () => ({ value: v, max }), actions: { setValue: (n: number) => setV(n) } })
89
+ ```
90
+
91
+ The agent bridge now lists it as `{ component: 'stars', label: 'Rating', value: 3, actions: ['setValue'] }`.
92
+
93
+ ## 5. Make it a form control
94
+
95
+ Call `useFieldControl()` and spread its `id`, `aria-describedby` and `aria-invalid` onto the focusable element. The component then works inside `<Field label error>`. If it isn't a native input, render `<input type="hidden" name={name} value={v} />` so it submits with a form.
96
+
97
+ ## 6. Register and document it
98
+
99
+ Follow *Contributing components*:
100
+
101
+ 1. Export the component.
102
+ 2. Add a `defineMeta` entry. Its `dom.operate` lists the bridge actions.
103
+ 3. Add a demo.
104
+ 4. Run `npm run agent:build`.
105
+
106
+ ## 7. Check it
107
+
108
+ - **Keyboard only:** tab to it, operate it, and see the focus ring.
109
+ - **Screen reader name:** `aria-label` or a Field label.
110
+ - **Light and dark:** both themes, at 375px width.
111
+ - **Agent bridge:** on `#/agent`, run `window.agent.snapshot()` and check it shows up with a label and actions.
112
+ - **`npm run typecheck`.**
113
+
114
+ ---
115
+
116
+ # Contributing components
117
+
118
+ 1. **Build** `packages/ui/src/components/<name>.tsx`.
119
+ - Root element gets `data-sw="<slug>"` and state as `data-*` / ARIA attributes.
120
+ - Rounded surfaces use `useSquircle` + `SquircleLayers`; colors via `--sw-sq-*`.
121
+ - Motion via presets from `motion/presets.ts`.
122
+ - Classes are `sw-<name>` / `sw-<name>__part`; CSS goes in `src/styles/components.css` using tokens only.
123
+ 2. **Export** it from `src/index.ts` (or `charts/index.ts`, `map/index.ts`).
124
+ 3. **Describe** it: add a `defineMeta({...})` entry to `src/meta/core.ts` (or `charts.ts`, `map.ts`) and include it in the exported array. Fill in `whenToUse`, `avoid`, `props`, at least one `examples` entry, `rules` and `dom`.
125
+ 4. **Demo** it: add a demo to `apps/playground/src/demos/index.tsx` keyed by slug. It then shows up in the gallery and on its docs page.
126
+ - Let the gallery poster or demo stage provide the grouping frame. Use the component's unframed mode where supported and keep functional boundaries such as an artboard outline.
127
+ - Don't draw a frame of your own (an inline border, outline shadow or background) around the component. The docs ruler measures the component, so a fake frame makes the number look wrong. Show it at its real width instead (for example, SidebarNav at 232px, a 248px sidebar minus its padding).
128
+ - If the demo has backdrops or several variants, set `measureTarget` to the canonical instance and `measureRulerPlacement: 'below-target'`. The ruler marks what it measured with `data-sw-measured`, and `tests/docs-measure.spec.ts` fails when a demo frame and the ruler disagree.
129
+ 5. **Generate**: `npm run agent:build` rebuilds `packages/ui/agent/` (`registry.json`, `llms.txt`, the topic files in `llms/`, `llms-full.txt` and `components/<slug>.md`). A new category must be added to a topic in `scripts/build-agent-docs.ts`; the build fails until it is.
130
+ 6. **Check**: `npm run typecheck`, then look at it in `npm run dev` in light and dark mode at phone and desktop widths.
131
+
132
+ ---