From 6742a038cb869ea937f163ef1b75e03cbfbe8309 Mon Sep 17 00:00:00 2001 From: Mark Learst Date: Tue, 27 Jan 2026 15:39:01 -0500 Subject: [PATCH] Rename Frontend Developer role to Frontend Engineer --- docmd.config.js | 6 +- docs/adapters/tailwind.md | 2 +- docs/adoption/getting-started.md | 16 +- docs/adoption/implementation-checklist.md | 11 +- docs/faq.md | 12 +- docs/governance/accessibility.md | 26 ++- docs/governance/change-control.md | 14 +- docs/governance/getting-started.md | 21 ++- docs/governance/index.md | 27 +++- docs/governance/migration.md | 28 +++- docs/governance/overview.md | 61 ++++++- docs/governance/roles/design-engineer.md | 29 +++- docs/governance/roles/designer.md | 29 ++-- ...tend-developer.md => frontend-engineer.md} | 52 ++++-- docs/governance/validation.md | 32 +++- docs/governance/versioning.md | 25 ++- docs/index.md | 152 ++++++++++-------- docs/reference/conformance.md | 10 +- docs/reference/glossary.md | 13 +- docs/reference/quick-reference.md | 2 +- docs/tooling/build-pipelines.md | 31 +++- docs/tooling/ci-cd.md | 30 +++- docs/tooling/ecosystem.md | 108 ++++++++----- 23 files changed, 525 insertions(+), 212 deletions(-) rename docs/governance/roles/{frontend-developer.md => frontend-engineer.md} (69%) diff --git a/docmd.config.js b/docmd.config.js index 72260d0..7c9244b 100644 --- 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" }, ], }, { diff --git a/docs/adapters/tailwind.md b/docs/adapters/tailwind.md index 589a665..7b9fc1d 100644 --- 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 index 86ed91b..91440e1 100644 --- 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 index 4615b55..3490ffc 100644 --- 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 index 6366d11..c4289cb 100644 --- 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,7 +36,7 @@ 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? @@ -40,7 +44,7 @@ Any DTCG-compliant tool works. Variable Design Standard (VDS) is tool-agnostic. ## 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 index dc2d603..d7de924 100644 --- a/docs/governance/accessibility.md +++ b/docs/governance/accessibility.md @@ -1,19 +1,19 @@ --- -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: @@ -21,3 +21,21 @@ When a variable changes: 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 index 575a3c1..19db0bd 100644 --- a/docs/governance/change-control.md +++ b/docs/governance/change-control.md @@ -1,8 +1,8 @@ --- -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. @@ -10,7 +10,7 @@ Use this workflow so a variable change doesn't silently break components. - **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 index e294f6e..a490020 100644 --- 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 index b72f302..151f0e2 100644 --- 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) diff --git a/docs/governance/migration.md b/docs/governance/migration.md index 6a6a68b..e96d00b 100644 --- a/docs/governance/migration.md +++ b/docs/governance/migration.md @@ -1,14 +1,14 @@ --- -title: Governance - Migration +title: Governance: Migration --- # Migration Guide -How to migrate existing variable formats to Variable Design Standard (VDS) format. +Scope: migration rules for converting existing variable formats to Variable Design Standard (VDS). -If you skip migration steps, you lose reference resolution, break type validation, and create maintenance burden. +Failure if ignored: references fail, type validation breaks, and maintenance cost grows. -## Migration overview +## Workflow Migration converts existing variable formats to Variable Design Standard (VDS) (DTCG 2025.10) format with governance rules applied. @@ -21,6 +21,14 @@ Migration steps: 5. Validate output (run validation checklist) 6. Test consumption (verify generated outputs work) +## Review checklist + +- [ ] Reference syntax converted to curly brace format +- [ ] All variables include `$type` +- [ ] Tool metadata moved to `$extensions` +- [ ] Validation checklist passes +- [ ] Outputs match previous behavior + ## From older DTCG formats If you have variables in DTCG formats before 2025.10: @@ -264,7 +272,7 @@ After migration, verify: - Names follow naming convention - No circular references - Types match values -- Modes are consistent +- Mode keys match within a collection - Validation passes ## Testing migration @@ -302,3 +310,13 @@ If migration is incomplete: - Cross-format conversion libraries - Migration UI tools +## Ownership + +- Design Engineer: plans and reviews migration steps +- Frontend Engineer: validates outputs after migration + +## Links + +- [Adapters](/adapters) +- [Validation](validation) +- [Conformance](../reference/conformance) diff --git a/docs/governance/overview.md b/docs/governance/overview.md index e7ab1d1..e6a9afb 100644 --- a/docs/governance/overview.md +++ b/docs/governance/overview.md @@ -4,18 +4,65 @@ title: Variable Governance # Variable Governance -Governance is how you keep a token change from turning into a cleanup project across components. +Governance keeps a variable change from turning into a cleanup project across components. The rules here treat variable names and references like an API: changes are reviewed, and breaking changes are called out. The contract rules (schema and validation expectations) live in [Variable Design Standard (VDS)](/contract/variable-contract). +## Governance purpose + +Governance keeps variable changes from breaking components. The contract is the JSON in version control. CI validates structure, naming, references, and modes. Contract changes are reviewed before merge. + +## Quality and reliability + +- Variable JSON is the contract input. +- CI blocks invalid JSON, broken references, and mode mismatches. +- Review is required for any change that edits names, references, or modes. + +## Automation and AI + +- Automated checks run on every PR. +- Changes from tools or AI follow the same validation rules. +- Only validated JSON is merged. + +## Policies and standards + +- Policies define what is allowed. +- Standards define required structure and naming. +- Procedures define the PR steps. + +## Workflow + +1. Create a PR that changes JSON in version control. +2. Run validation in CI (structure, naming, references, modes). +3. Review changes for breaking impact and release notes. +4. Merge only after checks pass. + +## Review checklist + +- [ ] Naming and structure follow the contract +- [ ] References resolve and no cycles exist +- [ ] Mode keys match within each collection +- [ ] Breaking changes are documented + +## Risk and compliance + +- Validation and review are the controls. +- The repo history is the audit trail. + +## File selection rule + +Brand and mode selection happens by file list, not by a mapped layer. + ## Principles - Variable names are an API. - Prefer semantic aliases for UI usage. - Keep base scales and palettes unchanged unless you plan a migration. - Treat variable JSON (Design Tokens JSON) as the contract. +- Brand selection is a file selection rule. Do not add a mapped layer in tool panels. +- JSON-as-API means file paths and names are the interface. Review changes like API changes. ## What good looks like @@ -25,9 +72,9 @@ The contract rules (schema and validation expectations) live in [Variable Design ## 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 ## Scope @@ -38,3 +85,9 @@ Covers: - Change control and semantic versioning - Accessibility constraints and checks - Role definitions and responsibilities + +## Links + +- [Change Control](change-control) +- [Validation](validation) +- [Versioning](versioning) diff --git a/docs/governance/roles/design-engineer.md b/docs/governance/roles/design-engineer.md index de1f48b..1a6bdd7 100644 --- a/docs/governance/roles/design-engineer.md +++ b/docs/governance/roles/design-engineer.md @@ -1,8 +1,8 @@ --- -title: Role - Design Engineer +title: Role: Design Engineer --- -# Variable Governance - Design Engineer Role +# Variable Governance: Design Engineer Role True hybrid role. Masters both design and frontend. Owns the Variable Design Standard (VDS). Approves all variable changes. @@ -73,10 +73,23 @@ If a candidate cannot demonstrate these skills, they are not ready for this role - Translate design intent to variables. Map design decisions to variable structure. - Verify consumption feasibility. Test variables in React/Storybook before approving. -- Work between Designer and Frontend Developer. Communicate in both languages. +- Work between Designer and Frontend Engineer. Communicate in both languages. - Build component libraries in both Figma and React. Maintain parity. - Resolve design/development tensions. +## Ownership + +- Owns the Variable Design Standard (VDS) contract +- Owns validation rules and review gates + +## Workflow + +1. Designer submits changes via PR. +2. Run validation checks. +3. Test consumption in code. +4. Approve or request changes. +5. Merge after checks pass. + ### Review gate responsibilities Design Engineer reviews ALL variable changes. No exceptions. @@ -85,7 +98,7 @@ Review checklist: - [ ] Naming convention compliance (dot-separated, lowercase, no platform prefixes) - [ ] Reference validity (all references resolve, no circular references) -- [ ] Mode consistency (mode keys match within collections) +- [ ] Mode key set match within collections - [ ] Type correctness (`$value` matches `$type`) - [ ] Consumption feasibility (tested in React/Storybook) - [ ] Breaking change assessment (is this a rename? removal? type change?) @@ -107,7 +120,7 @@ If review fails, Designer revises and resubmits. ## Interfaces - **Designer**: Creates variables in Figma. Design Engineer reviews ALL changes for contract compliance and tests consumption feasibility. -- **Frontend Developer**: Consumes variables in code. Design Engineer structures variables so consumption requires zero manual work. +- **Frontend Engineer**: Consumes variables in code. Design Engineer structures variables so consumption requires zero manual work. - **Product**: Agrees on change priorities and release timing. ## Failure modes @@ -143,3 +156,9 @@ Design Engineer bridges design and development. This requires demonstrated profi In smaller teams, one person fills this role. In larger teams, multiple Design Engineers may work together, with one serving as the primary contract owner. The Variable Design Standard (VDS) depends on this role being held to a clear standard. The skills are specific and verifiable. + +## Links + +- [Variable Contract](/contract/variable-contract) +- [Change Control](../change-control) +- [Validation](../validation) diff --git a/docs/governance/roles/designer.md b/docs/governance/roles/designer.md index 589716c..719dfca 100644 --- a/docs/governance/roles/designer.md +++ b/docs/governance/roles/designer.md @@ -1,8 +1,8 @@ --- -title: Role - Designer +title: Role: Designer --- -# Variable Governance - Designer Role +# Variable Governance: Designer Role Creates variables in Figma. Does not own the contract. Does not approve changes. @@ -21,6 +21,11 @@ Design Engineer reviews and approves all variable changes before they enter the - Export variables for normalization (see [Figma Workflow](/design/figma-workflow)). - Submit variable changes for review by Design Engineer. +## Ownership + +- Owns variable authoring in design tools +- Owns export quality for adapter input + ## Boundaries Designer MUST NOT: @@ -39,14 +44,14 @@ These boundaries exist because variable changes affect production code. A rename - Variables follow naming convention (dot-separated paths, lowercase). - No duplicate values when a base variable exists. - Semantic variables reference base variables (not raw values). -- Mode values are consistent within collections. +- Mode values use one mode key set within each collection. - Variables are used in Figma components (not hardcoded values). - All variable changes are reviewed by Design Engineer before entering the contract. ## Interfaces - **Design Engineer**: Reviews all variable changes. Validates contract compliance (naming, structure, references). Tests consumption feasibility in React. Approves changes before they enter version control. -- **Frontend Developer**: Consumes variables in code. Designer creates variables. Design Engineer validates. Frontend Developer consumes generated outputs. +- **Frontend Engineer**: Consumes variables in code. Designer creates variables. Design Engineer validates. Frontend Engineer consumes generated outputs. ## Workflow @@ -59,7 +64,7 @@ These boundaries exist because variable changes affect production code. A rename 7. Design Engineer approves and commits to version control. 8. Variables are released. -## Review gate +## Review checklist All variable changes go through Design Engineer review. No exceptions. @@ -67,7 +72,7 @@ Design Engineer checks: - Naming convention compliance - Reference validity -- Mode consistency +- Mode key set match within collections - Consumption feasibility - Breaking change assessment @@ -77,7 +82,7 @@ If Design Engineer rejects, Designer revises and resubmits. - Creating variables with platform names (example: `color.ios.primary`). - Duplicating values instead of referencing base variables. -- Using inconsistent naming (mixing styles within the same collection). +- Mixing naming styles within the same collection. - Hardcoding values in components instead of using variables. - Pushing variables without Design Engineer review. - Making renames without understanding the downstream impact. @@ -89,13 +94,19 @@ If Designer bypasses Design Engineer review: - Broken references ship to production. - Naming convention violations break code generation. - Breaking changes ship without migration notes. -- Frontend Developer consumes invalid variables. +- Frontend Engineer consumes invalid variables. - Component styling breaks. ## Out of scope - Maintaining the Variable Design Standard (VDS) (Design Engineer owns this). -- Writing code or build pipelines (Frontend Developer owns this). +- Writing code or build pipelines (Frontend Engineer owns this). - Defining consumption patterns (Design Engineer owns this). - Approving variable changes (Design Engineer owns this). - Making contract decisions (Design Engineer owns this). + +## Links + +- [Naming](/contract/naming) +- [Change Control](../change-control) +- [Validation](../validation) diff --git a/docs/governance/roles/frontend-developer.md b/docs/governance/roles/frontend-engineer.md similarity index 69% rename from docs/governance/roles/frontend-developer.md rename to docs/governance/roles/frontend-engineer.md index 5b573e8..293910e 100644 --- a/docs/governance/roles/frontend-developer.md +++ b/docs/governance/roles/frontend-engineer.md @@ -1,16 +1,16 @@ --- -title: Role - Frontend Developer +title: Role: Frontend Engineer --- -# Variable Governance - Frontend Developer Role +# Variable Governance: Frontend Engineer Role Consumes variables in code. Maintains build pipelines. Does not create variables. Does not own the contract. ## Scope -Frontend Developers (UI/Engineer) consume variables generated from the Variable Design Standard (VDS). They maintain build pipelines. They do not create variables. They do not own the contract. +Frontend Engineers consume variables generated from the Variable Design Standard (VDS). They maintain build pipelines. They do not create variables. They do not own the contract. -Design Engineer owns the contract. Designer creates variables. Frontend Developer consumes outputs. +Design Engineer owns the contract. Designer creates variables. Frontend Engineer consumes outputs. ## Responsibilities @@ -20,9 +20,14 @@ Design Engineer owns the contract. Designer creates variables. Frontend Develope - Test variable consumption (see [Consumption Tests](/testing/consumption-tests)). - Report consumption issues to Design Engineer. +## Ownership + +- Owns build pipeline configuration +- Owns integration of generated outputs into code + ## Boundaries -Frontend Developer MUST NOT: +Frontend Engineer MUST NOT: - Create variables in Figma (Designer owns this). - Modify the Variable Design Standard (VDS) JSON directly without Design Engineer approval. @@ -30,7 +35,7 @@ Frontend Developer MUST NOT: - Approve variable changes (Design Engineer owns this). - Hand-edit generated outputs (regenerate from Variable Design Standard (VDS) JSON). -These boundaries exist because variable authoring and contract ownership require design fluency. Frontend Developer consumes. Design Engineer validates. Designer creates. +These boundaries exist because variable authoring and contract ownership require design fluency. Frontend Engineer consumes. Design Engineer validates. Designer creates. ## What success looks like @@ -43,8 +48,21 @@ These boundaries exist because variable authoring and contract ownership require ## Interfaces -- **Design Engineer**: Provides Variable Design Standard (VDS) JSON. Maintains contract. Tests variables in React before approval. Frontend Developer reports consumption issues. Design Engineer troubleshoots. -- **Designer**: Creates variables in Figma. Frontend Developer consumes generated outputs. No direct variable creation handoff. +- **Design Engineer**: Provides Variable Design Standard (VDS) JSON. Maintains contract. Tests variables in React before approval. Frontend Engineer reports consumption issues. Design Engineer troubleshoots. +- **Designer**: Creates variables in Figma. Frontend Engineer consumes generated outputs. No direct variable creation handoff. + +## Workflow + +1. Pull the latest generated outputs. +2. Update component usage to semantic variables. +3. Run consumption tests. +4. Report broken references or mode issues. + +## Checklist + +- [ ] Outputs are generated from contract JSON +- [ ] Components use semantic variables +- [ ] Consumption tests pass ## Consumption patterns @@ -81,7 +99,7 @@ function Button() { ## Build pipeline -Frontend Developers maintain pipelines that: +Frontend Engineers maintain pipelines that: 1. Read Variable Design Standard (VDS) JSON from version control. 2. Generate CSS variables, TypeScript types, theme objects. @@ -100,19 +118,19 @@ See [Build Pipelines](/tooling/build-pipelines) for examples. ## Failure modes -If Frontend Developer bypasses Design Engineer: +If Frontend Engineer bypasses Design Engineer: -- Variable issues are fixed in code, not in contract (drift). +- Variable issues are fixed in code while contract JSON stays unchanged. - Workarounds accumulate (technical debt). -- Contract becomes stale (not source of truth). +- Contract JSON no longer matches production usage. -If Frontend Developer hand-edits outputs: +If Frontend Engineer hand-edits outputs: - Next build overwrites changes. - Variables don't match contract. - Debugging becomes impossible. -If Frontend Developer doesn't report consumption issues: +If Frontend Engineer doesn't report consumption issues: - Design Engineer doesn't know about problems. - Variables ship with consumption bugs. @@ -124,3 +142,9 @@ If Frontend Developer doesn't report consumption issues: - Maintaining the Variable Design Standard (VDS) (Design Engineer owns this). - Defining naming conventions (Design Engineer owns this). - Approving variable changes (Design Engineer owns this). + +## Links + +- [CSS Consumption](/consumption/css) +- [Build Pipelines](/tooling/build-pipelines) +- [Change Control](../change-control) diff --git a/docs/governance/validation.md b/docs/governance/validation.md index 1a0f126..81d5896 100644 --- a/docs/governance/validation.md +++ b/docs/governance/validation.md @@ -1,5 +1,5 @@ --- -title: Governance - Validation +title: Governance: Validation --- # Variable Design Standard (VDS) Validation @@ -18,17 +18,23 @@ Validation MUST check: 4. Reference resolution (all references point to existing variables) 5. Circular references (no reference cycles) 6. Type correctness (`$value` matches `$type` format) -7. Mode consistency (mode keys shared within collections) +7. Mode key set checks (mode keys match within collections) 8. Group extension (`$extends` targets exist, no circular group references) +## Workflow + +1. Run schema validation on JSON files. +2. Run VDS checks (naming, references, mode key set). +3. Block merge if any errors are found. + ## Validation tools ### DTCG-compliant validators Use DTCG-compliant validators for format validation: -- [@tokens-studio/sd-transforms](https://github.com/tokens-studio/sd-transforms) - Style Dictionary transforms with DTCG support -- [style-dictionary](https://github.com/style-dictionary/style-dictionary) - Built-in DTCG format validation +- [@tokens-studio/sd-transforms](https://github.com/tokens-studio/sd-transforms): Style Dictionary transforms with DTCG support +- [style-dictionary](https://github.com/style-dictionary/style-dictionary): Built-in DTCG format validation - Custom validators using DTCG JSON Schema ### Custom validation scripts @@ -38,7 +44,7 @@ Create custom scripts to check Variable Design Standard (VDS)-specific rules: - Naming convention enforcement - Reference resolution - Circular reference detection -- Mode consistency checks +- Mode key set checks Example validation script structure: @@ -53,7 +59,7 @@ function validateVariableContract(json) { // Check references resolve // Check for circular references // Check type correctness - // Check mode consistency + // Check mode key sets return errors; } @@ -139,7 +145,7 @@ A Variable Design Standard (VDS) JSON file is valid if: ### Mode validation - Mode keys are strings -- Mode keys are consistent within collections +- Mode keys match within collections - Mode values are valid for the variable type - Mode references resolve correctly @@ -218,4 +224,14 @@ If validation is skipped: - Runtime validation libraries (use DTCG-compliant validators) - Validation UI tools (use existing tools or build custom) -- Performance optimization for large token sets (handle separately) +- Performance work for large token sets (handle separately) + +## Ownership + +- Design Engineer: owns validation rules and CI setup +- Frontend Engineer: validates outputs in consumption + +## Links + +- [Conformance](../reference/conformance) +- [Change Control](change-control) diff --git a/docs/governance/versioning.md b/docs/governance/versioning.md index eddbb66..293d4ff 100644 --- a/docs/governance/versioning.md +++ b/docs/governance/versioning.md @@ -1,12 +1,12 @@ --- -title: Governance - Versioning +title: Governance: Versioning --- # Variable Design Standard (VDS) Versioning Versioning communicates breaking changes and migration requirements. -If versioning is inconsistent, consumers cannot plan upgrades and breaking changes ship without notice. +If versioning rules are not followed, consumers cannot plan upgrades and breaking changes ship without notice. ## Semantic versioning @@ -207,7 +207,7 @@ Action: Bump to v1.1.0. Changing a variable value may or may not be breaking depending on usage. -If the value change is intentional and documented, it may be MINOR: +If the value change is approved in review and documented, it may be MINOR: ```json { @@ -231,7 +231,7 @@ If the value change is intentional and documented, it may be MINOR: } ``` -Action: Bump to v1.1.0 if change is intentional and documented. +Action: Bump to v1.1.0 if change is approved in review and documented. If the value change is accidental or breaks visual output, treat as breaking. @@ -330,9 +330,15 @@ Migration: Use `color.new` instead. 5. Tag release in version control 6. Publish release notes +## Review checklist + +- [ ] Change type is labeled (breaking or non-breaking) +- [ ] Version bump matches the change type +- [ ] Release notes include breaking changes and migrations + ## Failure modes -If versioning is inconsistent: +If versioning rules are not followed: - Breaking changes ship without notice - Consumers cannot plan upgrades @@ -345,3 +351,12 @@ If versioning is inconsistent: - Version comparison tools - Release automation +## Ownership + +- Design Engineer: owns versioning decisions +- Frontend Engineer: validates impact in code + +## Links + +- [Change Control](change-control) +- [Conformance](../reference/conformance) diff --git a/docs/index.md b/docs/index.md index 38e5259..e4618f8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,120 +17,132 @@ A deterministic protocol for design-to-code variable governance. JSON shape, nam This specification is protected under the [Variable Design Standard License](license). Usage for AI-generated derivative standards, false compatibility claims, or ecosystem fragmentation is prohibited. +## Abstract + +Variable Design Standard (VDS) defines how variables are named, structured, reviewed, and shipped across design and code. It adds governance, validation, and role boundaries to the DTCG 2025.10 format so handoff holds as teams and products grow. JSON-as-API means file paths and names are the interface. + +## Status of This Document + +This specification is Draft. The table above lists the current version, license, and schema. + +## Conformance + +Conformance requires DTCG 2025.10 format compliance, Variable Design Standard (VDS) naming rules, reference syntax, validation, and versioning. See [Conformance](reference/conformance). + ## Start here -- [Why Variables](introduction/why-variables) - Why we call them variables, not design tokens -- [Variable Design Standard (VDS)](contract/variable-contract) - JSON shape and structure -- [Variables Governance](governance/overview) - Governance principles and workflow -- [DTCG Alignment](contract/dtcg-alignment) - DTCG 2025.10 compliance -- [Getting Started](adoption/getting-started) - Team adoption guide +- [Why Variables](introduction/why-variables): Why we call them variables, not design tokens +- [Variable Design Standard (VDS)](contract/variable-contract): JSON shape and structure +- [Variables Governance](governance/overview): Governance principles and workflow +- [DTCG Alignment](contract/dtcg-alignment): DTCG 2025.10 compliance +- [Getting Started](adoption/getting-started): Team adoption guide ## Introduction -- [Why Variables](introduction/why-variables) - Why "variables" not "design tokens" -- [Comparison](introduction/comparison) - Variable Design Standard vs other standards -- [Positioning](introduction/positioning) - What Variable Design Standard is and is not +- [Why Variables](introduction/why-variables): Why "variables" not "design tokens" +- [Comparison](introduction/comparison): Variable Design Standard vs other standards +- [Positioning](introduction/positioning): What Variable Design Standard is and is not ## Contract reference -- [Variable Design Standard (VDS)](contract/variable-contract) - JSON shape and structure -- [Groups](contract/groups) - Group structure and extension -- [References](contract/references) - Reference syntax and resolution -- [Modes](contract/modes) - Mode structure and resolution -- [Types](contract/types) - Type system reference -- [Composite Types](contract/composite-types) - Border, Transition, Shadow, Gradient, Typography -- [Naming](contract/naming) - Naming convention -- [Anatomy](contract/anatomy) - Base, alias, and component variables +- [Variable Design Standard (VDS)](contract/variable-contract): JSON shape and structure +- [Groups](contract/groups): Group structure and extension +- [References](contract/references): Reference syntax and resolution +- [Modes](contract/modes): Mode structure and resolution +- [Types](contract/types): Type system reference +- [Composite Types](contract/composite-types): Border, Transition, Shadow, Gradient, Typography +- [Naming](contract/naming): Naming convention +- [Anatomy](contract/anatomy): Base, alias, and component variables ## Adoption -- [Getting Started](adoption/getting-started) - Team adoption guide and implementation -- [Implementation Checklist](adoption/implementation-checklist) - Pre/post implementation checklists -- [Migration Strategy](adoption/migration-strategy) - Phased migration approaches +- [Getting Started](adoption/getting-started): Team adoption guide and implementation +- [Implementation Checklist](adoption/implementation-checklist): Pre/post implementation checklists +- [Migration Strategy](adoption/migration-strategy): Phased migration approaches ## Governance -- [Governance Overview](governance) - Governance principles and workflow -- [Getting Started](governance/getting-started) - Checklist for variable changes -- [Change Control](governance/change-control) - Review and release process -- [Validation](governance/validation) - Validation tools and CI setup -- [Versioning](governance/versioning) - Semantic versioning and breaking changes -- [Migration](governance/migration) - Migrating from other formats -- [Troubleshooting](governance/troubleshooting) - Common issues and solutions -- [Accessibility](governance/accessibility) - Accessibility constraints -- [Roles](governance/roles) - Role definitions - - [Designer](governance/roles/designer) - Creates variables in Figma - - [Design Engineer](governance/roles/design-engineer) - Bridges design and development, owns contract - - [Frontend Developer](governance/roles/frontend-developer) - Consumes variables in code +- [Governance Overview](governance): Governance principles and workflow +- [Getting Started](governance/getting-started): Checklist for variable changes +- [Change Control](governance/change-control): Review and release process +- [Validation](governance/validation): Validation tools and CI setup +- [Versioning](governance/versioning): Semantic versioning and breaking changes +- [Migration](governance/migration): Migrating from other formats +- [Troubleshooting](governance/troubleshooting): Common issues and solutions +- [Accessibility](governance/accessibility): Accessibility constraints +- [Roles](governance/roles): Role definitions + - [Designer](governance/roles/designer): Creates variables in Figma + - [Design Engineer](governance/roles/design-engineer): Bridges design and development, owns contract + - [Frontend Engineer](governance/roles/frontend-engineer): Consumes variables in code ## Scenarios -- [Multi-Brand](scenarios/multi-brand) - Multi-brand architecture patterns -- [Multi-Theme](scenarios/multi-theme) - Theme composition and mode inheritance -- [Large Sets](scenarios/large-sets) - Performance considerations and optimization -- [Component Integration](scenarios/component-integration) - Component library integration patterns +- [Multi-Brand](scenarios/multi-brand): Multi-brand architecture patterns +- [Multi-Theme](scenarios/multi-theme): Theme composition and mode inheritance +- [Large Sets](scenarios/large-sets): Performance considerations and limits +- [Component Integration](scenarios/component-integration): Component library integration patterns ## Tooling -- [Ecosystem](tooling/ecosystem) - Tools that support Variable Design Standard -- [CI/CD](tooling/ci-cd) - CI/CD integration patterns and examples -- [Build Pipelines](tooling/build-pipelines) - Complete build pipeline examples -- [Figma](adapters/figma) - Figma export normalization and workflow -- [Tokens Studio](adapters/tokens-studio) - Tokens Studio export normalization and workflow -- [Style Dictionary](adapters/style-dictionary) - CSS/TypeScript output generation +- [Ecosystem](tooling/ecosystem): Tools that support Variable Design Standard +- [CI/CD](tooling/ci-cd): CI/CD integration patterns and examples +- [Build Pipelines](tooling/build-pipelines): Complete build pipeline examples +- [Figma](adapters/figma): Figma export normalization and workflow +- [Tokens Studio](adapters/tokens-studio): Tokens Studio export normalization and workflow +- [Style Dictionary](adapters/style-dictionary): CSS/TypeScript output generation ## Consumption -- [CSS](consumption/css) - CSS variable consumption patterns -- [TypeScript](consumption/typescript) - TypeScript type generation and usage -- [Frameworks](consumption/frameworks) - React/Vue integration patterns +- [CSS](consumption/css): CSS variable consumption patterns +- [TypeScript](consumption/typescript): TypeScript type generation and usage +- [UI Libraries](consumption/frameworks): React/Vue integration patterns ## Design -- [Figma Naming](design/figma-naming) - How to name variables in Figma UI -- [Figma Workflow](design/figma-workflow) - Designer workflow optimization -- [Component Variables](design/component-variables) - Using variables in Figma components +- [Figma Naming](design/figma-naming): How to name variables in Figma UI +- [Figma Workflow](design/figma-workflow): Designer workflow tuning +- [Component Variables](design/component-variables): Using variables in Figma components ## Testing -- [Validation](testing/validation) - Testing variable changes and reference validation -- [Visual Regression](testing/visual-regression) - Visual regression testing strategies -- [Consumption Tests](testing/consumption-tests) - Testing generated outputs +- [Validation](testing/validation): Testing variable changes and reference validation +- [Visual Regression](testing/visual-regression): Visual regression testing strategies +- [Consumption Tests](testing/consumption-tests): Testing generated outputs ## Patterns -- [Multi-Brand Architecture](patterns/multi-brand-architecture) - Complete multi-brand example -- [Theme Composition](patterns/theme-composition) - Theme composition patterns and examples -- [Performance](patterns/performance) - Performance optimization strategies +- [Multi-Brand Architecture](patterns/multi-brand-architecture): Complete multi-brand example +- [Theme Composition](patterns/theme-composition): Theme composition patterns and examples +- [Performance](patterns/performance): Performance strategies ## Adapters -- [Adapters Overview](adapters) - Adapter pattern and responsibilities -- [Figma Adapter](adapters/figma) - Figma export normalization and workflow -- [Tokens Studio Adapter](adapters/tokens-studio) - Tokens Studio export normalization and workflow -- [Style Dictionary Adapter](adapters/style-dictionary) - CSS/TypeScript output generation -- [Tailwind Adapter](adapters/tailwind) - Tailwind theme configuration generation +- [Adapters Overview](adapters): Adapter pattern and responsibilities +- [Figma Adapter](adapters/figma): Figma export normalization and workflow +- [Tokens Studio Adapter](adapters/tokens-studio): Tokens Studio export normalization and workflow +- [Style Dictionary Adapter](adapters/style-dictionary): CSS/TypeScript output generation +- [Tailwind Adapter](adapters/tailwind): Tailwind theme configuration generation ## Examples -- [Figma Export JSON](examples/figma-export) - Example Figma export -- [DTCG Compliant Example](examples/dtcg-compliant) - Complete DTCG 2025.10 example -- [Adapter Pipeline](examples/adapter-pipeline) - End-to-end transformation example +- [Figma Export JSON](examples/figma-export): Example Figma export +- [DTCG Compliant Example](examples/dtcg-compliant): Complete DTCG 2025.10 example +- [Adapter Pipeline](examples/adapter-pipeline): Export-to-contract conversion example ## Reference -- [Glossary](reference/glossary) - Terminology definitions -- [Quick Reference](reference/quick-reference) - Cheat sheet for common tasks -- [Conformance](reference/conformance) - How to claim compliance +- [Glossary](reference/glossary): Terminology definitions +- [Quick Reference](reference/quick-reference): Cheat sheet for common tasks +- [Conformance](reference/conformance): How to claim compliance ## Meta -- [Status of this Document](meta/status-of-this-document) - Publication status, editors, acknowledgments -- [Specification Status](meta/status) - Status taxonomy and definitions -- [Change Log](meta/change-log) - Version history and release notes -- [Contributors](meta/contributors) - People who have contributed -- [References](meta/references) - External standards and specifications +- [Status of this Document](meta/status-of-this-document): Publication status, editors, acknowledgments +- [Specification Status](meta/status): Status taxonomy and definitions +- [Change Log](meta/change-log): Version history and release notes +- [Contributors](meta/contributors): People who have contributed +- [References](meta/references): External standards and specifications ## FAQ -- [FAQ](faq) - Common questions and answers +- [FAQ](faq): Common questions and answers diff --git a/docs/reference/conformance.md b/docs/reference/conformance.md index 45e905b..62fa6f8 100644 --- a/docs/reference/conformance.md +++ b/docs/reference/conformance.md @@ -8,7 +8,13 @@ title: Conformance Claiming conformance without meeting these requirements violates the [Standards Integrity License](../license). False conformance claims result in automatic license termination. ::: -How to claim Variable Design Standard (VDS) compliance and what it means. +Scope: conformance claims and the required evidence. + +Failure if ignored: conformance claims are invalid. + +## Conformance posture + +Conformance claims require automated validation and a documented review gate. If the gate does not exist, do not claim conformance. ## Technical Conformance Tests @@ -193,7 +199,7 @@ SHOULD: - Review variable changes before merge - Follow change control process -- Assign roles (Designer, Design Engineer, Frontend Developer) +- Assign roles (Designer, Design Engineer, Frontend Engineer) - Document team-specific patterns ## Claiming conformance diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 45cdca2..44d4d13 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -24,6 +24,14 @@ A component-scoped alias that references semantic variables. Component variables Example: `component.button.color.background.default` with `$value: "{color.surface.brand}"` +## File selection rule + +A file selection model where the folder path and file name select the active brand or mode. The JSON file set is the contract input. + +## JSON-as-API + +Treat the JSON file set as the API surface. Paths and names are the interface. File selection chooses brand and mode. + ## Variable Design Standard (VDS) The governance standard for design variables. Defines JSON structure, naming rules, validation requirements, and versioning strategy. @@ -42,7 +50,7 @@ A `$value` that points to another variable by name. References use curly brace s ## Mode -Intentional variants of a variable. Modes are stored as object keys in `$value`. +Named variants of a variable. Modes are stored as object keys in `$value`. Example: `$value: { "light": "#ffffff", "dark": "#000000" }` @@ -86,7 +94,6 @@ Role: Creates variables in Figma following naming conventions. Role: Bridges design and development. Owns Variable Design Standard (VDS), maintains naming rules, reviews changes. Understands both Figma and React component libraries. -## Frontend Developer +## Frontend Engineer Role: Consumes variables in code. Maintains build pipelines and component integration. - diff --git a/docs/reference/quick-reference.md b/docs/reference/quick-reference.md index 2db97fa..85b0a83 100644 --- a/docs/reference/quick-reference.md +++ b/docs/reference/quick-reference.md @@ -111,7 +111,7 @@ Example: - Run adapters - Publish releases -**Frontend Developer:** +**Frontend Engineer:** - Consume variables in code - Maintain build pipelines - Test consumption diff --git a/docs/tooling/build-pipelines.md b/docs/tooling/build-pipelines.md index 594f6ff..523bfea 100644 --- a/docs/tooling/build-pipelines.md +++ b/docs/tooling/build-pipelines.md @@ -1,11 +1,17 @@ --- -title: Tooling - Build Pipelines +title: Tooling: Build Pipelines --- # Build Pipeline Examples Complete build pipeline examples for generating outputs from Variable Design Standard (VDS). +## Workflow + +1. Validate token JSON. +2. Build outputs from the validated contract. +3. Publish artifacts to the build output location. + ## Basic pipeline ### Input @@ -336,21 +342,38 @@ console.log("Build complete!"); 1. Validate before building 2. Generate all needed outputs -3. Use consistent naming +3. Use the same naming rules across outputs 4. Cache build outputs 5. Document build process +## Review checklist + +- [ ] Validation runs before build +- [ ] Outputs include CSS and TypeScript where required +- [ ] Naming rules match across outputs +- [ ] Build artifacts are published + ## Failure modes If build pipeline is wrong: - Invalid outputs generated - Missing outputs -- Inconsistent naming +- Names differ across outputs - Slow builds ## Out of scope - Tool-specific build configs (see tool docs) - Deployment strategies (focus on build) -- Build optimization (see performance docs) +- Build performance (see performance docs) + +## Ownership + +- Frontend Engineer: owns build pipeline configuration +- Design Engineer: reviews output correctness + +## Links + +- [Validation](../governance/validation) +- [Change Control](../governance/change-control) diff --git a/docs/tooling/ci-cd.md b/docs/tooling/ci-cd.md index 1a8061d..75c0124 100644 --- a/docs/tooling/ci-cd.md +++ b/docs/tooling/ci-cd.md @@ -1,12 +1,18 @@ --- -title: Tooling - CI/CD Integration +title: Tooling: CI/CD Integration --- # CI/CD Integration -How to integrate Variable Design Standard (VDS) validation and builds into CI/CD pipelines. +Scope: CI/CD integration for Variable Design Standard (VDS) validation and builds. -If CI/CD is not set up, invalid variables ship to production and breaking changes go unnoticed. +Failure if ignored: invalid variables ship and breaking changes go unnoticed. + +## Workflow + +1. Validate token JSON on every PR. +2. Build outputs after validation. +3. Deploy outputs only after validation and build succeed. ## CI/CD patterns @@ -179,7 +185,7 @@ Create pre-commit hook: npx husky add .husky/pre-commit "npm run validate:tokens" ``` -### Pre-commit framework +### Pre-commit config Create `.pre-commit-config.yaml`: @@ -311,6 +317,12 @@ Add to `package.json`: 4. Cache dependencies in CI 5. Run validation before build +## Review checklist + +- [ ] Validation runs on every PR +- [ ] Builds run only after validation passes +- [ ] Outputs are checked for changes + ## Failure modes If CI/CD is not set up: @@ -325,3 +337,13 @@ If CI/CD is not set up: - Tool-specific CI/CD setup (see tool docs) - Deployment strategies (focus on validation/build) - Monitoring and alerting (separate concern) + +## Ownership + +- Frontend Engineer: owns CI configuration +- Design Engineer: defines validation rules + +## Links + +- [Validation](../governance/validation) +- [Build Pipelines](build-pipelines) diff --git a/docs/tooling/ecosystem.md b/docs/tooling/ecosystem.md index 0ad6fd1..f19f2fa 100644 --- a/docs/tooling/ecosystem.md +++ b/docs/tooling/ecosystem.md @@ -1,5 +1,5 @@ --- -title: Tooling - Ecosystem +title: Tooling: Ecosystem --- # Variable Design Standard (VDS) Tooling Ecosystem @@ -10,15 +10,15 @@ Tools that support Variable Design Standard (VDS) (DTCG 2025.10 format). ### DTCG-compliant validators -- **@dtcg/validator** - Official DTCG validator -- **style-dictionary** - Built-in DTCG format validation -- **Custom validators** - Build using DTCG JSON Schema +- **@dtcg/validator**: Official DTCG validator +- **style-dictionary**: Built-in DTCG format validation +- **Custom validators**: Build using DTCG JSON Schema ### Variable Design Standard (VDS) validators -- **Custom validation scripts** - Check naming, references, modes -- **CI validation** - GitHub Actions, GitLab CI, etc. -- **Pre-commit hooks** - Husky, pre-commit framework +- **Custom validation scripts**: Check naming, references, modes +- **CI validation**: GitHub Actions, GitLab CI, etc. +- **Pre-commit hooks**: Husky, pre-commit tool ## Build tools @@ -39,85 +39,98 @@ Tools that support Variable Design Standard (VDS) (DTCG 2025.10 format). ### Figma adapters -- **Figma REST API** - Export variables from Figma -- **Figma Dev Mode plugin** - Export variables -- **Custom adapters** - Normalize Figma exports to Variable Design Standard (VDS) +- **Figma REST API**: Export variables from Figma +- **Figma Dev Mode plugin**: Export variables +- **Custom adapters**: Normalize Figma exports to Variable Design Standard (VDS) ### Tokens Studio adapters -- **Tokens Studio plugin** - Export from Figma -- **Custom adapters** - Normalize Tokens Studio exports +- **Tokens Studio plugin**: Export from Figma +- **Custom adapters**: Normalize Tokens Studio exports ### Other adapters -- **Material Design** - Convert Material tokens to Variable Design Standard (VDS) -- **Adobe Spectrum** - Convert Spectrum tokens to Variable Design Standard (VDS) -- **Custom formats** - Build adapters for any format +- **Material Design**: Convert Material tokens to Variable Design Standard (VDS) +- **Adobe Spectrum**: Convert Spectrum tokens to Variable Design Standard (VDS) +- **Custom formats**: Build adapters for any format ## Editor integrations ### VS Code -- **Design Tokens extension** - Syntax highlighting for DTCG format -- **JSON Schema validation** - Validate Variable Design Standard (VDS) JSON -- **Custom extensions** - Build Variable Design Standard (VDS)-specific features +- **Design Tokens extension**: Syntax highlighting for DTCG format +- **JSON Schema validation**: Validate Variable Design Standard (VDS) JSON +- **Custom extensions**: Build Variable Design Standard (VDS)-specific features ### Other editors -- **WebStorm** - JSON Schema validation -- **Sublime Text** - JSON syntax highlighting -- **Vim** - JSON syntax highlighting +- **WebStorm**: JSON Schema validation +- **Sublime Text**: JSON syntax highlighting +- **Vim**: JSON syntax highlighting ## CI/CD tools ### GitHub Actions -- **Validation workflows** - Validate Variable Design Standard (VDS) JSON -- **Build workflows** - Generate outputs -- **Release workflows** - Version and release variables +- **Validation workflows**: Validate Variable Design Standard (VDS) JSON +- **Build workflows**: Generate outputs +- **Release workflows**: Version and release variables ### GitLab CI -- **Validation pipelines** - Validate Variable Design Standard (VDS) JSON -- **Build pipelines** - Generate outputs +- **Validation pipelines**: Validate Variable Design Standard (VDS) JSON +- **Build pipelines**: Generate outputs ### Other CI/CD -- **Jenkins** - Custom pipelines -- **CircleCI** - Custom workflows -- **Azure DevOps** - Custom pipelines +- **Jenkins**: Custom pipelines +- **CircleCI**: Custom workflows +- **Azure DevOps**: Custom pipelines ## Design tools ### Figma -- **Variables panel** - Create and manage variables -- **Dev Mode** - Export variables -- **Tokens Studio plugin** - Enhanced variable management +- **Variables panel**: Create and manage variables +- **Dev Mode**: Export variables +- **Tokens Studio plugin**: Enhanced variable management ### Other design tools -- **Sketch** - Variable support (limited) -- **Adobe XD** - Variable support (limited) +- **Sketch**: Variable support (limited) +- **Adobe XD**: Variable support (limited) ## Consumption tools ### CSS -- **CSS custom properties** - Native browser support -- **PostCSS** - Process CSS variables -- **CSS-in-JS** - Use variables in JavaScript +- **CSS custom properties**: Native browser support +- **PostCSS**: Process CSS variables +- **CSS-in-JS**: Use variables in JavaScript ### TypeScript -- **Type generation** - Generate TypeScript types from variables -- **Type-safe access** - Type-safe variable access +- **Type generation**: Generate TypeScript types from variables +- **Type-safe access**: Type-safe variable access -### Frameworks +### UI libraries -- **React** - Use CSS variables or generated types -- **Vue** - Use CSS variables or generated types -- **Angular** - Use CSS variables or generated types +- **React**: Use CSS variables or generated types +- **Vue**: Use CSS variables or generated types +- **Angular**: Use CSS variables or generated types + +## Workflow + +1. Choose export sources (Figma, Tokens Studio, or other tools). +2. Select adapters to normalize inputs to Variable Design Standard (VDS) JSON. +3. Select validation tools for schema and contract rules. +4. Select build tools for the outputs you need. + +## Review checklist + +- [ ] Adapter output matches Variable Design Standard (VDS) structure +- [ ] Validation covers naming, references, and mode key sets +- [ ] Build outputs cover CSS and TypeScript needs ## Tool compatibility matrix @@ -155,3 +168,12 @@ Tools that support Variable Design Standard (VDS) (DTCG 2025.10 format). - Runtime libraries (use existing DTCG validators) - UI tools (use existing tools) +## Ownership + +- Design Engineer: selects validators and adapters +- Frontend Engineer: selects build tools + +## Links + +- [Adapters](/adapters) +- [Build Pipelines](build-pipelines)