Merge pull request #16 from marklearst/pr-version-0-5

Bump version to 0.5.0

Author: marklearst

README.md

@@ -2,7 +2,7 @@
 
 Public specification and governance standard for design variables. DTCG 2025.10 compliant format with naming rules, validation requirements, versioning strategy, and adapter patterns.
 
-**Version:** 0.4.0
+**Version:** 0.5.0
 **Status:** Draft
 **Editor:** Mark Learst
 

assets/schema/dtcg-compliant.json

@@ -28,7 +28,7 @@
           "hex": "#4763BF"
         },
         "$extensions": {
-          "com.variables-contract.version": "0.4.0"
+          "com.variables-contract.version": "0.5.0"
         }
       },
       "secondary": {

docs/contract/types.md

@@ -67,7 +67,7 @@ Examples:
         "hex": "#4763BF"
       },
       "$extensions": {
-        "com.variables-contract.version": "0.4.0"
+        "com.variables-contract.version": "0.5.0"
       }
     },
     "primary-shorthand": {

docs/examples/dtcg-compliant.md

@@ -45,7 +45,7 @@ DTCG requires color values as objects with `colorSpace` and `components`:
           "hex": "#4763BF"
         },
         "$extensions": {
-          "com.variables-contract.version": "0.4.0"
+          "com.variables-contract.version": "0.5.0"
         }
       }
     }

docs/faq.md

@@ -114,7 +114,7 @@ See [License](license) for usage terms.
 
 ## Is Variable Design Standard (VDS) production-ready?
 
-Yes. Version 0.4.0 is in Draft status but production-ready. Used by teams in production. See [Specification Status](meta/status) for status definitions.
+Yes. Version 0.5.0 is in Draft status but production-ready. Used by teams in production. See [Specification Status](meta/status) for status definitions.
 
 ## How do I claim conformance?
 

docs/index.md

@@ -7,7 +7,7 @@ title: Variable Design Standard (VDS)
 |                |                                    |
 | -------------- | ---------------------------------- |
 | **Status**     | Draft                              |
-| **Version**    | 0.4.0                              |
+| **Version**    | 0.5.0                              |
 | **Editor**     | Mark Learst                        |
 | **Compliance** | DTCG 2025.10                       |
 | **Schema**     | [v1.json](assets/schema/v1.json)   |

docs/meta/change-log.md

@@ -6,64 +6,50 @@ title: Change Log
 
 Version history and release notes for Variable Design Standard (VDS).
 
-## Version 0.4.0 (Current)
+## Version 0.5.0 (Current)
 
 **Status:** Draft
-**Date:** January 26, 2026
+**Date:** January 27, 2026
 
-Documentation hardening and DTCG 2025.10 compliance improvements.
+Spec-wide cadence alignment, role naming update, and JSON-as-API framing.
 
 ### Changes
 
-#### DTCG 2025.10 Compliance Improvements
+#### Cadence and voice alignment
 
-- **Clarified modes as Variable Design Standard (VDS) extension**: Modes in `$value` objects are NOT part of DTCG 2025.10 specification. This is a Variable Design Standard (VDS) extension inspired by Figma's modes concept.
-- **Updated group extension syntax**: Changed from `$ref` to `$extends` with curly brace syntax (`"$extends": "{group.path}"`) to align with DTCG 2025.10.
-- **Fixed format documentation**: Updated Color, Dimension, and Duration type documentation to show DTCG object format as canonical, with Variable Design Standard (VDS) string shortcuts as convenience formats.
-- **Corrected DTCG feature claims**: Removed "Mode support" from DTCG features list; added modes, string shortcuts, and hex color shorthand to Variable Design Standard (VDS) extensions.
+- Added “Scope + Failure if ignored” openers across scenarios, patterns, consumption, testing, adoption, and design docs.
+- Tightened introduction pages to a spec voice and removed guide-only phrasing.
+- Aligned navigation labels with page titles (UI Libraries).
 
-#### Figma Documentation Improvements
+#### JSON-as-API framing
 
-- **Clarified export formats**: Distinguished plugin-generated format from REST API format.
-- **Fixed REST API access claim**: Corrected to "Enterprise plan only" (not Enterprise/Organization).
-- **Clarified export prefixes**: Documented that `@` and `$` prefixes are added by export plugins, not typed in Figma UI.
-- **Added comprehensive Figma links**: Added Designer Resources and Developer Resources sections to LINKS.md.
+- Declared JSON-as-API as the interface across contract, governance, patterns, consumption, and reference glossary.
+- Reinforced file selection rule as the brand/mode switch instead of mapped layers.
 
-#### Documentation Hardening
+#### Role naming and governance clarity
 
-- **Version references**: Updated all version references from 0.3.7 to 0.4.0.
-- **Fixed incorrect version claims**: Corrected FAQ claim that 1.0.0 is the current release.
-- **Updated examples**: Fixed `dtcg-compliant.json` to use strict DTCG object formats.
-- **Improved accuracy**: Ensured all DTCG compliance claims are accurate and verifiable.
+- Renamed Frontend Developer to Frontend Engineer across governance, tooling, adoption, and reference docs.
+- Added or refined workflow and review checklists to reinforce governance gates.
 
 ### Files Updated
 
-- `package.json`: Version bump to 0.4.0
-- `README.md`: Version update and DTCG claims correction
-- `docs/index.md`: Version update
-- `docs/faq.md`: Fixed version claim
-- `docs/contract/dtcg-alignment.md`: Clarified VDS extensions
-- `docs/contract/modes.md`: Added DTCG disclaimer
-- `docs/contract/types.md`: Updated to show object format as canonical
-- `docs/contract/groups.md`: Updated to use `$extends`
-- `docs/contract/references.md`: Clarified modes are VDS extension
-- `docs/contract/variable-contract.md`: Updated group extension syntax
-- `docs/examples/dtcg-compliant.md`: Updated to match corrected JSON
-- `docs/examples/figma-export.md`: Fixed REST API claims
-- `docs/adapters/figma.md`: Clarified plugin vs REST API formats
-- `docs/design/figma-naming.md`: Clarified export prefixes
-- `assets/schema/dtcg-compliant.json`: Fixed to strict DTCG format
-- `LINKS.md`: Added Figma documentation links
+Highlights across introduction, contract, governance, scenarios, patterns, consumption, testing, tooling, and adapters. See git history for full file list.
+
+## Version 0.4.0
+
+**Status:** Draft
+**Date:** January 26, 2026
+
+Documentation hardening and DTCG 2025.10 compliance improvements.
 
 ## Version 0.3.7
 
 Previous version with initial documentation structure.
 
 ## Future versions
 
-- **v0.5.0**: Reference validator CLI and test fixtures
 - **v0.6.0**: Reference adapters as code (Figma, Tokens Studio)
 - **v0.7.0**: Reference output generators (CSS, TypeScript, Tailwind v4)
-- **v1.0.0**: Formal Status of this Document (SOTD), conformance registry, schema frozen for 1.x
+- **v1.0.0**: Formal Status of this Document (SOTD), conformance registry, stabilized schema
 
 See [Versioning](governance/versioning) for versioning strategy and breaking change definitions.

docs/meta/status-of-this-document.md

@@ -8,9 +8,9 @@ This section describes the status of this document at the time of its publicatio
 
 ## Current Publication
 
-**Version**: 0.4.0
+**Version**: 0.5.0
 **Status**: Draft
-**Date**: January 26, 2026
+**Date**: January 27, 2026
 **Editor**: Mark Learst
 
 ## Document Status
@@ -51,7 +51,7 @@ Issues, questions, and feedback are welcome via:
 
 When filing an issue, please include:
 
-- **Variable Design Standard (VDS) version** (e.g., 0.4.0)
+- **Variable Design Standard (VDS) version** (e.g., 0.5.0)
 - **Type of issue**: Bug, question, proposal, documentation
 - **Description**: Clear description of the issue or question
 - **Steps to reproduce** (for bugs): How to reproduce the issue
@@ -72,7 +72,7 @@ When filing an issue, please include:
 
 ### Editor
 
-**Mark Learst**: Editor and maintainer
+**Mark Learst** - Editor and maintainer
 
 Variable Design Standard (VDS) has been in development since 2017.
 
@@ -84,10 +84,10 @@ See [Contributors](contributors) for a list of people who have contributed to Va
 
 Variable Design Standard (VDS) builds on:
 
-- [DTCG 2025.10 Format Specification](https://www.designtokens.org/tr/2025.10/format/): Base format specification
-- [Style Dictionary](https://styledictionary.com/): Output generation tool
-- Figma Variables: Design tool integration
-- Tokens Studio: Design tool integration
+- [DTCG 2025.10 Format Specification](https://www.designtokens.org/tr/2025.10/format/) - Base format specification
+- [Style Dictionary](https://styledictionary.com/) - Output generation tool
+- Figma Variables - Design tool integration
+- Tokens Studio - Design tool integration
 - The design systems community for feedback and validation
 
 ## Document History
@@ -96,8 +96,8 @@ Version history and release notes are documented in the [Change Log](change-log)
 
 ### Recent Versions
 
-- **0.4.0** (Current): Documentation hardening and DTCG compliance improvements
-- **0.3.7**: Previous version with initial documentation structure
+- **0.5.0** (Current) - Cadence alignment, JSON-as-API framing, and role naming update
+- **0.4.0** - Documentation hardening and DTCG compliance improvements
 
 ### Future Versions
 

docs/meta/status.md

@@ -33,7 +33,7 @@ This document defines the status taxonomy for Variable Design Standard (VDS) and
 - Suitable for production use with awareness of potential minor changes
 
 **Transition criteria**: Move from Draft to Candidate Standard when:
-- Core features are frozen for the current major version
+- Core features are stable
 - Breaking changes are limited to major versions
 - Community feedback period begins
 
@@ -42,7 +42,7 @@ This document defines the status taxonomy for Variable Design Standard (VDS) and
 **Definition**: Production-ready, breaking changes only in major versions.
 
 **Characteristics**:
-- Required fields are frozen for the current major version
+- Specification is stable and production-ready
 - Breaking changes only in major versions (following semantic versioning)
 - Minor and patch versions are backward-compatible
 - Recommended for production use
@@ -72,22 +72,22 @@ This document defines the status taxonomy for Variable Design Standard (VDS) and
 
 ## Current Status
 
-**Variable Design Standard (VDS) 0.4.0**: **Draft**
+**Variable Design Standard (VDS) 0.5.0**: **Draft**
 
-The specification is in active development. While it is used in production by some teams, breaking changes may occur as the specification evolves based on feedback and implementation experience.
+The specification is in active development. While it is production-ready and used by teams, breaking changes may occur as the specification evolves based on feedback and implementation experience.
 
 ## Status History
 
-- **0.1.0: 0.3.7**: Draft
-- **0.4.0**: Draft (current)
+- **0.1.0 - 0.4.0**: Draft
+- **0.5.0**: Draft (current)
 
 ## Status Indicators
 
 Status is indicated in:
-- `docs/index.md`: Status metadata table
-- `docs/meta/change-log.md`: Version status field
-- `docs/faq.md`: Production-ready answer
-- This document: Status definitions
+- `docs/index.md` - Status metadata table
+- `docs/meta/change-log.md` - Version status field
+- `docs/faq.md` - Production-ready answer
+- This document - Status definitions
 
 ## Compatibility Promises by Status
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "variable-design-standard",
   "private": true,
-  "version": "0.4.0",
+  "version": "0.5.0",
   "packageManager": "pnpm@10.26.0",
   "scripts": {
     "dev": "docmd dev",