Fix broken links by appending .md extensions and using absolute paths

marklearst · marklearst · commit d28edbf00aa4 · 2026-01-28T00:41:28.000-05:00
diff --git a/docs/adapters/figma.md b/docs/adapters/figma.md
@@ -223,7 +223,7 @@ After:
 
 ### Step 6: Validate naming
 
-Check that normalized names follow Variable Design Standard (VDS) naming convention (see [Naming](/contract/naming)).
+Check that normalized names follow Variable Design Standard (VDS) naming convention (see [Naming](/contract/naming.md)).
 
 - Names MUST use dot-separated paths
 - Names MUST be lowercase
@@ -365,12 +365,12 @@ Designers author variables in Figma. Changes flow through export, normalization,
 2. Design Engineer runs Figma adapter to normalize export JSON.
 3. Design Engineer commits normalized JSON to version control.
 4. Design Engineer opens PR for review.
-5. Reviewers check naming, types, references (see [Change Control](/governance/change-control)).
+5. Reviewers check naming, types, references (see [Change Control](/governance/change-control.md)).
 6. After merge, CI generates build outputs.
 
 ### What gets reviewed
 
-- Variable names follow naming convention ([Naming](/contract/naming))
+- Variable names follow naming convention ([Naming](/contract/naming.md))
 - References resolve correctly
 - Modes are limited (`light`, `dark`)
 - No duplicate values when base tokens exist
diff --git a/docs/adapters/tokens-studio.md b/docs/adapters/tokens-studio.md
@@ -74,7 +74,7 @@ This format is already correct. No conversion needed.
 
 ### Step 4: Validate naming
 
-Check that names follow Variable Design Standard (VDS) naming convention (see [Naming](/contract/naming)).
+Check that names follow Variable Design Standard (VDS) naming convention (see [Naming](/contract/naming.md)).
 
 - Names MUST use dot-separated paths
 - Names MUST be lowercase
@@ -204,12 +204,12 @@ Designers author variables in Figma using Tokens Studio plugin. The repo JSON is
 2. Design Engineer validates export JSON (run adapter if needed).
 3. Design Engineer commits JSON to version control.
 4. Design Engineer opens PR for review.
-5. Reviewers check naming, types, references (see [Change Control](/governance/change-control)).
+5. Reviewers check naming, types, references (see [Change Control](/governance/change-control.md)).
 6. After merge, CI validates JSON and generates build outputs.
 
 ### What gets reviewed
 
-- Variable names follow naming convention ([Naming](/contract/naming))
+- Variable names follow naming convention ([Naming](/contract/naming.md))
 - References resolve correctly
 - Token organization (base, semantic, component layers)
 - Breaking changes are documented
@@ -232,7 +232,7 @@ Before exporting from Tokens Studio:
 - Semantic aliases: reference base tokens, describe usage
 - Component tokens: reference semantic aliases, component-scoped
 
-See [Anatomy](/contract/anatomy) for details.
+See [Anatomy](/contract/anatomy.md) for details.
 
 ### Artifacts that change
 
diff --git a/docs/contract/dtcg-alignment.md b/docs/contract/dtcg-alignment.md
@@ -37,9 +37,9 @@ Variable Design Standard (VDS) adds governance and extensions on top of DTCG for
 - **String shortcuts**: Convenience formats like `"16px"` for dimensions and `"200ms"` for durations. DTCG requires object format.
 - **Hex color shorthand**: Convenience format like `"#0066cc"` for colors. DTCG requires object format with `colorSpace` and `components`.
 - Naming convention rules (see [Naming](naming))
-- Change control process (see [Change Control](/governance/change-control))
-- Role definitions (see [Design Engineer](/governance/roles/design-engineer))
-- Adapter patterns for tool integration (see [Adapters](/adapters))
+- Change control process (see [Change Control](/governance/change-control.md))
+- Role definitions (see [Design Engineer](/governance/roles/design-engineer.md))
+- Adapter patterns for tool integration (see [Adapters](/adapters.md))
 - Validation requirements beyond format correctness
 
 ## Compatibility matrix
diff --git a/docs/contract/variable-contract.md b/docs/contract/variable-contract.md
@@ -20,7 +20,7 @@ This contract defines the canonical shape used in version control.
 
 Tool exports (example: a Figma variable export JSON) are treated as inputs. They may include extra metadata and alternate reference syntax. An adapter can normalize those inputs into this contract.
 
-See [Adapters](/adapters) for adapter patterns and implementations.
+See [Adapters](/adapters.md) for adapter patterns and implementations.
 
 ## Adapter pipeline
 
@@ -182,7 +182,7 @@ Variable Design Standard (VDS) conformance requires:
 - Validation implementation
 - Versioning compliance
 
-See [Conformance](/reference/conformance) for complete conformance requirements and how to claim compliance.
+See [Conformance](/reference/conformance.md) for complete conformance requirements and how to claim compliance.
 
 ## Out of scope
 
diff --git a/docs/examples/adapter-pipeline.md b/docs/examples/adapter-pipeline.md
@@ -228,5 +228,5 @@ Validate at each step:
 
 ## Out of scope
 
-- Alternate adapter pipelines (see [Adapters](/adapters))
+- Alternate adapter pipelines (see [Adapters](/adapters.md))
 - Tool-specific deployment steps
diff --git a/docs/examples/dtcg-compliant.md b/docs/examples/dtcg-compliant.md
@@ -8,7 +8,7 @@ A strictly DTCG 2025.10 compliant variable file demonstrating primitive types, c
 
 - Raw file: [dtcg-compliant.json](/assets/schema/dtcg-compliant.json)
 
-This file uses only features defined in the [DTCG 2025.10 specification](https://www.designtokens.org/tr/drafts/format/). It does NOT use Variable Design Standard (VDS) extensions like modes in `$value`. See [DTCG Alignment](/contract/dtcg-alignment) for what DTCG provides vs what Variable Design Standard (VDS) adds.
+This file uses only features defined in the [DTCG 2025.10 specification](https://www.designtokens.org/tr/drafts/format/). It does NOT use Variable Design Standard (VDS) extensions like modes in `$value`. See [DTCG Alignment](/contract/dtcg-alignment.md) for what DTCG provides vs what Variable Design Standard (VDS) adds.
 
 ## File overview
 
@@ -22,12 +22,12 @@ The example file includes:
 
 **Not included** (Variable Design Standard (VDS) extensions):
 
-- Modes in `$value` objects (see [Modes](/contract/modes) for VC extension)
+- Modes in `$value` objects (see [Modes](/contract/modes.md) for VC extension)
 - String shortcuts for dimension/duration/color
 
 ## Primitive types
 
-DTCG 2025.10 requires specific object formats for certain types. See [Types](/contract/types) for complete reference.
+DTCG 2025.10 requires specific object formats for certain types. See [Types](/contract/types.md) for complete reference.
 
 ### Color (object format required)
 
@@ -126,7 +126,7 @@ Font family, font weight, cubic bezier, and number types use simple values:
 
 ## Composite types
 
-Structured types combining multiple values. See [Composite Types](/contract/composite-types) for complete reference.
+Structured types combining multiple values. See [Composite Types](/contract/composite-types.md) for complete reference.
 
 ```json
 {
@@ -177,7 +177,7 @@ Structured types combining multiple values. See [Composite Types](/contract/comp
 
 ## References
 
-Variables can reference other variables using curly brace syntax. See [References](/contract/references) for resolution rules.
+Variables can reference other variables using curly brace syntax. See [References](/contract/references.md) for resolution rules.
 
 ```json
 {
@@ -208,7 +208,7 @@ Variables can reference other variables using curly brace syntax. See [Reference
 
 ## Group extension
 
-Groups can extend other groups using `$extends` with curly brace syntax. See [Groups](/contract/groups) for extension rules.
+Groups can extend other groups using `$extends` with curly brace syntax. See [Groups](/contract/groups.md) for extension rules.
 
 ```json
 {
@@ -275,7 +275,7 @@ This pattern creates a clear hierarchy: base → semantic → component.
 
 ## Modes (Variable Design Standard (VDS) extension)
 
-**Note**: Modes in `$value` are NOT part of the DTCG 2025.10 specification. If you need light/dark theme variants, Variable Design Standard (VDS) provides modes as an extension. See [Modes](/contract/modes).
+**Note**: Modes in `$value` are NOT part of the DTCG 2025.10 specification. If you need light/dark theme variants, Variable Design Standard (VDS) provides modes as an extension. See [Modes](/contract/modes.md).
 
 For strict DTCG compliance without modes, use separate variables:
 
@@ -314,10 +314,10 @@ Invalid DTCG format causes build failures:
 
 This example demonstrates strict DTCG format compliance, not:
 
-- **Variable Design Standard (VDS) extensions**: Modes, string shortcuts. See [Modes](/contract/modes) for VC extensions.
-- **Platform output**: CSS, SCSS, or JavaScript output. See [Adapter Pipeline](/examples/adapter-pipeline).
-- **Tool-specific input**: Figma or Tokens Studio export formats. See [Figma Export](/examples/figma-export).
-- **Multi-brand architecture**: Brand overrides and theme composition. See [Multi-brand Architecture](/patterns/multi-brand-architecture).
+- **Variable Design Standard (VDS) extensions**: Modes, string shortcuts. See [Modes](/contract/modes.md) for VC extensions.
+- **Platform output**: CSS, SCSS, or JavaScript output. See [Adapter Pipeline](/examples/adapter-pipeline.md).
+- **Tool-specific input**: Figma or Tokens Studio export formats. See [Figma Export](/examples/figma-export.md).
+- **Multi-brand architecture**: Brand overrides and theme composition. See [Multi-brand Architecture](/patterns/multi-brand-architecture.md).
 
 ## Validation
 
@@ -327,4 +327,4 @@ Validate DTCG compliance using the JSON schema:
 npx ajv validate -s schema/v1.json -d examples/dtcg-compliant.json
 ```
 
-See [Validation](/governance/validation) for CI integration patterns.
+See [Validation](/governance/validation.md) for CI integration patterns.
diff --git a/docs/examples/figma-export.md b/docs/examples/figma-export.md
@@ -169,7 +169,7 @@ The REST API uses a different structure than plugin exports. Key differences:
 }
 ```
 
-The Figma adapter handles both formats. See [Figma Adapter](/adapters/figma) for details.
+The Figma adapter handles both formats. See [Figma Adapter](/adapters/figma.md) for details.
 
 ## Failure modes
 
@@ -184,18 +184,18 @@ Using raw Figma exports without normalization causes:
 
 This example shows raw Figma output, not:
 
-- **Normalized format**: See [DTCG Compliant Example](/examples/dtcg-compliant) for canonical structure.
-- **Normalization steps**: See [Figma Adapter](/adapters/figma) for conversion rules.
+- **Normalized format**: See [DTCG Compliant Example](/examples/dtcg-compliant.md) for canonical structure.
+- **Normalization steps**: See [Figma Adapter](/adapters/figma.md) for conversion rules.
 - **Tokens Studio format**: Different export structure with its own adapter.
 - **Plugin development**: See [Figma Plugin API](https://developers.figma.com/docs/plugins/api/figma-variables/) for building export tools.
 
 ## Normalization
 
-The [Figma Adapter](/adapters/figma) transforms this format into Variable Design Standard (VDS) canonical structure:
+The [Figma Adapter](/adapters/figma.md) transforms this format into Variable Design Standard (VDS) canonical structure:
 
 1. Remove `@` and `$` prefixes from paths
 2. Move `$variable_metadata.modes` into `$value` objects
 3. Convert reference syntax to DTCG format
 4. Relocate metadata to `$extensions`
 
-See [Adapter Pipeline](/examples/adapter-pipeline) for export-to-contract conversion examples.
+See [Adapter Pipeline](/examples/adapter-pipeline.md) for export-to-contract conversion examples.
diff --git a/docs/governance/accessibility.md b/docs/governance/accessibility.md
@@ -36,6 +36,6 @@ When a variable changes:
 
 ## Links
 
-- [Types](/contract/types)
-- [Modes](/contract/modes)
-- [CSS Consumption](/consumption/css)
+- [Types](/contract/types.md)
+- [Modes](/contract/modes.md)
+- [CSS Consumption](/consumption/css.md)
diff --git a/docs/governance/getting-started.md b/docs/governance/getting-started.md
@@ -16,8 +16,8 @@ Use this checklist when you're adding or changing a variable.
 
 1. Read:
    - [Variable Governance](overview)
-   - [Naming](/contract/naming)
-   - [Tokens Studio](/adapters/tokens-studio)
+   - [Naming](/contract/naming.md)
+   - [Tokens Studio](/adapters/tokens-studio.md)
    - [Change Control](change-control)
 2. Identify which variable category you are working in:
    - base
diff --git a/docs/governance/index.md b/docs/governance/index.md
@@ -62,6 +62,6 @@ Governance keeps variable changes reviewed, versioned, and safe to roll out.
 
 ## Related
 
-- [Naming](/contract/naming)
-- [Tokens Studio](/adapters/tokens-studio)
+- [Naming](/contract/naming.md)
+- [Tokens Studio](/adapters/tokens-studio.md)
 - [Accessibility](accessibility)
diff --git a/docs/governance/migration.md b/docs/governance/migration.md
@@ -318,6 +318,6 @@ If migration is incomplete:
 
 ## Links
 
-- [Adapters](/adapters)
+- [Adapters](/adapters.md)
 - [Validation](validation)
 - [Conformance](../reference/conformance)
diff --git a/docs/governance/overview.md b/docs/governance/overview.md
@@ -8,7 +8,7 @@ Governance keeps a variable change from turning into a cleanup project across co
 
 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).
+The contract rules (schema and validation expectations) live in [Variable Design Standard (VDS)](/contract/variable-contract.md).
 
 ## Governance purpose
 
diff --git a/docs/governance/roles/design-engineer.md b/docs/governance/roles/design-engineer.md
@@ -60,7 +60,7 @@ If a candidate cannot demonstrate these skills, they are not ready for this role
 
 ### Contract owner responsibilities
 
-- Own the Variable Design Standard (VDS) ([Variable Design Standard (VDS)](/contract/variable-contract)).
+- Own the Variable Design Standard (VDS) ([Variable Design Standard (VDS)](/contract/variable-contract.md)).
 - Approve all variable changes before they enter version control.
 - Maintain naming rules and category boundaries (base, alias, component).
 - Review variable changes for contract correctness, references, and mode strategy.
@@ -159,6 +159,6 @@ The Variable Design Standard (VDS) depends on this role being held to a clear st
 
 ## Links
 
-- [Variable Contract](/contract/variable-contract)
+- [Variable Contract](/contract/variable-contract.md)
 - [Change Control](../change-control)
 - [Validation](../validation)
diff --git a/docs/governance/roles/designer.md b/docs/governance/roles/designer.md
@@ -14,11 +14,11 @@ Design Engineer reviews and approves all variable changes before they enter the
 
 ## Responsibilities
 
-- Create variables in Figma following naming convention (see [Naming](/contract/naming)).
+- Create variables in Figma following naming convention (see [Naming](/contract/naming.md)).
 - Define semantic intent for variables (what they represent, not just values).
 - Define mode values (light/dark, mobile/desktop) when needed.
-- Use variables in Figma components (see [Component Variables](/design/component-variables)).
-- Export variables for normalization (see [Figma Workflow](/design/figma-workflow)).
+- Use variables in Figma components (see [Component Variables](/design/component-variables.md)).
+- Export variables for normalization (see [Figma Workflow](/design/figma-workflow.md)).
 - Submit variable changes for review by Design Engineer.
 
 ## Ownership
@@ -107,6 +107,6 @@ If Designer bypasses Design Engineer review:
 
 ## Links
 
-- [Naming](/contract/naming)
+- [Naming](/contract/naming.md)
 - [Change Control](../change-control)
 - [Validation](../validation)
diff --git a/docs/governance/roles/frontend-engineer.md b/docs/governance/roles/frontend-engineer.md
@@ -17,7 +17,7 @@ Design Engineer owns the contract. Designer creates variables. Frontend Engineer
 - Consume variables in code (CSS variables, TypeScript types, theme objects).
 - Maintain build pipelines that generate outputs from Variable Design Standard (VDS) JSON.
 - Integrate variables into component libraries (React, Vue, etc.).
-- Test variable consumption (see [Consumption Tests](/testing/consumption-tests)).
+- Test variable consumption (see [Consumption Tests](/testing/consumption-tests.md)).
 - Report consumption issues to Design Engineer.
 
 ## Ownership
@@ -106,7 +106,7 @@ Frontend Engineers maintain pipelines that:
 3. Output platform-specific formats.
 4. Integrate with component libraries.
 
-See [Build Pipelines](/tooling/build-pipelines) for examples.
+See [Build Pipelines](/tooling/build-pipelines.md) for examples.
 
 ## Common mistakes
 
@@ -145,6 +145,6 @@ If Frontend Engineer doesn't report consumption issues:
 
 ## Links
 
-- [CSS Consumption](/consumption/css)
-- [Build Pipelines](/tooling/build-pipelines)
+- [CSS Consumption](/consumption/css.md)
+- [Build Pipelines](/tooling/build-pipelines.md)
 - [Change Control](../change-control)
diff --git a/docs/governance/troubleshooting.md b/docs/governance/troubleshooting.md
@@ -493,4 +493,4 @@ If issues persist:
 
 - [Validation](validation)
 - [Change Control](change-control)
-- [Adapters](/adapters)
+- [Adapters](/adapters.md)
diff --git a/docs/schema/index.md b/docs/schema/index.md
@@ -190,4 +190,4 @@ The schema is available at:
 
 ## Conformance
 
-Using this schema for validation is one component of Variable Design Standard (VDS) conformance. See [Conformance](/reference/conformance) for complete requirements.
+Using this schema for validation is one component of Variable Design Standard (VDS) conformance. See [Conformance](/reference/conformance.md) for complete requirements.
diff --git a/docs/tooling/ecosystem.md b/docs/tooling/ecosystem.md
@@ -175,5 +175,5 @@ Tools that support Variable Design Standard (VDS) (DTCG 2025.10 format).
 
 ## Links
 
-- [Adapters](/adapters)
+- [Adapters](/adapters/index.md)
 - [Build Pipelines](build-pipelines)
