@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.0e1fbdb

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 (254) hide show
  1. package/README.md +49 -40
  2. package/api/build/build.doc.mjs +6 -1
  3. package/api/build/build.test.mjs +22 -0
  4. package/api/build/kit/kit.mjs +44 -5
  5. package/api/component/component.doc.mjs +14 -7
  6. package/api/docs/_adapter.d.mts +8 -3
  7. package/api/docs/_adapter.mjs +14 -6
  8. package/api/docs/docOverlays.test.mjs +27 -1
  9. package/api/docs/docs.doc.mjs +2 -2
  10. package/api/doctor/doctor.doc.mjs +17 -8
  11. package/api/doctor/doctor.type.d.mts +1 -1
  12. package/api/doctor/doctor.type.mjs +1 -1
  13. package/api/gap-report/gap-report.doc.mjs +19 -10
  14. package/api/hook/hook.doc.mjs +6 -3
  15. package/api/index.d.mts +2 -0
  16. package/api/index.mjs +3 -1
  17. package/api/init/init.doc.mjs +17 -12
  18. package/api/integration/add-theme.mjs +22 -1
  19. package/api/integration/add-theme.test.mjs +34 -0
  20. package/api/integration/authoring-checks.mjs +2 -2
  21. package/api/integration/integrationPackCheck.doc.mjs +3 -3
  22. package/api/integration/pack-check.lifecycle-output.test.mjs +2 -0
  23. package/api/integration/pack-check.mjs +54 -6
  24. package/api/integration/pack-check.test.mjs +90 -0
  25. package/api/integration/pack-check.type.mjs +1 -1
  26. package/api/json/assertResponse.doc.mjs +1 -1
  27. package/api/json/index.ts +1 -0
  28. package/api/json/isError.doc.mjs +1 -1
  29. package/api/layout/_adapter.d.mts +34 -0
  30. package/api/layout/_adapter.mjs +148 -0
  31. package/api/layout/check/check.d.mts +16 -0
  32. package/api/layout/check/check.mjs +40 -0
  33. package/api/layout/expand/expand.d.mts +22 -0
  34. package/api/layout/expand/expand.mjs +155 -0
  35. package/api/layout/expand/expand.path-safety.test.mjs +53 -0
  36. package/api/layout/grammar/grammar.d.mts +13 -0
  37. package/api/layout/grammar/grammar.mjs +87 -0
  38. package/api/layout/layout.d.mts +6 -0
  39. package/api/layout/layout.mjs +17 -0
  40. package/api/layout/layout.test.mjs +297 -0
  41. package/api/layout/layout.type.d.mts +89 -0
  42. package/api/layout/layout.type.mjs +103 -0
  43. package/api/layout/layoutCheck.doc.d.mts +11 -0
  44. package/api/layout/layoutCheck.doc.mjs +85 -0
  45. package/api/layout/layoutExpand.doc.d.mts +11 -0
  46. package/api/layout/layoutExpand.doc.mjs +107 -0
  47. package/api/layout/layoutGrammar.doc.d.mts +11 -0
  48. package/api/layout/layoutGrammar.doc.mjs +57 -0
  49. package/api/search/search.d.mts +27 -1
  50. package/api/search/search.doc.mjs +2 -2
  51. package/api/search/search.mjs +228 -16
  52. package/api/swizzle/swizzle.doc.mjs +7 -5
  53. package/api/template/copy/copy.mjs +1 -1
  54. package/api/template/copy/copy.test.mjs +9 -0
  55. package/api/template/template-integration.test.mjs +65 -1
  56. package/api/template/template.doc.mjs +2 -1
  57. package/api/template/template.mjs +1 -1
  58. package/api/theme/generateTonalPalette.doc.mjs +1 -2
  59. package/api/theme/listThemes.doc.mjs +1 -1
  60. package/api/theme/themeAdd.doc.mjs +9 -10
  61. package/api/theme/themeBuild.doc.mjs +13 -13
  62. package/api/theme/themeList.doc.mjs +1 -1
  63. package/api/theme/themeListAvailable.doc.mjs +2 -1
  64. package/api/theme/themePaletteGenerate.doc.mjs +15 -8
  65. package/api/theme/themeTargets.doc.mjs +3 -2
  66. package/api/theme/themeTemplate.doc.mjs +2 -1
  67. package/api/upgrade/run/run.mjs +1 -1
  68. package/api/upgrade/upgrade.doc.mjs +24 -22
  69. package/assets/docs/README.md +4 -2
  70. package/assets/docs/browser-support.doc.mjs +11 -11
  71. package/assets/docs/color.doc.mjs +8 -2
  72. package/assets/docs/elevation.doc.mjs +6 -4
  73. package/assets/docs/getting-started.doc.mjs +5 -16
  74. package/assets/docs/icons.doc.mjs +2 -21
  75. package/assets/docs/illustrations.doc.mjs +7 -15
  76. package/assets/docs/layout.doc.dense.mjs +130 -82
  77. package/assets/docs/layout.doc.mjs +133 -77
  78. package/assets/docs/migration.doc.mjs +19 -21
  79. package/assets/docs/motion.doc.mjs +16 -3
  80. package/assets/docs/principles.doc.dense.mjs +5 -5
  81. package/assets/docs/principles.doc.mjs +8 -0
  82. package/assets/docs/principles.doc.zh.mjs +6 -6
  83. package/assets/docs/shape.doc.mjs +8 -3
  84. package/assets/docs/spacing.doc.mjs +7 -2
  85. package/assets/docs/styling-libraries.doc.mjs +6 -2
  86. package/assets/docs/styling.doc.mjs +19 -23
  87. package/assets/docs/theme.doc.dense.mjs +58 -18
  88. package/assets/docs/theme.doc.mjs +56 -46
  89. package/assets/docs/theme.doc.zh.mjs +9 -8
  90. package/assets/docs/tokens.doc.dense.mjs +2 -2
  91. package/assets/docs/tokens.doc.mjs +389 -8
  92. package/assets/docs/tokens.doc.zh.mjs +2 -2
  93. package/assets/docs/tree/add-a-component.doc.mjs +75 -0
  94. package/assets/docs/tree/add-a-theme.doc.mjs +85 -0
  95. package/assets/docs/tree/add-a-topic.doc.mjs +144 -0
  96. package/assets/docs/tree/agent-guidance.doc.mjs +138 -0
  97. package/assets/docs/tree/block-template.doc.mjs +130 -0
  98. package/assets/docs/tree/build-the-template.doc.mjs +28 -0
  99. package/assets/docs/tree/building-blocks.doc.mjs +46 -0
  100. package/assets/docs/tree/check-your-docs.doc.mjs +137 -0
  101. package/assets/docs/tree/checks.doc.mjs +119 -0
  102. package/assets/docs/tree/codemods.doc.mjs +147 -0
  103. package/assets/docs/tree/component-family.doc.mjs +113 -0
  104. package/assets/docs/tree/component-imports.doc.mjs +69 -0
  105. package/assets/docs/tree/components.doc.mjs +23 -0
  106. package/assets/docs/tree/configuration.doc.mjs +23 -0
  107. package/assets/docs/tree/debug-and-gap-reports.doc.mjs +182 -0
  108. package/assets/docs/tree/define-the-theme.doc.mjs +118 -0
  109. package/assets/docs/tree/describe-the-component.doc.mjs +57 -0
  110. package/assets/docs/tree/docs.doc.mjs +21 -0
  111. package/assets/docs/tree/document-the-template.doc.mjs +28 -0
  112. package/assets/docs/tree/document-the-theme.doc.mjs +68 -0
  113. package/assets/docs/tree/export-template-assets.doc.mjs +147 -0
  114. package/assets/docs/tree/extend-or-replace.doc.mjs +103 -0
  115. package/assets/docs/tree/fonts-and-assets.doc.mjs +106 -0
  116. package/assets/docs/tree/generate-a-palette.doc.mjs +66 -0
  117. package/assets/docs/tree/grade-template-with-agent.doc.mjs +105 -0
  118. package/assets/docs/tree/help.doc.mjs +16 -0
  119. package/assets/docs/tree/integrations.doc.mjs +25 -470
  120. package/assets/docs/tree/links.doc.mjs +98 -0
  121. package/assets/docs/tree/package-and-test.doc.mjs +32 -0
  122. package/assets/docs/tree/page-template.doc.mjs +71 -0
  123. package/assets/docs/tree/publishing.doc.mjs +111 -0
  124. package/assets/docs/tree/quick-start.doc.mjs +272 -0
  125. package/assets/docs/tree/replace-a-core-component.doc.mjs +104 -0
  126. package/assets/docs/tree/replace-a-core-template.doc.mjs +172 -0
  127. package/assets/docs/tree/sections-and-placement.doc.mjs +108 -0
  128. package/assets/docs/tree/see-it-in-an-app.doc.mjs +59 -0
  129. package/assets/docs/tree/ship.doc.mjs +16 -0
  130. package/assets/docs/tree/short-and-findable.doc.mjs +108 -0
  131. package/assets/docs/tree/single-component.doc.mjs +165 -0
  132. package/assets/docs/tree/start-a-template.doc.mjs +143 -0
  133. package/assets/docs/tree/subcomponent.doc.mjs +115 -0
  134. package/assets/docs/tree/template-assets.doc.mjs +64 -0
  135. package/assets/docs/tree/template-doc-overview.doc.mjs +109 -0
  136. package/assets/docs/tree/template-fonts.doc.mjs +102 -0
  137. package/assets/docs/tree/template-grading-rubric.doc.mjs +452 -0
  138. package/assets/docs/tree/template-icons.doc.mjs +97 -0
  139. package/assets/docs/tree/template-images-media.doc.mjs +127 -0
  140. package/assets/docs/tree/template-styles.doc.mjs +93 -0
  141. package/assets/docs/tree/templates.doc.mjs +34 -0
  142. package/assets/docs/tree/test-in-an-app.doc.mjs +115 -0
  143. package/assets/docs/tree/test-template-in-app.doc.mjs +128 -0
  144. package/assets/docs/tree/themes.doc.mjs +39 -0
  145. package/assets/docs/tree/troubleshooting.doc.mjs +149 -0
  146. package/assets/docs/tree/upgrading.doc.mjs +103 -0
  147. package/assets/docs/tree/use-a-theme-in-an-app.doc.mjs +51 -0
  148. package/assets/docs/tree/verify-packed-template.doc.mjs +77 -0
  149. package/assets/docs/tree/versioning.doc.mjs +161 -0
  150. package/assets/docs/tree/write-good-templates.doc.mjs +64 -0
  151. package/assets/docs/tree/write-the-template-file.doc.mjs +154 -0
  152. package/assets/docs/typography.doc.mjs +24 -4
  153. package/assets/docs/working-with-ai.doc.mjs +30 -22
  154. package/authoring/config/config.doc.mjs +2 -2
  155. package/authoring/config/type.ts +2 -2
  156. package/authoring/doctypes/_schema.d.mts +3 -2
  157. package/authoring/doctypes/_schema.mjs +6 -0
  158. package/authoring/doctypes/base/graph-fields.doc.mjs +3 -3
  159. package/authoring/doctypes/base/type.ts +4 -2
  160. package/authoring/doctypes/command/command.doc.mjs +1 -1
  161. package/authoring/doctypes/command/type.ts +1 -1
  162. package/authoring/doctypes/component/component.doc.mjs +6 -0
  163. package/authoring/doctypes/component/type.ts +8 -0
  164. package/authoring/doctypes/reference/reference.doc.mjs +7 -0
  165. package/authoring/doctypes/reference/type.ts +5 -0
  166. package/authoring/doctypes/schema/schema.doc.mjs +2 -2
  167. package/authoring/doctypes/template/template.doc.mjs +1 -1
  168. package/authoring/doctypes/template/type.ts +2 -2
  169. package/authoring/integration/integration.doc.mjs +12 -10
  170. package/clients/cli/command-result-coverage.test.mjs +7 -7
  171. package/clients/cli/commands/component.doc.mjs +4 -3
  172. package/clients/cli/commands/debug-result-summary.test.mjs +2 -2
  173. package/clients/cli/commands/docs.doc.mjs +1 -1
  174. package/clients/cli/commands/docs.mjs +60 -17
  175. package/clients/cli/commands/doctor-integration-docs.doc.mjs +3 -2
  176. package/clients/cli/commands/doctor-integration.test.mjs +53 -0
  177. package/clients/cli/commands/doctor.doc.mjs +3 -1
  178. package/clients/cli/commands/doctor.mjs +49 -5
  179. package/clients/cli/commands/gap-report.doc.mjs +10 -9
  180. package/clients/cli/commands/init.doc.mjs +9 -6
  181. package/clients/cli/commands/integration-add.doc.mjs +9 -9
  182. package/clients/cli/commands/integration-authoring.test.mjs +61 -10
  183. package/clients/cli/commands/integration-pack.doc.mjs +5 -9
  184. package/clients/cli/commands/integration-real-world.test.mjs +1 -1
  185. package/clients/cli/commands/integration-verify.doc.mjs +22 -0
  186. package/clients/cli/commands/integration.doc.mjs +4 -4
  187. package/clients/cli/commands/integration.mjs +74 -43
  188. package/clients/cli/commands/layout-check.doc.mjs +65 -0
  189. package/clients/cli/commands/layout-expand.doc.mjs +83 -0
  190. package/clients/cli/commands/layout-grammar.doc.mjs +30 -0
  191. package/clients/cli/commands/layout.doc.mjs +34 -0
  192. package/clients/cli/commands/layout.error-codes.test.mjs +66 -0
  193. package/clients/cli/commands/layout.exit-parity.test.mjs +41 -0
  194. package/clients/cli/commands/layout.mjs +275 -0
  195. package/clients/cli/commands/layout.path-help.test.mjs +33 -0
  196. package/clients/cli/commands/layout.stdin-cap.test.mjs +47 -0
  197. package/clients/cli/commands/layout.text-fields.test.mjs +39 -0
  198. package/clients/cli/commands/manifest.doc.mjs +1 -1
  199. package/clients/cli/commands/search.doc.mjs +10 -3
  200. package/clients/cli/commands/search.mjs +21 -2
  201. package/clients/cli/commands/search.test.mjs +21 -4
  202. package/clients/cli/commands/swizzle.doc.mjs +1 -1
  203. package/clients/cli/commands/template.doc.mjs +1 -1
  204. package/clients/cli/commands/text-json-parity.test.mjs +24 -1
  205. package/clients/cli/commands/theme-add.doc.mjs +1 -1
  206. package/clients/cli/commands/theme-palette-generate.doc.mjs +3 -2
  207. package/clients/cli/commands/theme-palette.doc.mjs +1 -2
  208. package/clients/cli/commands/theme-targets.doc.mjs +2 -2
  209. package/clients/cli/commands/theme.doc.mjs +2 -1
  210. package/clients/cli/commands/upgrade.doc.mjs +62 -3
  211. package/clients/cli/index.mjs +32 -6
  212. package/clients/cli/lib/define-command.mjs +28 -4
  213. package/clients/cli/lib/define-command.test.mjs +54 -0
  214. package/clients/cli/lib/exit-codes.test.mjs +25 -2
  215. package/clients/cli/lib/json-shim.test.mjs +20 -6
  216. package/clients/cli/lib/manifest.mjs +23 -5
  217. package/foundation/agent-docs/agent-docs.mjs +1 -1
  218. package/foundation/discovery/authoring-self-docs.test.mjs +6 -2
  219. package/foundation/discovery/cli-self-docs.mjs +16 -2
  220. package/foundation/discovery/cli-self-docs.test.mjs +20 -0
  221. package/foundation/discovery/docs-discovery.mjs +5 -1
  222. package/foundation/discovery/docs-discovery.test.mjs +21 -0
  223. package/foundation/discovery/docs-section-key.d.mts +1 -1
  224. package/foundation/discovery/docs-section-key.mjs +1 -1
  225. package/foundation/discovery/template-adapter.mjs +1 -1
  226. package/foundation/doc-compiler/doc-loads.test.mjs +15 -2
  227. package/foundation/doc-compiler/inputs.test.mjs +0 -1
  228. package/foundation/doc-compiler/tree.d.mts +4 -0
  229. package/foundation/doc-compiler/tree.mjs +6 -1
  230. package/foundation/integrations/cli-requirement.d.mts +26 -6
  231. package/foundation/integrations/cli-requirement.mjs +46 -11
  232. package/foundation/integrations/cli-requirement.test.mjs +7 -2
  233. package/foundation/integrations/contribution-inventory.mjs +1 -1
  234. package/foundation/response/error-codes.doc.mjs +6 -8
  235. package/foundation/response/error-codes.test.mjs +30 -5
  236. package/foundation/response/response-types.doc.d.mts +4 -3
  237. package/foundation/response/response-types.doc.mjs +42 -6
  238. package/foundation/response/response.doc.mjs +11 -10
  239. package/foundation/xle/browser.d.mts +3 -3
  240. package/foundation/xle/browser.mjs +3 -3
  241. package/foundation/xle/expand.mjs +2 -2
  242. package/foundation/xle/parse.mjs +1 -1
  243. package/foundation/xle/print.mjs +2 -2
  244. package/foundation/xle/splice.mjs +1 -1
  245. package/package.json +9 -9
  246. package/api/docs/docs.test.mjs +0 -245
  247. package/api/docs/integration-tree.test.mjs +0 -555
  248. package/api/docs/integrationDocs.test.mjs +0 -314
  249. package/api/search/search.test.mjs +0 -530
  250. package/assets/docs/tree/integrations.test.mjs +0 -62
  251. package/assets/docs/tree/writing-docs.doc.mjs +0 -286
  252. package/clients/cli/commands/docs.test.mjs +0 -323
  253. package/foundation/agent-docs/agent-docs.test.mjs +0 -1159
  254. package/foundation/doc-compiler/tree.test.mjs +0 -606
@@ -73,7 +73,7 @@ export const docs = {
73
73
  'Baseline 2026: the tightest requirement.',
74
74
  ],
75
75
  [
76
- '[`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API',
76
+ '`Popover` API',
77
77
  'Opens, stacks, and light-dismisses layered surfaces via the top layer.',
78
78
  'Baseline 2025.',
79
79
  ],
@@ -86,7 +86,7 @@ export const docs = {
86
86
  },
87
87
  {
88
88
  type: 'prose',
89
- text: 'The gap that matters is between Tier 1 and Tier 2: the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
89
+ text: 'The gap that matters is between Tier 1 and Tier 2: the `Popover` API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
90
90
  },
91
91
  ],
92
92
  },
@@ -95,24 +95,24 @@ export const docs = {
95
95
  content: [
96
96
  {
97
97
  type: 'prose',
98
- text: 'The browser requirement is concentrated in the layered-surface components: anything that renders content in an overlay positioned against a trigger:',
98
+ text: 'Any component that opens a menu, popover, tooltip, or dropdown carries the browser requirement: it renders that surface in an overlay positioned against its trigger. That includes:',
99
99
  },
100
100
  {
101
101
  type: 'list',
102
102
  style: 'unordered',
103
103
  items: [
104
- 'Tooltip',
105
- 'HoverCard',
106
- 'Popover',
107
- 'ContextMenu',
108
- 'Selector and MultiSelector (dropdown surfaces)',
104
+ 'Tooltip, HoverCard, and Popover, and any prop that shows one (such as the Button `tooltip`)',
105
+ 'DropdownMenu, MoreMenu, and ContextMenu',
106
+ 'Selector, MultiSelector, ComplexSelector, Typeahead, and PowerSearch (dropdown surfaces)',
107
+ 'DateInput, DateRangeInput, and DateTimeInput (calendar popovers)',
109
108
  'Tokenizer (suggestion menu)',
109
+ 'The overflow and flyout menus in Breadcrumbs, TabList, TopNav, and SideNav',
110
110
  'Carousel (anchored controls)',
111
111
  ],
112
112
  },
113
113
  {
114
114
  type: 'prose',
115
- text: 'If your product does not use any of these, it has no anchor-positioning requirement at all; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Page layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
115
+ text: 'If your product opens no menus, popovers, tooltips, or dropdowns, it has no anchor-positioning requirement; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Page layout, typography, forms, buttons, cards, and tables work down to Tier 2 with no special handling.',
116
116
  },
117
117
  ],
118
118
  },
@@ -123,7 +123,7 @@ export const docs = {
123
123
  type: 'list',
124
124
  style: 'do',
125
125
  items: [
126
- 'Components never throw on missing platform APIs. Where a browser lacks the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API, layers fall back to plain visibility instead of crashing.',
126
+ 'Components never throw on missing platform APIs. Where a browser lacks the `Popover` API, layers fall back to plain visibility instead of crashing.',
127
127
  'Tier 1 and Tier 2 are officially supported and tested.',
128
128
  'Non-layered components render correctly down to Tier 2.',
129
129
  ],
@@ -192,7 +192,7 @@ const hasLightDark = CSS.supports('color', 'light-dark(#000, #fff)');`,
192
192
  },
193
193
  {
194
194
  type: 'prose',
195
- text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
195
+ text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the `Popover` API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
196
196
  },
197
197
  ],
198
198
  },
@@ -22,7 +22,8 @@ export const docs = {
22
22
  ],
23
23
  },
24
24
  {
25
- title: 'Surface Colors',
25
+ id: 'surface-colors',
26
+ title: 'Color Tokens',
26
27
  category: 'foundations',
27
28
  content: [
28
29
  {
@@ -37,9 +38,14 @@ export const docs = {
37
38
  ],
38
39
  },
39
40
  {
40
- title: 'Usage',
41
+ id: 'usage',
42
+ title: 'Use color tokens in StyleX',
41
43
  category: 'foundations',
42
44
  content: [
45
+ {
46
+ type: 'prose',
47
+ text: 'Import the typed color tokens and use them in `stylex.create()`; they resolve to the active theme and color mode.',
48
+ },
43
49
  {
44
50
  type: 'code',
45
51
  lang: 'tsx',
@@ -82,7 +82,7 @@ export const docs = {
82
82
  content: [
83
83
  {
84
84
  type: 'prose',
85
- text: 'Configurable surfaces expose a single `elevation` prop instead of asking consumers to hand-write a box-shadow. It takes the graded enum `none | low | med | high`, narrowed per component to the steps that surface needs: Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, and Banner expose the full scale, while ChatComposer exposes only `none | low`. `none` is a flat literal (`box-shadow: none`); the other levels map to the `--shadow-*` tokens above, so a surface stays theme-agnostic.',
85
+ text: 'Configurable surfaces expose a single `elevation` prop instead of asking consumers to hand-write a box-shadow. It takes the graded enum `none | low | med | high`, narrowed per component to the steps that surface needs: Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, ToggleButton, and Banner expose the full scale, while ChatComposer exposes only `none | low`. `none` is a flat literal (`box-shadow: none`); the other levels map to the `--shadow-*` tokens above, so a surface stays theme-agnostic.',
86
86
  },
87
87
  {
88
88
  type: 'prose',
@@ -92,11 +92,13 @@ export const docs = {
92
92
  type: 'code',
93
93
  lang: 'tsx',
94
94
  label: 'Raising a surface with the elevation prop',
95
- code: `// Flat by default; raise only when the surface needs to float.
95
+ code: `import {Plus} from 'lucide-react';
96
+
97
+ // Flat by default; raise only when the surface needs to float.
96
98
  <Card elevation="low">Raised card</Card>
97
99
 
98
100
  // A floating action button.
99
- <IconButton icon={<Icon icon="add" />} label="New" variant="primary" elevation="med" />
101
+ <IconButton icon={<Icon icon={Plus} />} label="New" variant="primary" elevation="med" />
100
102
 
101
103
  // Flatten the composer (defaults to 'low').
102
104
  <ChatComposer elevation="none" onSubmit={handleSubmit} />`,
@@ -119,7 +121,7 @@ export const docs = {
119
121
  type: 'code',
120
122
  lang: 'tsx',
121
123
  label: 'Applying elevation',
122
- code: `import {shadowVars} from '@astryxdesign/core';
124
+ code: `import {shadowVars} from '@astryxdesign/core/theme/tokens.stylex';
123
125
 
124
126
  const styles = stylex.create({
125
127
  dropdown: {
@@ -8,6 +8,7 @@ export const docs = {
8
8
  category: 'guide',
9
9
  description:
10
10
  'Add the design system to your project and start building.',
11
+ keywords: ['quick start', 'setup', 'install'],
11
12
 
12
13
  sections: [
13
14
  {
@@ -81,24 +82,11 @@ export const docs = {
81
82
  },
82
83
  {
83
84
  type: 'prose',
84
- text: 'Available themes:',
85
- },
86
- {
87
- type: 'list',
88
- style: 'unordered',
89
- items: [
90
- '`@astryxdesign/theme-neutral`: muted and minimal; a good starting point',
91
- '`@astryxdesign/theme-butter`: warm, golden tones with blue accents',
92
- '`@astryxdesign/theme-chocolate`: rich chocolate and caramel tones',
93
- '`@astryxdesign/theme-gothic`: dark-only theme with ink and noir influences',
94
- '`@astryxdesign/theme-matcha`: earthy greens and botanical tones',
95
- '`@astryxdesign/theme-stone`: warm neutrals inspired by sandstone',
96
- '`@astryxdesign/theme-y2k`: playful early-2000s pop aesthetic',
97
- ],
85
+ text: 'Run `astryx theme list` to see every theme.',
98
86
  },
99
87
  {
100
88
  type: 'prose',
101
- text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in {@link generic:migration} before building screens.',
89
+ text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. Before building screens, read the two cascade layer sections of {@link generic:migration}.',
102
90
  },
103
91
  {
104
92
  type: 'prose',
@@ -135,7 +123,7 @@ export default function Page() {
135
123
  content: [
136
124
  {
137
125
  type: 'prose',
138
- text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See the [styling docs](/docs/styling) for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',
126
+ text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See {@link generic:styling} for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',
139
127
  },
140
128
  {
141
129
  type: 'code',
@@ -167,6 +155,7 @@ const overrides = stylex.create({
167
155
  ['Next.js + Tailwind', 'Next.js + Tailwind bridge', '[apps/example-nextjs-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-tailwind)'],
168
156
  ['Next.js Source', 'Next.js importing from source', '[apps/example-nextjs-source](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-source)'],
169
157
  ['Vite', 'Vite', '[apps/example-vite](https://github.com/facebook/astryx/tree/main/apps/example-vite)'],
158
+ ['Vite + Tailwind', 'Vite + Tailwind bridge', '[apps/example-vite-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-vite-tailwind)'],
170
159
  ],
171
160
  },
172
161
  {
@@ -73,7 +73,7 @@ export const docs = {
73
73
  import { HeartIcon } from 'lucide-react';
74
74
 
75
75
  <Icon icon={PhotoIcon} size="lg" />
76
- <Icon icon={HeartIcon} color="negative" />`,
76
+ <Icon icon={HeartIcon} color="error" />`,
77
77
  },
78
78
  ],
79
79
  },
@@ -128,26 +128,7 @@ export const brandTheme = defineTheme({
128
128
  },
129
129
  {
130
130
  type: 'prose',
131
- text: 'Ship the fallback in `defaultIcons` under the same key so the glyph still renders with no theme, or pass one to `getExtendedIcon(key, fallback)` when the icon lives outside core.',
132
- },
133
- ],
134
- },
135
- {
136
- title: 'Adding New Icons',
137
- category: 'foundations',
138
- content: [
139
- {
140
- type: 'prose',
141
- text: 'To add a new semantic icon name to the design system, only for a glyph the whole system shares; a component-owned one takes a namespaced key instead:',
142
- },
143
- {
144
- type: 'list',
145
- style: 'ordered',
146
- items: [
147
- 'Add the name to IconName type in `packages/core/src/Icon/globalIconRegistry.tsx`',
148
- 'Add the default SVG to `packages/core/src/Icon/defaultIcons.tsx`',
149
- 'Add a row to the Available Names table in `packages/cli/assets/docs/icons.doc.mjs`',
150
- ],
131
+ text: 'Outside core, pass a fallback to `getExtendedIcon(key, fallback)` so the glyph renders with no theme.',
151
132
  },
152
133
  ],
153
134
  },
@@ -7,6 +7,7 @@ export const docs = {
7
7
  category: 'foundations',
8
8
  description:
9
9
  'Illustration guidelines for empty states, onboarding flows, and feature highlights.',
10
+ keywords: ['empty state'],
10
11
 
11
12
  sections: [
12
13
  {
@@ -59,26 +60,17 @@ export const docs = {
59
60
  content: [
60
61
  {
61
62
  type: 'prose',
62
- text: 'Place illustrations inside Center with supporting text stacked below. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a heading and optional body text to explain what the user should do next.',
63
+ text: 'For an empty state, pass the illustration to the `icon` slot of `EmptyState`, which centers it above the title and description. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a title and a description that says what to do next.',
63
64
  },
64
65
  {
65
66
  type: 'code',
66
67
  lang: 'tsx',
67
68
  label: 'Empty state with illustration',
68
- code: `<Center>
69
- <Stack direction="vertical" gap={3} hAlign="center">
70
- <img
71
- src="/illustrations/empty-search.svg"
72
- alt="No results"
73
- style={{ width: 200, height: 200 }}
74
- />
75
- <Heading level={3}>No results found</Heading>
76
- <Text type="body" color="secondary">
77
- Try adjusting your search or filters to find what you\u2019re
78
- looking for.
79
- </Text>
80
- </Stack>
81
- </Center>`,
69
+ code: `<EmptyState
70
+ icon={<img src="/illustrations/empty-search.svg" alt="" width={200} height={200} />}
71
+ title="No results found"
72
+ description="Try adjusting your search or filters."
73
+ />`,
82
74
  },
83
75
  ],
84
76
  },
@@ -33,8 +33,35 @@ export const docsDense = {
33
33
  section: 'Scaffold',
34
34
  title: 'Scaffold',
35
35
  content: [
36
- // Shell
37
- null,
36
+ {
37
+ type: 'prose',
38
+ text: 'pick shell, budget regions, choose nav, before content. steps: Shell, Navigation. rules for both:',
39
+ },
40
+ {
41
+ type: 'list',
42
+ items: [
43
+ 'decide frame + region width budgets + fill-or-capped before content',
44
+ 'state the reason for the nav choice, or inherit template pairing',
45
+ 'raw px for structural widths; interior = tokens',
46
+ ],
47
+ },
48
+ {
49
+ type: 'list',
50
+ items: [
51
+ 'build content-first, Card-wrapping each section',
52
+ 'stretch prose/forms/lists across a wide region instead of capping with contentWidth',
53
+ 'SideNav when the nav is really filters/controls, or must hold wide elements like breadcrumbs',
54
+ 'TopNav when top-slot ownership is unclear, or hierarchy is deep or still growing',
55
+ 'both bars when the ecosystem layer is thin',
56
+ 'break template nav pairing without a reason',
57
+ ],
58
+ },
59
+ ],
60
+ },
61
+ {
62
+ section: 'Shell',
63
+ title: 'Shell',
64
+ content: [
38
65
  {
39
66
  type: 'prose',
40
67
  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.',
@@ -53,8 +80,12 @@ export const docsDense = {
53
80
  type: 'prose',
54
81
  text: 'verify: every region has a width budget + fill-or-capped + a container policy written down before any content.',
55
82
  },
56
- // Navigation
57
- null,
83
+ ],
84
+ },
85
+ {
86
+ section: 'Navigation',
87
+ title: 'Navigation',
88
+ content: [
58
89
  {
59
90
  type: 'prose',
60
91
  text: 'nav left open? default SideNav: it absorbs destinations you have not planned yet. app type + destination count are guiding indicators, not determining rules.',
@@ -73,35 +104,45 @@ export const docsDense = {
73
104
  type: 'prose',
74
105
  text: 'verify: you can state the reason in one sentence, and it still holds if the nav doubles. npx astryx build "<idea>" names the template to start from; scaffold it and the pairing is wired up.',
75
106
  },
76
- // Best practices
77
- null,
107
+ ],
108
+ },
109
+ {
110
+ section: 'Structure',
111
+ title: 'Structure',
112
+ content: [
113
+ {
114
+ type: 'prose',
115
+ text: 'rank content per region, pick the weakest container that groups it. steps: Type hierarchy, Card or rows, Headers and footers, Side panels. rules for all:',
116
+ },
78
117
  {
79
118
  type: 'list',
80
119
  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',
120
+ 'one lead per region; rank via weight+color; one primary action',
121
+ 'leave body copy at its defaults; demote via weight+color, not size',
122
+ 'default Section; weakest container that reads as a group',
123
+ 'collections = rows (Table/List), edge-to-edge with dividers',
124
+ 'side panel on select; it yields width at narrow sizes',
84
125
  ],
85
126
  },
86
127
  {
87
128
  type: 'list',
88
129
  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',
130
+ 'grey + shrink body copy, so a whole region reads as metadata',
131
+ 'the disabled color for content; it fails contrast, it is for disabled controls',
132
+ 'card soup: each record in its own Card',
133
+ 'cards-in-cards, or full-width Cards as page structure',
134
+ 'a header/footer rebuilt inside the body, where it scrolls away with the rows',
135
+ 'flexbox soup instead of Grid/Layout/Section/FormLayout',
136
+ 'two competing primary actions in one region',
137
+ 'Badge as decoration; use StatusDot/Token for status',
95
138
  ],
96
139
  },
97
140
  ],
98
141
  },
99
142
  {
100
- section: 'Structure',
101
- title: 'Structure',
143
+ section: 'Type hierarchy',
144
+ title: 'Type hierarchy',
102
145
  content: [
103
- // Type hierarchy
104
- null,
105
146
  {
106
147
  type: 'prose',
107
148
  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.',
@@ -120,8 +161,12 @@ export const docsDense = {
120
161
  type: 'prose',
121
162
  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
163
  },
123
- // Containers
124
- null,
164
+ ],
165
+ },
166
+ {
167
+ section: 'Card or rows',
168
+ title: 'Card or rows',
169
+ content: [
125
170
  {
126
171
  type: 'prose',
127
172
  text: 'weakest container that reads as a group, escalate only when it fails. weakest to strongest:',
@@ -140,8 +185,12 @@ export const docsDense = {
140
185
  type: 'prose',
141
186
  text: 'test: records -> rows (Table columnar, List single-line); self-contained widget or hard boundary -> Card; everything else -> Section.',
142
187
  },
143
- // Headers and footers
144
- null,
188
+ ],
189
+ },
190
+ {
191
+ section: 'Headers and footers',
192
+ title: 'Headers and footers',
193
+ content: [
145
194
  {
146
195
  type: 'prose',
147
196
  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.',
@@ -160,8 +209,12 @@ export const docsDense = {
160
209
  type: 'prose',
161
210
  text: 'verify: scroll the body. header + footer stay put, dividers run full-bleed, all three still share one left content line.',
162
211
  },
163
- // Side panels
164
- null,
212
+ ],
213
+ },
214
+ {
215
+ section: 'Side panels',
216
+ title: 'Side panels',
217
+ content: [
165
218
  {
166
219
  type: 'prose',
167
220
  text: 'master-detail: select a row -> fixed-width side panel, no navigation away.',
@@ -179,41 +232,43 @@ export const docsDense = {
179
232
  null,
180
233
  {
181
234
  type: 'prose',
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.',
235
+ text: 'verify: at narrow widths the panel yields width instead of squeezing content (see Responsive contract), and only one element between the regions draws a border.',
236
+ },
237
+ ],
238
+ },
239
+ {
240
+ section: 'Spacing',
241
+ title: 'Spacing',
242
+ content: [
243
+ {
244
+ type: 'prose',
245
+ text: 'one content line per region, then tune gaps + density. steps: Alignment, Rhythm, Density and size. rules for all:',
183
246
  },
184
- // Best practices
185
- null,
186
247
  {
187
248
  type: 'list',
188
249
  items: [
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',
250
+ 'container owns padding; children zero margins',
251
+ 'one content line: text on line, hover bleeds to edge',
252
+ 'one padding token across region header/body/footer',
253
+ 'contrast tight vs generous gaps',
254
+ 'one control size per row; density by use frequency',
194
255
  ],
195
256
  },
196
257
  {
197
258
  type: 'list',
198
259
  items: [
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',
260
+ 'double padding (component past its heading); keep one inset owner',
261
+ 'raw px for interior spacing; tokens only',
262
+ 'one repeated gap everywhere',
263
+ 'mixed control sizes in one row',
207
264
  ],
208
265
  },
209
266
  ],
210
267
  },
211
268
  {
212
- section: 'Spacing',
213
- title: 'Spacing',
269
+ section: 'Alignment',
270
+ title: 'Alignment',
214
271
  content: [
215
- // Alignment
216
- null,
217
272
  {
218
273
  type: 'prose',
219
274
  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.',
@@ -231,8 +286,12 @@ export const docsDense = {
231
286
  type: 'prose',
232
287
  text: 'verify: draw one vertical line down the left. every label touches it; only hover/selected backgrounds cross it.',
233
288
  },
234
- // Rhythm
235
- null,
289
+ ],
290
+ },
291
+ {
292
+ section: 'Rhythm',
293
+ title: 'Rhythm',
294
+ content: [
236
295
  {
237
296
  type: 'prose',
238
297
  text: 'grouping = contrast between tight and generous gaps, not one repeated value. same step everywhere = proximity does no work.',
@@ -250,8 +309,12 @@ export const docsDense = {
250
309
  type: 'prose',
251
310
  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
311
  },
253
- // Density and size
254
- null,
312
+ ],
313
+ },
314
+ {
315
+ section: 'Density and size',
316
+ title: 'Density and size',
317
+ content: [
255
318
  {
256
319
  type: 'prose',
257
320
  text: 'density by use frequency; every control in a row shares one size so heights share a baseline.',
@@ -269,35 +332,38 @@ export const docsDense = {
269
332
  type: 'prose',
270
333
  text: 'verify: one size per row, paired with the density of the region it sits in.',
271
334
  },
272
- // Best practices
273
- null,
335
+ ],
336
+ },
337
+ {
338
+ section: 'Breakpoints',
339
+ title: 'Breakpoints',
340
+ content: [
341
+ {
342
+ type: 'prose',
343
+ text: 'decide what each region does as width changes. step: Responsive contract. rules:',
344
+ },
274
345
  {
275
346
  type: 'list',
276
347
  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',
348
+ 'write the contract down for every region before calling the layout done',
349
+ 'decide per region: revealed, resized, or swapped at each width',
350
+ 'drop a region rather than let it fight for width it lacks',
282
351
  ],
283
352
  },
284
353
  {
285
354
  type: 'list',
286
355
  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',
356
+ '3 regions at a width where none has usable space',
357
+ 'shrink every region uniformly instead of swapping/dropping one',
358
+ 'a CSS breakpoint the contract comment never mentions',
291
359
  ],
292
360
  },
293
361
  ],
294
362
  },
295
363
  {
296
- section: 'Breakpoints',
297
- title: 'Breakpoints',
364
+ section: 'Responsive contract',
365
+ title: 'Responsive contract',
298
366
  content: [
299
- // Responsive contract
300
- null,
301
367
  {
302
368
  type: 'prose',
303
369
  text: 'lock what each region does as width changes; pair each contract line with the prop/hook that enforces it.',
@@ -316,24 +382,6 @@ export const docsDense = {
316
382
  type: 'prose',
317
383
  text: 'verify: every contract line names a mechanism, so the comment cannot drift from the behavior.',
318
384
  },
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
- },
337
385
  ],
338
386
  },
339
387
  ],