@astryxdesign/cli 0.4.4 → 0.4.5-canary.33ba2b6
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.
- package/CHANGELOG.md +5 -0
- package/assets/docs/layout.doc.dense.mjs +275 -30
- package/assets/docs/layout.doc.mjs +412 -78
- package/assets/templates/blocks/components/BottomSheet/BottomSheetSnapPoints.doc.mjs +23 -0
- package/assets/templates/blocks/components/BottomSheet/BottomSheetSnapPoints.tsx +155 -0
- package/package.json +9 -9
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
# @xds/cli
|
|
2
2
|
|
|
3
|
+
# 0.4.5
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
3
7
|
# 0.4.4
|
|
4
8
|
|
|
5
9
|
#### New Components
|
|
@@ -16,6 +20,7 @@
|
|
|
16
20
|
Three more lessons came out of building a real app on it. The page now `<link>`s the theme's webfont from Google Fonts, because the theme _names_ Figtree and never loads it, so every viewer silently got the fallback stack (#5015 again). It imports the theme OBJECT and wraps in `<Theme theme={neutralTheme} mode="system">`, so light and dark follow the OS — the `data-astryx-theme` attribute alone scopes the stylesheet but cannot switch modes. And `#root:empty` carries a "Loading…" state, because ESM-from-CDN has real latency and a blank page reads as broken. Markup is `htm`, with a comment saying it is optional and `createElement` is the dependency-free alternative.
|
|
17
21
|
|
|
18
22
|
A recipe that is only read is a recipe that is only assumed to work, so CI renders it: `.github/scripts/cdn-template-smoke-test.mjs` scaffolds the page with the real CLI and opens it in headless Chromium, failing on any console error, page error or failed request, and on a page that loads without rendering.
|
|
23
|
+
|
|
19
24
|
- `astryx theme build` takes any number of theme files — `astryx theme build themes/*.ts` compiles them all in one process, so an app with several themes no longer hand-rolls a loop that re-enters the CLI once per theme. Outputs are byte-identical to the serial invocations; the run stops at the first failure and names the theme that failed. The CLI's Node floor (>=22.13) is now declared in `engines`, so a package manager can enforce it at install instead of the build failing later (#5121).
|
|
20
25
|
- `defineTheme`: `color.accent` accepts a `[light, dark]` tuple (#2279)
|
|
21
26
|
`ColorScaleConfig.accent` now takes either a single hex or a `[light, dark]` tuple, matching `TokenValue`. With a tuple, `expandColorScale` derives the light half of every generated `light-dark()` pair from the light seed's palettes and the dark half from the dark seed's, so each scheme gets a consistent derived palette (muted, on-accent, neutrals) instead of the `tokens['--color-accent']` workaround that skips scale generation. Single-string configs are unchanged, token for token. Also documents the precedence between `color` and `tokens` for accent-derived values: `tokens` entries win token by token, the `var(--color-accent)` reference tokens follow a `--color-accent` override at runtime, and the baked `--color-on-accent` stays derived from the `color.accent` seed.
|
|
@@ -4,91 +4,336 @@
|
|
|
4
4
|
|
|
5
5
|
export const docsDense = {
|
|
6
6
|
description:
|
|
7
|
-
'
|
|
7
|
+
'outside-in app layout: scaffold -> structure -> spacing -> breakpoints.',
|
|
8
8
|
sections: [
|
|
9
9
|
{
|
|
10
|
-
section: '
|
|
11
|
-
title: '
|
|
10
|
+
section: 'Overview',
|
|
11
|
+
title: 'Overview',
|
|
12
12
|
content: [
|
|
13
13
|
{
|
|
14
14
|
type: 'prose',
|
|
15
|
-
text: '
|
|
15
|
+
text: 'build outside-in. settle the shell + region budgets before any content, then work inward. content-first drifts into a padded column of cards, each section inventing its own container.',
|
|
16
16
|
},
|
|
17
17
|
{
|
|
18
18
|
type: 'list',
|
|
19
19
|
items: [
|
|
20
|
-
'
|
|
21
|
-
'
|
|
22
|
-
'
|
|
23
|
-
'
|
|
20
|
+
'scaffold: pick shell, budget regions, choose nav',
|
|
21
|
+
'structure: rank content per region, pick the weakest container that groups it',
|
|
22
|
+
'spacing: hold one content line per region, then tune gaps + density',
|
|
23
|
+
'breakpoints: decide what each region does as width changes',
|
|
24
24
|
],
|
|
25
25
|
},
|
|
26
|
-
|
|
26
|
+
{
|
|
27
|
+
type: 'prose',
|
|
28
|
+
text: 'decides layout, not component APIs. npx astryx build "<idea>" = closest template for your app type. npx astryx component <Name> = props.',
|
|
29
|
+
},
|
|
27
30
|
],
|
|
28
31
|
},
|
|
29
32
|
{
|
|
30
|
-
section: '
|
|
31
|
-
title: '
|
|
33
|
+
section: 'Scaffold',
|
|
34
|
+
title: 'Scaffold',
|
|
32
35
|
content: [
|
|
36
|
+
// Shell
|
|
37
|
+
null,
|
|
33
38
|
{
|
|
34
39
|
type: 'prose',
|
|
35
|
-
text: '
|
|
40
|
+
text: 'pick the shell + budget its regions before any content exists. structural widths are the one place raw px belongs; everything inside uses the scale.',
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
type: 'list',
|
|
44
|
+
items: [
|
|
45
|
+
'pick frame: AppShell (nav apps) | Layout + LayoutPanel in a start/end slot (multi-pane tools) | plain column (docs/forms)',
|
|
46
|
+
'give every fixed region a width budget, so none negotiates for space at render time',
|
|
47
|
+
'read content to set fill vs capped: tables/charts/boards fill; prose/forms/lists cap via Layout contentWidth',
|
|
48
|
+
'set container policy (rows or card grid) before writing content',
|
|
49
|
+
],
|
|
50
|
+
},
|
|
51
|
+
null,
|
|
52
|
+
{
|
|
53
|
+
type: 'prose',
|
|
54
|
+
text: 'verify: every region has a width budget + fill-or-capped + a container policy written down before any content.',
|
|
55
|
+
},
|
|
56
|
+
// Navigation
|
|
57
|
+
null,
|
|
58
|
+
{
|
|
59
|
+
type: 'prose',
|
|
60
|
+
text: 'nav left open? default SideNav: it absorbs destinations you have not planned yet. app type + destination count are guiding indicators, not determining rules.',
|
|
61
|
+
},
|
|
62
|
+
{
|
|
63
|
+
type: 'list',
|
|
64
|
+
items: [
|
|
65
|
+
'SideNav (default): need grouping, customizable, items carry secondary actions, or must collapse. trackers, consoles, settings usually start here',
|
|
66
|
+
'TopNav: shallow nav you expect to stay shallow, context must stay visible, or control/filter-heavy page; + TabList for a 2nd level. media libraries often sit over grid content',
|
|
67
|
+
'both: a genuine suite. TopNav = ecosystem concerns (context switcher, global search), SideNav = product nav',
|
|
68
|
+
'neither: messaging/feeds use a column frame of rail, nav, stream, panel',
|
|
69
|
+
],
|
|
36
70
|
},
|
|
37
71
|
null,
|
|
38
72
|
{
|
|
39
73
|
type: 'prose',
|
|
40
|
-
text: '
|
|
74
|
+
text: 'verify: you can state the reason in one sentence, and it still holds if the nav doubles. npx astryx build "<idea>" names the closest template, --skeleton shows the pairing wired up.',
|
|
75
|
+
},
|
|
76
|
+
// Best practices
|
|
77
|
+
null,
|
|
78
|
+
{
|
|
79
|
+
type: 'list',
|
|
80
|
+
items: [
|
|
81
|
+
'decide frame + region width budgets + fill-or-capped before content',
|
|
82
|
+
'state the reason for the nav choice, or inherit template pairing',
|
|
83
|
+
'raw px for structural widths; interior = tokens',
|
|
84
|
+
],
|
|
85
|
+
},
|
|
86
|
+
{
|
|
87
|
+
type: 'list',
|
|
88
|
+
items: [
|
|
89
|
+
'build content-first, Card-wrapping each section',
|
|
90
|
+
'stretch prose/forms/lists across a wide region instead of capping with contentWidth',
|
|
91
|
+
'SideNav when the nav is really filters/controls, or must hold wide elements like breadcrumbs',
|
|
92
|
+
'TopNav when top-slot ownership is unclear, or hierarchy is deep or still growing',
|
|
93
|
+
'both bars when the ecosystem layer is thin',
|
|
94
|
+
'break template nav pairing without a reason',
|
|
95
|
+
],
|
|
41
96
|
},
|
|
42
97
|
],
|
|
43
98
|
},
|
|
44
99
|
{
|
|
45
|
-
section: '
|
|
46
|
-
title: '
|
|
100
|
+
section: 'Structure',
|
|
101
|
+
title: 'Structure',
|
|
47
102
|
content: [
|
|
103
|
+
// Type hierarchy
|
|
104
|
+
null,
|
|
105
|
+
{
|
|
106
|
+
type: 'prose',
|
|
107
|
+
text: 'one lead per region, then rank with weight+color, not size. two text colors only: primary + secondary, nothing dimmer. body copy needs no props.',
|
|
108
|
+
},
|
|
109
|
+
{
|
|
110
|
+
type: 'list',
|
|
111
|
+
items: [
|
|
112
|
+
'body (default): plain Text, no type/color/size prop',
|
|
113
|
+
'lead: Heading at the level matching page depth, or body Text at a heavier weight',
|
|
114
|
+
'support: step to secondary color, not to a smaller size',
|
|
115
|
+
'meta: the supporting type, or StatusDot/Token instead of prose',
|
|
116
|
+
],
|
|
117
|
+
},
|
|
118
|
+
null,
|
|
119
|
+
{
|
|
120
|
+
type: 'prose',
|
|
121
|
+
text: 'squint test: read lead, then support, then groups, in order. everything at once = raise contrast (weight/color), not borders and not smaller text.',
|
|
122
|
+
},
|
|
123
|
+
// Containers
|
|
124
|
+
null,
|
|
125
|
+
{
|
|
126
|
+
type: 'prose',
|
|
127
|
+
text: 'weakest container that reads as a group, escalate only when it fails. weakest to strongest:',
|
|
128
|
+
},
|
|
129
|
+
{
|
|
130
|
+
type: 'list',
|
|
131
|
+
items: [
|
|
132
|
+
'spacing/gap: related items inside one group. the default rhythm',
|
|
133
|
+
'Divider: peers in a dense list/toolbar, or fencing a header from a scrollable body',
|
|
134
|
+
'Section: default page-structure unit, related content under a heading. no border',
|
|
135
|
+
'Card: self-contained widget (KPI tile, chart, gallery entry) or hard boundary',
|
|
136
|
+
],
|
|
137
|
+
},
|
|
138
|
+
null,
|
|
139
|
+
{
|
|
140
|
+
type: 'prose',
|
|
141
|
+
text: 'test: records -> rows (Table columnar, List single-line); self-contained widget or hard boundary -> Card; everything else -> Section.',
|
|
142
|
+
},
|
|
143
|
+
// Headers and footers
|
|
144
|
+
null,
|
|
145
|
+
{
|
|
146
|
+
type: 'prose',
|
|
147
|
+
text: 'a region can pin a header/footer while its body scrolls. both are Layout slots, and padding set once on Layout reaches all three, so header/body/footer share one content line.',
|
|
148
|
+
},
|
|
149
|
+
{
|
|
150
|
+
type: 'list',
|
|
151
|
+
items: [
|
|
152
|
+
'LayoutHeader in the header slot: region title + its primary action',
|
|
153
|
+
'Toolbar instead of LayoutHeader when the header carries interactive controls',
|
|
154
|
+
'LayoutFooter in the footer slot: actions that commit the work + must stay reachable',
|
|
155
|
+
'defaultHasDividers on Layout fences both at once, rather than hasDivider per slot',
|
|
156
|
+
],
|
|
157
|
+
},
|
|
158
|
+
null,
|
|
159
|
+
{
|
|
160
|
+
type: 'prose',
|
|
161
|
+
text: 'verify: scroll the body. header + footer stay put, dividers run full-bleed, all three still share one left content line.',
|
|
162
|
+
},
|
|
163
|
+
// Side panels
|
|
164
|
+
null,
|
|
165
|
+
{
|
|
166
|
+
type: 'prose',
|
|
167
|
+
text: 'master-detail: select a row -> fixed-width side panel, no navigation away.',
|
|
168
|
+
},
|
|
169
|
+
{
|
|
170
|
+
type: 'list',
|
|
171
|
+
items: [
|
|
172
|
+
'LayoutPanel in the start or end slot of Layout, holding a fixed width budget',
|
|
173
|
+
'hasDivider fences it from content; isScrollable so long detail scrolls on its own',
|
|
174
|
+
'user-adjustable width: useResizable() + ResizeHandle on the panel inner edge. after the panel in a start slot, before it in an end slot w/ isReversed',
|
|
175
|
+
'the handle then owns the divider, so the panel sets hasDivider={false}',
|
|
176
|
+
'EmptyState when nothing is selected, so the region never collapses',
|
|
177
|
+
],
|
|
178
|
+
},
|
|
179
|
+
null,
|
|
48
180
|
{
|
|
49
181
|
type: 'prose',
|
|
50
|
-
text: '
|
|
182
|
+
text: 'verify: at narrow widths the panel yields width instead of squeezing content (see Breakpoints), and only one element between the regions draws a border.',
|
|
51
183
|
},
|
|
184
|
+
// Best practices
|
|
185
|
+
null,
|
|
52
186
|
{
|
|
53
187
|
type: 'list',
|
|
54
188
|
items: [
|
|
55
|
-
'
|
|
56
|
-
'
|
|
57
|
-
'
|
|
58
|
-
'
|
|
189
|
+
'one lead per region; rank via weight+color; one primary action',
|
|
190
|
+
'leave body copy at its defaults; demote via weight+color, not size',
|
|
191
|
+
'default Section; weakest container that reads as a group',
|
|
192
|
+
'collections = rows (Table/List), edge-to-edge with dividers',
|
|
193
|
+
'side panel on select; it yields width at narrow sizes',
|
|
59
194
|
],
|
|
60
195
|
},
|
|
61
196
|
{
|
|
62
197
|
type: 'list',
|
|
63
198
|
items: [
|
|
64
|
-
'
|
|
65
|
-
'
|
|
66
|
-
'
|
|
67
|
-
'
|
|
199
|
+
'grey + shrink body copy, so a whole region reads as metadata',
|
|
200
|
+
'the disabled color for content; it fails contrast, it is for disabled controls',
|
|
201
|
+
'card soup: each record in its own Card',
|
|
202
|
+
'cards-in-cards, or full-width Cards as page structure',
|
|
203
|
+
'a header/footer rebuilt inside the body, where it scrolls away with the rows',
|
|
204
|
+
'flexbox soup instead of Grid/Layout/Section/FormLayout',
|
|
205
|
+
'two competing primary actions in one region',
|
|
206
|
+
'Badge as decoration; use StatusDot/Token for status',
|
|
68
207
|
],
|
|
69
208
|
},
|
|
70
209
|
],
|
|
71
210
|
},
|
|
72
211
|
{
|
|
73
|
-
section: '
|
|
74
|
-
title: '
|
|
212
|
+
section: 'Spacing',
|
|
213
|
+
title: 'Spacing',
|
|
75
214
|
content: [
|
|
215
|
+
// Alignment
|
|
216
|
+
null,
|
|
217
|
+
{
|
|
218
|
+
type: 'prose',
|
|
219
|
+
text: 'container owns padding + child gaps; children zero margins; interior spacing = token. one content line per region, hold the line not the padding: container_inset = content_line - component_intrinsic_inset.',
|
|
220
|
+
},
|
|
221
|
+
{
|
|
222
|
+
type: 'list',
|
|
223
|
+
items: [
|
|
224
|
+
'Text/Heading carry no inset -> container takes the full padding',
|
|
225
|
+
'List/Tab/Menu/nav items carry a small inset -> container gives up padding, component owns the line',
|
|
226
|
+
'Table cells carry a larger inset -> container gives up padding, cell owns the line',
|
|
227
|
+
],
|
|
228
|
+
},
|
|
229
|
+
null,
|
|
76
230
|
{
|
|
77
231
|
type: 'prose',
|
|
78
|
-
text: '
|
|
232
|
+
text: 'verify: draw one vertical line down the left. every label touches it; only hover/selected backgrounds cross it.',
|
|
79
233
|
},
|
|
234
|
+
// Rhythm
|
|
80
235
|
null,
|
|
236
|
+
{
|
|
237
|
+
type: 'prose',
|
|
238
|
+
text: 'grouping = contrast between tight and generous gaps, not one repeated value. same step everywhere = proximity does no work.',
|
|
239
|
+
},
|
|
240
|
+
{
|
|
241
|
+
type: 'list',
|
|
242
|
+
items: [
|
|
243
|
+
'tight gaps bind: the smallest steps, inside an item or field',
|
|
244
|
+
'generous gaps separate: several steps up, between sections',
|
|
245
|
+
'reach for the in-between steps to tune cadence, not the same two values everywhere',
|
|
246
|
+
],
|
|
247
|
+
},
|
|
248
|
+
null,
|
|
249
|
+
{
|
|
250
|
+
type: 'prose',
|
|
251
|
+
text: 'verify: borders removed, you can still name the groups from spacing alone. cannot = intervals too uniform. form fields excepted: FormLayout owns their spacing.',
|
|
252
|
+
},
|
|
253
|
+
// Density and size
|
|
254
|
+
null,
|
|
255
|
+
{
|
|
256
|
+
type: 'prose',
|
|
257
|
+
text: 'density by use frequency; every control in a row shares one size so heights share a baseline.',
|
|
258
|
+
},
|
|
259
|
+
{
|
|
260
|
+
type: 'list',
|
|
261
|
+
items: [
|
|
262
|
+
'compact: high-volume, fast scan (logs, monitors, large datasets)',
|
|
263
|
+
'balanced: most Table/List surfaces',
|
|
264
|
+
'spacious: low-frequency or high-stakes rows (settings, short selection list)',
|
|
265
|
+
],
|
|
266
|
+
},
|
|
267
|
+
null,
|
|
268
|
+
{
|
|
269
|
+
type: 'prose',
|
|
270
|
+
text: 'verify: one size per row, paired with the density of the region it sits in.',
|
|
271
|
+
},
|
|
272
|
+
// Best practices
|
|
273
|
+
null,
|
|
274
|
+
{
|
|
275
|
+
type: 'list',
|
|
276
|
+
items: [
|
|
277
|
+
'container owns padding; children zero margins',
|
|
278
|
+
'one content line: text on line, hover bleeds to edge',
|
|
279
|
+
'one padding token across region header/body/footer',
|
|
280
|
+
'contrast tight vs generous gaps',
|
|
281
|
+
'one control size per row; density by use frequency',
|
|
282
|
+
],
|
|
283
|
+
},
|
|
284
|
+
{
|
|
285
|
+
type: 'list',
|
|
286
|
+
items: [
|
|
287
|
+
'double padding (component past its heading); keep one inset owner',
|
|
288
|
+
'raw px for interior spacing; tokens only',
|
|
289
|
+
'one repeated gap everywhere',
|
|
290
|
+
'mixed control sizes in one row',
|
|
291
|
+
],
|
|
292
|
+
},
|
|
81
293
|
],
|
|
82
294
|
},
|
|
83
295
|
{
|
|
84
|
-
section: '
|
|
85
|
-
title: '
|
|
296
|
+
section: 'Breakpoints',
|
|
297
|
+
title: 'Breakpoints',
|
|
86
298
|
content: [
|
|
299
|
+
// Responsive contract
|
|
300
|
+
null,
|
|
87
301
|
{
|
|
88
302
|
type: 'prose',
|
|
89
|
-
text: '
|
|
303
|
+
text: 'lock what each region does as width changes; pair each contract line with the prop/hook that enforces it.',
|
|
304
|
+
},
|
|
305
|
+
{
|
|
306
|
+
type: 'list',
|
|
307
|
+
items: [
|
|
308
|
+
'divide: how many regions survive at each width',
|
|
309
|
+
'reveal: which regions earn their width only when there is room, opening on demand below that',
|
|
310
|
+
'resize: content flexes, fixed regions hold their budgets, text capped by contentWidth so line length holds',
|
|
311
|
+
'swap: nav -> MobileNav at the AppShell mobileNav breakpoint; side panel -> Dialog/BottomSheet via useMediaQuery',
|
|
312
|
+
],
|
|
90
313
|
},
|
|
91
314
|
null,
|
|
315
|
+
{
|
|
316
|
+
type: 'prose',
|
|
317
|
+
text: 'verify: every contract line names a mechanism, so the comment cannot drift from the behavior.',
|
|
318
|
+
},
|
|
319
|
+
// Best practices
|
|
320
|
+
null,
|
|
321
|
+
{
|
|
322
|
+
type: 'list',
|
|
323
|
+
items: [
|
|
324
|
+
'write the contract down for every region before calling the layout done',
|
|
325
|
+
'decide per region: revealed, resized, or swapped at each width',
|
|
326
|
+
'drop a region rather than let it fight for width it lacks',
|
|
327
|
+
],
|
|
328
|
+
},
|
|
329
|
+
{
|
|
330
|
+
type: 'list',
|
|
331
|
+
items: [
|
|
332
|
+
'3 regions at a width where none has usable space',
|
|
333
|
+
'shrink every region uniformly instead of swapping/dropping one',
|
|
334
|
+
'a CSS breakpoint the contract comment never mentions',
|
|
335
|
+
],
|
|
336
|
+
},
|
|
92
337
|
],
|
|
93
338
|
},
|
|
94
339
|
],
|
|
@@ -7,152 +7,486 @@ export const docs = {
|
|
|
7
7
|
title: 'Layout',
|
|
8
8
|
category: 'guide',
|
|
9
9
|
description:
|
|
10
|
-
'
|
|
10
|
+
'Build an app layout outside-in: scaffold the regions, structure the content, tune the spacing, then adapt across widths.',
|
|
11
11
|
|
|
12
12
|
sections: [
|
|
13
13
|
{
|
|
14
|
-
title: '
|
|
14
|
+
title: 'Overview',
|
|
15
15
|
content: [
|
|
16
16
|
{
|
|
17
17
|
type: 'prose',
|
|
18
|
-
text: '
|
|
18
|
+
text: 'Build a layout outside-in. Settle the shell and its region budgets before any content exists, then work inward. Content-first layouts drift into a padded column of cards, because every section ends up inventing its own container.',
|
|
19
19
|
},
|
|
20
20
|
{
|
|
21
21
|
type: 'list',
|
|
22
22
|
style: 'ordered',
|
|
23
23
|
items: [
|
|
24
|
-
'
|
|
25
|
-
'
|
|
26
|
-
'
|
|
27
|
-
'
|
|
24
|
+
'Scaffold: pick the shell, budget each region, and choose navigation',
|
|
25
|
+
'Structure: rank the content in each region, then pick the weakest container that groups it',
|
|
26
|
+
'Spacing: hold one content line per region, then tune gaps and density',
|
|
27
|
+
'Breakpoints: decide what each region does as width changes',
|
|
28
28
|
],
|
|
29
29
|
},
|
|
30
30
|
{
|
|
31
|
-
type: '
|
|
32
|
-
|
|
33
|
-
label: 'A three-region tool frame',
|
|
34
|
-
code: `// Frame: nav 256 | content flex | inspector 380 (resizable)
|
|
35
|
-
<AppShell sideNav={<SideNav>{/* nav items */}</SideNav>} contentPadding={0}>
|
|
36
|
-
<Layout>
|
|
37
|
-
<LayoutContent>{/* dense list or table, edge-to-edge */}</LayoutContent>
|
|
38
|
-
<LayoutPanel width={380} resizable={{minSizePx: 320, maxSizePx: 480}} hasDivider>
|
|
39
|
-
{/* inspector for the selected row */}
|
|
40
|
-
</LayoutPanel>
|
|
41
|
-
</Layout>
|
|
42
|
-
</AppShell>`,
|
|
31
|
+
type: 'prose',
|
|
32
|
+
text: 'This guide decides layout, not component APIs. Run `npx astryx build "<idea>"` to start from the closest template for your app type, and `npx astryx component <Name>` for a component\'s props.',
|
|
43
33
|
},
|
|
44
34
|
],
|
|
45
35
|
},
|
|
46
36
|
{
|
|
47
|
-
title: '
|
|
37
|
+
title: 'Scaffold',
|
|
48
38
|
content: [
|
|
39
|
+
{type: 'heading', level: 3, text: 'Shell'},
|
|
49
40
|
{
|
|
50
41
|
type: 'prose',
|
|
51
|
-
text: '
|
|
42
|
+
text: 'Pick the shell and budget its regions before any content exists. Structural widths are the one place raw px belongs; everything inside them uses the spacing scale.',
|
|
52
43
|
},
|
|
53
44
|
{
|
|
54
|
-
type: '
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
],
|
|
62
|
-
[
|
|
63
|
-
'Console / observability (metrics, logs, deploys)',
|
|
64
|
-
'AppShell + SideNav or TopNav + TabList',
|
|
65
|
-
'Card grid for dashboard widgets; Table for everything else',
|
|
66
|
-
],
|
|
67
|
-
[
|
|
68
|
-
'Messaging / feed',
|
|
69
|
-
'Column frame: rail + sidebar + stream + panel',
|
|
70
|
-
'Rows and bubbles. No cards in the stream',
|
|
71
|
-
],
|
|
72
|
-
[
|
|
73
|
-
'Media library / gallery',
|
|
74
|
-
'AppShell + TopNav; grid content',
|
|
75
|
-
'Card grid (ClickableCard) with dense metadata rows in detail views',
|
|
76
|
-
],
|
|
77
|
-
[
|
|
78
|
-
'Settings / forms',
|
|
79
|
-
'AppShell + SideNav or settings template',
|
|
80
|
-
'Sections with FormLayout; Card only to group dangerous or billing actions',
|
|
81
|
-
],
|
|
45
|
+
type: 'list',
|
|
46
|
+
style: 'ordered',
|
|
47
|
+
items: [
|
|
48
|
+
'Pick the frame: AppShell for nav apps, Layout with LayoutPanel in a start or end slot for multi-pane tools, or a plain content column for documents and forms',
|
|
49
|
+
'Give every fixed region a width budget, so no region has to negotiate for space at render time',
|
|
50
|
+
'Read the content to set fill or capped: tables, charts, and boards fill their region; prose, forms, and lists cap with Layout contentWidth so lines never over-stretch',
|
|
51
|
+
'Set each region container policy, rows or card grid, before writing content',
|
|
82
52
|
],
|
|
83
53
|
},
|
|
54
|
+
{
|
|
55
|
+
type: 'code',
|
|
56
|
+
lang: 'tsx',
|
|
57
|
+
label: 'A three-region tool frame',
|
|
58
|
+
code: `// Recommended budgets: SideNav 240–280, icon rail 64–72,
|
|
59
|
+
// side panel 340–420, filter rail 220–260.
|
|
60
|
+
<AppShell sideNav={<SideNav>{/* nav items */}</SideNav>}>
|
|
61
|
+
<Layout
|
|
62
|
+
content={<LayoutContent>{/* table fills its region */}</LayoutContent>}
|
|
63
|
+
end={<LayoutPanel width={380} hasDivider>{/* detail */}</LayoutPanel>}
|
|
64
|
+
/>
|
|
65
|
+
</AppShell>
|
|
66
|
+
|
|
67
|
+
// Capped instead: 640 suits text and forms, 960 mixed content.
|
|
68
|
+
// Dividers stay full-bleed.
|
|
69
|
+
<Layout
|
|
70
|
+
contentWidth={640}
|
|
71
|
+
content={<LayoutContent>{/* settings form */}</LayoutContent>}
|
|
72
|
+
/>`,
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
type: 'prose',
|
|
76
|
+
text: 'Verify: every region has a width budget, a fill-or-capped decision, and a container policy written down before any content exists.',
|
|
77
|
+
},
|
|
78
|
+
|
|
79
|
+
{type: 'heading', level: 3, text: 'Navigation'},
|
|
84
80
|
{
|
|
85
81
|
type: 'prose',
|
|
86
|
-
text: '
|
|
82
|
+
text: 'When the frame leaves navigation open, default to SideNav: it absorbs destinations you have not planned yet. App type and destination count are guiding indicators, not determining rules.',
|
|
83
|
+
},
|
|
84
|
+
{
|
|
85
|
+
type: 'list',
|
|
86
|
+
style: 'unordered',
|
|
87
|
+
items: [
|
|
88
|
+
'SideNav, the default: grouping needed, customizable nav, items with secondary actions, or nav that collapses. Trackers, consoles, and settings usually start here',
|
|
89
|
+
'TopNav: a shallow nav you expect to stay shallow, context that must stay visible, or a control- and filter-heavy page; add a TabList for a second level. Media libraries often sit here, over grid content',
|
|
90
|
+
'Both: a genuine suite, where TopNav carries ecosystem-wide concerns (context switcher, global search) and SideNav carries product nav',
|
|
91
|
+
'Neither: messaging and feeds use a column frame of rail, nav, stream, and panel',
|
|
92
|
+
],
|
|
93
|
+
},
|
|
94
|
+
{
|
|
95
|
+
type: 'code',
|
|
96
|
+
lang: 'tsx',
|
|
97
|
+
label: 'Navigation passed to AppShell',
|
|
98
|
+
code: `// Default: product nav on the side.
|
|
99
|
+
<AppShell sideNav={<SideNav>{/* items */}</SideNav>} />
|
|
100
|
+
|
|
101
|
+
// Shallow, stable nav on a control-heavy page.
|
|
102
|
+
<AppShell topNav={<TopNav>{/* items */}</TopNav>} />
|
|
103
|
+
|
|
104
|
+
// Suite: ecosystem concerns on top, product nav on the side.
|
|
105
|
+
<AppShell topNav={<TopNav />} sideNav={<SideNav />} />`,
|
|
106
|
+
},
|
|
107
|
+
{
|
|
108
|
+
type: 'prose',
|
|
109
|
+
text: 'Verify: you can state the reason in one sentence, and the choice still holds if the nav doubles in size. `npx astryx build "<idea>"` names the closest template, and its `--skeleton` shows the pairing already wired up.',
|
|
110
|
+
},
|
|
111
|
+
|
|
112
|
+
{type: 'heading', level: 3, text: 'Best practices'},
|
|
113
|
+
{
|
|
114
|
+
type: 'list',
|
|
115
|
+
style: 'do',
|
|
116
|
+
items: [
|
|
117
|
+
'Decide the frame, region width budgets, and fill or capped before any content exists',
|
|
118
|
+
'State the reason for the navigation choice, or inherit the template pairing',
|
|
119
|
+
'Reserve raw px for structural widths; interior spacing uses tokens',
|
|
120
|
+
],
|
|
121
|
+
},
|
|
122
|
+
{
|
|
123
|
+
type: 'list',
|
|
124
|
+
style: 'dont',
|
|
125
|
+
items: [
|
|
126
|
+
'Build content-first and wrap each section in a Card, producing a padded scroll column',
|
|
127
|
+
'Stretch prose, forms, or lists across a wide region instead of capping with contentWidth',
|
|
128
|
+
'SideNav when the nav is really filters or controls, or must hold wide elements like breadcrumbs',
|
|
129
|
+
'TopNav when top-slot ownership is unclear, or the hierarchy is deep or still growing',
|
|
130
|
+
'Both bars when the ecosystem layer is thin, so the second only wastes space',
|
|
131
|
+
'Deviate from the template navigation pairing without a stated reason',
|
|
132
|
+
],
|
|
87
133
|
},
|
|
88
134
|
],
|
|
89
135
|
},
|
|
90
136
|
{
|
|
91
|
-
title: '
|
|
137
|
+
title: 'Structure',
|
|
92
138
|
content: [
|
|
139
|
+
{type: 'heading', level: 3, text: 'Type hierarchy'},
|
|
140
|
+
{
|
|
141
|
+
type: 'prose',
|
|
142
|
+
text: 'Give every region one lead, then rank the rest with weight and color rather than size. Content uses two text colors, primary and secondary, and nothing dimmer: body copy needs no props at all.',
|
|
143
|
+
},
|
|
144
|
+
{
|
|
145
|
+
type: 'list',
|
|
146
|
+
style: 'unordered',
|
|
147
|
+
items: [
|
|
148
|
+
'Body, the default: plain Text with no type, color, or size prop',
|
|
149
|
+
'Lead: Heading at the level matching page depth, or body Text at a heavier weight',
|
|
150
|
+
'Support: step to the secondary color, not to a smaller size',
|
|
151
|
+
'Metadata: the supporting type, or a StatusDot or Token instead of prose',
|
|
152
|
+
],
|
|
153
|
+
},
|
|
154
|
+
{
|
|
155
|
+
type: 'code',
|
|
156
|
+
lang: 'tsx',
|
|
157
|
+
label: 'Body copy, then one row of four ranks',
|
|
158
|
+
code: `// Body copy takes no props. Text already defaults to body
|
|
159
|
+
// size in the primary color.
|
|
160
|
+
<Text>Credentials rotate every 90 days</Text>
|
|
161
|
+
|
|
162
|
+
<HStack gap={2}>
|
|
163
|
+
<Text weight="semibold">Payments API</Text>
|
|
164
|
+
<StatusDot variant="success" label="Healthy" />
|
|
165
|
+
<Text color="secondary">v2.14</Text>
|
|
166
|
+
<Text type="supporting">edited 3h ago</Text>
|
|
167
|
+
</HStack>`,
|
|
168
|
+
},
|
|
169
|
+
{
|
|
170
|
+
type: 'prose',
|
|
171
|
+
text: 'Squint test: blurred, you read lead, then support, then groups, in that order. If everything reads at once, raise contrast with weight and color, not borders and not smaller text.',
|
|
172
|
+
},
|
|
173
|
+
|
|
174
|
+
{type: 'heading', level: 3, text: 'Containers'},
|
|
175
|
+
{
|
|
176
|
+
type: 'prose',
|
|
177
|
+
text: 'Reach for the weakest container that reads as a group, and escalate only when it fails. Weakest to strongest:',
|
|
178
|
+
},
|
|
179
|
+
{
|
|
180
|
+
type: 'list',
|
|
181
|
+
style: 'ordered',
|
|
182
|
+
items: [
|
|
183
|
+
'spacing and gap: related items inside one group. The default rhythm',
|
|
184
|
+
'Divider: peers in a dense list or toolbar, or fencing a header from a scrollable body',
|
|
185
|
+
'Section: the default page-structure unit, related content under a heading. No border',
|
|
186
|
+
'Card: a self-contained widget (KPI tile, chart, gallery entry), or a hard boundary around critical content',
|
|
187
|
+
],
|
|
188
|
+
},
|
|
189
|
+
{
|
|
190
|
+
type: 'code',
|
|
191
|
+
lang: 'tsx',
|
|
192
|
+
label: 'Section as the default unit',
|
|
193
|
+
code: `// Records are rows in one Section, not one Card each.
|
|
194
|
+
// Recommended row height: 32–40px.
|
|
195
|
+
<Section padding={0}>
|
|
196
|
+
<List header={<Heading level={3}>Members</Heading>} hasDividers>
|
|
197
|
+
{/* ListItem per member */}
|
|
198
|
+
</List>
|
|
199
|
+
</Section>`,
|
|
200
|
+
},
|
|
201
|
+
{
|
|
202
|
+
type: 'prose',
|
|
203
|
+
text: 'Decision test: records render as rows, Table for columnar and List for single-line; a self-contained widget or hard boundary is a Card; everything else is a Section.',
|
|
204
|
+
},
|
|
205
|
+
|
|
206
|
+
{type: 'heading', level: 3, text: 'Headers and footers'},
|
|
207
|
+
{
|
|
208
|
+
type: 'prose',
|
|
209
|
+
text: 'A region can pin a header or footer while its body scrolls. Both are Layout slots, and padding set once on Layout reaches all three, so header, body, and footer share one content line.',
|
|
210
|
+
},
|
|
211
|
+
{
|
|
212
|
+
type: 'list',
|
|
213
|
+
style: 'unordered',
|
|
214
|
+
items: [
|
|
215
|
+
'LayoutHeader in the header slot: the region title and its primary action',
|
|
216
|
+
'Toolbar instead of LayoutHeader when the header carries interactive controls',
|
|
217
|
+
'LayoutFooter in the footer slot: actions that commit the work and must stay reachable',
|
|
218
|
+
'defaultHasDividers on Layout fences both at once, rather than hasDivider per slot',
|
|
219
|
+
],
|
|
220
|
+
},
|
|
221
|
+
{
|
|
222
|
+
type: 'code',
|
|
223
|
+
lang: 'tsx',
|
|
224
|
+
label: 'Pinned header and footer around a scrolling body',
|
|
225
|
+
code: `// padding on Layout reaches every slot, so all three align.
|
|
226
|
+
<Layout
|
|
227
|
+
padding={4}
|
|
228
|
+
defaultHasDividers
|
|
229
|
+
header={<LayoutHeader>{/* title + primary action */}</LayoutHeader>}
|
|
230
|
+
content={<LayoutContent>{/* rows */}</LayoutContent>}
|
|
231
|
+
footer={<LayoutFooter>{/* Save and Cancel */}</LayoutFooter>}
|
|
232
|
+
/>`,
|
|
233
|
+
},
|
|
234
|
+
{
|
|
235
|
+
type: 'prose',
|
|
236
|
+
text: 'Verify: scroll the body. The header and footer stay put, their dividers run full-bleed, and all three still share one left content line.',
|
|
237
|
+
},
|
|
238
|
+
|
|
239
|
+
{type: 'heading', level: 3, text: 'Side panels'},
|
|
240
|
+
{
|
|
241
|
+
type: 'prose',
|
|
242
|
+
text: 'Master-detail: selecting a row opens a fixed-width side panel instead of navigating away.',
|
|
243
|
+
},
|
|
244
|
+
{
|
|
245
|
+
type: 'list',
|
|
246
|
+
style: 'unordered',
|
|
247
|
+
items: [
|
|
248
|
+
'LayoutPanel in the start or end slot of Layout, holding a fixed width budget',
|
|
249
|
+
'hasDivider to fence it from the content region; isScrollable so long detail scrolls on its own',
|
|
250
|
+
'For user-adjustable width, pair useResizable() with a ResizeHandle on the panel inner edge: after the panel in a start slot, before it in an end slot with isReversed',
|
|
251
|
+
'The handle then owns the divider, so the panel sets hasDivider={false}',
|
|
252
|
+
'Render an EmptyState when nothing is selected, so the region never collapses',
|
|
253
|
+
],
|
|
254
|
+
},
|
|
255
|
+
{
|
|
256
|
+
type: 'code',
|
|
257
|
+
lang: 'tsx',
|
|
258
|
+
label: 'Fixed panel, then the resizable form',
|
|
259
|
+
code: `// Recommended panel width: 340–420.
|
|
260
|
+
<Layout
|
|
261
|
+
content={<LayoutContent>{/* rows */}</LayoutContent>}
|
|
262
|
+
end={
|
|
263
|
+
<LayoutPanel width={380} hasDivider isScrollable label="Details">
|
|
264
|
+
{/* detail fields, or EmptyState when nothing is selected */}
|
|
265
|
+
</LayoutPanel>
|
|
266
|
+
}
|
|
267
|
+
/>
|
|
268
|
+
|
|
269
|
+
// Resizable: handle first in an end slot, and isReversed so
|
|
270
|
+
// dragging left widens the panel.
|
|
271
|
+
end={
|
|
272
|
+
<>
|
|
273
|
+
<ResizeHandle isReversed hasDivider resizable={panel.props}
|
|
274
|
+
label="Resize details" />
|
|
275
|
+
<LayoutPanel width={panel.size} hasDivider={false} />
|
|
276
|
+
</>
|
|
277
|
+
}`,
|
|
278
|
+
},
|
|
93
279
|
{
|
|
94
280
|
type: 'prose',
|
|
95
|
-
text: '
|
|
281
|
+
text: 'Verify: at narrow widths the panel yields width instead of squeezing content (see Breakpoints), and only one element between the regions draws a border.',
|
|
96
282
|
},
|
|
283
|
+
|
|
284
|
+
{type: 'heading', level: 3, text: 'Best practices'},
|
|
97
285
|
{
|
|
98
286
|
type: 'list',
|
|
99
287
|
style: 'do',
|
|
100
288
|
items: [
|
|
101
|
-
'
|
|
102
|
-
'
|
|
103
|
-
'
|
|
104
|
-
'
|
|
289
|
+
'One lead per region; rank with weight and color; one primary action',
|
|
290
|
+
'Leave body copy at its defaults; demote by weight and color, not size',
|
|
291
|
+
'Default to Section; use the weakest container that reads as a group',
|
|
292
|
+
'Render collections as rows (Table or List), edge-to-edge with dividers',
|
|
293
|
+
'Open a fixed-width side panel on select; let it yield width at narrow sizes',
|
|
105
294
|
],
|
|
106
295
|
},
|
|
107
296
|
{
|
|
108
297
|
type: 'list',
|
|
109
298
|
style: 'dont',
|
|
110
299
|
items: [
|
|
111
|
-
'
|
|
112
|
-
'
|
|
113
|
-
'
|
|
114
|
-
'
|
|
300
|
+
'Grey and shrink body copy, so a whole region reads as secondary metadata',
|
|
301
|
+
'The disabled color for content; it fails contrast and is for disabled controls',
|
|
302
|
+
'Card soup: each record wrapped in its own Card instead of rendered as rows',
|
|
303
|
+
'Cards inside Cards, or full-width Cards stacked as page structure',
|
|
304
|
+
'A header or footer rebuilt inside the body, where it scrolls away with the rows',
|
|
305
|
+
'Flexbox soup: nested ad-hoc flexboxes instead of Grid, Layout, Section, or FormLayout',
|
|
306
|
+
'Two competing primary actions in one region',
|
|
307
|
+
'Badge as decoration; use StatusDot or Token for status and metadata',
|
|
115
308
|
],
|
|
116
309
|
},
|
|
117
310
|
],
|
|
118
311
|
},
|
|
119
312
|
{
|
|
120
|
-
title: '
|
|
313
|
+
title: 'Spacing',
|
|
121
314
|
content: [
|
|
315
|
+
{type: 'heading', level: 3, text: 'Alignment'},
|
|
316
|
+
{
|
|
317
|
+
type: 'prose',
|
|
318
|
+
text: 'The container owns padding and child gaps; children zero their margins, and interior spacing is always a token. Pick one content line per region and hold it constant, not the padding: `container_inset = content_line - component_intrinsic_inset`.',
|
|
319
|
+
},
|
|
320
|
+
{
|
|
321
|
+
type: 'list',
|
|
322
|
+
style: 'unordered',
|
|
323
|
+
items: [
|
|
324
|
+
'Text and Heading carry no inset, so the container takes the full padding',
|
|
325
|
+
'List, Tab, Menu, and nav items carry a small inset, so the container gives up its padding and the component owns the line',
|
|
326
|
+
'Table cells carry a larger inset, so the container gives up its padding and the cell owns the line',
|
|
327
|
+
],
|
|
328
|
+
},
|
|
329
|
+
{
|
|
330
|
+
type: 'code',
|
|
331
|
+
lang: 'tsx',
|
|
332
|
+
label: 'One content line, two inset owners',
|
|
333
|
+
code: `// Target content line = 16px.
|
|
334
|
+
// Heading has 0 inset, so the Section takes the full padding.
|
|
335
|
+
<Section padding={4}><Heading level={3}>Members</Heading></Section>
|
|
336
|
+
|
|
337
|
+
// List has ~8px built in, Table cells 12–16px, so the Section
|
|
338
|
+
// gives up its padding and the component owns the inset.
|
|
339
|
+
<Section padding={0}><List>{/* items */}</List></Section>`,
|
|
340
|
+
},
|
|
341
|
+
{
|
|
342
|
+
type: 'prose',
|
|
343
|
+
text: 'Verify: draw one vertical line down the left of the region. Every label touches it; only hover and selected backgrounds cross it.',
|
|
344
|
+
},
|
|
345
|
+
|
|
346
|
+
{type: 'heading', level: 3, text: 'Rhythm'},
|
|
347
|
+
{
|
|
348
|
+
type: 'prose',
|
|
349
|
+
text: 'Grouping comes from contrast between tight and generous gaps, not one repeated value. If every gap is the same step, proximity does no work.',
|
|
350
|
+
},
|
|
351
|
+
{
|
|
352
|
+
type: 'list',
|
|
353
|
+
style: 'unordered',
|
|
354
|
+
items: [
|
|
355
|
+
'Tight gaps bind: the smallest steps, used inside an item or field',
|
|
356
|
+
'Generous gaps separate: several steps up, used between sections',
|
|
357
|
+
'Reach for the in-between steps to tune cadence, rather than rounding everything to the same two values',
|
|
358
|
+
],
|
|
359
|
+
},
|
|
360
|
+
{
|
|
361
|
+
type: 'code',
|
|
362
|
+
lang: 'tsx',
|
|
363
|
+
label: 'Tight inside, generous between',
|
|
364
|
+
code: `// Tight binds at gap={1}–{2}, generous separates at gap={4}–{6}.
|
|
365
|
+
// In-between steps tune cadence: gap={3} = 12px, gap={5} = 20px.
|
|
366
|
+
<VStack gap={6}>
|
|
367
|
+
<VStack gap={1}>
|
|
368
|
+
<Text weight="semibold">Retention</Text>
|
|
369
|
+
<Text color="secondary">Logs are kept for 30 days</Text>
|
|
370
|
+
</VStack>
|
|
371
|
+
<VStack gap={1}>{/* next label and value */}</VStack>
|
|
372
|
+
</VStack>`,
|
|
373
|
+
},
|
|
374
|
+
{
|
|
375
|
+
type: 'prose',
|
|
376
|
+
text: 'Verify: with every border removed, you can still name the groups from spacing alone. If you cannot, the intervals are too uniform. Form fields are the exception: FormLayout owns their spacing.',
|
|
377
|
+
},
|
|
378
|
+
|
|
379
|
+
{type: 'heading', level: 3, text: 'Density and size'},
|
|
122
380
|
{
|
|
123
381
|
type: 'prose',
|
|
124
|
-
text: '
|
|
382
|
+
text: 'Match density to how often a region is used, and give every control in a row the same size so heights share a baseline.',
|
|
383
|
+
},
|
|
384
|
+
{
|
|
385
|
+
type: 'list',
|
|
386
|
+
style: 'unordered',
|
|
387
|
+
items: [
|
|
388
|
+
'Compact: high-volume regions scanned fast, like logs, monitors, and large datasets',
|
|
389
|
+
'Balanced: most Table and List surfaces',
|
|
390
|
+
'Spacious: low-frequency or high-stakes rows, like settings or a short selection list',
|
|
391
|
+
],
|
|
125
392
|
},
|
|
126
393
|
{
|
|
127
394
|
type: 'code',
|
|
128
395
|
lang: 'tsx',
|
|
129
|
-
label: '
|
|
130
|
-
code:
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
396
|
+
label: 'Density paired with control size',
|
|
397
|
+
code: `// Pair density with one control size: compact with sm,
|
|
398
|
+
// balanced with sm or md, spacious with md or lg.
|
|
399
|
+
<Table data={rows} columns={columns} density="compact" hasHover />
|
|
400
|
+
<Button label="Retry" size="sm" variant="ghost" />`,
|
|
401
|
+
},
|
|
402
|
+
{
|
|
403
|
+
type: 'prose',
|
|
404
|
+
text: 'Verify: every interactive element in a row shares one size, and that size is paired with the density of the region it sits in.',
|
|
405
|
+
},
|
|
406
|
+
|
|
407
|
+
{type: 'heading', level: 3, text: 'Best practices'},
|
|
408
|
+
{
|
|
409
|
+
type: 'list',
|
|
410
|
+
style: 'do',
|
|
411
|
+
items: [
|
|
412
|
+
'Let the container own padding; children zero their own margins',
|
|
413
|
+
'Hold one content line per region: text on the line, hover backgrounds bleed to the edge',
|
|
414
|
+
'Hold one padding token across a region header, body, and footer',
|
|
415
|
+
'Contrast tight and generous gaps so grouping reads without borders',
|
|
416
|
+
'One control size per row; match density to use frequency',
|
|
417
|
+
],
|
|
418
|
+
},
|
|
419
|
+
{
|
|
420
|
+
type: 'list',
|
|
421
|
+
style: 'dont',
|
|
422
|
+
items: [
|
|
423
|
+
'Double padding: a component indented past its Section heading (keep one inset owner)',
|
|
424
|
+
'Raw px for interior spacing; tokens only, px is for structural widths',
|
|
425
|
+
'One repeated gap everywhere, which flattens grouping',
|
|
426
|
+
'Mixed control sizes in a single row',
|
|
427
|
+
],
|
|
138
428
|
},
|
|
139
429
|
],
|
|
140
430
|
},
|
|
141
431
|
{
|
|
142
|
-
title: '
|
|
432
|
+
title: 'Breakpoints',
|
|
143
433
|
content: [
|
|
434
|
+
{type: 'heading', level: 3, text: 'Responsive contract'},
|
|
144
435
|
{
|
|
145
436
|
type: 'prose',
|
|
146
|
-
text: '
|
|
437
|
+
text: 'Lock what each region does as width changes, and pair every line of the contract with the prop or hook that enforces it.',
|
|
438
|
+
},
|
|
439
|
+
{
|
|
440
|
+
type: 'list',
|
|
441
|
+
style: 'unordered',
|
|
442
|
+
items: [
|
|
443
|
+
'Divide: how many regions survive at each width',
|
|
444
|
+
'Reveal: which regions earn their width only when there is room, and open on demand below that',
|
|
445
|
+
'Resize: content flexes while fixed regions hold their budgets, and text stays capped by contentWidth so line length holds',
|
|
446
|
+
'Swap: navigation becomes MobileNav at the AppShell mobileNav breakpoint; the side panel becomes a Dialog or BottomSheet, driven by useMediaQuery',
|
|
447
|
+
],
|
|
147
448
|
},
|
|
148
449
|
{
|
|
149
450
|
type: 'code',
|
|
150
451
|
lang: 'tsx',
|
|
151
|
-
label: 'Contract
|
|
152
|
-
code: `//
|
|
153
|
-
//
|
|
154
|
-
//
|
|
155
|
-
// <=
|
|
452
|
+
label: 'Contract wired to props',
|
|
453
|
+
code: `// Recommended thresholds: 3 regions above 1024, 2 from 768,
|
|
454
|
+
// 1 below. Text reads best at 40–60 characters per line.
|
|
455
|
+
// >1024 SideNav 256 | content | side panel 380
|
|
456
|
+
// <=1024 panel moves to a Dialog (useMediaQuery)
|
|
457
|
+
// <=768 nav collapses to MobileNav (mobileNav "md")
|
|
458
|
+
const isNarrow = useMediaQuery('(max-width: 1024px)');
|
|
459
|
+
|
|
460
|
+
<AppShell sideNav={<SideNav />} mobileNav={{breakpoint: 'md'}}>
|
|
461
|
+
<Layout
|
|
462
|
+
content={<LayoutContent>{/* rows */}</LayoutContent>}
|
|
463
|
+
end={isNarrow ? undefined : <LayoutPanel width={380} hasDivider />}
|
|
464
|
+
/>
|
|
465
|
+
</AppShell>`,
|
|
466
|
+
},
|
|
467
|
+
{
|
|
468
|
+
type: 'prose',
|
|
469
|
+
text: 'Verify: every contract line names a mechanism, so the comment cannot drift from the behavior.',
|
|
470
|
+
},
|
|
471
|
+
|
|
472
|
+
{type: 'heading', level: 3, text: 'Best practices'},
|
|
473
|
+
{
|
|
474
|
+
type: 'list',
|
|
475
|
+
style: 'do',
|
|
476
|
+
items: [
|
|
477
|
+
'Write the contract down for every region before you call the layout done',
|
|
478
|
+
'Decide per region whether it is revealed, resized, or swapped at each width',
|
|
479
|
+
'Drop a region rather than let it compete for width it does not have',
|
|
480
|
+
],
|
|
481
|
+
},
|
|
482
|
+
{
|
|
483
|
+
type: 'list',
|
|
484
|
+
style: 'dont',
|
|
485
|
+
items: [
|
|
486
|
+
'Hold three regions at a width where none of them has usable space',
|
|
487
|
+
'Shrink every region uniformly instead of swapping or dropping one',
|
|
488
|
+
'Wire a breakpoint in CSS that the contract comment never mentions',
|
|
489
|
+
],
|
|
156
490
|
},
|
|
157
491
|
],
|
|
158
492
|
},
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
// Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
2
|
+
|
|
3
|
+
/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
|
|
4
|
+
export const doc = {
|
|
5
|
+
type: 'block',
|
|
6
|
+
exampleFor: 'BottomSheet',
|
|
7
|
+
name: 'Bottom Sheet — Snap points',
|
|
8
|
+
displayName: 'Bottom Sheet — Snap points',
|
|
9
|
+
description:
|
|
10
|
+
'Drag-to-resize stops: a half-height working surface, and a peek that slides away and thins the scrim.',
|
|
11
|
+
isReady: true,
|
|
12
|
+
aspectRatio: 3 / 4,
|
|
13
|
+
componentsUsed: [
|
|
14
|
+
'BottomSheet',
|
|
15
|
+
'Button',
|
|
16
|
+
'Divider',
|
|
17
|
+
'Heading',
|
|
18
|
+
'Icon',
|
|
19
|
+
'Item',
|
|
20
|
+
'Stack',
|
|
21
|
+
'Text',
|
|
22
|
+
],
|
|
23
|
+
};
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
// Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
2
|
+
|
|
3
|
+
'use client';
|
|
4
|
+
|
|
5
|
+
import {useState} from 'react';
|
|
6
|
+
import {
|
|
7
|
+
BottomSheet,
|
|
8
|
+
type BottomSheetSnapPoint,
|
|
9
|
+
} from '@astryxdesign/core/BottomSheet';
|
|
10
|
+
import {Button} from '@astryxdesign/core/Button';
|
|
11
|
+
import {Divider} from '@astryxdesign/core/Divider';
|
|
12
|
+
import {Heading} from '@astryxdesign/core/Heading';
|
|
13
|
+
import {Icon} from '@astryxdesign/core/Icon';
|
|
14
|
+
import {Item} from '@astryxdesign/core/Item';
|
|
15
|
+
import {HStack, VStack} from '@astryxdesign/core/Stack';
|
|
16
|
+
import {Text} from '@astryxdesign/core/Text';
|
|
17
|
+
import {
|
|
18
|
+
ArrowLeftIcon,
|
|
19
|
+
ArrowRightIcon,
|
|
20
|
+
ArrowUpIcon,
|
|
21
|
+
ArrowUturnLeftIcon,
|
|
22
|
+
FlagIcon,
|
|
23
|
+
MapPinIcon,
|
|
24
|
+
} from '@heroicons/react/24/outline';
|
|
25
|
+
|
|
26
|
+
// Half the viewport is a working surface — the sheet lays its content out at
|
|
27
|
+
// that height and keeps a full scrim. The 96px stop is a peek: a sliver, so the
|
|
28
|
+
// sheet slides away rather than reflowing into it, and the scrim thins.
|
|
29
|
+
const SNAP_POINTS: ReadonlyArray<BottomSheetSnapPoint> = ['96px', '50%'];
|
|
30
|
+
|
|
31
|
+
const steps = [
|
|
32
|
+
{
|
|
33
|
+
icon: MapPinIcon,
|
|
34
|
+
label: 'Head northeast on Mission St',
|
|
35
|
+
detail: 'Toward 3rd St',
|
|
36
|
+
distance: '350 ft',
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
icon: ArrowRightIcon,
|
|
40
|
+
label: 'Turn right onto 3rd St',
|
|
41
|
+
detail: 'Pass Yerba Buena Gardens on your left',
|
|
42
|
+
distance: '0.2 mi',
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
icon: ArrowUpIcon,
|
|
46
|
+
label: 'Continue onto Kearny St',
|
|
47
|
+
detail: 'Stay in the right lane',
|
|
48
|
+
distance: '0.4 mi',
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
icon: ArrowLeftIcon,
|
|
52
|
+
label: 'Turn left onto Market St',
|
|
53
|
+
detail: 'Cable car crossing ahead',
|
|
54
|
+
distance: '0.6 mi',
|
|
55
|
+
},
|
|
56
|
+
{
|
|
57
|
+
icon: ArrowRightIcon,
|
|
58
|
+
label: 'Bear right onto Sutter St',
|
|
59
|
+
detail: 'Toward the Financial District',
|
|
60
|
+
distance: '0.3 mi',
|
|
61
|
+
},
|
|
62
|
+
{
|
|
63
|
+
icon: ArrowUpIcon,
|
|
64
|
+
label: 'Continue on Sansome St',
|
|
65
|
+
detail: 'Four blocks, past Pine St',
|
|
66
|
+
distance: '0.5 mi',
|
|
67
|
+
},
|
|
68
|
+
{
|
|
69
|
+
icon: ArrowUturnLeftIcon,
|
|
70
|
+
label: 'Make a U-turn at Washington St',
|
|
71
|
+
detail: 'Construction detour until March',
|
|
72
|
+
distance: '150 ft',
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
icon: ArrowRightIcon,
|
|
76
|
+
label: 'Turn right onto Battery St',
|
|
77
|
+
detail: 'Follow signs for the Embarcadero',
|
|
78
|
+
distance: '0.4 mi',
|
|
79
|
+
},
|
|
80
|
+
{
|
|
81
|
+
icon: ArrowLeftIcon,
|
|
82
|
+
label: 'Turn left onto Sacramento St',
|
|
83
|
+
detail: 'Toward the waterfront',
|
|
84
|
+
distance: '0.2 mi',
|
|
85
|
+
},
|
|
86
|
+
{
|
|
87
|
+
icon: ArrowRightIcon,
|
|
88
|
+
label: 'Turn right onto The Embarcadero',
|
|
89
|
+
detail: 'Bay Bridge on your right',
|
|
90
|
+
distance: '0.5 mi',
|
|
91
|
+
},
|
|
92
|
+
{
|
|
93
|
+
icon: ArrowUpIcon,
|
|
94
|
+
label: 'Continue past Pier 14',
|
|
95
|
+
detail: 'Ferry terminal signage begins here',
|
|
96
|
+
distance: '0.3 mi',
|
|
97
|
+
},
|
|
98
|
+
{
|
|
99
|
+
icon: FlagIcon,
|
|
100
|
+
label: 'Arrive at the Ferry Building',
|
|
101
|
+
detail: 'Parking garage entrance on Washington St',
|
|
102
|
+
distance: '—',
|
|
103
|
+
},
|
|
104
|
+
];
|
|
105
|
+
|
|
106
|
+
export default function BottomSheetSnapPoints() {
|
|
107
|
+
const [isOpen, setIsOpen] = useState(false);
|
|
108
|
+
|
|
109
|
+
return (
|
|
110
|
+
<>
|
|
111
|
+
<VStack gap={3} align="start">
|
|
112
|
+
<Text type="body">
|
|
113
|
+
This sheet has two extra stops: half the viewport, and a 96px peek.
|
|
114
|
+
Drag the handle down to collapse it, then back up — it rests at each
|
|
115
|
+
stop instead of following your finger.
|
|
116
|
+
</Text>
|
|
117
|
+
<Button label="Show directions" onClick={() => setIsOpen(true)} />
|
|
118
|
+
</VStack>
|
|
119
|
+
<BottomSheet
|
|
120
|
+
isOpen={isOpen}
|
|
121
|
+
onOpenChange={setIsOpen}
|
|
122
|
+
label="Directions to the Ferry Building"
|
|
123
|
+
height="tall"
|
|
124
|
+
snapPoints={SNAP_POINTS}>
|
|
125
|
+
<VStack gap={4} padding={4}>
|
|
126
|
+
<VStack gap={1}>
|
|
127
|
+
<Heading level={3}>Ferry Building</Heading>
|
|
128
|
+
<HStack gap={2}>
|
|
129
|
+
<Text type="label">18 min</Text>
|
|
130
|
+
<Text type="supporting">3.7 mi · arrive 9:41 AM</Text>
|
|
131
|
+
</HStack>
|
|
132
|
+
</VStack>
|
|
133
|
+
<Divider />
|
|
134
|
+
<VStack gap={0}>
|
|
135
|
+
{steps.map(step => (
|
|
136
|
+
<Item
|
|
137
|
+
key={step.label}
|
|
138
|
+
startContent={<Icon icon={step.icon} size="sm" />}
|
|
139
|
+
label={step.label}
|
|
140
|
+
description={step.detail}
|
|
141
|
+
endContent={<Text type="supporting">{step.distance}</Text>}
|
|
142
|
+
/>
|
|
143
|
+
))}
|
|
144
|
+
</VStack>
|
|
145
|
+
<Divider />
|
|
146
|
+
<Button
|
|
147
|
+
label="Start"
|
|
148
|
+
onClick={() => setIsOpen(false)}
|
|
149
|
+
variant="primary"
|
|
150
|
+
/>
|
|
151
|
+
</VStack>
|
|
152
|
+
</BottomSheet>
|
|
153
|
+
</>
|
|
154
|
+
);
|
|
155
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astryxdesign/cli",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.5-canary.33ba2b6",
|
|
4
4
|
"displayName": "CLI",
|
|
5
5
|
"description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
|
|
6
6
|
"author": "Meta Open Source",
|
|
@@ -87,10 +87,10 @@
|
|
|
87
87
|
"zod": "^4.4.3"
|
|
88
88
|
},
|
|
89
89
|
"peerDependencies": {
|
|
90
|
-
"@astryxdesign/charts": "
|
|
91
|
-
"@astryxdesign/core": "
|
|
92
|
-
"@astryxdesign/lab": "
|
|
93
|
-
"@astryxdesign/theme-neutral": "
|
|
90
|
+
"@astryxdesign/charts": "0.4.5-canary.33ba2b6",
|
|
91
|
+
"@astryxdesign/core": "0.4.5-canary.33ba2b6",
|
|
92
|
+
"@astryxdesign/lab": "0.4.5-canary.33ba2b6",
|
|
93
|
+
"@astryxdesign/theme-neutral": "0.4.5-canary.33ba2b6",
|
|
94
94
|
"gpt-tokenizer": "^3.4.0"
|
|
95
95
|
},
|
|
96
96
|
"peerDependenciesMeta": {
|
|
@@ -108,10 +108,10 @@
|
|
|
108
108
|
}
|
|
109
109
|
},
|
|
110
110
|
"devDependencies": {
|
|
111
|
-
"@astryxdesign/charts": "
|
|
112
|
-
"@astryxdesign/core": "
|
|
113
|
-
"@astryxdesign/lab": "
|
|
114
|
-
"@astryxdesign/theme-neutral": "
|
|
111
|
+
"@astryxdesign/charts": "0.4.5-canary.33ba2b6",
|
|
112
|
+
"@astryxdesign/core": "0.4.5-canary.33ba2b6",
|
|
113
|
+
"@astryxdesign/lab": "0.4.5-canary.33ba2b6",
|
|
114
|
+
"@astryxdesign/theme-neutral": "0.4.5-canary.33ba2b6",
|
|
115
115
|
"gpt-tokenizer": "^3.4.0"
|
|
116
116
|
},
|
|
117
117
|
"scripts": {
|