@flowstack-ui/agent-tools 0.1.0-bootstrap.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (239) hide show
  1. package/.codex-plugin/plugin.json +37 -0
  2. package/CHANGELOG.md +21 -0
  3. package/LICENSE +21 -0
  4. package/README.md +125 -0
  5. package/docs/architecture.md +77 -0
  6. package/docs/releasing.md +26 -0
  7. package/docs/testing.md +32 -0
  8. package/package.json +63 -0
  9. package/public/index.json +2073 -0
  10. package/public/llms.txt +19 -0
  11. package/public/packages/atom/0.24.0/components/accordion.txt +131 -0
  12. package/public/packages/atom/0.24.0/components/alert-dialog.txt +112 -0
  13. package/public/packages/atom/0.24.0/components/app-bar.txt +96 -0
  14. package/public/packages/atom/0.24.0/components/aspect-ratio.txt +111 -0
  15. package/public/packages/atom/0.24.0/components/avatar.txt +119 -0
  16. package/public/packages/atom/0.24.0/components/badge.txt +123 -0
  17. package/public/packages/atom/0.24.0/components/bottom-navigation.txt +96 -0
  18. package/public/packages/atom/0.24.0/components/breadcrumb.txt +96 -0
  19. package/public/packages/atom/0.24.0/components/button.txt +98 -0
  20. package/public/packages/atom/0.24.0/components/carousel.txt +128 -0
  21. package/public/packages/atom/0.24.0/components/checkbox-group.txt +118 -0
  22. package/public/packages/atom/0.24.0/components/checkbox.txt +100 -0
  23. package/public/packages/atom/0.24.0/components/clipboard.txt +112 -0
  24. package/public/packages/atom/0.24.0/components/collapsible.txt +112 -0
  25. package/public/packages/atom/0.24.0/components/color-picker.txt +117 -0
  26. package/public/packages/atom/0.24.0/components/combobox.txt +126 -0
  27. package/public/packages/atom/0.24.0/components/context-menu.txt +114 -0
  28. package/public/packages/atom/0.24.0/components/data-grid.txt +136 -0
  29. package/public/packages/atom/0.24.0/components/dialog.txt +116 -0
  30. package/public/packages/atom/0.24.0/components/direction.txt +132 -0
  31. package/public/packages/atom/0.24.0/components/divider.txt +94 -0
  32. package/public/packages/atom/0.24.0/components/drag-drop.txt +141 -0
  33. package/public/packages/atom/0.24.0/components/drawer.txt +96 -0
  34. package/public/packages/atom/0.24.0/components/dropdown-menu.txt +112 -0
  35. package/public/packages/atom/0.24.0/components/feed.txt +132 -0
  36. package/public/packages/atom/0.24.0/components/field.txt +108 -0
  37. package/public/packages/atom/0.24.0/components/fieldset.txt +96 -0
  38. package/public/packages/atom/0.24.0/components/file-upload.txt +120 -0
  39. package/public/packages/atom/0.24.0/components/form.txt +98 -0
  40. package/public/packages/atom/0.24.0/components/hover-card.txt +114 -0
  41. package/public/packages/atom/0.24.0/components/image.txt +94 -0
  42. package/public/packages/atom/0.24.0/components/input.txt +96 -0
  43. package/public/packages/atom/0.24.0/components/label.txt +121 -0
  44. package/public/packages/atom/0.24.0/components/link.txt +100 -0
  45. package/public/packages/atom/0.24.0/components/list.txt +131 -0
  46. package/public/packages/atom/0.24.0/components/listbox.txt +120 -0
  47. package/public/packages/atom/0.24.0/components/menu.txt +126 -0
  48. package/public/packages/atom/0.24.0/components/menubar.txt +120 -0
  49. package/public/packages/atom/0.24.0/components/modal.txt +118 -0
  50. package/public/packages/atom/0.24.0/components/multi-select.txt +120 -0
  51. package/public/packages/atom/0.24.0/components/nav-list.txt +104 -0
  52. package/public/packages/atom/0.24.0/components/navigation-menu.txt +104 -0
  53. package/public/packages/atom/0.24.0/components/number-input.txt +124 -0
  54. package/public/packages/atom/0.24.0/components/otp-field.txt +122 -0
  55. package/public/packages/atom/0.24.0/components/pagination.txt +111 -0
  56. package/public/packages/atom/0.24.0/components/password-toggle-field.txt +116 -0
  57. package/public/packages/atom/0.24.0/components/popover.txt +122 -0
  58. package/public/packages/atom/0.24.0/components/pressable.txt +94 -0
  59. package/public/packages/atom/0.24.0/components/progress.txt +130 -0
  60. package/public/packages/atom/0.24.0/components/radio-group.txt +118 -0
  61. package/public/packages/atom/0.24.0/components/rating.txt +122 -0
  62. package/public/packages/atom/0.24.0/components/reorder.txt +141 -0
  63. package/public/packages/atom/0.24.0/components/scroll-area.txt +96 -0
  64. package/public/packages/atom/0.24.0/components/select.txt +126 -0
  65. package/public/packages/atom/0.24.0/components/sidebar.txt +96 -0
  66. package/public/packages/atom/0.24.0/components/skip-link.txt +96 -0
  67. package/public/packages/atom/0.24.0/components/slider.txt +124 -0
  68. package/public/packages/atom/0.24.0/components/swipeable-item.txt +118 -0
  69. package/public/packages/atom/0.24.0/components/switch.txt +116 -0
  70. package/public/packages/atom/0.24.0/components/table.txt +128 -0
  71. package/public/packages/atom/0.24.0/components/tabs.txt +96 -0
  72. package/public/packages/atom/0.24.0/components/textarea.txt +96 -0
  73. package/public/packages/atom/0.24.0/components/toast.txt +124 -0
  74. package/public/packages/atom/0.24.0/components/toggle-group.txt +118 -0
  75. package/public/packages/atom/0.24.0/components/toggle.txt +110 -0
  76. package/public/packages/atom/0.24.0/components/toolbar.txt +98 -0
  77. package/public/packages/atom/0.24.0/components/tooltip.txt +112 -0
  78. package/public/packages/atom/0.24.0/components/tree-grid.txt +138 -0
  79. package/public/packages/atom/0.24.0/components/tree.txt +138 -0
  80. package/public/packages/atom/0.24.0/components/visually-hidden.txt +119 -0
  81. package/public/packages/atom/0.24.0/docs/guides/agent-knowledge.txt +55 -0
  82. package/public/packages/atom/0.24.0/docs/guides/getting-started.txt +65 -0
  83. package/public/packages/atom/0.24.0/docs/guides/imports.txt +26 -0
  84. package/public/packages/atom/0.24.0/docs/guides/public-api.txt +100 -0
  85. package/public/packages/atom/0.24.0/guides/behavior-composition.txt +277 -0
  86. package/public/packages/atom/0.24.0/guides/layer-selection.txt +807 -0
  87. package/public/packages/atom/0.24.0/index.txt +89 -0
  88. package/public/packages/brick/0.1.11/components/accordion.txt +158 -0
  89. package/public/packages/brick/0.1.11/components/alert-dialog.txt +175 -0
  90. package/public/packages/brick/0.1.11/components/app-bar.txt +134 -0
  91. package/public/packages/brick/0.1.11/components/appearance.txt +143 -0
  92. package/public/packages/brick/0.1.11/components/aspect-ratio.txt +136 -0
  93. package/public/packages/brick/0.1.11/components/avatar.txt +152 -0
  94. package/public/packages/brick/0.1.11/components/badge.txt +139 -0
  95. package/public/packages/brick/0.1.11/components/bleed.txt +104 -0
  96. package/public/packages/brick/0.1.11/components/bottom-navigation.txt +106 -0
  97. package/public/packages/brick/0.1.11/components/breadcrumb.txt +96 -0
  98. package/public/packages/brick/0.1.11/components/button.txt +103 -0
  99. package/public/packages/brick/0.1.11/components/card.txt +132 -0
  100. package/public/packages/brick/0.1.11/components/carousel.txt +206 -0
  101. package/public/packages/brick/0.1.11/components/checkbox-group.txt +175 -0
  102. package/public/packages/brick/0.1.11/components/checkbox.txt +103 -0
  103. package/public/packages/brick/0.1.11/components/chip.txt +128 -0
  104. package/public/packages/brick/0.1.11/components/code-block.txt +134 -0
  105. package/public/packages/brick/0.1.11/components/code.txt +120 -0
  106. package/public/packages/brick/0.1.11/components/collapsible.txt +179 -0
  107. package/public/packages/brick/0.1.11/components/color-picker.txt +135 -0
  108. package/public/packages/brick/0.1.11/components/color-swatch.txt +98 -0
  109. package/public/packages/brick/0.1.11/components/combobox.txt +157 -0
  110. package/public/packages/brick/0.1.11/components/container.txt +112 -0
  111. package/public/packages/brick/0.1.11/components/context-menu.txt +174 -0
  112. package/public/packages/brick/0.1.11/components/data-grid.txt +199 -0
  113. package/public/packages/brick/0.1.11/components/data-list.txt +115 -0
  114. package/public/packages/brick/0.1.11/components/dialog.txt +176 -0
  115. package/public/packages/brick/0.1.11/components/divider.txt +104 -0
  116. package/public/packages/brick/0.1.11/components/drawer.txt +146 -0
  117. package/public/packages/brick/0.1.11/components/dropdown-menu.txt +179 -0
  118. package/public/packages/brick/0.1.11/components/feed.txt +143 -0
  119. package/public/packages/brick/0.1.11/components/field.txt +115 -0
  120. package/public/packages/brick/0.1.11/components/fieldset.txt +103 -0
  121. package/public/packages/brick/0.1.11/components/file-upload.txt +154 -0
  122. package/public/packages/brick/0.1.11/components/form.txt +108 -0
  123. package/public/packages/brick/0.1.11/components/frame.txt +132 -0
  124. package/public/packages/brick/0.1.11/components/grid.txt +141 -0
  125. package/public/packages/brick/0.1.11/components/group.txt +136 -0
  126. package/public/packages/brick/0.1.11/components/hide.txt +121 -0
  127. package/public/packages/brick/0.1.11/components/hover-card.txt +156 -0
  128. package/public/packages/brick/0.1.11/components/icon-button.txt +119 -0
  129. package/public/packages/brick/0.1.11/components/icon.txt +160 -0
  130. package/public/packages/brick/0.1.11/components/image.txt +163 -0
  131. package/public/packages/brick/0.1.11/components/input.txt +101 -0
  132. package/public/packages/brick/0.1.11/components/link-box.txt +161 -0
  133. package/public/packages/brick/0.1.11/components/link.txt +133 -0
  134. package/public/packages/brick/0.1.11/components/list.txt +139 -0
  135. package/public/packages/brick/0.1.11/components/menubar.txt +174 -0
  136. package/public/packages/brick/0.1.11/components/multi-select.txt +153 -0
  137. package/public/packages/brick/0.1.11/components/nav-list.txt +130 -0
  138. package/public/packages/brick/0.1.11/components/navigation-menu.txt +150 -0
  139. package/public/packages/brick/0.1.11/components/notification-badge.txt +148 -0
  140. package/public/packages/brick/0.1.11/components/number-input.txt +150 -0
  141. package/public/packages/brick/0.1.11/components/otp-field.txt +146 -0
  142. package/public/packages/brick/0.1.11/components/pagination.txt +124 -0
  143. package/public/packages/brick/0.1.11/components/password-toggle-field.txt +146 -0
  144. package/public/packages/brick/0.1.11/components/popover.txt +181 -0
  145. package/public/packages/brick/0.1.11/components/progress-circle.txt +142 -0
  146. package/public/packages/brick/0.1.11/components/progress.txt +150 -0
  147. package/public/packages/brick/0.1.11/components/radio-group.txt +152 -0
  148. package/public/packages/brick/0.1.11/components/rating.txt +151 -0
  149. package/public/packages/brick/0.1.11/components/reorderable-list.txt +130 -0
  150. package/public/packages/brick/0.1.11/components/scroll-area.txt +110 -0
  151. package/public/packages/brick/0.1.11/components/section.txt +118 -0
  152. package/public/packages/brick/0.1.11/components/segment-group.txt +116 -0
  153. package/public/packages/brick/0.1.11/components/select.txt +157 -0
  154. package/public/packages/brick/0.1.11/components/show.txt +121 -0
  155. package/public/packages/brick/0.1.11/components/sidebar.txt +126 -0
  156. package/public/packages/brick/0.1.11/components/skeleton.txt +127 -0
  157. package/public/packages/brick/0.1.11/components/skip-link.txt +102 -0
  158. package/public/packages/brick/0.1.11/components/slider.txt +147 -0
  159. package/public/packages/brick/0.1.11/components/stack.txt +155 -0
  160. package/public/packages/brick/0.1.11/components/status.txt +110 -0
  161. package/public/packages/brick/0.1.11/components/surface.txt +194 -0
  162. package/public/packages/brick/0.1.11/components/swipeable-item.txt +154 -0
  163. package/public/packages/brick/0.1.11/components/switch.txt +152 -0
  164. package/public/packages/brick/0.1.11/components/table.txt +183 -0
  165. package/public/packages/brick/0.1.11/components/tabs.txt +136 -0
  166. package/public/packages/brick/0.1.11/components/text.txt +148 -0
  167. package/public/packages/brick/0.1.11/components/textarea.txt +101 -0
  168. package/public/packages/brick/0.1.11/components/toast.txt +150 -0
  169. package/public/packages/brick/0.1.11/components/toggle-group.txt +149 -0
  170. package/public/packages/brick/0.1.11/components/toggle.txt +140 -0
  171. package/public/packages/brick/0.1.11/components/toolbar.txt +118 -0
  172. package/public/packages/brick/0.1.11/components/tooltip.txt +156 -0
  173. package/public/packages/brick/0.1.11/components/tree-grid.txt +160 -0
  174. package/public/packages/brick/0.1.11/components/tree.txt +156 -0
  175. package/public/packages/brick/0.1.11/components/visually-hidden.txt +123 -0
  176. package/public/packages/brick/0.1.11/components/z-stack.txt +143 -0
  177. package/public/packages/brick/0.1.11/docs/guides/agent-knowledge.txt +67 -0
  178. package/public/packages/brick/0.1.11/docs/guides/appearance-and-tokens.txt +179 -0
  179. package/public/packages/brick/0.1.11/docs/guides/browser-support.txt +25 -0
  180. package/public/packages/brick/0.1.11/docs/guides/control-sizing.txt +59 -0
  181. package/public/packages/brick/0.1.11/docs/guides/installation.txt +79 -0
  182. package/public/packages/brick/0.1.11/docs/guides/theme-contract.txt +90 -0
  183. package/public/packages/brick/0.1.11/guides/interface-composition.txt +665 -0
  184. package/public/packages/brick/0.1.11/guides/layer-selection.txt +1437 -0
  185. package/public/packages/brick/0.1.11/index.txt +110 -0
  186. package/public/packages/colors/0.1.1/docs/agent-knowledge.txt +63 -0
  187. package/public/packages/colors/0.1.1/docs/architecture.txt +74 -0
  188. package/public/packages/colors/0.1.1/docs/color-foundations.txt +128 -0
  189. package/public/packages/colors/0.1.1/docs/compatibility.txt +75 -0
  190. package/public/packages/colors/0.1.1/docs/dependency-qualification.txt +117 -0
  191. package/public/packages/colors/0.1.1/docs/installation.txt +48 -0
  192. package/public/packages/colors/0.1.1/docs/palette-generation.txt +151 -0
  193. package/public/packages/colors/0.1.1/docs/releasing.txt +34 -0
  194. package/public/packages/colors/0.1.1/docs/testing.txt +51 -0
  195. package/public/packages/colors/0.1.1/guides/colors-system.txt +282 -0
  196. package/public/packages/colors/0.1.1/index.txt +29 -0
  197. package/public/packages/colors/0.1.1/operations/color-conversion.txt +14 -0
  198. package/public/packages/colors/0.1.1/operations/color-inspection.txt +23 -0
  199. package/public/packages/colors/0.1.1/operations/color-measurement.txt +18 -0
  200. package/public/packages/colors/0.1.1/operations/color-provenance.txt +14 -0
  201. package/public/packages/colors/0.1.1/operations/named-palette-reference.txt +15 -0
  202. package/public/packages/colors/0.1.1/operations/palette-candidate.txt +37 -0
  203. package/public/packages/theme/0.1.1/docs/agent-knowledge.txt +44 -0
  204. package/public/packages/theme/0.1.1/docs/appearances-and-portals.txt +41 -0
  205. package/public/packages/theme/0.1.1/docs/architecture.txt +121 -0
  206. package/public/packages/theme/0.1.1/docs/authoring.txt +141 -0
  207. package/public/packages/theme/0.1.1/docs/colors-interchange.txt +82 -0
  208. package/public/packages/theme/0.1.1/docs/fonts.txt +40 -0
  209. package/public/packages/theme/0.1.1/docs/installation.txt +45 -0
  210. package/public/packages/theme/0.1.1/docs/migration.txt +40 -0
  211. package/public/packages/theme/0.1.1/docs/testing.txt +64 -0
  212. package/public/packages/theme/0.1.1/docs/troubleshooting.txt +53 -0
  213. package/public/packages/theme/0.1.1/guides/theme-system.txt +340 -0
  214. package/public/packages/theme/0.1.1/index.txt +31 -0
  215. package/public/packages/theme/0.1.1/operations/brick-contract-compatibility.txt +35 -0
  216. package/public/packages/theme/0.1.1/operations/colors-interchange.txt +35 -0
  217. package/public/packages/theme/0.1.1/operations/theme-artifacts.txt +19 -0
  218. package/public/packages/theme/0.1.1/operations/theme-cli.txt +10 -0
  219. package/public/packages/theme/0.1.1/operations/theme-compilation.txt +23 -0
  220. package/public/packages/theme/0.1.1/operations/theme-definition.txt +36 -0
  221. package/public/packages/theme/0.1.1/operations/theme-validation.txt +19 -0
  222. package/public/tasks/data.txt +39 -0
  223. package/public/tasks/forms.txt +65 -0
  224. package/public/tasks/layout.txt +37 -0
  225. package/public/tasks/navigation.txt +51 -0
  226. package/public/tasks/overlays.txt +39 -0
  227. package/public/tasks/theming.txt +37 -0
  228. package/skills/flowstack-ui-builder/SKILL.md +35 -0
  229. package/skills/flowstack-ui-builder/agents/openai.yaml +4 -0
  230. package/skills/flowstack-ui-builder/scripts/resolve-agent-knowledge.mjs +399 -0
  231. package/skills/flowstack-ui-compose/SKILL.md +32 -0
  232. package/skills/flowstack-ui-compose/agents/openai.yaml +4 -0
  233. package/skills/flowstack-ui-compose/scripts/resolve-agent-knowledge.mjs +399 -0
  234. package/skills/flowstack-ui-maintainer/SKILL.md +40 -0
  235. package/skills/flowstack-ui-maintainer/agents/openai.yaml +4 -0
  236. package/skills/flowstack-ui-maintainer/scripts/resolve-agent-knowledge.mjs +399 -0
  237. package/skills/flowstack-ui-review/SKILL.md +29 -0
  238. package/skills/flowstack-ui-review/agents/openai.yaml +4 -0
  239. package/skills/flowstack-ui-review/scripts/resolve-agent-knowledge.mjs +399 -0
@@ -0,0 +1,37 @@
1
+ # Palette candidate generation and review
2
+
3
+ Source: @flowstack-ui/colors@0.1.1
4
+ Kind: operation
5
+ ID: palette-candidate
6
+ Guide: [colors-system](/packages/colors/0.1.1/guides/colors-system.txt)
7
+
8
+ ## Covered public surfaces
9
+
10
+ - `.#BrandSeedInput`
11
+ - `.#CandidateAppearance`
12
+ - `.#CandidateColorValue`
13
+ - `.#CandidateMeasurement`
14
+ - `.#CandidateReview`
15
+ - `.#CandidateReviewDecision`
16
+ - `.#CandidateReviewStatus`
17
+ - `.#CandidateStatus`
18
+ - `.#ColorGenerationRequest`
19
+ - `.#ColorsCandidateEnvelope`
20
+ - `.#DecorativeCandidateAppearance`
21
+ - `.#DecorativeCandidateFamily`
22
+ - `.#DecorativeSeedInput`
23
+ - `.#GenerationDiagnostic`
24
+ - `.#GenerationDiagnosticCode`
25
+ - `.#InterfaceCandidateFamily`
26
+ - `.#InterfaceRole`
27
+ - `.#InterfaceSeedInput`
28
+ - `.#NeutralCandidateFamily`
29
+ - `.#NeutralRole`
30
+ - `.#NeutralSeedInput`
31
+ - `.#PaletteAppearance`
32
+ - `.#PaletteCandidateFamily`
33
+ - `.#PaletteProfile`
34
+ - `.#PaletteSeedBase`
35
+ - `.#defineColorGenerationRequest`
36
+ - `.#generatePaletteCandidate`
37
+ - `.#reviewPaletteCandidate`
@@ -0,0 +1,44 @@
1
+ # Public document: agent-knowledge
2
+
3
+ Source: @flowstack-ui/theme@0.1.1
4
+
5
+ # Agent Knowledge
6
+
7
+ Theme publishes the same ownership and validation guidance for humans and
8
+ coding agents.
9
+
10
+ ```js
11
+ import manifest from "@flowstack-ui/theme/agents/manifest.json" with { type: "json" };
12
+ ```
13
+
14
+ The manifest points to:
15
+
16
+ - `@flowstack-ui/theme/agents/theme-system.json` for structured decisions,
17
+ rules, ownership, and validation checks; and
18
+ - `@flowstack-ui/theme/agents/theme-system.md` for the equivalent readable
19
+ guide.
20
+
21
+ It also links `@flowstack-ui/theme/agents/coverage.json`. The deterministic
22
+ `flowstack.agent-coverage.v1` report reconciles every public root and schema
23
+ symbol plus the `flowstack-theme` CLI with seven selectable operation owners:
24
+ definition, validation, installed Brick contract compatibility, Colors file
25
+ interchange, compilation, artifact writing, and CLI automation. Release checks
26
+ require all seven operations and every public surface to be classified, routed,
27
+ and failure-free.
28
+
29
+ `agents/theme-system.json` is the structured authority and its Markdown is
30
+ generated from that file. `npm run agents:build` regenerates the source
31
+ Markdown and complete `dist/agents` directory. `npm run agents:check` rejects
32
+ source/Markdown drift and missing, stale, or extra generated artifacts.
33
+
34
+ Agents should read this package guide together with Brick's package and
35
+ component Agent Knowledge. Brick teaches component selection and semantic
36
+ consumption; Theme teaches project value mapping and compilation. Neither
37
+ artifact grants an agent permission to invent brand direction. Creative input
38
+ and application product intent remain explicit inputs.
39
+
40
+ Theme reads the contract belonging to the exact installed Brick build input;
41
+ it does not copy Brick's token inventory or depend on Brick at runtime. Colors
42
+ is an optional reviewed serialized handoff and is likewise not a Theme runtime
43
+ dependency. Applications continue to own activation, persistence, first paint,
44
+ fonts, assets, portals, routes, and delivery of the compiled CSS.
@@ -0,0 +1,41 @@
1
+ # Public document: appearances-and-portals
2
+
3
+ Source: @flowstack-ui/theme@0.1.1
4
+
5
+ # Appearances and portals
6
+
7
+ Light and dark are appearances inside one brand theme. A definition may be
8
+ fixed light, fixed dark, or dual appearance with a fixed or `system` default.
9
+
10
+ The theme identity uses `data-flowstack-theme`. Brick continues to own
11
+ appearance boundaries through `data-brick-appearance="light|dark"` and its
12
+ server-safe `Appearance` component. Generated CSS emits a complete token map
13
+ at every explicit boundary, so light → dark → light re-entry works without a
14
+ provider.
15
+
16
+ ```html
17
+ <body data-flowstack-theme="acme">
18
+ <main data-brick-appearance="light">
19
+ <aside data-brick-appearance="dark">
20
+ <section data-brick-appearance="light"></section>
21
+ </aside>
22
+ </main>
23
+ </body>
24
+ ```
25
+
26
+ The application owns root preference, persistence, and the earliest safe
27
+ pre-paint attribute setup. Theme does not read `localStorage`, inspect media
28
+ queries, or mutate the document.
29
+
30
+ ## Portals
31
+
32
+ A portal inherits React context but not the trigger's CSS ancestry. Content
33
+ rendered under `document.body` therefore inherits the document theme and
34
+ appearance, not a locally themed trigger subtree.
35
+
36
+ When a portal must retain a local appearance, render it into a container under
37
+ that visual boundary or apply an explicit theme/appearance boundary to the
38
+ portal root. Do not copy computed CSS variables in JavaScript.
39
+
40
+ Nested different-brand themes remain structurally possible, but complete
41
+ multi-brand nesting is not a Theme `0.1` qualification claim.
@@ -0,0 +1,121 @@
1
+ # Public document: architecture
2
+
3
+ Source: @flowstack-ui/theme@0.1.1
4
+
5
+ # Architecture
6
+
7
+ ## Package purpose
8
+
9
+ `@flowstack-ui/theme` is build-time infrastructure for serializable FLOWSTACK
10
+ theme definitions. Brick owns components and its default semantic contract. A
11
+ theme maps project visual decisions into that contract and may also retain
12
+ additional project roles that Brick does not consume.
13
+
14
+ ## Definition and compiler boundary
15
+
16
+ The definition envelope is `flowstack.theme.v1`. Compilable token leaves are
17
+ strings or finite numbers. Exact `{path.to.token}` aliases may cross palettes,
18
+ roles, Brick mappings, foundations, component inputs, and extensions. Unknown
19
+ or circular aliases fail compilation.
20
+
21
+ The first schema identifier is `flowstack.theme.v1`. Additive optional fields
22
+ may remain within version 1. Removing a field, changing existing meaning, or
23
+ making previously valid data invalid requires a new schema identifier or a
24
+ documented compatibility migration.
25
+
26
+ ## Contract mapping
27
+
28
+ The compiler receives Brick's generated
29
+ `flowstack.brick-theme-contract.v1` as data; it does not import Brick source or
30
+ carry a copied token list. Theme `brick.light` and `brick.dark` objects address
31
+ required semantic paths after the contract's `semantic.<appearance>` prefix.
32
+ Compilation requires contract revision 2 or newer so contrast declarations
33
+ cannot be absent silently. Revision 3 contracts may additionally declare
34
+ closed `allowedValues` for categorical component inputs and a `when` condition
35
+ on contrast pairs. These fields remain optional so revision 2 contracts stay
36
+ compatible.
37
+ Theme `foundations` addresses derived semantic paths. Theme `components`
38
+ addresses only declared inherited component inputs, for example
39
+ `components.drawer.radius`.
40
+
41
+ Sparse authoring is safe at the family level. A completely omitted atomic
42
+ family inherits Brick defaults, but a partially overridden family is rejected.
43
+ Every emitted appearance contains the complete required Brick map.
44
+ Compatibility accepts exact semantic versions, caret or tilde ranges,
45
+ comparator sets, and `||` alternatives.
46
+
47
+ Brick also owns a versioned list of maintained semantic contrast pairs. Theme
48
+ evaluates those pairs for every supported appearance with WCAG 2 relative
49
+ luminance in sRGB. Text pairs require at least 4.5:1 and non-text or
50
+ text-distinction pairs require at least 3:1; the unrounded ratio decides
51
+ success. A conditional pair runs only when its declared categorical
52
+ component-input value is active, using either the authored value or Brick
53
+ fallback. A participating token must resolve to an opaque sRGB hex or `rgb()`
54
+ value. Compilation fails when a pair is insufficient or cannot be proved. This
55
+ contract deliberately excludes disabled presentation and does not claim to
56
+ model gradients, transparency, images, consumer overrides, or the final
57
+ browser composition.
58
+
59
+ Project `palettes`, `roles`, and `extensions` are open vocabularies. They emit
60
+ under `--flowstack-theme-*`, never create new `--brick-*` meanings, and are
61
+ also retained in the token artifact. Extension top-level keys are the
62
+ discoverable namespaces recorded by the manifest.
63
+
64
+ Project meanings that vary by appearance belong in `appearanceRoles`. Each
65
+ logical path must provide every supported appearance and emits one stable
66
+ `--flowstack-theme-roles-*` variable through the same default, system,
67
+ explicit, and nested appearance selectors used by Brick mappings. An
68
+ appearance role cannot collide with an invariant `roles` path.
69
+
70
+ Themes may declare contrast relationships between appearance roles. Theme
71
+ evaluates these separately from Brick-owned pairs and records both groups in
72
+ the report. This proves only the resolved opaque foreground and background;
73
+ images, gradients, transparency, and the final browser composition remain
74
+ consumer qualification responsibilities.
75
+
76
+ ## Colors interchange
77
+
78
+ Theme may read a reviewed serialized `flowstack.colors-candidate.v1` document
79
+ as optional build input. It never imports Colors code and has no Colors runtime
80
+ dependency. An explicit scaffold mapping assigns selected candidate families
81
+ to project palette names and, separately, assigns compatible interface or
82
+ neutral families to semantic Brick jobs.
83
+
84
+ The scaffold writes exact candidate hex values beneath the reserved
85
+ `palettes.colors` namespace and generates aliases for complete atomic families
86
+ from the installed Brick contract. Decorative and otherwise extra families
87
+ remain project palettes without being forced into Brick meaning. The result is
88
+ an ordinary editable `flowstack.theme.v1` definition; compilation remains the
89
+ authority for exact Brick compatibility and contrast.
90
+
91
+ ## Generated artifacts
92
+
93
+ - `theme.css` contains the static `flowstack.theme` layer and activation
94
+ selectors taken from the Brick contract.
95
+ - `theme.tokens.json` contains resolved DTCG-compatible `$value` leaves.
96
+ - `theme.manifest.json` records identity, compatibility, activation,
97
+ extensions, requirements, and artifact names.
98
+ - `theme.report.json` records deterministic compilation counts, every declared
99
+ contrast result at 12 significant digits, and warnings. Validation compares
100
+ the unrounded ratio before this serialization boundary.
101
+
102
+ Fixed-light and fixed-dark definitions emit one complete appearance. Dual
103
+ definitions may select a fixed default or `system`; the latter adds a static
104
+ `prefers-color-scheme` rule. Explicit nearest Brick appearance boundaries
105
+ always receive a complete map.
106
+
107
+ ## Runtime boundary
108
+
109
+ The core package has no runtime dependencies and no React provider. It produces
110
+ deterministic static CSS and machine-readable artifacts at build time.
111
+ Optional future framework integration may coordinate selection and first paint
112
+ without resolving component styles during React rendering.
113
+
114
+ ## Dependency direction
115
+
116
+ - Brick never depends on Theme.
117
+ - Theme does not import Brick component source.
118
+ - Theme builds read a versioned contract exposed by the installed Brick
119
+ package.
120
+ - Colors remains optional build-time tooling after its algorithms qualify.
121
+ - Applications own preference, persistence, fonts, assets, and routes.
@@ -0,0 +1,141 @@
1
+ # Public document: authoring
2
+
3
+ Source: @flowstack-ui/theme@0.1.1
4
+
5
+ # Authoring
6
+
7
+ A theme definition is serializable project data. JSON is the CLI boundary;
8
+ TypeScript may use `defineTheme` for typing as long as the resulting object
9
+ remains JSON-compatible.
10
+
11
+ ## Start with project meaning
12
+
13
+ Define any number of raw palettes, then name the roles your product needs:
14
+
15
+ ```json
16
+ {
17
+ "$schema": "flowstack.theme.v1",
18
+ "metadata": { "id": "acme", "name": "Acme" },
19
+ "compatibility": { "brick": "^0.1.11" },
20
+ "appearances": {
21
+ "supported": ["light", "dark"],
22
+ "default": "system"
23
+ },
24
+ "palettes": {
25
+ "brand": {
26
+ "blue": "#2457c5",
27
+ "orange": "#c44d18",
28
+ "magenta": "#a53c8e"
29
+ }
30
+ },
31
+ "roles": {
32
+ "brandPrimary": "{palettes.brand.blue}",
33
+ "promotion": "{palettes.brand.magenta}"
34
+ }
35
+ }
36
+ ```
37
+
38
+ Extra colors are not forced into Brick's smaller vocabulary. Charts,
39
+ campaigns, syntax, editorial colors, maps, and future Block roles remain in
40
+ `roles` or a namespaced `extensions` object and emit as
41
+ `--flowstack-theme-*` variables.
42
+
43
+ ## Appearance-aware project roles
44
+
45
+ Use `appearanceRoles` when one project meaning must adapt with light and dark
46
+ appearance without becoming a required Brick semantic:
47
+
48
+ ```json
49
+ {
50
+ "appearanceRoles": {
51
+ "light": {
52
+ "blocks": {
53
+ "expressiveSurface": {
54
+ "surface": "#4a2f00",
55
+ "foreground": "#ffffff"
56
+ }
57
+ }
58
+ },
59
+ "dark": {
60
+ "blocks": {
61
+ "expressiveSurface": {
62
+ "surface": "#2f2108",
63
+ "foreground": "#ffffff"
64
+ }
65
+ }
66
+ }
67
+ },
68
+ "relationships": {
69
+ "contrast": [
70
+ {
71
+ "id": "blocks-expressive-surface-content",
72
+ "kind": "text",
73
+ "foreground": "blocks.expressiveSurface.foreground",
74
+ "background": "blocks.expressiveSurface.surface",
75
+ "minimumRatio": 4.5
76
+ }
77
+ ]
78
+ }
79
+ }
80
+ ```
81
+
82
+ The compiler emits stable
83
+ `--flowstack-theme-roles-blocks-expressive-surface-*` variables under the
84
+ active appearance selectors. Every logical role must exist in every supported
85
+ appearance. Declared project contrast relationships must resolve to opaque
86
+ sRGB colors and meet the same unrounded WCAG 2 floors used for Brick pairs.
87
+ Keep media-composition and transparency checks in the consuming product.
88
+
89
+ ## Map Brick semantics
90
+
91
+ The `brick` section changes stable UI meanings. Map by purpose, not merely by
92
+ hue: a promotional orange is not a warning unless it communicates warning.
93
+
94
+ ```json
95
+ {
96
+ "brick": {
97
+ "light": {
98
+ "color": {
99
+ "accent": {
100
+ "border": "#829fe0",
101
+ "on-soft": "#173b86",
102
+ "on-solid": "#ffffff",
103
+ "soft": "#e8efff",
104
+ "soft-hover": "#d9e5ff",
105
+ "soft-pressed": "#c6d7ff",
106
+ "solid": "{roles.brandPrimary}",
107
+ "solid-hover": "#1c489f",
108
+ "solid-pressed": "#173d88",
109
+ "text": "#214b9e"
110
+ }
111
+ }
112
+ }
113
+ }
114
+ }
115
+ ```
116
+
117
+ Brick publishes atomic families. Changing one member requires every member of
118
+ that family for the same appearance; omitting the entire family safely
119
+ inherits Brick's defaults. This prevents a new rest color from accidentally
120
+ keeping unrelated hover, pressed, or foreground values.
121
+
122
+ ## Other sections
123
+
124
+ - `foundations` accepts contract-declared appearance-invariant typography,
125
+ radius, density, and motion paths. Appearance-dependent semantic shadows are
126
+ mapped under `brick.light.shadow` and `brick.dark.shadow`.
127
+ - `components` accepts only Brick's audited inherited component inputs. It is
128
+ not a selector or arbitrary-recipe registry. For example,
129
+ `components.link.decoration` accepts the intent values `"always"` or
130
+ `"interaction"`; the latter emits interaction-only decoration and compiles
131
+ only when the theme's accent link text remains at least `3:1` distinct from
132
+ adjacent primary text. A single Link can still override the theme with
133
+ `variant="underline"` or `variant="plain"`.
134
+ - `requirements` records application work such as font and asset loading.
135
+ - `guidance` records intent and review notes for people and agents.
136
+ - `relationships.contrast` validates explicit foreground/background pairs
137
+ from `appearanceRoles`; it does not expand Brick's semantic vocabulary.
138
+
139
+ Aliases must occupy the complete value, for example
140
+ `"{roles.brandPrimary}"`. Unknown aliases, cycles, unsupported values,
141
+ incomplete families, and unknown Brick paths fail compilation.
@@ -0,0 +1,82 @@
1
+ # Public document: colors-interchange
2
+
3
+ Source: @flowstack-ui/theme@0.1.1
4
+
5
+ # Colors candidate interchange
6
+
7
+ Theme can turn a reviewed Colors candidate into a normal editable Theme. This
8
+ is a file contract between two independent tools, not a package dependency.
9
+
10
+ ## The three inputs
11
+
12
+ 1. A serialized `flowstack.colors-candidate.v1` document whose generator
13
+ result is accepted and whose explicit review is `accepted` or `edited`.
14
+ 2. A `flowstack.colors-theme-scaffold.v1` mapping that contains the base Theme,
15
+ selected project palette names, and optional semantic assignments.
16
+ 3. The exact `theme-contract.json` from the installed Brick package.
17
+
18
+ Example mapping:
19
+
20
+ ```json
21
+ {
22
+ "$schema": "flowstack.colors-theme-scaffold.v1",
23
+ "theme": {
24
+ "$schema": "flowstack.theme.v1",
25
+ "metadata": { "id": "acme", "name": "Acme" },
26
+ "compatibility": { "brick": "^0.1.0" },
27
+ "appearances": {
28
+ "supported": ["light", "dark"],
29
+ "default": "system"
30
+ }
31
+ },
32
+ "palettes": {
33
+ "neutral": "neutral-source",
34
+ "brand": "primary-brand",
35
+ "campaign": "campaign-source"
36
+ },
37
+ "semantics": {
38
+ "neutral": "neutral",
39
+ "accent": "brand",
40
+ "focus": "brand"
41
+ }
42
+ }
43
+ ```
44
+
45
+ `palettes` maps the name wanted in the Theme to a candidate family ID. Every
46
+ selected light/dark value is preserved under
47
+ `palettes.colors.<name>.<appearance>`. This is where extra brand, campaign,
48
+ chart, or editorial colors can live even when Brick has no matching role.
49
+
50
+ `semantics` maps a UI job to one of those selected palette names:
51
+
52
+ - `neutral` requires a neutral family and fills Brick surface, border, and
53
+ text families;
54
+ - `accent`, `danger`, `info`, `success`, and `warning` require interface
55
+ families; and
56
+ - `focus` requires an interface family and maps its focus-ring role.
57
+
58
+ Theme reads the installed Brick contract and expands each selection to the
59
+ complete atomic family. Developers choose the family and job; they do not copy
60
+ Brick's token inventory or configure every hex line manually.
61
+
62
+ ## Output and safety
63
+
64
+ Run:
65
+
66
+ ```bash
67
+ flowstack-theme scaffold-colors ./colors.candidate.json \
68
+ --mapping ./colors.theme-scaffold.json \
69
+ --contract ./node_modules/@flowstack-ui/brick/dist/theme-contract.json \
70
+ --out-dir ./theme
71
+ ```
72
+
73
+ The command writes:
74
+
75
+ - `flowstack.theme.json`, the ordinary editable Theme definition; and
76
+ - `theme.scaffold.report.json`, the source-family, mapping, and count record.
77
+
78
+ The scaffold fails on unreviewed or rejected candidates, rejected selected
79
+ families, incompatible profiles, missing appearances or roles, unknown
80
+ contract families, and naming collisions. It does not declare accessibility
81
+ success. Compile the generated Theme against the same Brick contract; the
82
+ compiler remeasures every Brick-declared contrast pair in every appearance.
@@ -0,0 +1,40 @@
1
+ # Public document: fonts
2
+
3
+ Source: @flowstack-ui/theme@0.1.1
4
+
5
+ # Fonts
6
+
7
+ Theme chooses semantic font-family values but does not download, bundle, or
8
+ preload font files. The application owns that work because frameworks have
9
+ different optimization, licensing, privacy, and first-paint behavior.
10
+
11
+ Record the expected integration in `requirements`:
12
+
13
+ ```json
14
+ {
15
+ "foundations": {
16
+ "font": {
17
+ "family": {
18
+ "body": "var(--font-acme), ui-sans-serif, system-ui, sans-serif",
19
+ "heading": "var(--font-acme-display), ui-sans-serif, system-ui, sans-serif"
20
+ }
21
+ }
22
+ },
23
+ "requirements": {
24
+ "fonts": [
25
+ { "family": "Acme Sans", "variable": "--font-acme", "source": "application" },
26
+ { "family": "Acme Display", "variable": "--font-acme-display", "source": "application" }
27
+ ]
28
+ }
29
+ }
30
+ ```
31
+
32
+ In Next.js, load the files with the project's supported `next/font` workflow
33
+ and place its generated variables on the same document boundary as
34
+ `data-flowstack-theme`. In Vite or another bundler, import licensed font CSS or
35
+ local `@font-face` declarations through the application entrypoint and expose
36
+ the declared variables there.
37
+
38
+ Always provide fallback families. Validate the production build with fonts
39
+ loaded, blocked, and slow; the manifest records requirements but cannot prove
40
+ that the application fulfilled them.
@@ -0,0 +1,45 @@
1
+ # Public document: installation
2
+
3
+ Source: @flowstack-ui/theme@0.1.1
4
+
5
+ # Installation
6
+
7
+ Install Brick as the application UI package and Theme as development-only
8
+ build tooling:
9
+
10
+ ```bash
11
+ npm install @flowstack-ui/brick
12
+ npm install --save-dev @flowstack-ui/theme
13
+ ```
14
+
15
+ Theme `0.1` requires a Brick package whose exported theme contract has
16
+ `contractVersion: 2` or newer. Compile a JSON definition against the installed
17
+ artifact:
18
+
19
+ ```bash
20
+ npx flowstack-theme compile ./theme/app.theme.json \
21
+ --contract ./node_modules/@flowstack-ui/brick/dist/theme-contract.json \
22
+ --out-dir ./src/theme/generated
23
+ ```
24
+
25
+ Import Brick CSS and the generated Theme CSS once at the application root.
26
+ Brick must load first so the `flowstack.theme` cascade layer can override its
27
+ defaults and still precede Brick foundations:
28
+
29
+ ```ts
30
+ import "@flowstack-ui/brick/styles.css";
31
+ import "./theme/generated/theme.css";
32
+ ```
33
+
34
+ Activate the compiled theme on the document or a subtree:
35
+
36
+ ```html
37
+ <html data-flowstack-theme="acme">
38
+ ```
39
+
40
+ Only the generated CSS is needed in the browser. Keep the compiler in
41
+ `devDependencies`; do not import it from client or server rendering code.
42
+
43
+ For deterministic builds, run compilation in a checked build step and either
44
+ commit the generated artifacts or generate them in CI. Do not mix both models
45
+ without a drift check.
@@ -0,0 +1,40 @@
1
+ # Public document: migration
2
+
3
+ Source: @flowstack-ui/theme@0.1.1
4
+
5
+ # Migration
6
+
7
+ ## From handwritten Brick variables
8
+
9
+ 1. Inventory application CSS variables and separate Brick semantic values
10
+ from application colors, fonts, assets, and layout policy.
11
+ 2. Move raw colors into `palettes`; give product meanings to reusable values in
12
+ `roles`.
13
+ 3. Map only actual Brick UI meanings under `brick.light` and `brick.dark`.
14
+ 4. Move supported foundations and audited global component inputs into their
15
+ closed sections.
16
+ 5. Keep charts, syntax, campaigns, and product-specific colors in namespaced
17
+ extensions.
18
+ 6. Compile against the installed Brick contract, compare generated CSS with
19
+ the old application values, then remove the handwritten Brick assignments.
20
+ 7. Build and qualify appearance re-entry, portals, first paint, contrast, and
21
+ representative application compositions.
22
+
23
+ Do not copy Brick's complete token contract into the application. Sparse
24
+ families inherit Brick safely; the generated result is complete.
25
+
26
+ ## Compatibility and diagnostics
27
+
28
+ `compatibility.brick` describes the Brick package versions the theme accepts.
29
+ The compiler separately requires theme contract revision 2 or newer. These
30
+ checks distinguish “wrong Brick release” from a malformed contract.
31
+
32
+ Compilation diagnostics include stable codes for incompatible Brick versions,
33
+ unknown paths, incomplete atomic families, invalid aliases, alias cycles,
34
+ unsupported component inputs, insufficient contrast, and contrast values the
35
+ compiler cannot prove. Treat them as migration instructions rather than
36
+ silencing them with application CSS.
37
+
38
+ Brick contract deprecations, when introduced, include a replacement. Theme
39
+ rejects authored deprecated semantic paths with a migration diagnostic instead
40
+ of emitting an obsolete variable silently.
@@ -0,0 +1,64 @@
1
+ # Public document: testing
2
+
3
+ Source: @flowstack-ui/theme@0.1.1
4
+
5
+ # Testing
6
+
7
+ This repository implements focused, repository, and release verification.
8
+
9
+ ```bash
10
+ npm run check:focused -- definition
11
+ npm run check:focused -- validation
12
+ npm run check:focused -- compiler
13
+ npm run check:focused -- interchange
14
+ npm run check:focused -- cli
15
+ npm run check:repository
16
+ npm run check:release
17
+ ```
18
+
19
+ ## Focused owners
20
+
21
+ - `definition` builds the package and compiles public type fixtures.
22
+ - `validation` builds the package and runs structural validation tests.
23
+ - `compiler` covers aliases, defaults, atomic families, fixed and dual
24
+ appearances, component inputs, project roles, artifact writes, deterministic
25
+ output, declared semantic contrast pairs, categorical component inputs,
26
+ conditional contrast activation, appearance-aware project roles, project
27
+ contrast relationships, and failure diagnostics.
28
+ - `interchange` covers reviewed Colors candidate ingestion, project palette
29
+ preservation, semantic-profile compatibility, complete Brick-family
30
+ expansion, ordinary Theme compilation, and fail-closed diagnostics.
31
+ - `cli` builds the package and runs CLI process tests.
32
+ - `all` runs every focused package test.
33
+
34
+ ## Repository gate
35
+
36
+ The repository gate verifies routing and workflows, rejects runtime
37
+ dependencies and private imports, typechecks source, runs unit and type tests,
38
+ builds the package, inspects the publishable archive, installs that exact
39
+ archive into a temporary clean consumer, executes public imports, and checks
40
+ that no automated-test port is registered or occupied. Archive qualification
41
+ also traverses the complete Agent Knowledge manifest and coverage report,
42
+ imports every public runtime value from its classified root or schema subpath,
43
+ compiles against the exact installed Brick contract, exercises the serialized
44
+ Colors handoff, runs CLI help, and bundles Brick with only the generated Theme
45
+ CSS to prove the Theme compiler stays outside browser delivery.
46
+
47
+ Before an exact Brick candidate is published, coordinated local qualification
48
+ passes `FLOWSTACK_BRICK_ARCHIVE` and `FLOWSTACK_ATOM_ARCHIVE` to the same gate.
49
+ The verifier reads both archive manifests, requires the Brick version to equal
50
+ Theme's exact devDependency, requires Atom to equal Brick's exact dependency,
51
+ and installs those archives into the isolated consumer. These variables are
52
+ archive inputs only; no machine path is recorded in package source or output.
53
+
54
+ ## Release boundary
55
+
56
+ The release gate equals the repository gate because the compiler has no browser
57
+ or server surface. Browser qualification of Brick appearance boundaries belongs
58
+ to the cross-repository Theme qualification batch and does not weaken this
59
+ package's exact-archive consumer.
60
+
61
+ Human review remains responsible for deciding whether public schema meaning is
62
+ appropriately stable. Automated structural success cannot approve product
63
+ semantics. Compiler contrast results cover declared opaque color pairs; browser
64
+ qualification remains responsible for rendered states and composition.