marklearst · marklearst · Jan 27, 2026 · Jan 27, 2026 · Copilot · Jan 27, 2026
diff --git a/docmd.config.js b/docmd.config.js
@@ -161,8 +161,8 @@ module.exports = {
               icon: "user",
             },
             {
-              title: "Frontend Developer",
-              path: "governance/roles/frontend-developer",
+              title: "Frontend Engineer",
+              path: "governance/roles/frontend-engineer",
               icon: "code",
             },
           ],
@@ -224,7 +224,7 @@ module.exports = {
       children: [
         { title: "CSS", path: "consumption/css", icon: "file-code" },
         { title: "TypeScript", path: "consumption/typescript", icon: "type" },
-        { title: "Frameworks", path: "consumption/frameworks", icon: "layers" },
+        { title: "UI Libraries", path: "consumption/frameworks", icon: "layers" },
-        { title: "UI Libraries", path: "consumption/frameworks", icon: "layers" },
+        { title: "Frameworks", path: "consumption/frameworks", icon: "layers" },
-        { title: "UI Libraries", path: "consumption/frameworks", icon: "layers" },
+        { title: "Frameworks", path: "consumption/frameworks", icon: "layers" },
       ],
     },
     {

diff --git a/docs/adapters/tailwind.md b/docs/adapters/tailwind.md
@@ -209,7 +209,7 @@ Design Engineer MUST:
 4. Design Engineer generates CSS custom properties from Variable Design Standard (VDS) JSON
 5. Design Engineer tests variables in Tailwind CSS v4 components
 6. Commit Variable Design Standard (VDS) JSON and generated CSS
-7. Frontend Developer consumes Tailwind utilities in components
+7. Frontend Engineer consumes Tailwind utilities in components
 
 ## Example component
 

diff --git a/docs/adoption/getting-started.md b/docs/adoption/getting-started.md
@@ -1,12 +1,14 @@
 ---
-title: Adoption - Getting Started
+title: Adoption: Getting Started
 ---
 
 # Team Adoption Guide
 
-How to adopt Variable Design Standard (VDS) in your team or organization.
+Scope: team adoption steps for Variable Design Standard (VDS).
 
-If you skip adoption steps, you get inconsistent variables, broken validation, and team confusion.
+Failure if ignored: naming rules break and validation fails.
+
+If you skip adoption steps, naming rules break, validation fails, and teams diverge on usage.
 
 ## Prerequisites
 
@@ -28,6 +30,7 @@ Before adopting Variable Design Standard (VDS):
    - Set up `tokens/` directory in version control
    - Create initial Variable Design Standard (VDS) JSON files
    - Set up file organization (base, semantic, component)
+   - Define brand and mode folders (file selection rule)
 
 2. Set up validation
 
@@ -39,6 +42,7 @@ Before adopting Variable Design Standard (VDS):
    - Create team-specific guidelines
    - Document roles and responsibilities
    - Set up review process
+   - Define the contract review gate
 
 **Deliverables**:
 
@@ -113,7 +117,7 @@ Responsibilities:
 - Review variable changes
 - Use variables in components
 
-### Developer
+### Frontend Engineer
 
 Responsibilities:
 
@@ -324,14 +328,14 @@ Adoption is successful when:
 - Developers consume variables easily
 - Review process works
 - No broken references
-- Versioning is consistent
+- Versioning follows semantic versioning rules
 
 ## Common pitfalls
 
 Avoid these mistakes:
 
 1. Skipping validation setup (invalid variables ship)
-2. Not training team (inconsistent usage)
+2. Not training team (base values used in components instead of alias variables)
 3. Skipping review process (breaking changes)
 4. Not documenting workflow (confusion)
 5. Rushing adoption (incomplete setup)

diff --git a/docs/adoption/implementation-checklist.md b/docs/adoption/implementation-checklist.md
@@ -1,5 +1,5 @@
 ---
-title: Adoption - Implementation Checklist
+title: Adoption: Implementation Checklist
 ---
 
 # Implementation Checklist
@@ -41,6 +41,7 @@ During implementation, complete:
 
 - [ ] Create `tokens/` directory structure
 - [ ] Set up base/semantic/component folders
+- [ ] Define brand and mode folders (file selection rule)
 - [ ] Install validation tool
 - [ ] Configure CI validation
 - [ ] Set up pre-commit hooks
@@ -87,6 +88,7 @@ To claim Variable Design Standard (VDS) compliance, verify:
 - [ ] All variables have `$type` and `$value`
 - [ ] Valid DTCG types used (color, dimension, etc.)
 - [ ] Group structure used correctly
+- [ ] No mapped layer in the contract graph
 
 ### Naming compliance
 
@@ -121,9 +123,11 @@ To claim Variable Design Standard (VDS) compliance, verify:
 ### Governance compliance
 
 - [ ] Change control process defined
-- [ ] Roles assigned (Designer, Design Engineer, Frontend Developer)
+- [ ] Roles assigned (Designer, Design Engineer, Frontend Engineer)
 - [ ] Review process documented
 - [ ] Release process documented
+- [ ] File selection rule documented (brand and mode folders)
+- [ ] Contract review gate defined
 
 See [Conformance](reference/conformance) for complete conformance requirements.
 
@@ -179,7 +183,7 @@ Implementation is successful when:
 If implementation fails:
 
 - Validation not set up (invalid variables ship)
-- Team not trained (inconsistent usage)
+- Team not trained (base values used in components instead of alias variables)
 - Review process missing (breaking changes)
 - Documentation missing (confusion)
 - Integration incomplete (variables not used)
@@ -198,4 +202,3 @@ After successful implementation:
 - Tool-specific implementation (see adapter docs)
 - Design system creation (focus on variables)
 - Component library setup (separate concern)
-
diff --git a/docs/faq.md b/docs/faq.md
@@ -18,6 +18,10 @@ Variables are variables. CSS variables, JavaScript variables, Figma variables. E
 
 No. Variable Design Standard (VDS) uses DTCG 2025.10 format. It adds governance (naming rules, validation, versioning) on top of the format.
 
+## Is Variable Design Standard (VDS) a spec or governance?
+
+Both. The spec defines JSON shape, naming, references, and modes. Governance defines review and validation gates. The contract is the JSON in version control.
+
 ## Do I need to change my existing variables?
 
 Not immediately. Variable Design Standard (VDS) provides migration paths from existing formats (Style Dictionary, custom formats, older DTCG). See [Migration Strategy](adoption/migration-strategy).
@@ -32,15 +36,15 @@ Any DTCG-compliant tool works. Variable Design Standard (VDS) is tool-agnostic.
 
 ## Who owns variables?
 
-**Designer** creates variables in Figma. **Design Engineer** owns the Variable Design Standard (VDS) (maintains naming rules, reviews changes). **Frontend Developer** consumes variables in code.
+**Designer** creates variables in Figma. **Design Engineer** owns the Variable Design Standard (VDS) (maintains naming rules, reviews changes). **Frontend Engineer** consumes variables in code.
 
 ## What's the difference between Designer and Design Engineer?
 
 **Designer** creates variables in Figma. **Design Engineer** bridges design and development, owns the contract, understands both Figma and React component libraries.
 
 ## Do I need all three roles?
 
-In smaller teams, one person (Design Engineer) may fill multiple roles. But responsibilities remain distinct: authoring (Designer), contract ownership (Design Engineer), consumption (Frontend Developer).
+In smaller teams, one person (Design Engineer) may fill multiple roles. But responsibilities remain distinct: authoring (Designer), contract ownership (Design Engineer), consumption (Frontend Engineer).
 
 ## How do I handle breaking changes?
 
@@ -79,6 +83,10 @@ Yes. Modes are supported. Mode keys must match within collections (validation en
 
 See [Modes](contract/modes) for details.
 
+## Do I need a mapped layer or mapped collection?
+
+No. Variable Design Standard (VDS) uses three layers only: base, alias, component. Brand selection happens by file selection or alias modes. CSS cascade layers handle consumption. See [Anatomy](contract/anatomy), [Multi-Brand Architecture](patterns/multi-brand-architecture), and [CSS Consumption](consumption/css).
+
 ## What's the difference between base, alias, and component variables?
 
 - **Base variables**: Raw values (color.gray.900)

diff --git a/docs/governance/accessibility.md b/docs/governance/accessibility.md
@@ -1,23 +1,41 @@
 ---
-title: Governance - Accessibility
+title: Governance: Accessibility
 ---
 
-# Variable Governance - Accessibility
+# Variable Governance: Accessibility
 
 Accessibility is a constraint on variables, not an afterthought. Variables should make accessible defaults easier to ship, not easier to bypass.
 
 ## What variables should encode
 
 1. Color and contrast: Semantic color variables should be chosen so common UI combinations can meet contrast requirements.
-2. Focus visibility: Variables for focus rings (color, width, offset) should exist and be used consistently.
+2. Focus visibility: Variables for focus rings (color, width, offset) should exist and be used across all interactive states.
 3. Motion: Duration and easing variables should support reduced motion modes.
 4. Typography: Font sizes and line heights should avoid unreadable defaults.
 
-## Review expectations
+## Workflow
 
 When a variable changes:
 
 1. Identify impacted UI states (default, hover, active, disabled, focus).
 2. Verify contrast for intended pairings (text on surface, icon on surface, borders).
 3. Confirm focus variables remain visible across themes/modes.
 4. If the change affects motion variables, confirm reduced motion behavior.
+
+## Review checklist
+
+- [ ] Contrast pairs meet the intended target
+- [ ] Focus rings remain visible across modes
+- [ ] Motion variables support reduced motion
+- [ ] Typography variables avoid unreadable defaults
+
+## Ownership
+
+- Design Engineer: owns accessibility rules for variables
+- Frontend Engineer: validates UI consumption
+
+## Links
+
+- [Types](/contract/types)
+- [Modes](/contract/modes)
+- [CSS Consumption](/consumption/css)
diff --git a/docs/governance/change-control.md b/docs/governance/change-control.md
@@ -1,16 +1,16 @@
 ---
-title: Governance - Change Control
+title: Governance: Change Control
 ---
 
-# Governance - Design and Development Workflow
+# Governance: Design and Development Workflow
 
 Use this workflow so a variable change doesn't silently break components.
 
 ## Roles
 
 - **Designer**: Proposes intent and usage (states, pairings, constraints). Creates variables in Figma.
 - **Design Engineer**: Reviews changes, validates contract compliance, maintains naming rules. Bridges design and development.
-- **Frontend Developer**: Validates consumption feasibility, implements variables in code, owns compatibility.
+- **Frontend Engineer**: Validates consumption feasibility, implements variables in code, owns compatibility.
 
 ## Workflow overview
 
@@ -52,7 +52,7 @@ Before creating or changing tokens:
 All variable changes should be reviewed by at least:
 
 - Design Engineer (contract owner, reviews naming, structure, references)
-- Frontend Developer (validates consumption feasibility)
+- Frontend Engineer (validates consumption feasibility)
 
 Reviews should verify:
 
@@ -75,3 +75,9 @@ Reviews should verify:
   - what changed
   - who needs to update
   - migration steps when applicable
+
+## Links
+
+- [Versioning](versioning)
+- [Validation](validation)
+- [Conformance](../reference/conformance)
diff --git a/docs/governance/getting-started.md b/docs/governance/getting-started.md
@@ -1,8 +1,8 @@
 ---
-title: Governance - Getting Started
+title: Governance: Getting Started
 ---
 
-# Governance - Getting Started
+# Governance: Getting Started
 
 Use this checklist when you're adding or changing a variable.
 
@@ -32,7 +32,7 @@ Create a new variable only when:
 - multiple components need the same decision
 - you can name it in a way you won't want to rename later
 
-## How to propose a variable change
+## Workflow
 
 Before you open a change:
 
@@ -42,15 +42,26 @@ Before you open a change:
 4. Add a description if the intent is not obvious.
 5. Decide whether the change is breaking.
 
-## Review requirements
+## Review checklist
 
 Reviews need:
 
 - Design Engineer (contract owner, reviews naming, structure, references)
-- Frontend Developer (validates consumption feasibility)
+- Frontend Engineer (validates consumption feasibility)
+
+## Ownership
+
+- Design Engineer: owns the contract and validation rules
+- Frontend Engineer: owns consumption checks
 
 ## Release expectations
 
 - Use semantic versioning.
 - Renames and removals are breaking changes.
 - Publish release notes with migration steps when applicable.
+
+## Links
+
+- [Validation](validation)
+- [Versioning](versioning)
+- [Conformance](../reference/conformance)
diff --git a/docs/governance/index.md b/docs/governance/index.md
@@ -4,7 +4,7 @@ title: Variable Governance Overview
 
 # Variable Governance Overview
 
-Governance is what keeps variable changes boring: reviewed, versioned, and safe to roll out.
+Governance keeps variable changes reviewed, versioned, and safe to roll out.
 
 ## What a governed variable system provides
 
@@ -30,7 +30,22 @@ Governance is what keeps variable changes boring: reviewed, versioned, and safe
 - Breaking changes are versioned and documented.
 - Releases include notes and migration guidance when needed.
 
-## Next docs to read
+## Workflow
+
+1. Design proposes a change with intended usage.
+2. Design Engineer updates JSON and runs validation.
+3. Frontend Engineer validates consumption impact.
+4. PR is reviewed and merged.
+5. Release notes document breaking changes.
+
+## Review checklist
+
+- [ ] Naming follows the contract
+- [ ] References resolve and are acyclic
+- [ ] Mode keys match within a collection
+- [ ] Breaking changes are versioned
+
+## Links
 
 - [Getting Started](getting-started)
 - [Change Control](change-control)
@@ -41,11 +56,11 @@ Governance is what keeps variable changes boring: reviewed, versioned, and safe
 
 ## Roles
 
-- [Designer](roles/designer) - Creates variables in Figma
-- [Design Engineer](roles/design-engineer) - Bridges design and development, owns contract
-- [Frontend Developer](roles/frontend-developer) - Consumes variables in code
+- [Designer](roles/designer): Creates variables in Figma
+- [Design Engineer](roles/design-engineer): Bridges design and development, owns contract
+- [Frontend Engineer](roles/frontend-engineer): Consumes variables in code
 
-## Reference
+## Related
 
 - [Naming](/contract/naming)
 - [Tokens Studio](/adapters/tokens-studio)