@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.
- package/.codex-plugin/plugin.json +37 -0
- package/CHANGELOG.md +21 -0
- package/LICENSE +21 -0
- package/README.md +125 -0
- package/docs/architecture.md +77 -0
- package/docs/releasing.md +26 -0
- package/docs/testing.md +32 -0
- package/package.json +63 -0
- package/public/index.json +2073 -0
- package/public/llms.txt +19 -0
- package/public/packages/atom/0.24.0/components/accordion.txt +131 -0
- package/public/packages/atom/0.24.0/components/alert-dialog.txt +112 -0
- package/public/packages/atom/0.24.0/components/app-bar.txt +96 -0
- package/public/packages/atom/0.24.0/components/aspect-ratio.txt +111 -0
- package/public/packages/atom/0.24.0/components/avatar.txt +119 -0
- package/public/packages/atom/0.24.0/components/badge.txt +123 -0
- package/public/packages/atom/0.24.0/components/bottom-navigation.txt +96 -0
- package/public/packages/atom/0.24.0/components/breadcrumb.txt +96 -0
- package/public/packages/atom/0.24.0/components/button.txt +98 -0
- package/public/packages/atom/0.24.0/components/carousel.txt +128 -0
- package/public/packages/atom/0.24.0/components/checkbox-group.txt +118 -0
- package/public/packages/atom/0.24.0/components/checkbox.txt +100 -0
- package/public/packages/atom/0.24.0/components/clipboard.txt +112 -0
- package/public/packages/atom/0.24.0/components/collapsible.txt +112 -0
- package/public/packages/atom/0.24.0/components/color-picker.txt +117 -0
- package/public/packages/atom/0.24.0/components/combobox.txt +126 -0
- package/public/packages/atom/0.24.0/components/context-menu.txt +114 -0
- package/public/packages/atom/0.24.0/components/data-grid.txt +136 -0
- package/public/packages/atom/0.24.0/components/dialog.txt +116 -0
- package/public/packages/atom/0.24.0/components/direction.txt +132 -0
- package/public/packages/atom/0.24.0/components/divider.txt +94 -0
- package/public/packages/atom/0.24.0/components/drag-drop.txt +141 -0
- package/public/packages/atom/0.24.0/components/drawer.txt +96 -0
- package/public/packages/atom/0.24.0/components/dropdown-menu.txt +112 -0
- package/public/packages/atom/0.24.0/components/feed.txt +132 -0
- package/public/packages/atom/0.24.0/components/field.txt +108 -0
- package/public/packages/atom/0.24.0/components/fieldset.txt +96 -0
- package/public/packages/atom/0.24.0/components/file-upload.txt +120 -0
- package/public/packages/atom/0.24.0/components/form.txt +98 -0
- package/public/packages/atom/0.24.0/components/hover-card.txt +114 -0
- package/public/packages/atom/0.24.0/components/image.txt +94 -0
- package/public/packages/atom/0.24.0/components/input.txt +96 -0
- package/public/packages/atom/0.24.0/components/label.txt +121 -0
- package/public/packages/atom/0.24.0/components/link.txt +100 -0
- package/public/packages/atom/0.24.0/components/list.txt +131 -0
- package/public/packages/atom/0.24.0/components/listbox.txt +120 -0
- package/public/packages/atom/0.24.0/components/menu.txt +126 -0
- package/public/packages/atom/0.24.0/components/menubar.txt +120 -0
- package/public/packages/atom/0.24.0/components/modal.txt +118 -0
- package/public/packages/atom/0.24.0/components/multi-select.txt +120 -0
- package/public/packages/atom/0.24.0/components/nav-list.txt +104 -0
- package/public/packages/atom/0.24.0/components/navigation-menu.txt +104 -0
- package/public/packages/atom/0.24.0/components/number-input.txt +124 -0
- package/public/packages/atom/0.24.0/components/otp-field.txt +122 -0
- package/public/packages/atom/0.24.0/components/pagination.txt +111 -0
- package/public/packages/atom/0.24.0/components/password-toggle-field.txt +116 -0
- package/public/packages/atom/0.24.0/components/popover.txt +122 -0
- package/public/packages/atom/0.24.0/components/pressable.txt +94 -0
- package/public/packages/atom/0.24.0/components/progress.txt +130 -0
- package/public/packages/atom/0.24.0/components/radio-group.txt +118 -0
- package/public/packages/atom/0.24.0/components/rating.txt +122 -0
- package/public/packages/atom/0.24.0/components/reorder.txt +141 -0
- package/public/packages/atom/0.24.0/components/scroll-area.txt +96 -0
- package/public/packages/atom/0.24.0/components/select.txt +126 -0
- package/public/packages/atom/0.24.0/components/sidebar.txt +96 -0
- package/public/packages/atom/0.24.0/components/skip-link.txt +96 -0
- package/public/packages/atom/0.24.0/components/slider.txt +124 -0
- package/public/packages/atom/0.24.0/components/swipeable-item.txt +118 -0
- package/public/packages/atom/0.24.0/components/switch.txt +116 -0
- package/public/packages/atom/0.24.0/components/table.txt +128 -0
- package/public/packages/atom/0.24.0/components/tabs.txt +96 -0
- package/public/packages/atom/0.24.0/components/textarea.txt +96 -0
- package/public/packages/atom/0.24.0/components/toast.txt +124 -0
- package/public/packages/atom/0.24.0/components/toggle-group.txt +118 -0
- package/public/packages/atom/0.24.0/components/toggle.txt +110 -0
- package/public/packages/atom/0.24.0/components/toolbar.txt +98 -0
- package/public/packages/atom/0.24.0/components/tooltip.txt +112 -0
- package/public/packages/atom/0.24.0/components/tree-grid.txt +138 -0
- package/public/packages/atom/0.24.0/components/tree.txt +138 -0
- package/public/packages/atom/0.24.0/components/visually-hidden.txt +119 -0
- package/public/packages/atom/0.24.0/docs/guides/agent-knowledge.txt +55 -0
- package/public/packages/atom/0.24.0/docs/guides/getting-started.txt +65 -0
- package/public/packages/atom/0.24.0/docs/guides/imports.txt +26 -0
- package/public/packages/atom/0.24.0/docs/guides/public-api.txt +100 -0
- package/public/packages/atom/0.24.0/guides/behavior-composition.txt +277 -0
- package/public/packages/atom/0.24.0/guides/layer-selection.txt +807 -0
- package/public/packages/atom/0.24.0/index.txt +89 -0
- package/public/packages/brick/0.1.11/components/accordion.txt +158 -0
- package/public/packages/brick/0.1.11/components/alert-dialog.txt +175 -0
- package/public/packages/brick/0.1.11/components/app-bar.txt +134 -0
- package/public/packages/brick/0.1.11/components/appearance.txt +143 -0
- package/public/packages/brick/0.1.11/components/aspect-ratio.txt +136 -0
- package/public/packages/brick/0.1.11/components/avatar.txt +152 -0
- package/public/packages/brick/0.1.11/components/badge.txt +139 -0
- package/public/packages/brick/0.1.11/components/bleed.txt +104 -0
- package/public/packages/brick/0.1.11/components/bottom-navigation.txt +106 -0
- package/public/packages/brick/0.1.11/components/breadcrumb.txt +96 -0
- package/public/packages/brick/0.1.11/components/button.txt +103 -0
- package/public/packages/brick/0.1.11/components/card.txt +132 -0
- package/public/packages/brick/0.1.11/components/carousel.txt +206 -0
- package/public/packages/brick/0.1.11/components/checkbox-group.txt +175 -0
- package/public/packages/brick/0.1.11/components/checkbox.txt +103 -0
- package/public/packages/brick/0.1.11/components/chip.txt +128 -0
- package/public/packages/brick/0.1.11/components/code-block.txt +134 -0
- package/public/packages/brick/0.1.11/components/code.txt +120 -0
- package/public/packages/brick/0.1.11/components/collapsible.txt +179 -0
- package/public/packages/brick/0.1.11/components/color-picker.txt +135 -0
- package/public/packages/brick/0.1.11/components/color-swatch.txt +98 -0
- package/public/packages/brick/0.1.11/components/combobox.txt +157 -0
- package/public/packages/brick/0.1.11/components/container.txt +112 -0
- package/public/packages/brick/0.1.11/components/context-menu.txt +174 -0
- package/public/packages/brick/0.1.11/components/data-grid.txt +199 -0
- package/public/packages/brick/0.1.11/components/data-list.txt +115 -0
- package/public/packages/brick/0.1.11/components/dialog.txt +176 -0
- package/public/packages/brick/0.1.11/components/divider.txt +104 -0
- package/public/packages/brick/0.1.11/components/drawer.txt +146 -0
- package/public/packages/brick/0.1.11/components/dropdown-menu.txt +179 -0
- package/public/packages/brick/0.1.11/components/feed.txt +143 -0
- package/public/packages/brick/0.1.11/components/field.txt +115 -0
- package/public/packages/brick/0.1.11/components/fieldset.txt +103 -0
- package/public/packages/brick/0.1.11/components/file-upload.txt +154 -0
- package/public/packages/brick/0.1.11/components/form.txt +108 -0
- package/public/packages/brick/0.1.11/components/frame.txt +132 -0
- package/public/packages/brick/0.1.11/components/grid.txt +141 -0
- package/public/packages/brick/0.1.11/components/group.txt +136 -0
- package/public/packages/brick/0.1.11/components/hide.txt +121 -0
- package/public/packages/brick/0.1.11/components/hover-card.txt +156 -0
- package/public/packages/brick/0.1.11/components/icon-button.txt +119 -0
- package/public/packages/brick/0.1.11/components/icon.txt +160 -0
- package/public/packages/brick/0.1.11/components/image.txt +163 -0
- package/public/packages/brick/0.1.11/components/input.txt +101 -0
- package/public/packages/brick/0.1.11/components/link-box.txt +161 -0
- package/public/packages/brick/0.1.11/components/link.txt +133 -0
- package/public/packages/brick/0.1.11/components/list.txt +139 -0
- package/public/packages/brick/0.1.11/components/menubar.txt +174 -0
- package/public/packages/brick/0.1.11/components/multi-select.txt +153 -0
- package/public/packages/brick/0.1.11/components/nav-list.txt +130 -0
- package/public/packages/brick/0.1.11/components/navigation-menu.txt +150 -0
- package/public/packages/brick/0.1.11/components/notification-badge.txt +148 -0
- package/public/packages/brick/0.1.11/components/number-input.txt +150 -0
- package/public/packages/brick/0.1.11/components/otp-field.txt +146 -0
- package/public/packages/brick/0.1.11/components/pagination.txt +124 -0
- package/public/packages/brick/0.1.11/components/password-toggle-field.txt +146 -0
- package/public/packages/brick/0.1.11/components/popover.txt +181 -0
- package/public/packages/brick/0.1.11/components/progress-circle.txt +142 -0
- package/public/packages/brick/0.1.11/components/progress.txt +150 -0
- package/public/packages/brick/0.1.11/components/radio-group.txt +152 -0
- package/public/packages/brick/0.1.11/components/rating.txt +151 -0
- package/public/packages/brick/0.1.11/components/reorderable-list.txt +130 -0
- package/public/packages/brick/0.1.11/components/scroll-area.txt +110 -0
- package/public/packages/brick/0.1.11/components/section.txt +118 -0
- package/public/packages/brick/0.1.11/components/segment-group.txt +116 -0
- package/public/packages/brick/0.1.11/components/select.txt +157 -0
- package/public/packages/brick/0.1.11/components/show.txt +121 -0
- package/public/packages/brick/0.1.11/components/sidebar.txt +126 -0
- package/public/packages/brick/0.1.11/components/skeleton.txt +127 -0
- package/public/packages/brick/0.1.11/components/skip-link.txt +102 -0
- package/public/packages/brick/0.1.11/components/slider.txt +147 -0
- package/public/packages/brick/0.1.11/components/stack.txt +155 -0
- package/public/packages/brick/0.1.11/components/status.txt +110 -0
- package/public/packages/brick/0.1.11/components/surface.txt +194 -0
- package/public/packages/brick/0.1.11/components/swipeable-item.txt +154 -0
- package/public/packages/brick/0.1.11/components/switch.txt +152 -0
- package/public/packages/brick/0.1.11/components/table.txt +183 -0
- package/public/packages/brick/0.1.11/components/tabs.txt +136 -0
- package/public/packages/brick/0.1.11/components/text.txt +148 -0
- package/public/packages/brick/0.1.11/components/textarea.txt +101 -0
- package/public/packages/brick/0.1.11/components/toast.txt +150 -0
- package/public/packages/brick/0.1.11/components/toggle-group.txt +149 -0
- package/public/packages/brick/0.1.11/components/toggle.txt +140 -0
- package/public/packages/brick/0.1.11/components/toolbar.txt +118 -0
- package/public/packages/brick/0.1.11/components/tooltip.txt +156 -0
- package/public/packages/brick/0.1.11/components/tree-grid.txt +160 -0
- package/public/packages/brick/0.1.11/components/tree.txt +156 -0
- package/public/packages/brick/0.1.11/components/visually-hidden.txt +123 -0
- package/public/packages/brick/0.1.11/components/z-stack.txt +143 -0
- package/public/packages/brick/0.1.11/docs/guides/agent-knowledge.txt +67 -0
- package/public/packages/brick/0.1.11/docs/guides/appearance-and-tokens.txt +179 -0
- package/public/packages/brick/0.1.11/docs/guides/browser-support.txt +25 -0
- package/public/packages/brick/0.1.11/docs/guides/control-sizing.txt +59 -0
- package/public/packages/brick/0.1.11/docs/guides/installation.txt +79 -0
- package/public/packages/brick/0.1.11/docs/guides/theme-contract.txt +90 -0
- package/public/packages/brick/0.1.11/guides/interface-composition.txt +665 -0
- package/public/packages/brick/0.1.11/guides/layer-selection.txt +1437 -0
- package/public/packages/brick/0.1.11/index.txt +110 -0
- package/public/packages/colors/0.1.1/docs/agent-knowledge.txt +63 -0
- package/public/packages/colors/0.1.1/docs/architecture.txt +74 -0
- package/public/packages/colors/0.1.1/docs/color-foundations.txt +128 -0
- package/public/packages/colors/0.1.1/docs/compatibility.txt +75 -0
- package/public/packages/colors/0.1.1/docs/dependency-qualification.txt +117 -0
- package/public/packages/colors/0.1.1/docs/installation.txt +48 -0
- package/public/packages/colors/0.1.1/docs/palette-generation.txt +151 -0
- package/public/packages/colors/0.1.1/docs/releasing.txt +34 -0
- package/public/packages/colors/0.1.1/docs/testing.txt +51 -0
- package/public/packages/colors/0.1.1/guides/colors-system.txt +282 -0
- package/public/packages/colors/0.1.1/index.txt +29 -0
- package/public/packages/colors/0.1.1/operations/color-conversion.txt +14 -0
- package/public/packages/colors/0.1.1/operations/color-inspection.txt +23 -0
- package/public/packages/colors/0.1.1/operations/color-measurement.txt +18 -0
- package/public/packages/colors/0.1.1/operations/color-provenance.txt +14 -0
- package/public/packages/colors/0.1.1/operations/named-palette-reference.txt +15 -0
- package/public/packages/colors/0.1.1/operations/palette-candidate.txt +37 -0
- package/public/packages/theme/0.1.1/docs/agent-knowledge.txt +44 -0
- package/public/packages/theme/0.1.1/docs/appearances-and-portals.txt +41 -0
- package/public/packages/theme/0.1.1/docs/architecture.txt +121 -0
- package/public/packages/theme/0.1.1/docs/authoring.txt +141 -0
- package/public/packages/theme/0.1.1/docs/colors-interchange.txt +82 -0
- package/public/packages/theme/0.1.1/docs/fonts.txt +40 -0
- package/public/packages/theme/0.1.1/docs/installation.txt +45 -0
- package/public/packages/theme/0.1.1/docs/migration.txt +40 -0
- package/public/packages/theme/0.1.1/docs/testing.txt +64 -0
- package/public/packages/theme/0.1.1/docs/troubleshooting.txt +53 -0
- package/public/packages/theme/0.1.1/guides/theme-system.txt +340 -0
- package/public/packages/theme/0.1.1/index.txt +31 -0
- package/public/packages/theme/0.1.1/operations/brick-contract-compatibility.txt +35 -0
- package/public/packages/theme/0.1.1/operations/colors-interchange.txt +35 -0
- package/public/packages/theme/0.1.1/operations/theme-artifacts.txt +19 -0
- package/public/packages/theme/0.1.1/operations/theme-cli.txt +10 -0
- package/public/packages/theme/0.1.1/operations/theme-compilation.txt +23 -0
- package/public/packages/theme/0.1.1/operations/theme-definition.txt +36 -0
- package/public/packages/theme/0.1.1/operations/theme-validation.txt +19 -0
- package/public/tasks/data.txt +39 -0
- package/public/tasks/forms.txt +65 -0
- package/public/tasks/layout.txt +37 -0
- package/public/tasks/navigation.txt +51 -0
- package/public/tasks/overlays.txt +39 -0
- package/public/tasks/theming.txt +37 -0
- package/skills/flowstack-ui-builder/SKILL.md +35 -0
- package/skills/flowstack-ui-builder/agents/openai.yaml +4 -0
- package/skills/flowstack-ui-builder/scripts/resolve-agent-knowledge.mjs +399 -0
- package/skills/flowstack-ui-compose/SKILL.md +32 -0
- package/skills/flowstack-ui-compose/agents/openai.yaml +4 -0
- package/skills/flowstack-ui-compose/scripts/resolve-agent-knowledge.mjs +399 -0
- package/skills/flowstack-ui-maintainer/SKILL.md +40 -0
- package/skills/flowstack-ui-maintainer/agents/openai.yaml +4 -0
- package/skills/flowstack-ui-maintainer/scripts/resolve-agent-knowledge.mjs +399 -0
- package/skills/flowstack-ui-review/SKILL.md +29 -0
- package/skills/flowstack-ui-review/agents/openai.yaml +4 -0
- 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.
|