@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,674 @@
1
+ # SW3 UI SDK · Foundations
2
+
3
+ > Design principles (structure vs. look), color, type, corners, motion, layout, dark mode, tokens, SwProvider. Read once per task.
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
+ # Design principles
12
+
13
+ SW3 rules come in two layers. Keep them apart when you build:
14
+
15
+ - **Structure** rules hold in every app, whatever it looks like. Breaking one makes the UI harder to use, so follow them even when an app has its own brand.
16
+ - **Look** rules describe the default theme. They are a starting point. When the app or the user asks for a different look, change tokens (`--sw-*`), a `data-design` theme or variant props. Don't change the structure to get a look.
17
+
18
+ When a request conflicts with a look rule, follow the request. When it conflicts with a structure rule, follow the rule and say why.
19
+
20
+ ## Structure (every app)
21
+
22
+ 1. **One clear next step.** Each view has at most one primary action (`variant="accent"` or the default solid button). Everything else is secondary, quiet or in a menu.
23
+ 2. **Hierarchy follows the document.** Pick heading levels (`as`) from the outline and size from emphasis. Order content from general to specific.
24
+ 3. **One frame per group.** Separate groups with one boundary or with spacing, never both nested. A frame inside a frame needs a reason, such as an editable area or a scroll region.
25
+ 4. **Fit the container.** Content reflows from 320px to wide desktop without page-level horizontal scrolling. See *Layout*.
26
+ 5. **Accessible by default.** Every control has a visible or programmatic name, works with the keyboard, shows focus and doesn't depend on color alone. Charts carry an `aria-label` that states the takeaway. Motion turns off when the OS asks for reduced motion.
27
+ 6. **Values come from tokens.** Use `var(--sw-*)` and component props, not hard-coded colors, radii or shadows. That's what makes a theme change reach every screen.
28
+ 7. **State is visible and machine-readable.** Use the component's own selected, loading, disabled and error states rather than custom styling, so people and agents read the same state.
29
+
30
+ ## Look (default theme)
31
+
32
+ The default SW3 theme is quiet and typographic. Each line says where to change it.
33
+
34
+ | Default | Change it with |
35
+ | --- | --- |
36
+ | Neutral palette: near-black ink on a light canvas, white surfaces, neutral accent | `--sw-accent*`, `--sw-canvas`, `--sw-background` and other color tokens. See *Color*. |
37
+ | Geist and Geist Mono, headings at weight 450 with tight tracking | `--sw-font-sans`, `--sw-font-mono`. See *Typography*. |
38
+ | Small mono uppercase captions | Use `<Text size="sm">` instead of `<Caption>` when the brand doesn't use them. |
39
+ | Squircle corners with 0.6 smoothing | The `radius` and `smoothing` props on surfaces. See *Corners*. |
40
+ | 1px frames instead of drop shadows | Frame tokens (`--sw-frame`, `--sw-divider`); popovers and dialogs keep one soft shadow. |
41
+ | Short press, glide and enter motion (≤ 350 ms) | Motion presets and `SwProvider reducedMotion`. See *Motion*. |
42
+ | Alternative designs | `data-design="calm"` or `data-design="frost"` with `@peerproblem/sw3-ui/themes/<name>.css`. |
43
+
44
+ ## Voice
45
+
46
+ - Sentence case everywhere. Buttons start with a verb ("Copy prompt").
47
+ - Helper text is a plain instruction: "Drag or type a value".
48
+ - Keep it short. If a description needs two sentences, the component is probably doing too much.
49
+
50
+ ---
51
+
52
+ # Color
53
+
54
+ All colors are CSS variables named `--sw-<token>` with light and dark values. The full table is generated from `packages/ui/src/tokens/tokens.ts`, see *Tokens* (`tokens.md`, also in `llms/foundations.txt`).
55
+
56
+ | Role | Token | Use |
57
+ | --- | --- | --- |
58
+ | Page | `--sw-canvas` | Behind everything. |
59
+ | Surface | `--sw-background` | Cards, inputs, posters. |
60
+ | Ink | `--sw-foreground` | Text and the primary button fill. |
61
+ | Quiet text | `--sw-muted-foreground` | Descriptions, captions, axis labels. |
62
+ | Wells | `--sw-muted` | Secondary buttons, tracks, segmented background. |
63
+ | Frames | `--sw-frame` | 1px card borders. |
64
+ | Lines | `--sw-hairline` | Dividers, hatch patterns, chart grid. |
65
+ | Accent | `--sw-accent`, `--sw-accent-solid` | Neutral by default. Emphasize a key action, focus or a selected control. |
66
+ | Selection | `--sw-selection` | Soft background for selected text or content. |
67
+ | Status | `--sw-success`, `--sw-warning`, `--sw-danger` | Status and deltas. |
68
+
69
+ ## Rules
70
+
71
+ - Mix, don't invent: `color-mix(in oklab, var(--sw-foreground) 15%, transparent)` for a quieter border. Never hard-code hex values in components.
72
+ - One accent fill per view (structure rule: it marks the primary action).
73
+ - Text and marks on `accent-solid` use `--sw-accent-foreground`. Check the contrast on both the default and hover fills.
74
+ - Dark mode is automatic (prefers-color-scheme) or forced with `<html data-theme="dark">` via `<SwProvider theme="dark">`.
75
+
76
+ ## App brand accents
77
+
78
+ Set the accent variables in your app stylesheet on a wrapper around the SDK components, or on the document root for app-wide branding. Use the same `variant="accent"` on a branded button. Set `--sw-selection` as well if you want soft highlights to carry the brand tint.
79
+
80
+ ```css
81
+ /* Apply .brand-accent to the app wrapper. This example uses violet. */
82
+ .brand-accent {
83
+ --sw-accent: #6543a0;
84
+ --sw-accent-solid: #6543a0;
85
+ --sw-accent-solid-hover: #533487;
86
+ --sw-accent-foreground: #ffffff;
87
+ --sw-selection: #eee8f7;
88
+ }
89
+
90
+ @media (prefers-color-scheme: dark) {
91
+ :root:not([data-theme='light']) .brand-accent {
92
+ --sw-accent: #c7aff0;
93
+ --sw-accent-solid: #c7aff0;
94
+ --sw-accent-solid-hover: #d5c2f5;
95
+ --sw-accent-foreground: #241737;
96
+ --sw-selection: #322642;
97
+ }
98
+ }
99
+
100
+ :root[data-theme='dark'] .brand-accent {
101
+ --sw-accent: #c7aff0;
102
+ --sw-accent-solid: #c7aff0;
103
+ --sw-accent-solid-hover: #d5c2f5;
104
+ --sw-accent-foreground: #241737;
105
+ --sw-selection: #322642;
106
+ }
107
+ ```
108
+
109
+ ## Charts
110
+
111
+ Series colors are `--sw-chart-1` … `--sw-chart-8` in order: blue, ink, green, orange, violet, red, cyan, grey. Always use them in order so the first series is blue.
112
+
113
+ ---
114
+
115
+ # Typography
116
+
117
+ The default theme uses **Geist** for interface text and **Geist Mono** for compact captions and code. Swap them with two variables (below) when the app has its own typefaces. The SDK stylesheet defines the font stacks. Install the fonts in the consuming app and import them once at its entry point to match the Playground:
118
+
119
+ ```sh
120
+ npm install @fontsource-variable/geist @fontsource-variable/geist-mono
121
+ ```
122
+
123
+ ```ts
124
+ import '@fontsource-variable/geist'
125
+ import '@fontsource-variable/geist-mono'
126
+ ```
127
+
128
+ For scripts outside the loaded fonts' coverage, configure `--sw-font-sans` with an appropriate language font in the stack and check the page with real content in that language.
129
+
130
+ Set both stacks in app CSS to replace the default typefaces. Set them on `:root` for shared typography across the page and portalled overlays. An app wrapper can set a local stack for its descendants.
131
+
132
+ ```css
133
+ :root {
134
+ --sw-font-sans: 'App Sans', system-ui, sans-serif;
135
+ --sw-font-mono: 'App Mono', ui-monospace, monospace;
136
+ }
137
+ ```
138
+
139
+ | Style | Component | Size | Weight | Tracking |
140
+ | --- | --- | --- | --- | --- |
141
+ | Display | `<Display size="lg">` | 40–72px fluid | 450 | -0.055em |
142
+ | Section heading | `<Heading size="lg">` | 36–72px fluid | 450 | -0.045em |
143
+ | Title | `<CardTitle>` | 18px | 500 | -0.025em |
144
+ | Lede | `<Text size="lg" tone="subtle">` | 18–24px | 400 | -0.015em |
145
+ | Body | `<Text>` | 16px | 400 | -0.011em |
146
+ | Caption | `<Caption>` | 11px mono, uppercase via CSS | 400 | +0.08em |
147
+
148
+ The table describes rendered component variants. The numeric values in `tokens.type` are reference sizes. Fluid component variants set their own ranges.
149
+
150
+ ## Rules
151
+
152
+ - Default look: headings stay at weight 450–500. A brand with heavier headings can change this; keep one weight per heading level.
153
+ - Set `as` from the document hierarchy and `size` from visual emphasis. For example, `<Heading as="h1" size="md">` is a compact page title and `<Heading as="h2" size="lg">` can introduce a prominent section. Use `<Display as="p">` for decorative hero copy under an existing page title.
154
+ - Use `<Outline>` for one or two words of a Display line to get stroked poster type. Don't outline body text.
155
+ - Reserve Caption for short eyebrows or supporting metadata. Use `<Text size="sm">` for instructions and use the control's `label` prop or `<Field>` for field labels.
156
+ - Numbers in stats and tables use `font-variant-numeric: tabular-nums` (built into Stat).
157
+ - Line length: keep ledes under ~50rem (`max-width: 50rem`).
158
+
159
+ ---
160
+
161
+ # Corners
162
+
163
+ A standard CSS `border-radius` joins a circular arc to a straight edge. A smoothed corner (a *squircle*) eases the curve into the straight edge. SW3 uses smoothing **0.6** by default.
164
+
165
+ `useSquircle()` measures the element with a ResizeObserver and returns the path. `<SquircleLayers>` draws the fill, the inner border, and the outer focus ring. Set `clipContent` when content needs to follow the surface shape.
166
+
167
+ ## Radius scale
168
+
169
+ | Token | px | Typical use |
170
+ | --- | --- | --- |
171
+ | `xs` | 6 | Small buttons, badges inside cards |
172
+ | `sm` | 10 | Buttons (md), inputs, option cards, segmented |
173
+ | `md` | 14 | Large buttons |
174
+ | `lg` | 20 | Cards, xl buttons, maps — the default surface |
175
+ | `xl` | 28 | Hero posters |
176
+ | `2xl` | 36 | Full-bleed feature panels |
177
+ | `full` | 9999 | Pills (the radius is clamped to half the height) |
178
+
179
+ **Nesting rule:** subtract the inset from the frame's effective radius, with a minimum of zero for exact nesting. Use the frame's smoothing and the same drawing method for both shapes.
180
+
181
+ ## Building a new component
182
+
183
+ ```tsx
184
+ const sq = useSquircle<HTMLDivElement>({ radius: 'lg' })
185
+ return (
186
+ <div ref={sq.ref} className="sw-sq my-tile">
187
+ <SquircleLayers paths={sq.paths} radius={sq.radius} ringOffset={sq.ringOffset} borderWidth={1} />
188
+ {children}
189
+ </div>
190
+ )
191
+ ```
192
+
193
+ ```css
194
+ .my-tile { --sw-sq-bg: var(--sw-background); --sw-sq-border: var(--sw-frame); }
195
+ .my-tile:hover { --sw-sq-border: var(--sw-foreground); }
196
+ ```
197
+
198
+ Don't use `border`, `border-radius`, `box-shadow` rings or `background` on squircle hosts; set the `--sw-sq-*` variables instead.
199
+
200
+ ## Inner corners are concentric
201
+
202
+ A rounded fill inside a squircle uses **container radius − container padding**. Examples are a menu row, a list row, a panel or accordion header, a hover or selected fill, or a toolbar button. **The container computes that value once and publishes it; fills only read it.**
203
+
204
+ - Every `SquircleLayers` host publishes its radius as `--sw-sq-r`. A frame's own rule also sets `--sw-inset` to its real padding: the distance from the frame edge to its fills.
205
+ - A frame whose fills sit at its inset publishes `--sw-inner-r: max(4px, calc(var(--sw-sq-r) - var(--sw-inset)))` in its own rule. These are Listbox, Popup/Menu, Command, Menubar, Toolbar, Tree, Accordion, Waterfall, NavigationMenu and Card panels.
206
+ - Every other squircle resets `--sw-inner-r` to the row radius (`.sw-sq` in base.css). That covers a padded Card, a Button and the docs stage. Their content is not in their corners. Before this rule, the docs stage Card (28px) passed 28 − 4 = 24px down to SidebarNav, and its 28px rows turned into pills. A new frame with fills at its inset needs its own `--sw-inner-r` rule.
207
+ - Frameless dashboard surfaces (AppShell, flush grids) publish the row radius (`--sw-row-r`, 8px). A panel inside them publishes 14 − 6 = 8.
208
+ - **A fill sets `border-radius: var(--sw-inner-r)` on all four corners and nothing else.** It never computes its own `sq-r − inset`. Inherited radius and inset can come from two different ancestors and mix: that bug caused the mismatched hover corners. Rows in the middle and rows in a corner are identical, so nothing has to be measured or re-tagged when a panel folds, animates or scrolls.
209
+ - The row fill (`.sw-row-fill`, shared by Listbox, Select, Combobox, Menu, Command and Tree) is plain CSS with that radius. SVG squircles are for frames and large surfaces.
210
+ - The right radius is not enough: the fill's curve must also run parallel to the frame's curve. CSS fills use `corner-shape: var(--sw-corner-shape)`, which is `round`. Measured against the 0.6 SVG squircle at the same radius, a round corner stays within 0.013 × r of it. `superellipse(1.6)` bulges out by 0.125 × r, which is 1px on an 8px row, so a 6px gap shrank to 5px at the corner. Don't change the token without rerunning the corner test.
211
+ - Frames are drawn at their exact layout size (ResizeObserver border-box), not `offsetWidth`/`offsetHeight`. Those round to whole pixels and drew the outline up to 0.5px off a frame with a fractional height.
212
+ - A frame that can be turned on and off still passes `sq.ref` on every render and switches with `useSquircle({ enabled })`. Motion elements bind their ref once, at mount, so `framed ? sq.ref : undefined` never draws a frame that turns on later.
213
+ - For SDK buttons that sit against the frame, use `InsetSquircleButton` (Number Input steppers, the Input clear button, Password reveal, Date Picker and Combobox actions).
214
+ - Guardrails:
215
+ - `packages/ui/tests/css-lint.test.ts` fails when a fill sets its own radius, or when `[data-corner]` patching comes back.
216
+ - `css-lint.test.ts` also fails on a conditional `sq.ref`.
217
+ - `corner-geometry.spec.ts` also fails when any row fill on any page has a radius above 0.4 × its height, which catches an inherited radius.
218
+ - `apps/playground/tests/corner-geometry.spec.ts` measures every fill in a frame corner on every docs page. The gap must be even, the radius must equal the frame radius minus that gap, and along the whole corner the fill must stay within 0.4px of that gap from the drawn frame path.
219
+
220
+ ## Frames sit on top
221
+
222
+ The 1px squircle frame is an inside stroke that paints above the content. Full-bleed children, such as maps, images, panes and hover rows, never hide it. Components that hold content (Resizable, Tree, Calendar, Waterfall) are framed by default.
223
+
224
+ ---
225
+
226
+ # Motion
227
+
228
+ Built on [Motion for React](https://motion.dev/docs/react-animation) (`motion/react`). Use the presets from `@peerproblem/sw3-ui`, not hand-tuned numbers.
229
+
230
+ | Preset | What it does | Used by |
231
+ | --- | --- | --- |
232
+ | `press` | `whileTap: scale 0.97`, snappy spring | Button |
233
+ | `lift` | hover `y: -2`, gentle spring | Card `interactive` |
234
+ | `transitions.snappy` | spring 520 / 34 | Switch thumb, segmented pill (`layoutId`) |
235
+ | `transitions.gentle` | spring 260 / 28 | Lifts, scale-ins |
236
+ | `enter.fadeUp` | opacity 0→1, y 12→0 | Sections and grid items on enter |
237
+ | `stagger(step)` | parent variant staggering children | Galleries |
238
+
239
+ ```tsx
240
+ import { motion } from 'motion/react'
241
+ import { enter, stagger } from '@peerproblem/sw3-ui'
242
+
243
+ <motion.div variants={stagger(0.06)} initial="hidden" whileInView="show" viewport={{ once: true }}>
244
+ {items.map((i) => <motion.div key={i.id} variants={enter.fadeUp}>…</motion.div>)}
245
+ </motion.div>
246
+ ```
247
+
248
+ ## Rules
249
+
250
+ - Duration ≤ 350 ms for UI feedback, ≤ 600 ms for enter animations. Springs for anything the user drags or toggles.
251
+ - Animate `transform` and `opacity` only. Don't animate width, height or color with JS. Use `layout` / `layoutId` for size and position changes.
252
+ - Never block input on an animation.
253
+ - `SwProvider` sets `reducedMotion="user"`, so Motion turns off transforms when the OS asks. CSS transitions are also cut in `@media (prefers-reduced-motion)`.
254
+
255
+ ---
256
+
257
+ # Layout
258
+
259
+ Structure rules on this page hold in every app. Pick page widths and section spacing to suit the product; the values below are defaults, not requirements.
260
+
261
+ - **Spacing scale:** 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80 (`--sw-space-*`). Use the scale instead of arbitrary values. Gaps inside a card are usually 12–16, between cards 12.
262
+ - **Page (default):** `--sw-canvas` background, content max-width around 1280px, 16px side gutters on phones and 24–40px on desktop. Tools and dashboards can use the full width.
263
+ - **Grids of items:** 1 column on phones, more as the container grows. Size tracks with `minmax()` or container queries rather than fixed breakpoints when the grid can be embedded.
264
+ - **Patterns** (`Card pattern="grid|hatch|dots|dashed"`) are decoration for marketing and documentation pages only. Don't use them in app surfaces.
265
+
266
+ ## Fit the container first
267
+
268
+ - Pages, cards, previews, forms, and ordinary lists should fit the available width and flow vertically. Size components against their container, including when embedded in a narrow desktop column. Let text wrap, let grid tracks shrink, and stack content when it stops fitting.
269
+ - Preserve access to content and actions when space runs out. Reduce the number of visible columns, wrap controls, or provide labeled previous/next controls. WeekSchedule shows the days that fit and provides Previous/Next days for the rest. Keep keyboard navigation and focus visible across ranges.
270
+ - Reserve local horizontal scrolling or panning for views that depend on continuous two-dimensional space, such as wide data grids, timeline editors, and canvases. Keep any overflow inside that view and provide a clear way to navigate it. Hiding the scrollbar does not solve overflow.
271
+ - Before shipping, check the full component and its gallery preview in a narrow container (including 320px) and at a wide size. Verify that text, the last column, and focused controls remain reachable and that the page itself does not scroll horizontally.
272
+
273
+ ## Quiet surfaces
274
+
275
+ - **One frame per visual group.** A card should identify a distinct item or task. Inside a card or gallery poster, group related content with spacing, headings, or a divider. Use a plain layout wrapper for alignment and padding.
276
+ - **Give inner boundaries a purpose.** Keep outlines that show where interaction or content ends, such as an editable artboard, a field, or an independent scroll region. Use a component's unframed mode when its parent already provides the grouping. For example, embed `<Canvas framed={false} />` in a poster so the artboard boundary stays visible and the editor sits directly on the poster surface.
277
+ - **No background decoration** on cards or tiles: no grids, dots, hatching or dashed insets. The content is the decoration.
278
+ - **Surfaces don't move.** No hover lift or scale on cards. A clickable card darkens its frame on hover and shows a focus ring. Motion is for controls (press) and things entering (popups, dialogs).
279
+ - **Height follows content.** No fixed or min heights on cards, stages or panels. Use a fixed height only when the content needs one, like a map or a chart canvas.
280
+ - **Titles start top-left.** Gallery tiles, cards and sections put their title and caption in the top-left corner, with content below. Don't spread words across corners.
281
+ - **One "selected" look:** a neutral fill (`--sw-item-selected`) with weight 500. Blue is for focus rings, check marks and the one primary action.
282
+ - **Field focus.** A focused text field emphasizes its 1px frame. Keyboard focus on buttons, checkboxes, tabs and rows uses the accent ring to show where focus is.
283
+ - **Scrollbars are thin and trackless.** `system.css` gives every SDK scroller, and the page, a slim thumb that follows the theme. Don't add `::-webkit-scrollbar` styles, and don't make small containers scroll. A dialog never squeezes its body into a scroller: on short screens the overlay scrolls instead.
284
+
285
+ ---
286
+
287
+ # Dark mode and preferences
288
+
289
+ ## How it works
290
+
291
+ Every color is a token in `tokens.ts` with a light and a dark value. The generated `tokens.css` applies:
292
+
293
+ - the light values by default
294
+ - the dark values under `@media (prefers-color-scheme: dark)`
295
+ - the dark values when `<html data-theme="dark">` is set (and light when `data-theme="light"`)
296
+
297
+ Components never pick colors themselves, so dark mode needs no component code.
298
+
299
+ ## Follow the system (default)
300
+
301
+ ```tsx
302
+ <SwProvider theme="system">…</SwProvider>
303
+ ```
304
+
305
+ ## Add a switcher
306
+
307
+ ```tsx
308
+ const [theme, setTheme] = useState<'light' | 'dark' | 'system'>('system')
309
+ <SwProvider theme={theme}>
310
+ <SegmentedControl aria-label="Theme" value={theme} onValueChange={(v) => setTheme(v as typeof theme)}
311
+ options={[{ value: 'light', label: 'Light' }, { value: 'dark', label: 'Dark' }, { value: 'system', label: 'System' }]} />
312
+ </SwProvider>
313
+ ```
314
+
315
+ Or use `<PreferencesPanel>`, which also covers motion, contrast and density. It reads and writes `usePreferences()`, so you can build your own panel from the same hook.
316
+
317
+ ## No flash on load
318
+
319
+ With `PreferencesProvider`, render `<PreferencesScript />` in `<head>`. It applies the saved choices (from localStorage or a cookie) before the first paint. If you manage the theme yourself, save the choice and set `data-theme` with an inline script:
320
+
321
+ ```html
322
+ <script>
323
+ try { var t = localStorage.getItem('sw-theme'); if (t && t !== 'system') document.documentElement.dataset.theme = t } catch (e) {}
324
+ </script>
325
+ ```
326
+
327
+ With server rendering, store the choice in a cookie as well. Render `<html data-theme={cookieTheme}>` on the server so the first HTML is already right.
328
+
329
+ ## Add your own colors
330
+
331
+ Add a token with `light` and `dark` values to `tokens.ts`, then run `npm run agent:build`. Use it as `var(--sw-<name>)`. Don't hard-code a color for one theme, and don't write `[data-theme=dark]` overrides inside component CSS.
332
+
333
+ ## Other preferences
334
+
335
+ `PreferencesProvider` and `usePreferences()` write `data-*` attributes on `<html>`, for example `data-motion="reduce"`, `data-contrast="more"`, `data-density="compact|comfortable|spacious"` and `data-font-size="sm|lg"`. Pick one owner for the theme: either `SwProvider theme` or Preferences (`manageTheme`), not both. Styles can follow the attributes:
336
+
337
+ ```css
338
+ :root[data-density='compact'] .my-table td { padding-block: 4px; }
339
+ ```
340
+
341
+ Motion is automatic: `SwProvider` sets Motion's `reducedMotion="user"`, and `base.css` shortens transitions under `prefers-reduced-motion`.
342
+
343
+ ---
344
+
345
+ # Tokens
346
+
347
+ CSS variables, generated from `packages/ui/src/tokens/tokens.ts`.
348
+
349
+ ## Color
350
+
351
+ | Variable | Light | Dark | Use |
352
+ | --- | --- | --- | --- |
353
+ | `--sw-canvas` | `#f0f2f5` | `#101010` | Page background behind cards and posters. |
354
+ | `--sw-background` | `#ffffff` | `#0a0a0a` | Surface of cards, inputs and posters. |
355
+ | `--sw-foreground` | `#0a0a0a` | `#fafafa` | Primary text and the primary (ink) button fill. |
356
+ | `--sw-muted` | `#f5f5f5` | `#262626` | Quiet fills: secondary buttons, tracks, wells. |
357
+ | `--sw-muted-foreground` | `#6f6f6f` | `#a1a1a1` | Secondary text, captions, axis labels. |
358
+ | `--sw-subtle` | `#5d5d5d` | `#a4a4a4` | Body copy one step quieter than foreground. |
359
+ | `--sw-frame` | `#c8c8c8` | `#303030` | Card and poster borders (1px). |
360
+ | `--sw-hairline` | `#ebebeb` | `#1b1b1b` | Dividers, hatch patterns, grid lines. |
361
+ | `--sw-border` | `#e5e5e5` | `rgba(255,255,255,0.1)` | Input and control borders. |
362
+ | `--sw-accent` | `#424242` | `#c9c9c9` | Emphasis for text, focus rings and selected indicators. Apps can supply a brand color. |
363
+ | `--sw-accent-solid` | `#0a0a0a` | `#fafafa` | Fill for accent buttons and selected controls. |
364
+ | `--sw-accent-solid-hover` | `#2d2d2d` | `#dedede` | Hover fill for accent-solid. |
365
+ | `--sw-accent-foreground` | `#ffffff` | `#0a0a0a` | Text and marks on accent-solid. |
366
+ | `--sw-success` | `#00a74a` | `#7bf1a8` | Positive deltas, success state. |
367
+ | `--sw-warning` | `#c27800` | `#f5b544` | Caution: meters in the sub-optimum range, warning toasts. |
368
+ | `--sw-danger` | `#e40014` | `#ff6568` | Destructive actions, negative deltas, errors. |
369
+ | `--sw-selection` | `#e4e4e4` | `#323232` | Text selection and soft selected backgrounds. |
370
+
371
+ ## Chart palette (in order)
372
+
373
+ | Variable | Light | Dark |
374
+ | --- | --- | --- |
375
+ | `--sw-chart-1` | `#006bff` | `#5fa1f3` |
376
+ | `--sw-chart-2` | `#0a0a0a` | `#fafafa` |
377
+ | `--sw-chart-3` | `#00a74a` | `#7bf1a8` |
378
+ | `--sw-chart-4` | `#ff7a00` | `#ffa94d` |
379
+ | `--sw-chart-5` | `#8b5cf6` | `#b197fc` |
380
+ | `--sw-chart-6` | `#e40014` | `#ff6568` |
381
+ | `--sw-chart-7` | `#00b8d9` | `#66d9e8` |
382
+ | `--sw-chart-8` | `#a1a1a1` | `#737373` |
383
+
384
+ ## Radius (squircle, px)
385
+
386
+ `none`=0 · `xs`=6 · `sm`=10 · `md`=14 · `lg`=20 · `xl`=28 · `2xl`=36 · `full`=9999
387
+
388
+ Smoothing: `none`=0 · `soft`=0.6 · `max`=1 (default `soft`)
389
+
390
+ ## Space (px)
391
+
392
+ `--sw-space-0`=0 · `--sw-space-1`=4 · `--sw-space-2`=8 · `--sw-space-3`=12 · `--sw-space-4`=16 · `--sw-space-5`=20 · `--sw-space-6`=24 · `--sw-space-8`=32 · `--sw-space-10`=40 · `--sw-space-12`=48 · `--sw-space-16`=64 · `--sw-space-20`=80
393
+
394
+ ## Type
395
+
396
+ | Style | Size | Line | Tracking | Weight | Family | Use |
397
+ | --- | --- | --- | --- | --- | --- | --- |
398
+ | caption | 11px | 1.55 | 0.08em | 400 | mono | UPPERCASE mono labels on posters. |
399
+ | xs | 12px | 1.33 | 0 | 400 | sans | Meta text, badges. |
400
+ | sm | 14px | 1.43 | 0 | 400 | sans | Descriptions, secondary text. |
401
+ | base | 16px | 1.5 | -0.011em | 400 | sans | Body copy. |
402
+ | lg | 20px | 1.5 | -0.015em | 400 | sans | Lede paragraphs. |
403
+ | title | 24px | 1.2 | -0.03em | 450 | sans | Card titles, big buttons. |
404
+ | heading | 48px | 1.08 | -0.045em | 450 | sans | Section headings. |
405
+ | display | 72px | 1 | -0.055em | 450 | sans | Hero and poster words. |
406
+
407
+ ## Motion
408
+
409
+ Durations (s): instant=0.1, fast=0.15, base=0.2, slow=0.35, slower=0.6
410
+ Springs: snappy (stiffness 520, damping 34), gentle (stiffness 260, damping 28), bouncy (stiffness 400, damping 18)
411
+
412
+ ---
413
+
414
+ # Components
415
+
416
+ # SwProvider
417
+
418
+ > Sets the theme and motion defaults for all SW3 components. Wrap the app once.
419
+
420
+ Category: foundation · Status: stable · Slug: `provider`
421
+
422
+ ```tsx
423
+ import { SwProvider } from '@peerproblem/sw3-ui'
424
+ import '@peerproblem/sw3-ui/styles.css'
425
+ ```
426
+
427
+ ## When to use
428
+ - Once, at the root of every app that uses @peerproblem/sw3-ui.
429
+
430
+ ## Avoid
431
+ - Nesting several providers. Use one at the root.
432
+
433
+ ## Props
434
+
435
+ | Prop | Type | Default | Description |
436
+ | --- | --- | --- | --- |
437
+ | `theme` | `'light' \| 'dark' \| 'system'` | `'system'` | Sets data-theme on <html>. |
438
+ | `reducedMotion` | `'user' \| 'always' \| 'never'` | `'user'` | Follows the OS reduce-motion setting by default. |
439
+
440
+ ## Examples
441
+
442
+ ### App root
443
+
444
+ ```tsx
445
+ import { SwProvider } from '@peerproblem/sw3-ui'
446
+ import '@peerproblem/sw3-ui/styles.css'
447
+
448
+ export function App() {
449
+ return (
450
+ <SwProvider theme="system">
451
+ <main className="sw-root">{/* ... */}</main>
452
+ </SwProvider>
453
+ )
454
+ }
455
+ ```
456
+
457
+ ## Rules
458
+ - Add className="sw-root" on the page wrapper (or <body class="sw-body">) to get canvas background and Geist type.
459
+
460
+ ## DOM contract (for agents operating the page)
461
+
462
+ - Selector: `html[data-theme]`
463
+
464
+ ---
465
+
466
+ # Squircle
467
+
468
+ > Smoothed corners for any element. Use <Squircle> or combine useSquircle() with <SquircleLayers>.
469
+
470
+ Category: foundation · Status: stable · Slug: `squircle`
471
+
472
+ ```tsx
473
+ import { Squircle, useSquircle, SquircleLayers } from '@peerproblem/sw3-ui'
474
+ ```
475
+
476
+ ## When to use
477
+ - Building a new component that needs the system corner shape.
478
+ - Wrapping custom content (image, video) in a smoothed frame.
479
+
480
+ ## Avoid
481
+ - CSS border-radius on new surfaces — it will not match buttons and cards.
482
+ - Squircles on elements under ~20px tall; a plain pill is indistinguishable.
483
+
484
+ ## Props
485
+
486
+ | Prop | Type | Default | Description |
487
+ | --- | --- | --- | --- |
488
+ | `radius` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' \| number` | `'md'` | Squircle corner radius (token or px). |
489
+ | `smoothing` | `'none' \| 'soft' \| 'max' \| number` | `'soft' (0.6)` | Corner smoothing from 0 to 1. SW3 uses 0.6 by default. |
490
+ | `borderWidth` | `number` | `1` | Border drawn inside the shape. Color via --sw-sq-border. |
491
+ | `clipContent` | `boolean` | `false` | Clip children to the shape. |
492
+ | `preserveSmoothing` | `boolean` | `true` | Keep smoothing when the radius must shrink. |
493
+
494
+ ## Examples
495
+
496
+ ### Framed image
497
+
498
+ ```tsx
499
+ <Squircle radius="xl" clipContent style={{ width: 320, height: 200 }}>
500
+ <img src="/cover.jpg" alt="" style={{ width: '100%', height: '100%', objectFit: 'cover' }} />
501
+ </Squircle>
502
+ ```
503
+
504
+ ### Custom component
505
+
506
+ ```tsx
507
+ function Tile({ children }) {
508
+ const sq = useSquircle<HTMLDivElement>({ radius: 'lg' })
509
+ return (
510
+ <div ref={sq.ref} className="sw-sq" style={{ '--sw-sq-bg': 'var(--sw-muted)', padding: 16 } as React.CSSProperties}>
511
+ <SquircleLayers paths={sq.paths} radius={sq.radius} borderWidth={0} />
512
+ {children}
513
+ </div>
514
+ )
515
+ }
516
+ ```
517
+
518
+ ## Rules
519
+ - Colors are CSS variables on the host: --sw-sq-bg (fill), --sw-sq-border (stroke), --sw-sq-ring (focus ring). Change them in :hover/[data-state] selectors.
520
+
521
+ ## DOM contract (for agents operating the page)
522
+
523
+ - Selector: `[data-sw="squircle"], .sw-sq`
524
+
525
+ ---
526
+
527
+ # Typography
528
+
529
+ > Display, Outline, Heading, Text, Link, Caption and Kbd: the type scale for pages, panels and inline text.
530
+
531
+ Category: foundation · Status: stable · Slug: `typography`
532
+
533
+ ```tsx
534
+ import { Display, Outline, Heading, Text, Link, Caption, Kbd } from '@peerproblem/sw3-ui'
535
+ ```
536
+
537
+ ## When to use
538
+ - Display for heroes; Heading for sections; Text for copy; Caption for mono labels.
539
+
540
+ ## Avoid
541
+ - Picking heading levels by size. Set `as` from the outline and `size` from emphasis.
542
+ - ALL CAPS outside Caption.
543
+ - A horizontal rule from typography. Use Separator.
544
+
545
+ ## Props
546
+
547
+ | Prop | Type | Default | Description |
548
+ | --- | --- | --- | --- |
549
+ | `Display.size` | `'md' \| 'lg' \| 'xl'` | `'lg'` | Fluid sizes; xl is poster scale. |
550
+ | `Heading.size` | `'sm' \| 'md' \| 'lg'` | `'md'` | |
551
+ | `Text.size` | `'sm' \| 'base' \| 'lg'` | `'base'` | lg = lede paragraph. |
552
+ | `Text.tone` | `'default' \| 'muted' \| 'subtle'` | `'default'` | |
553
+ | `Display.as` | `'h1' \| 'h2' \| 'p' \| 'div'` | `'h1'` | Choose the hero heading level, or use p for decorative copy under a page title. |
554
+ | `Heading.as` | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h2'` | Choose the heading level from the document hierarchy. Use size for visual emphasis. |
555
+ | `Link.href` * | `string` | | Inline link destination. Supports standard anchor attributes. |
556
+ | `Text.as` | `'p' \| 'span' \| 'div'` | `'p'` | Use span for inline text. |
557
+
558
+ ## Examples
559
+
560
+ ### Section intro
561
+
562
+ ```tsx
563
+ <Separator tone="frame" />
564
+ <Heading as="h2" size="lg">Behaviors? What are those?</Heading>
565
+ <Text size="lg" tone="subtle">They are the pieces that make a component work.</Text>
566
+ <Caption>Tap a title to open it</Caption>
567
+ ```
568
+
569
+ ## Rules
570
+ - Use Display for the primary hero and Heading for page and section titles. Choose the HTML heading level independently of size.
571
+ - Look (default theme): headings at weight 450 with tight tracking, Geist and Geist Mono. Change the typefaces with --sw-font-sans and --sw-font-mono.
572
+ - Use Caption for short supporting metadata and Text for instructions.
573
+ - Kbd is a flat 1px frame.
574
+
575
+ ## DOM contract (for agents operating the page)
576
+
577
+ - Selector: `[data-sw="display"], [data-sw="heading"], [data-sw="text"], [data-sw="caption"]`
578
+
579
+ ---
580
+
581
+ # Preferences
582
+
583
+ > Applies user preferences (theme, reduced motion, contrast, density, font size) as data-* attributes on <html>, saves them to localStorage and a cookie, and ships a ready-made settings panel.
584
+
585
+ Category: foundation · Status: beta · Slug: `preferences`
586
+
587
+ ```tsx
588
+ import { PreferencesProvider, PreferencesPanel, usePreferences, PreferencesScript, readPreferencesCookie, getPreferenceAttributes } from '@peerproblem/sw3-ui'
589
+ ```
590
+
591
+ ## When to use
592
+ - An appearance/accessibility settings page or menu.
593
+ - Any app that should remember theme, motion, contrast, density or text size between visits (SSR-safe with the cookie).
594
+
595
+ ## Avoid
596
+ - Setting `SwProvider theme` while PreferencesProvider manages the theme — they would both write html[data-theme]. Leave SwProvider at its default, or pass `manageTheme={false}`.
597
+ - Reading localStorage yourself for these settings. Use `usePreferences()`.
598
+ - Building your own toggles for these. Use `<PreferencesPanel>` (or `usePreferences().setPreference`).
599
+
600
+ ## Props
601
+
602
+ | Prop | Type | Default | Description |
603
+ | --- | --- | --- | --- |
604
+ | `PreferencesProvider.defaultValue` | `Partial<PreferenceValues>` | | Starting values; pass the cookie value read on the server to avoid a flash. |
605
+ | `PreferencesProvider.value / onValueChange` | `PreferenceValues / (v) => void` | | Controlled preferences. |
606
+ | `PreferencesProvider.storage` | `'local' \| 'cookie' \| 'both' \| 'none'` | `'both'` | Where choices are saved (all access is try/catch guarded). |
607
+ | `PreferencesProvider.storageKey` | `string` | `'sw-preferences'` | localStorage key and cookie name. |
608
+ | `PreferencesProvider.manageTheme` | `boolean` | `true` | Write html[data-theme] (system removes it, exactly like SwProvider). |
609
+ | `PreferenceValues` | `{ theme: 'light'\|'dark'\|'system'; motion: 'system'\|'reduce'\|'full'; contrast: 'system'\|'more'\|'normal'; density: 'compact'\|'comfortable'\|'spacious'; fontSize: 'sm'\|'md'\|'lg' }` | | Defaults: system, system, system, comfortable, md. |
610
+ | `usePreferences()` | `{ preferences, resolved, setPreference(key, value), setPreferences(partial), reset() }` | | `resolved` says what system means right now (theme, motion, contrast). |
611
+ | `PreferencesPanel.show` | `PreferenceKey[]` | `all five` | Rows to show, in order. |
612
+ | `PreferencesPanel.resettable` | `boolean` | `true` | Show "Reset to defaults". |
613
+ | `PreferencesScript` | `{ storageKey?, nonce? }` | | Inline <head> script that applies saved values before first paint. |
614
+ | `readPreferencesCookie(cookieHeader, key?) / getPreferenceAttributes(prefs)` | `functions` | | Server helpers: read the cookie, then spread the attributes onto <html>. |
615
+
616
+ ## Examples
617
+
618
+ ### App root + settings page
619
+
620
+ ```tsx
621
+ <SwProvider>
622
+ <PreferencesProvider>
623
+ <App />
624
+ </PreferencesProvider>
625
+ </SwProvider>
626
+
627
+ function AppearanceSettings() {
628
+ return <PreferencesPanel />
629
+ }
630
+ ```
631
+
632
+ ### Read a preference
633
+
634
+ ```tsx
635
+ function Sidebar() {
636
+ const { preferences, setPreference } = usePreferences()
637
+ return <Switch label="Compact" checked={preferences.density === 'compact'}
638
+ onCheckedChange={(on) => setPreference('density', on ? 'compact' : 'comfortable')} />
639
+ }
640
+ ```
641
+
642
+ ### Server rendering
643
+
644
+ ```tsx
645
+ const prefs = readPreferencesCookie(request.headers.get('cookie'))
646
+ <html {...getPreferenceAttributes(prefs)}>
647
+ <head><PreferencesScript /></head>
648
+ <body><PreferencesProvider defaultValue={prefs}>…</PreferencesProvider></body>
649
+ </html>
650
+ ```
651
+
652
+ ## Rules
653
+ - Mount one PreferencesProvider near the root (inside SwProvider).
654
+ - Style with the attributes: `[data-density="compact"] .row { … }`, or use `var(--sw-density)` (0.85 / 1 / 1.2). Reduced motion and more contrast are applied to SW3 components for you.
655
+ - motion also drives motion/react (MotionConfig reducedMotion).
656
+
657
+ ## Accessibility
658
+ - PreferencesPanel is a labelled group of SegmentedControls (radiogroups) and Switches.
659
+ - Respect the OS by default: system values follow prefers-color-scheme, prefers-reduced-motion and prefers-contrast live.
660
+
661
+ ## DOM contract (for agents operating the page)
662
+
663
+ - Selector: `[data-sw="preferences-panel"]`
664
+ - `html[data-theme]`: 'light' | 'dark' (absent = system)
665
+ - `html[data-motion]`: 'reduce' | 'full' (resolved)
666
+ - `html[data-contrast]`: 'more' | 'normal' (resolved)
667
+ - `html[data-density]`: 'compact' | 'comfortable' | 'spacious'
668
+ - `html[data-font-size]`: 'sm' | 'md' | 'lg'
669
+ - `data-key / data-value (rows)`: each [data-sw="preferences-item"] row
670
+ - How to operate: Agent bridge (on the panel): setPreference(key, value), setValue(partial), reset(). DOM: click the radios in each [data-sw="preferences-item"] row or toggle its switch.
671
+
672
+ Related: `provider`, `segmented-control`, `switch`
673
+
674
+ ---