docs: update internal links for consistency and navigation

marklearst · marklearst · commit 6c9feab28fcd · 2026-01-01T00:11:46.000-05:00
- Updated internal links across various documentation files to use absolute paths for improved accessibility.
- Ensured that references to the Naming, Change Control, and Adapters sections are correctly linked.
- Enhanced clarity in the documentation by maintaining consistent link formatting throughout.
diff --git a/docs/adapters/figma.md b/docs/adapters/figma.md
@@ -212,7 +212,7 @@ After:
 
 ### Step 6: Validate naming
 
-Check that normalized names follow Variable Contract naming convention (see [Naming](../contract/naming)).
+Check that normalized names follow Variable Contract naming convention (see [Naming](/contract/naming)).
 
 - Names MUST use dot-separated paths
 - Names MUST be lowercase
@@ -354,12 +354,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)).
 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))
 - 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 transformation needed.
 
 ### Step 4: Validate naming
 
-Check that names follow Variable Contract naming convention (see [Naming](../contract/naming)).
+Check that names follow Variable Contract naming convention (see [Naming](/contract/naming)).
 
 - 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)).
 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))
 - 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) for details.
 
 ### Artifacts that change
 
diff --git a/docs/contract/dtcg-alignment.md b/docs/contract/dtcg-alignment.md
@@ -26,9 +26,9 @@ DTCG 2025.10 defines:
 Variable Contract adds a governance layer on top of DTCG format:
 
 - 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))
+- Role definitions (see [Design Engineer](/governance/roles/design-engineer))
+- Adapter patterns for tool integration (see [Adapters](/adapters))
 - Validation requirements beyond format correctness
 
 ## Compatibility matrix
diff --git a/docs/contract/variable-contract.md b/docs/contract/variable-contract.md
@@ -18,7 +18,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) for adapter patterns and implementations.
 
 ## Adapter pipeline
 
@@ -157,7 +157,7 @@ Variable Contract conformance requires:
 - Validation implementation
 - Versioning compliance
 
-See [Conformance](../reference/conformance) for complete conformance requirements and how to claim compliance.
+See [Conformance](/reference/conformance) for complete conformance requirements and how to claim compliance.
 
 ## Out of scope
 
diff --git a/docs/examples/figma-export.md b/docs/examples/figma-export.md
@@ -8,7 +8,7 @@ This is an example input file shape from a Figma Variables export.
 
 - Raw file: `figma-export.json`
 
-This export format includes Figma-specific metadata and reference syntax. Use the [Figma Adapter](../../adapters/figma) to normalize it into the canonical contract format defined in [Variable Contract](../../contract/variable-contract).
+This export format includes Figma-specific metadata and reference syntax. Use the [Figma Adapter](//adapters/figma) to normalize it into the canonical contract format defined in [Variable Contract](//contract/variable-contract).
 
 ## Normalization required
 
@@ -20,4 +20,4 @@ Figma exports need normalization before use:
 4. Convert reference syntax (`{@collection.token}` → `{collection.token}`)
 5. Move mode values from metadata to `$value` objects
 
-See [Figma Adapter](../adapters/figma) for complete normalization steps.
+See [Figma Adapter](/adapters/figma) for complete normalization steps.
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)
+   - [Tokens Studio](/adapters/tokens-studio)
    - [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
@@ -47,6 +47,6 @@ Governance is what keeps variable changes boring: reviewed, versioned, and safe
 
 ## Reference
 
-- [Naming](../contract/naming)
-- [Tokens Studio](../adapters/tokens-studio)
+- [Naming](/contract/naming)
+- [Tokens Studio](/adapters/tokens-studio)
 - [Accessibility](accessibility)
diff --git a/docs/governance/overview.md b/docs/governance/overview.md
@@ -8,7 +8,7 @@ Governance is how you keep a token change from turning into a cleanup project ac
 
 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 Contract](../contract/variable-contract).
+The contract rules (schema and validation expectations) live in [Variable Contract](/contract/variable-contract).
 
 ## Principles
 
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 Contract ([Variable Contract](../../contract/variable-contract)).
+- Own the Variable Contract ([Variable Contract](/contract/variable-contract)).
 - 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.
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)).
 - 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)).
+- Export variables for normalization (see [Figma Workflow](/design/figma-workflow)).
 - Submit variable changes for review by Design Engineer.
 
 ## Boundaries
diff --git a/docs/governance/roles/frontend-developer.md b/docs/governance/roles/frontend-developer.md
@@ -17,7 +17,7 @@ Design Engineer owns the contract. Designer creates variables. Frontend Develope
 - Consume variables in code (CSS variables, TypeScript types, theme objects).
 - Maintain build pipelines that generate outputs from Variable Contract 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)).
 - Report consumption issues to Design Engineer.
 
 ## Boundaries
@@ -88,7 +88,7 @@ Frontend Developers 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) for examples.
 
 ## Common mistakes
 
diff --git a/docs/meta/contributors.md b/docs/meta/contributors.md
@@ -16,7 +16,7 @@ Variable Contract has been in development since 2017.
 
 Contributions welcome. To contribute:
 
-1. Read [WRITING_GUIDE.md](../../WRITING_GUIDE.md)
+1. Read [WRITING_GUIDE.md](/WRITING_GUIDE.md)
 2. Follow writing guide rules
 3. Include examples for new concepts
 4. Document failure modes
@@ -25,4 +25,3 @@ Contributions welcome. To contribute:
 ## Recognition
 
 Contributors will be recognized here as the project grows.
-
diff --git a/site/adapters/figma/index.html b/site/adapters/figma/index.html
@@ -1443,7 +1443,7 @@ <h3 id="step-5-handle-modes">Step 5: Handle modes</h3>
 <span class="hljs-punctuation">}</span>
 </code></pre>
 <h3 id="step-6-validate-naming">Step 6: Validate naming</h3>
-<p>Check that normalized names follow Variable Contract naming convention (see <a href="../contract/naming">Naming</a>).</p>
+<p>Check that normalized names follow Variable Contract naming convention (see <a href="/contract/naming">Naming</a>).</p>
 <ul>
 <li>Names MUST use dot-separated paths</li>
 <li>Names MUST be lowercase</li>
@@ -1572,12 +1572,12 @@ <h3 id="workflow-steps">Workflow steps</h3>
 <li>Design Engineer runs Figma adapter to normalize export JSON.</li>
 <li>Design Engineer commits normalized JSON to version control.</li>
 <li>Design Engineer opens PR for review.</li>
-<li>Reviewers check naming, types, references (see <a href="../governance/change-control">Change Control</a>).</li>
+<li>Reviewers check naming, types, references (see <a href="/governance/change-control">Change Control</a>).</li>
 <li>After merge, CI generates build outputs.</li>
 </ol>
 <h3 id="what-gets-reviewed">What gets reviewed</h3>
 <ul>
-<li>Variable names follow naming convention (<a href="../contract/naming">Naming</a>)</li>
+<li>Variable names follow naming convention (<a href="/contract/naming">Naming</a>)</li>
 <li>References resolve correctly</li>
 <li>Modes are limited (<code>light</code>, <code>dark</code>)</li>
 <li>No duplicate values when base tokens exist</li>
diff --git a/site/adapters/tokens-studio/index.html b/site/adapters/tokens-studio/index.html
@@ -1331,7 +1331,7 @@ <h3 id="step-3-handle-modes">Step 3: Handle modes</h3>
 </code></pre>
 <p>This format is already correct. No transformation needed.</p>
 <h3 id="step-4-validate-naming">Step 4: Validate naming</h3>
-<p>Check that names follow Variable Contract naming convention (see <a href="../contract/naming">Naming</a>).</p>
+<p>Check that names follow Variable Contract naming convention (see <a href="/contract/naming">Naming</a>).</p>
 <ul>
 <li>Names MUST use dot-separated paths</li>
 <li>Names MUST be lowercase</li>
@@ -1445,12 +1445,12 @@ <h3 id="workflow-steps">Workflow steps</h3>
 <li>Design Engineer validates export JSON (run adapter if needed).</li>
 <li>Design Engineer commits JSON to version control.</li>
 <li>Design Engineer opens PR for review.</li>
-<li>Reviewers check naming, types, references (see <a href="../governance/change-control">Change Control</a>).</li>
+<li>Reviewers check naming, types, references (see <a href="/governance/change-control">Change Control</a>).</li>
 <li>After merge, CI validates JSON and generates build outputs.</li>
 </ol>
 <h3 id="what-gets-reviewed">What gets reviewed</h3>
 <ul>
-<li>Variable names follow naming convention (<a href="../contract/naming">Naming</a>)</li>
+<li>Variable names follow naming convention (<a href="/contract/naming">Naming</a>)</li>
 <li>References resolve correctly</li>
 <li>Token organization (base, semantic, component layers)</li>
 <li>Breaking changes are documented</li>
@@ -1472,7 +1472,7 @@ <h3 id="token-organization">Token organization</h3>
 <li>Semantic aliases: reference base tokens, describe usage</li>
 <li>Component tokens: reference semantic aliases, component-scoped</li>
 </ul>
-<p>See <a href="../contract/anatomy">Anatomy</a> for details.</p>
+<p>See <a href="/contract/anatomy">Anatomy</a> for details.</p>
 <h3 id="artifacts-that-change">Artifacts that change</h3>
 <ul>
 <li>Tokens Studio export JSON (input, may be committed)</li>
diff --git a/site/contract/dtcg-alignment/index.html b/site/contract/dtcg-alignment/index.html
@@ -1297,9 +1297,9 @@ <h2 id="what-variable-contract-adds">What Variable Contract adds</h2>
 <p>Variable Contract adds a governance layer on top of DTCG format:</p>
 <ul>
 <li>Naming convention rules (see <a href="naming">Naming</a>)</li>
-<li>Change control process (see <a href="../governance/change-control">Change Control</a>)</li>
-<li>Role definitions (see <a href="../governance/roles/design-engineer">Design Engineer</a>)</li>
-<li>Adapter patterns for tool integration (see <a href="../adapters">Adapters</a>)</li>
+<li>Change control process (see <a href="/governance/change-control">Change Control</a>)</li>
+<li>Role definitions (see <a href="/governance/roles/design-engineer">Design Engineer</a>)</li>
+<li>Adapter patterns for tool integration (see <a href="/adapters">Adapters</a>)</li>
 <li>Validation requirements beyond format correctness</li>
 </ul>
 <h2 id="compatibility-matrix">Compatibility matrix</h2>
diff --git a/site/contract/variable-contract/index.html b/site/contract/variable-contract/index.html
@@ -1287,7 +1287,7 @@ <h2 id="dtcg-compliance">DTCG compliance</h2>
 <h2 id="inputs-and-adapters">Inputs and adapters</h2>
 <p>This contract defines the canonical shape used in version control.</p>
 <p>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.</p>
-<p>See <a href="../adapters">Adapters</a> for adapter patterns and implementations.</p>
+<p>See <a href="/adapters">Adapters</a> for adapter patterns and implementations.</p>
 <h2 id="adapter-pipeline">Adapter pipeline</h2>
 <p>A typical pipeline looks like:</p>
 <ol><li>Input: Figma export JSON (Dev Mode plugin export) or Figma Variables REST API output.</li>
@@ -1399,7 +1399,7 @@ <h2 id="conformance">Conformance</h2>
 <li>Validation implementation</li>
 <li>Versioning compliance</li>
 </ul>
-<p>See <a href="../reference/conformance">Conformance</a> for complete conformance requirements and how to claim compliance.</p>
+<p>See <a href="/reference/conformance">Conformance</a> for complete conformance requirements and how to claim compliance.</p>
 <h2 id="out-of-scope">Out of scope</h2>
 <p>Variable Contract does NOT define:</p>
 <ul>
diff --git a/site/examples/figma-export/index.html b/site/examples/figma-export/index.html
@@ -1284,7 +1284,7 @@ <h1 id="figma-export-json">Figma Export JSON</h1>
 <ul>
 <li>Raw file: <code>figma-export.json</code></li>
 </ul>
-<p>This export format includes Figma-specific metadata and reference syntax. Use the <a href="../../adapters/figma">Figma Adapter</a> to normalize it into the canonical contract format defined in <a href="../../contract/variable-contract">Variable Contract</a>.</p>
+<p>This export format includes Figma-specific metadata and reference syntax. Use the <a href="//adapters/figma">Figma Adapter</a> to normalize it into the canonical contract format defined in <a href="//contract/variable-contract">Variable Contract</a>.</p>
 <h2 id="normalization-required">Normalization required</h2>
 <p>Figma exports need normalization before use:</p>
 <ol><li>Extract <code>$collection_metadata</code> to <code>$extensions</code></li>
@@ -1293,7 +1293,7 @@ <h2 id="normalization-required">Normalization required</h2>
 <li>Convert reference syntax (<code>{@collection.token}</code> → <code>{collection.token}</code>)</li>
 <li>Move mode values from metadata to <code>$value</code> objects</li>
 </ol>
-<p>See <a href="../adapters/figma">Figma Adapter</a> for complete normalization steps.</p>
+<p>See <a href="/adapters/figma">Figma Adapter</a> for complete normalization steps.</p>
 
                     
                     
diff --git a/site/governance/getting-started/index.html b/site/governance/getting-started/index.html
@@ -1291,8 +1291,8 @@ <h2 id="where-to-start">Where to start</h2>
 <ol><li>Read:
 <ul>
 <li><a href="overview">Variable Governance</a></li>
-<li><a href="../contract/naming">Naming</a></li>
-<li><a href="../adapters/tokens-studio">Tokens Studio</a></li>
+<li><a href="/contract/naming">Naming</a></li>
+<li><a href="/adapters/tokens-studio">Tokens Studio</a></li>
 <li><a href="change-control">Change Control</a></li>
 </ul>
 </li>
diff --git a/site/governance/index.html b/site/governance/index.html
@@ -1322,8 +1322,8 @@ <h2 id="roles">Roles</h2>
 </ul>
 <h2 id="reference">Reference</h2>
 <ul>
-<li><a href="../contract/naming">Naming</a></li>
-<li><a href="../adapters/tokens-studio">Tokens Studio</a></li>
+<li><a href="/contract/naming">Naming</a></li>
+<li><a href="/adapters/tokens-studio">Tokens Studio</a></li>
 <li><a href="accessibility">Accessibility</a></li>
 </ul>
 
diff --git a/site/governance/overview/index.html b/site/governance/overview/index.html
@@ -1282,7 +1282,7 @@ <h1>Variable Governance</h1>
                     <h1 id="variable-governance">Variable Governance</h1>
 <p>Governance is how you keep a token change from turning into a cleanup project across components.</p>
 <p>The rules here treat variable names and references like an API: changes are reviewed, and breaking changes are called out.</p>
-<p>The contract rules (schema and validation expectations) live in <a href="../contract/variable-contract">Variable Contract</a>.</p>
+<p>The contract rules (schema and validation expectations) live in <a href="/contract/variable-contract">Variable Contract</a>.</p>
 <h2 id="principles">Principles</h2>
 <ul>
 <li>Variable names are an API.</li>
diff --git a/site/governance/roles/design-engineer/index.html b/site/governance/roles/design-engineer/index.html
@@ -1349,7 +1349,7 @@ <h2 id="skill-verification">Skill verification</h2>
 <h2 id="responsibilities">Responsibilities</h2>
 <h3 id="contract-owner-responsibilities">Contract owner responsibilities</h3>
 <ul>
-<li>Own the Variable Contract (<a href="../../contract/variable-contract">Variable Contract</a>).</li>
+<li>Own the Variable Contract (<a href="/contract/variable-contract">Variable Contract</a>).</li>
 <li>Approve all variable changes before they enter version control.</li>
 <li>Maintain naming rules and category boundaries (base, alias, component).</li>
 <li>Review variable changes for contract correctness, references, and mode strategy.</li>
diff --git a/site/governance/roles/designer/index.html b/site/governance/roles/designer/index.html
@@ -1286,11 +1286,11 @@ <h2 id="scope">Scope</h2>
 <p>Design Engineer reviews and approves all variable changes before they enter the contract.</p>
 <h2 id="responsibilities">Responsibilities</h2>
 <ul>
-<li>Create variables in Figma following naming convention (see <a href="../../contract/naming">Naming</a>).</li>
+<li>Create variables in Figma following naming convention (see <a href="/contract/naming">Naming</a>).</li>
 <li>Define semantic intent for variables (what they represent, not just values).</li>
 <li>Define mode values (light/dark, mobile/desktop) when needed.</li>
-<li>Use variables in Figma components (see <a href="../../design/component-variables">Component Variables</a>).</li>
-<li>Export variables for normalization (see <a href="../../design/figma-workflow">Figma Workflow</a>).</li>
+<li>Use variables in Figma components (see <a href="/design/component-variables">Component Variables</a>).</li>
+<li>Export variables for normalization (see <a href="/design/figma-workflow">Figma Workflow</a>).</li>
 <li>Submit variable changes for review by Design Engineer.</li>
 </ul>
 <h2 id="boundaries">Boundaries</h2>
diff --git a/site/governance/roles/frontend-developer/index.html b/site/governance/roles/frontend-developer/index.html
@@ -1289,7 +1289,7 @@ <h2 id="responsibilities">Responsibilities</h2>
 <li>Consume variables in code (CSS variables, TypeScript types, theme objects).</li>
 <li>Maintain build pipelines that generate outputs from Variable Contract JSON.</li>
 <li>Integrate variables into component libraries (React, Vue, etc.).</li>
-<li>Test variable consumption (see <a href="../../testing/consumption-tests">Consumption Tests</a>).</li>
+<li>Test variable consumption (see <a href="/testing/consumption-tests">Consumption Tests</a>).</li>
 <li>Report consumption issues to Design Engineer.</li>
 </ul>
 <h2 id="boundaries">Boundaries</h2>
@@ -1346,7 +1346,7 @@ <h2 id="build-pipeline">Build pipeline</h2>
 <li>Output platform-specific formats.</li>
 <li>Integrate with component libraries.</li>
 </ol>
-<p>See <a href="../../tooling/build-pipelines">Build Pipelines</a> for examples.</p>
+<p>See <a href="/tooling/build-pipelines">Build Pipelines</a> for examples.</p>
 <h2 id="common-mistakes">Common mistakes</h2>
 <ul>
 <li>Consuming base palette variables directly in components (use semantic variables).</li>
diff --git a/site/meta/contributors/index.html b/site/meta/contributors/index.html
