Merge pull request #8 from marklearst/docs/adoption-usage

docs(adoption): expand adoption and usage guidance

Author: marklearst

docs/adoption/getting-started.md

@@ -4,13 +4,13 @@ title: Adoption - Getting Started
 
 # Team Adoption Guide
 
-How to adopt Variable Contract in your team or organization.
+How to adopt Variable Design Standard (VDS) in your team or organization.
 
 If you skip adoption steps, you get inconsistent variables, broken validation, and team confusion.
 
 ## Prerequisites
 
-Before adopting Variable Contract:
+Before adopting Variable Design Standard (VDS):
 
 - Designers use Figma (or similar design tool)
 - Developers use version control (Git)
@@ -26,7 +26,7 @@ Before adopting Variable Contract:
 1. Create variable repository structure
 
    - Set up `tokens/` directory in version control
-   - Create initial Variable Contract JSON files
+   - Create initial Variable Design Standard (VDS) JSON files
    - Set up file organization (base, semantic, component)
 
 2. Set up validation
@@ -51,14 +51,14 @@ Before adopting Variable Contract:
 **Goal**: Create first variable set
 
 1. Export existing variables from Figma
-2. Run adapter to normalize to Variable Contract format
+2. Run adapter to normalize to Variable Design Standard (VDS) format
 3. Validate normalized JSON
 4. Commit to version control
 5. Generate initial outputs (CSS, TypeScript)
 
 **Deliverables**:
 
-- First Variable Contract JSON files
+- First Variable Design Standard (VDS) JSON files
 - Generated CSS/TypeScript outputs
 - Validation passing
 
@@ -81,7 +81,7 @@ Before adopting Variable Contract:
 
 **Goal**: Establish ongoing workflow
 
-1. Train designers on Variable Contract naming
+1. Train designers on Variable Design Standard (VDS) naming
 2. Train developers on variable consumption
 3. Set up review process
 4. Document change workflow
@@ -98,7 +98,7 @@ Before adopting Variable Contract:
 
 Responsibilities:
 
-- Maintain Variable Contract JSON
+- Maintain Variable Design Standard (VDS) JSON
 - Review variable changes
 - Set up validation and CI
 - Manage versioning and releases
@@ -126,7 +126,9 @@ Responsibilities:
 
 ### Step 1: Repository setup
 
-Create repository structure:
+Create repository structure following the canonical file layout:
+
+#### Basic structure
 
 ```
 tokens/
@@ -142,6 +144,93 @@ tokens/
     input.json
 ```
 
+#### Grouping strategy
+
+- **base/**: Raw scales and palettes (base variables)
+- **semantic/**: Intent-based aliases (alias variables)
+- **component/**: Component-specific overrides (component variables)
+
+#### Multi-brand structure
+
+For multi-brand systems:
+
+```
+tokens/
+  base/
+    color.json
+    spacing.json
+    typography.json
+  brands/
+    brand-a/
+      color.json        # Extends base/color.json
+      spacing.json
+    brand-b/
+      color.json        # Extends base/color.json
+      spacing.json
+  semantic/
+    color.json          # References brand-specific variables
+    spacing.json
+  component/
+    button.json
+    input.json
+```
+
+#### Multi-theme structure
+
+For systems with multiple themes:
+
+```
+tokens/
+  base/
+    color.json
+    spacing.json
+  themes/
+    light/
+      color.json        # Light theme variables
+    dark/
+      color.json        # Dark theme variables
+  semantic/
+    color.json          # Uses modes to reference theme variables
+    spacing.json
+  component/
+    button.json
+```
+
+#### Combined multi-brand and multi-theme
+
+For complex systems:
+
+```
+tokens/
+  base/
+    color.json
+    spacing.json
+  brands/
+    brand-a/
+      themes/
+        light/
+          color.json
+        dark/
+          color.json
+    brand-b/
+      themes/
+        light/
+          color.json
+        dark/
+          color.json
+  semantic/
+    color.json
+  component/
+    button.json
+```
+
+#### File naming conventions
+
+- Use lowercase with hyphens for file names: `color.json`, `spacing-scale.json`
+- Group files by category (color, spacing, typography)
+- Keep related variables together in the same file
+- Split large files when they exceed ~500 variables for maintainability
+
 ### Step 2: Install tooling
 
 Install validation and build tools:

docs/adoption/implementation-checklist.md

@@ -4,7 +4,7 @@ title: Adoption - Implementation Checklist
 
 # Implementation Checklist
 
-Pre-implementation, implementation, and post-implementation checklists for Variable Contract adoption.
+Pre-implementation, implementation, and post-implementation checklists for Variable Design Standard (VDS) adoption.
 
 ## Pre-implementation checklist
 
@@ -15,7 +15,7 @@ Before starting implementation, verify:
 - [ ] Design Engineer role assigned
 - [ ] Designers available for training
 - [ ] Developers available for integration
-- [ ] Team understands Variable Contract concept
+- [ ] Team understands Variable Design Standard (VDS) concept
 - [ ] Stakeholders approve adoption
 
 ### Technical readiness
@@ -44,7 +44,7 @@ During implementation, complete:
 - [ ] Install validation tool
 - [ ] Configure CI validation
 - [ ] Set up pre-commit hooks
-- [ ] Create initial Variable Contract JSON structure
+- [ ] Create initial Variable Design Standard (VDS) JSON structure
 - [ ] Document team-specific guidelines
 
 ### Phase 2: Initial variables
@@ -53,7 +53,7 @@ During implementation, complete:
 - [ ] Run adapter to normalize export
 - [ ] Validate normalized JSON
 - [ ] Fix any validation errors
-- [ ] Commit Variable Contract JSON to version control
+- [ ] Commit Variable Design Standard (VDS) JSON to version control
 - [ ] Configure build tool (Style Dictionary)
 - [ ] Generate initial outputs (CSS, TypeScript)
 - [ ] Verify outputs are correct
@@ -79,7 +79,7 @@ During implementation, complete:
 
 ## Conformance checklist
 
-To claim Variable Contract compliance, verify:
+To claim Variable Design Standard (VDS) compliance, verify:
 
 ### Format compliance
 
@@ -158,7 +158,7 @@ After implementation, verify:
 ### Documentation
 
 - [ ] Team documentation is complete
-- [ ] Variable Contract JSON is documented
+- [ ] Variable Design Standard (VDS) JSON is documented
 - [ ] Consumption patterns are documented
 - [ ] Workflow is documented
 - [ ] Troubleshooting guide is available

docs/adoption/migration-strategy.md

@@ -4,7 +4,7 @@ title: Adoption - Migration Strategy
 
 # Phased Migration Strategy
 
-How to migrate existing variable systems to Variable Contract using a phased approach.
+How to migrate existing variable systems to Variable Design Standard (VDS) using a phased approach.
 
 If you migrate everything at once, you risk breaking production, losing references, and confusing the team.
 
@@ -53,9 +53,9 @@ Use when:
 
 ### Phase 1: Foundation (Week 1-2)
 
-**Goal**: Set up Variable Contract alongside existing system
+**Goal**: Set up Variable Design Standard (VDS) alongside existing system
 
-1. Set up Variable Contract structure
+1. Set up Variable Design Standard (VDS) structure
    - Create `tokens/` directory
    - Set up validation
    - Configure CI
@@ -71,20 +71,20 @@ Use when:
    - Commit to version control
 
 **Deliverables**:
-- Variable Contract structure set up
+- Variable Design Standard (VDS) structure set up
 - Adapter working
 - All variables converted (not yet consumed)
 
 ### Phase 2: Parallel run (Week 3-6)
 
 **Goal**: Run both systems in parallel
 
-1. Generate outputs from Variable Contract
+1. Generate outputs from Variable Design Standard (VDS)
    - Configure Style Dictionary
    - Generate CSS/TypeScript
    - Verify outputs match existing
 
-2. Update components to use Variable Contract outputs
+2. Update components to use Variable Design Standard (VDS) outputs
    - Start with new components
    - Gradually migrate existing components
    - Test each migration
@@ -95,7 +95,7 @@ Use when:
    - Document learnings
 
 **Deliverables**:
-- Variable Contract outputs generated
+- Variable Design Standard (VDS) outputs generated
 - Some components using new variables
 - Both systems running in parallel
 
@@ -109,9 +109,9 @@ Use when:
    - Document changes
 
 2. Update design workflow
-   - Train designers on Variable Contract
+   - Train designers on Variable Design Standard (VDS)
    - Update Figma workflow
-   - Export to Variable Contract format
+   - Export to Variable Design Standard (VDS) format
 
 3. Deprecate old system
    - Mark old variables as deprecated
@@ -137,14 +137,14 @@ Use when:
    - Remove old build configs
    - Update documentation
 
-3. Finalize Variable Contract
+3. Finalize Variable Design Standard (VDS)
    - Complete migration documentation
    - Train team on new system
    - Celebrate success
 
 **Deliverables**:
 - Old system removed
-- Variable Contract fully adopted
+- Variable Design Standard (VDS) fully adopted
 - Team trained
 
 ## Migration by format
@@ -170,7 +170,7 @@ Use when:
 
 **Phase 1**: Extract variables
 - Extract Material-specific variables
-- Map to Variable Contract structure
+- Map to Variable Design Standard (VDS) structure
 - Normalize naming
 
 **Phase 2**: Create adapters
@@ -181,7 +181,7 @@ Use when:
 **Phase 3**: Migrate consumption
 - Update components
 - Remove Material-specific code
-- Use Variable Contract outputs
+- Use Variable Design Standard (VDS) outputs
 
 ### From custom formats
 
@@ -198,7 +198,7 @@ Use when:
 **Phase 3**: Migrate consumption
 - Update components
 - Remove old system
-- Use Variable Contract
+- Use Variable Design Standard (VDS)
 
 ## Migration checklist
 
@@ -207,13 +207,13 @@ Use when:
 - [ ] Audit existing variables
 - [ ] Document current format
 - [ ] Identify migration approach
-- [ ] Set up Variable Contract structure
+- [ ] Set up Variable Design Standard (VDS) structure
 - [ ] Create adapter (if needed)
 - [ ] Test adapter output
 
 ### During migration
 
-- [ ] Convert variables to Variable Contract
+- [ ] Convert variables to Variable Design Standard (VDS)
 - [ ] Validate converted JSON
 - [ ] Generate outputs
 - [ ] Test outputs match existing

docs/consumption/css.md

@@ -4,13 +4,13 @@ title: Consumption - CSS
 
 # CSS Variable Consumption
 
-How to consume Variable Contract variables in CSS.
+How to consume Variable Design Standard (VDS) variables in CSS.
 
 ## Basic usage
 
 ### CSS custom properties
 
-Use CSS custom properties (variables) generated from Variable Contract:
+Use CSS custom properties (variables) generated from Variable Design Standard (VDS):
 
 ```css
 .button {

docs/consumption/frameworks.md

@@ -4,7 +4,7 @@ title: Consumption - Frameworks
 
 # Framework Integration
 
-How to integrate Variable Contract variables with React, Vue, and other frameworks.
+How to integrate Variable Design Standard (VDS) variables with React, Vue, and other frameworks.
 
 ## React integration
 

docs/consumption/typescript.md

@@ -4,7 +4,7 @@ title: Consumption - TypeScript
 
 # TypeScript Consumption
 
-How to consume Variable Contract variables in TypeScript with type safety.
+How to consume Variable Design Standard (VDS) variables in TypeScript with type safety.
 
 ## Type generation
 
@@ -283,7 +283,7 @@ export function useTheme() {
 
 ## Implementation rules
 
-1. Generate types from Variable Contract
+1. Generate types from Variable Design Standard (VDS)
 2. Use type-safe access
 3. Document type usage
 4. Test type safety