Merge pull request #12 from marklearst/pr-contract-schema

Harden contract and schema rules

Author: marklearst

docs/contract/anatomy.md

@@ -1,8 +1,8 @@
 ---
-title: Contract - Anatomy
+title: Contract: Anatomy
 ---
 
-# Contract - Anatomy
+# Contract: Anatomy
 
 These are the three layers we use so components do not depend on raw palette values.
 
@@ -57,6 +57,87 @@ Rules:
 - Alias variables: for usage in UI.
 - Component variables: for controlled overrides when needed.
 
+## No mapped layer
+
+VDS defines three layers only. Base, Alias, Component.
+
+Requirements:
+
+- VDS implementations MUST NOT add a fourth layer between Alias and Base.
+- Brand and theme selection MUST happen by file selection or by modes on Alias variables.
+- Alias variables SHOULD NOT exist only to redirect a base value under a second name.
+
+Example (conformant):
+
+```json
+// tokens/brand-a/color.json
+{
+  "color": {
+    "surface": {
+      "brand": { "$type": "color", "$value": "{color.brand.primary}" }
+    }
+  }
+}
+```
+
+```json
+// tokens/brand-b/color.json
+{
+  "color": {
+    "surface": {
+      "brand": { "$type": "color", "$value": "{color.brand.primary}" }
+    }
+  }
+}
+```
+
+Example (non-conformant):
+
+```json
+{
+  "mapped": {
+    "brand": {
+      "primary": { "$type": "color", "$value": "{color.blue.500}" }
+    }
+  },
+  "color": {
+    "surface": {
+      "brand": { "$type": "color", "$value": "{mapped.brand.primary}" }
+    }
+  }
+}
+```
+
+Example selection (CSS):
+
+```css
+@layer base, brand;
+@import "variables-base.css" layer(base);
+@import "variables-brand-a.css" layer(brand);
+```
+
+Guidance:
+
+- Treat the file tree as the selection boundary. The folder name picks the brand and mode.
+- Keep alias values direct. One alias hop from base is the default.
+- Do not add a mapped collection in a design tool panel. Use alias modes or file selection.
+- Use CSS cascade layers to select brand output at consumption time.
+- File selection rule selects brands and modes by file selection.
+
+Why this is faster:
+
+- A mapped layer forces a second naming decision for every semantic token.
+- A mapped layer adds one more reference hop for every resolution.
+- The three layer graph keeps review scope small and keeps pickers focused.
+- No extra collection to review, audit, or keep in sync.
+- CSS handles layout and motion. Tokens stay focused on values and intent.
+
+## Contract posture
+
+- Variable JSON in version control is the contract.
+- CI validates structure, naming, references, and modes.
+- Contract changes are reviewed before merge. See [Governance](../governance/overview).
+
 ## Formal Invariants
 
 These invariants MUST be maintained for Variable Design Standard (VDS) conformance. Violations are non-conformant.
@@ -70,6 +151,7 @@ These invariants MUST be maintained for Variable Design Standard (VDS) conforman
 - Base variables MUST NOT be consumed directly by components (unless explicitly allowed)
 
 **Example (conformant)**:
+
 ```json
 {
   "color": {
@@ -88,13 +170,14 @@ These invariants MUST be maintained for Variable Design Standard (VDS) conforman
 ```
 
 **Example (non-conformant)**:
+
 ```json
 {
   "color": {
     "gray": {
       "900": {
         "$type": "color",
-        "$value": "{color.gray.800}"  // Base variable referencing another base variable
+        "$value": "{color.gray.800}" // Base variable referencing another base variable
       }
     }
   }
@@ -110,27 +193,29 @@ These invariants MUST be maintained for Variable Design Standard (VDS) conforman
 - Alias variables form the semantic abstraction layer
 
 **Example (conformant)**:
+
 ```json
 {
   "color": {
     "text": {
       "primary": {
         "$type": "color",
-        "$value": "{color.gray.900}"  // References base variable
+        "$value": "{color.gray.900}" // References base variable
       }
     }
   }
 }
 ```
 
 **Example (non-conformant)**:
+
 ```json
 {
   "color": {
     "text": {
       "primary": {
         "$type": "color",
-        "$value": "{component.button.color.text}"  // Alias referencing component variable
+        "$value": "{component.button.color.text}" // Alias referencing component variable
       }
     }
   }
@@ -146,6 +231,7 @@ These invariants MUST be maintained for Variable Design Standard (VDS) conforman
 - Component variables provide fine-grained control when needed
 
 **Example (conformant)**:
+
 ```json
 {
   "component": {
@@ -154,7 +240,7 @@ These invariants MUST be maintained for Variable Design Standard (VDS) conforman
         "background": {
           "default": {
             "$type": "color",
-            "$value": "{color.surface.brand}"  // References alias variable
+            "$value": "{color.surface.brand}" // References alias variable
           }
         }
       }
@@ -164,6 +250,7 @@ These invariants MUST be maintained for Variable Design Standard (VDS) conforman
 ```
 
 **Example (non-conformant)**:
+
 ```json
 {
   "component": {
@@ -172,7 +259,7 @@ These invariants MUST be maintained for Variable Design Standard (VDS) conforman
         "background": {
           "default": {
             "$type": "color",
-            "$value": "{color.gray.900}"  // Component variable referencing base directly
+            "$value": "{color.gray.900}" // Component variable referencing base directly
           }
         }
       }
@@ -190,16 +277,18 @@ These invariants MUST be maintained for Variable Design Standard (VDS) conforman
 - Flattening destroys the dependency graph and breaks theme switching
 
 **Example (conformant output)**:
+
 ```json
 {
   "color.text.primary": "{color.gray.900}"
 }
 ```
 
 **Example (non-conformant output)**:
+
 ```json
 {
-  "color.text.primary": "#1a1a1a"  // Flattened - reference chain lost
+  "color.text.primary": "#1a1a1a" // Flattened - reference chain lost
 }
 ```
 
@@ -220,6 +309,7 @@ If anatomy rules are ignored:
 - Semantic intent is lost (developers guess meaning from value)
 - Component variables reference base variables (tight coupling, hard to refactor)
 - Alias layer is skipped (no semantic abstraction)
+- Mapped layers appear (extra decision and more reference hops)
 
 ## Out of scope
 

docs/contract/composite-types.md

@@ -6,6 +6,12 @@ title: Composite Types
 
 Composite types combine multiple primitive types into structured values. They represent complex design decisions like borders, shadows, and typography styles.
 
+## Requirements
+
+- Composite variables MUST use an object in `$value`.
+- The `$value` object MUST match the property list for that composite type.
+- Each property value MUST be a literal of the expected type or a reference to one.
+
 ## Border
 
 `$type: "border"`
@@ -50,9 +56,9 @@ Stroke style values:
 
 Property-level references:
 
-- `{variable.width}` - border width
-- `{variable.color}` - border color
-- `{variable.style}` - border style
+- `{variable.width}`: border width
+- `{variable.color}`: border color
+- `{variable.style}`: border style
 
 ## Transition
 
@@ -92,9 +98,9 @@ Example:
 
 Property-level references:
 
-- `{variable.duration}` - transition duration
-- `{variable.delay}` - transition delay
-- `{variable.timingFunction}` - timing function
+- `{variable.duration}`: transition duration
+- `{variable.delay}`: transition delay
+- `{variable.timingFunction}`: timing function
 
 ## Shadow
 
@@ -141,11 +147,11 @@ Example:
 
 Property-level references:
 
-- `{variable.color}` - shadow color
-- `{variable.offsetX}` - horizontal offset
-- `{variable.offsetY}` - vertical offset
-- `{variable.blur}` - blur radius
-- `{variable.spread}` - spread radius
+- `{variable.color}`: shadow color
+- `{variable.offsetX}`: horizontal offset
+- `{variable.offsetY}`: vertical offset
+- `{variable.blur}`: blur radius
+- `{variable.spread}`: spread radius
 
 ## Gradient
 
@@ -244,13 +250,32 @@ Example:
 }
 ```
 
+## Failure modes
+
+If composite rules are ignored:
+
+- Missing required fields for a composite type
+- Property-level references point to incompatible types
+- Consumers cannot render the composite correctly
+
+## Validation checklist
+
+- [ ] Each composite includes all required fields for its type
+- [ ] Each field value matches the expected primitive type
+- [ ] Property-level references resolve to matching fields
+
+## Out of scope
+
+- Runtime rendering rules for composites
+- Tool-specific composite extensions
+
 Property-level references:
 
-- `{variable.fontFamily}` - font family
-- `{variable.fontSize}` - font size
-- `{variable.fontWeight}` - font weight
-- `{variable.letterSpacing}` - letter spacing
-- `{variable.lineHeight}` - line height
+- `{variable.fontFamily}`: font family
+- `{variable.fontSize}`: font size
+- `{variable.fontWeight}`: font weight
+- `{variable.letterSpacing}`: letter spacing
+- `{variable.lineHeight}`: line height
 
 ## Composite type validation
 
@@ -421,4 +446,3 @@ A composite type is valid if:
 - Custom composite types (use `$extensions` for metadata)
 - Composite type coercion
 - Runtime composite type validation libraries (use DTCG-compliant validators)
-

docs/contract/dtcg-alignment.md

@@ -10,6 +10,14 @@ Variable Design Standard (VDS) is DTCG 2025.10 compliant. What that means and wh
 
 Variable Design Standard (VDS) uses the Design Tokens Community Group (DTCG) format 2025.10 as its base format. Variable Design Standard (VDS) extends DTCG with modes and convenience formats. Files using only DTCG features are strictly compliant. Files using modes or string shortcuts for dimension/duration are Variable Design Standard (VDS) format.
 
+## Requirements
+
+- Variable JSON MUST follow DTCG 2025.10 structure.
+- `$type` and `$value` MUST exist on every variable.
+- References MUST use curly brace syntax in Variable Design Standard (VDS) files.
+- JSON Pointer references MAY be supported for DTCG compliance.
+- Modes in `$value` are a Variable Design Standard (VDS) extension.
+
 ## What DTCG provides
 
 DTCG 2025.10 defines:
@@ -61,6 +69,30 @@ Variable Design Standard (VDS) extends DTCG format with:
 4. Validation that checks references resolve
 5. Governance that treats renames as breaking changes
 
+## Examples
+
+Strict DTCG:
+
+```json
+{
+  "$type": "color",
+  "$value": {
+    "colorSpace": "srgb",
+    "components": [0, 0.4, 0.8],
+    "hex": "#0066cc"
+  }
+}
+```
+
+Variable Design Standard (VDS) extension:
+
+```json
+{
+  "$type": "color",
+  "$value": "#0066cc"
+}
+```
+
 ## Strict DTCG compliance
 
 For strict DTCG 2025.10 compliance, use:
@@ -93,3 +125,10 @@ If you ignore DTCG compliance:
 - Runtime validation libraries (use DTCG-compliant validators)
 - Format conversion tools (use adapters)
 - Tool-specific features not in DTCG spec
+
+## Validation checklist
+
+- [ ] All variables include `$type` and `$value`
+- [ ] References in Variable Design Standard (VDS) files use `{path}` syntax
+- [ ] JSON Pointer references are only used for DTCG compliance
+- [ ] Modes in `$value` are documented as a Variable Design Standard (VDS) extension