Merge pull request #13 from marklearst/pr-scenarios-patterns

Tighten scenarios and patterns cadence

Author: marklearst

docs/patterns/multi-brand-architecture.md

@@ -1,10 +1,12 @@
 ---
-title: Patterns - Multi-Brand Architecture
+title: Patterns: Multi-Brand Architecture
 ---
 
 # Multi-Brand Architecture
 
-Complete example of multi-brand variable architecture using Variable Design Standard (VDS).
+This pattern specifies a multi-brand architecture that keeps one semantic name set across brands.
+
+Failure if ignored: brand values leak across outputs or require a mapped layer to resolve.
 
 ## Architecture overview
 
@@ -24,6 +26,84 @@ tokens/
     typography.json
 ```
 
+## File structure is the API
+
+Semantic names are the API. Consumers request `color.surface.brand`. The build selects the brand folder that defines that name.
+
+This replaces a mapped collection with file selection.
+
+JSON files are the contract input. The folder path is the selector. The semantic names stay the same across brands.
+
+Rules:
+
+- The semantic name set MUST match across brand folders.
+- Build config MUST select exactly one brand folder at a time.
+- Mapped variables MUST NOT exist in the contract graph.
+
+## File selection rule
+
+File selection rule is shorthand for this model.
+
+- The files are the contract input.
+- The folder path and file name are the selector.
+- The build or import list is the switch.
+
+JSON-as-API: the file set is the interface and the selector.
+
+This keeps brand choice out of a mapped layer and out of tool panels.
+
+This is a file selection rule. It is not a hosted service.
+
+Example selector:
+
+```
+tokens/brand-a/color.json
+tokens/brand-b/color.json
+```
+
+Pick one folder. The semantic names stay the same. The values change.
+
+If you can select files, you can switch brands. No map required.
+
+Example build selection:
+
+```json
+{
+  "source": ["tokens/base/**/*.json", "tokens/brand-a/**/*.json"]
+}
+```
+
+Example CSS selection:
+
+```css
+@layer base, brand;
+@import "variables-base.css" layer(base);
+@import "variables-brand-a.css" layer(brand);
+```
+
+## Decision surface
+
+Decisions live in files and build inputs, not in a mapped collection.
+
+- Choose the brand by the source list or by CSS imports.
+- Use alias modes in tools for preview. Do not store brand logic in a variables panel.
+- Use one decision point. Do not add a second map.
+
+Example preview:
+
+```
+Alias collection
+  Mode: brand-a
+  color.surface.brand -> {color.brand.primary}
+  Mode: brand-b
+  color.surface.brand -> {color.brand.primary}
+```
+
+## Governance note
+
+- The file list is the only switch.
+- Changes to brand folders follow the contract review gate.
+
 ### Shared base
 
 All brands share base scales:
@@ -93,10 +173,7 @@ Each brand has specific variables:
 
 ```json
 {
-  "source": [
-    "tokens/base/**/*.json",
-    "tokens/brand-a/**/*.json"
-  ],
+  "source": ["tokens/base/**/*.json", "tokens/brand-a/**/*.json"],
   "platforms": {
     "css": {
       "transformGroup": "css",
@@ -116,10 +193,7 @@ Each brand has specific variables:
 
 ```json
 {
-  "source": [
-    "tokens/base/**/*.json",
-    "tokens/brand-b/**/*.json"
-  ],
+  "source": ["tokens/base/**/*.json", "tokens/brand-b/**/*.json"],
   "platforms": {
     "css": {
       "transformGroup": "css",
@@ -174,21 +248,23 @@ Consume brand-specific variables:
 1. Share base scales across brands
 2. Keep brand-specific variables minimal
 3. Reference base variables in brand variables
-4. Use consistent naming across brands
+4. Use the same semantic name set across brand folders
 5. Document brand differences
 
 ## Failure modes
 
 If multi-brand architecture is wrong:
 
 - Duplication of shared variables
-- Inconsistent branding
+- Brand A values appear in Brand B output
 - Maintenance burden
 - Build complexity
+- Mapped variables appear as a shadow layer
+- Brand selection leaks into token names
+- All brands end up in one output bundle
 
 ## Out of scope
 
 - Brand management tools (use existing tools)
 - Brand switching at runtime (handle in consumption layer)
 - Brand-specific design decisions (focus on structure)
-

docs/patterns/performance.md

@@ -1,10 +1,12 @@
 ---
-title: Patterns - Performance Optimization
+title: Patterns: Performance
 ---
 
-# Performance Optimization
+# Performance
 
-How to reduce build times and file sizes for Variable Design Standard (VDS) with large variable sets.
+This pattern specifies constraints that keep build time and file size within limits.
+
+Failure if ignored: builds slow down and outputs become too large to manage.
 
 ## Performance considerations
 
@@ -32,7 +34,7 @@ Poor organization causes:
 - Merge conflicts
 - Maintenance burden
 
-## Optimization strategies
+## Performance strategies
 
 ### File organization
 
@@ -92,7 +94,7 @@ async function processFilesParallel(files) {
 }
 ```
 
-## Build optimization
+## Build performance
 
 ### Caching
 
@@ -144,6 +146,5 @@ If performance rules are not followed:
 ## Out of scope
 
 - Runtime performance (handle in consumption layer)
-- Database optimization (use version control)
-- Network optimization (separate concern)
-
+- Database performance (use version control)
+- Network performance (separate concern)

docs/patterns/theme-composition.md

@@ -1,10 +1,12 @@
 ---
-title: Patterns - Theme Composition
+title: Patterns: Theme Composition
 ---
 
 # Theme Composition Patterns
 
-How to compose themes using modes and variable references.
+This pattern specifies theme composition using modes and references.
+
+Failure if ignored: theme variants diverge and outputs do not match expected modes.
 
 ## Theme composition patterns
 
@@ -220,7 +222,7 @@ Theme with multiple modes:
 
 1. Use modes for theme variants
 2. Reference base variables in mode values
-3. Keep mode keys consistent
+3. Keep the same mode key set across the collection
 4. Document mode strategy
 5. Test theme switching
 
@@ -231,11 +233,10 @@ If theme composition is wrong:
 - Theme switching breaks
 - Mode-specific outputs fail
 - Reference resolution fails
-- Inconsistent theming
+- Mode keys differ across variables
 
 ## Out of scope
 
 - Runtime theme switching (handle in consumption layer)
 - Theme management UI (use existing tools)
 - Theme persistence (handle in application layer)
-

docs/scenarios/component-integration.md

@@ -1,12 +1,12 @@
 ---
-title: Scenarios - Component Integration
+title: Scenarios: Component Integration
 ---
 
 # Component Library Integration
 
-How to integrate Variable Design Standard (VDS) with component libraries.
+This scenario specifies how component libraries consume variables.
 
-If components don't use variables correctly, you get hardcoded values, inconsistent styling, and maintenance burden.
+Failure if ignored: components bypass semantic aliases and hardcode values.
 
 ## Component variable patterns
 

docs/scenarios/large-sets.md

@@ -1,12 +1,12 @@
 ---
-title: Scenarios - Large Variable Sets
+title: Scenarios: Large Variable Sets
 ---
 
 # Large Variable Sets
 
-How to handle large variable sets (100+ variables) with performance considerations.
+This scenario specifies constraints for large variable sets (100+ variables).
 
-If large sets are not organized correctly, you get slow builds, memory issues, and maintenance burden.
+Failure if ignored: build time and memory use grow until validation and output generation fail.
 
 ## Performance considerations
 
@@ -133,7 +133,7 @@ Cons:
 - Potential duplication
 - Cross-component references
 
-## Reference resolution optimization
+## Reference resolution performance
 
 ### Cache resolved references
 
@@ -175,7 +175,7 @@ async function resolveReferencesParallel(variables) {
 }
 ```
 
-## Build time optimization
+## Build time performance
 
 ### Incremental builds
 
@@ -276,7 +276,7 @@ tokens/
 
 1. Organize by category or component
 2. Keep files under 1000 variables
-3. Use consistent naming
+3. Use the same naming rules across files
 4. Cache resolved references
 5. Reduce build time (parallelize, cache)
 

docs/scenarios/multi-brand.md

@@ -1,12 +1,12 @@
 ---
-title: Scenarios - Multi-Brand
+title: Scenarios: Multi-Brand
 ---
 
 # Multi-Brand Architecture
 
-How to structure variables for multiple brands using Variable Design Standard (VDS).
+This scenario specifies a folder-based multi-brand structure where semantic names stay identical across brands.
 
-If brands share variables incorrectly, you get duplication, maintenance burden, and inconsistent branding.
+Failure if ignored: brand values leak across outputs and maintenance cost grows.
 
 ## Architecture patterns
 
@@ -285,15 +285,15 @@ Brands extend base groups:
 1. Share base scales (spacing, typography)
 2. Keep brand-specific variables minimal
 3. Reference base variables in brand variables
-4. Use consistent naming across brands
+4. Use the same semantic names across brand folders
 5. Document brand differences
 
 ## Failure modes
 
 If multi-brand structure is wrong:
 
 - Duplication of shared variables
-- Inconsistent branding
+- Brand A values appear in Brand B output
 - Maintenance burden
 - Build complexity
 

docs/scenarios/multi-theme.md

@@ -1,12 +1,12 @@
 ---
-title: Scenarios - Multi-Theme
+title: Scenarios: Multi-Theme
 ---
 
 # Multi-Theme Patterns
 
-How to structure variables for multiple themes (light/dark, mobile/desktop) using modes.
+This scenario specifies theme variants using mode keys (light/dark, mobile/desktop).
 
-If themes are inconsistent, theme switching breaks and mode-specific outputs fail.
+Failure if ignored: mode key sets diverge and theme switching fails.
 
 ## Theme composition patterns
 
@@ -145,7 +145,7 @@ Example:
 }
 ```
 
-The `$extensions.modes` documents expected modes but does not enforce them. Validation should check mode consistency.
+The `$extensions.modes` documents expected modes but does not enforce them. Validation should check mode key sets.
 
 ## Theme switching implementation
 
@@ -278,14 +278,14 @@ Avoid mode explosion. Prefer separate mode dimensions when possible.
 ## Implementation rules
 
 1. Keep modes limited (`light`, `dark`)
-2. Use consistent mode keys across variables
+2. Use the same mode keys on every variable in a collection
 3. Reference base variables in mode values
 4. Document mode strategy
-5. Validate mode consistency
+5. Validate that each variable exposes the same mode set
 
 ## Failure modes
 
-If themes are inconsistent:
+If mode keys differ across variables in the same collection:
 
 - Theme switching breaks
 - Mode-specific outputs fail
@@ -295,5 +295,5 @@ If themes are inconsistent:
 ## Out of scope
 
 - Runtime theme switching (handle in consumption layer)
-- Theme transformation (handle in adapters)
+- Theme conversion (handle in adapters)
 - Theme management UI (use existing tools)