Update documentation with enhanced descriptions and fixed links

- Added detailed descriptions to various sections to improve clarity and context.
- Fixed broken links by ensuring correct paths and appending .md extensions where necessary.
- Updated frontmatter titles for consistency and formatting.
- Refined references to ensure they point to the correct locations within the documentation.

Author: marklearst

docs/adapters/figma.md

@@ -1,5 +1,6 @@
 ---
 title: "Adapters: Figma"
+description: "Figma Variables exports include tool-specific metadata and reference syntax. This adapter normalizes Figma exports into Variable Design Standard (VDS) format."
 ---
 
 # Figma Adapter
@@ -223,7 +224,7 @@ After:
 
 ### Step 6: Validate naming
 
-Check that normalized names follow Variable Design Standard (VDS) naming convention (see [Naming](/contract/naming.md)).
+Check that normalized names follow Variable Design Standard (VDS) naming convention (see [Naming](/contract/naming)).
 
 - Names MUST use dot-separated paths
 - Names MUST be lowercase
@@ -365,12 +366,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.md)).
+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.md))
+- Variable names follow naming convention ([Naming](/contract/naming))
 - References resolve correctly
 - Modes are limited (`light`, `dark`)
 - No duplicate values when base tokens exist

docs/adapters/index.md

@@ -1,5 +1,6 @@
 ---
 title: "Adapters: Overview"
+description: "Adapters normalize tool outputs into Variable Design Standard (VDS) format and transform Variable Design Standard (VDS) format into tool inputs."
 ---
 
 # Adapters
@@ -69,10 +70,10 @@ If adapters fail:
 
 ## Adapter documentation
 
-- [Figma Adapter](figma): Figma Variables export normalization
-- [Tokens Studio Adapter](tokens-studio): Tokens Studio export normalization
-- [Style Dictionary Adapter](style-dictionary): Variable Design Standard (VDS) to CSS/TypeScript/etc.
-- [Tailwind Adapter](tailwind): Tailwind theme configuration generation
+- [Figma Adapter](adapters/figma): Figma Variables export normalization
+- [Tokens Studio Adapter](adapters/tokens-studio): Tokens Studio export normalization
+- [Style Dictionary Adapter](adapters/style-dictionary): Variable Design Standard (VDS) to CSS/TypeScript/etc.
+- [Tailwind Adapter](adapters/tailwind): Tailwind theme configuration generation
 
 ## Out of scope
 

docs/adapters/style-dictionary.md

@@ -1,5 +1,6 @@
 ---
 title: "Adapters: Style Dictionary"
+description: "Style Dictionary consumes Variable Design Standard (VDS) (DTCG) format and generates platform outputs like CSS variables, TypeScript types, and Tailwind CSS v4 custom properties."
 ---
 
 # Style Dictionary Adapter
@@ -272,7 +273,7 @@ Output (`dist/theme.css`):
 }
 ```
 
-Note: Tailwind CSS v4 uses CSS-first configuration. Generate CSS custom properties, not JavaScript config files. See [Tailwind Adapter](adapters/tailwind) for details.
+Note: Tailwind CSS v4 uses CSS-first configuration. Generate CSS custom properties, not JavaScript config files. See [Tailwind Adapter](/adapters/tailwind) for details.
 
 ## Links
 

docs/adapters/tailwind.md

@@ -1,5 +1,6 @@
 ---
 title: "Adapters: Tailwind"
+description: "Tailwind CSS v4 integration patterns for Variable Design Standard (VDS). Generate CSS custom properties from Variable Design Standard (VDS) JSON using Tailwind CSS v4's CSS-first approach."
 ---
 
 # Tailwind Adapter

docs/adapters/tokens-studio.md

@@ -1,5 +1,6 @@
 ---
 title: "Adapters: Tokens Studio"
+description: "Tokens Studio exports are close to Variable Design Standard (VDS) format but may include Tokens Studio-specific metadata. This adapter normalizes Tokens Studio exports."
 ---
 
 # Tokens Studio Adapter
@@ -74,7 +75,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.md)).
+Check that names follow Variable Design Standard (VDS) naming convention (see [Naming](/contract/naming)).
 
 - Names MUST use dot-separated paths
 - Names MUST be lowercase
@@ -204,12 +205,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.md)).
+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.md))
+- Variable names follow naming convention ([Naming](/contract/naming))
 - References resolve correctly
 - Token organization (base, semantic, component layers)
 - Breaking changes are documented
@@ -232,7 +233,7 @@ Before exporting from Tokens Studio:
 - Semantic aliases: reference base tokens, describe usage
 - Component tokens: reference semantic aliases, component-scoped
 
-See [Anatomy](/contract/anatomy.md) for details.
+See [Anatomy](/contract/anatomy) for details.
 
 ### Artifacts that change
 

docs/adoption/getting-started.md

@@ -1,5 +1,6 @@
 ---
 title: "Adoption: Getting Started"
+description: "Team adoption steps for Variable Design Standard (VDS)."
 ---
 
 # Team Adoption Guide
@@ -342,8 +343,8 @@ Avoid these mistakes:
 
 After adoption:
 
-- Review [Implementation Checklist](adoption/implementation-checklist)
-- Set up [Migration Strategy](adoption/migration-strategy) if migrating
+- Review [Implementation Checklist](implementation-checklist)
+- Set up [Migration Strategy](migration-strategy) if migrating
 - Document team-specific patterns
 - Iterate on workflow
 

docs/adoption/implementation-checklist.md

@@ -1,5 +1,6 @@
 ---
 title: "Adoption: Implementation Checklist"
+description: "Pre-implementation, implementation, and post-implementation checklists for Variable Design Standard (VDS) adoption."
 ---
 
 # Implementation Checklist
@@ -129,7 +130,7 @@ To claim Variable Design Standard (VDS) compliance, verify:
 - [ ] File selection rule documented (brand and mode folders)
 - [ ] Contract review gate defined
 
-See [Conformance](reference/conformance) for complete conformance requirements.
+See [Conformance](../reference/conformance) for complete conformance requirements.
 
 ## Post-implementation validation
 

docs/adoption/migration-strategy.md

@@ -1,5 +1,6 @@
 ---
 title: "Adoption: Migration Strategy"
+description: "Phased migration steps from existing variable systems to Variable Design Standard (VDS)."
 ---
 
 # Phased Migration Strategy

docs/consumption/css.md

@@ -1,5 +1,6 @@
 ---
 title: "Consumption: CSS"
+description: "CSS consumption patterns for Variable Design Standard (VDS) outputs. Use CSS custom properties generated from Variable Design Standard (VDS) JSON."
 ---
 
 # CSS Variable Consumption

docs/consumption/frameworks.md

@@ -1,5 +1,6 @@
 ---
 title: "Consumption: UI Libraries"
+description: "UI library integration using Variable Design Standard (VDS) outputs. Use CSS variables, TypeScript types, and theme context in React and Vue components."
 ---
 
 # UI Library Integration