docs: clean up documentation formatting and improve clarity

marklearst · marklearst · commit 82bcd26d77f6 · 2025-12-31T23:30:01.000-05:00
- Removed unnecessary blank lines in multiple documentation files for better readability.
- Corrected minor typographical errors in the Tokens Studio Adapter description.
- Enhanced table formatting in the Design Engineer role section for improved presentation.
- Updated comparison matrix formatting for consistency across the introduction documentation.
diff --git a/docs/adapters/index.md b/docs/adapters/index.md
@@ -79,4 +79,3 @@ If adapters fail:
 - Runtime adapter libraries (implement adapters as needed)
 - Adapter testing frameworks
 - Cross-tool synchronization (handle via version control)
-
diff --git a/docs/adapters/tokens-studio.md b/docs/adapters/tokens-studio.md
@@ -4,7 +4,7 @@ title: Tokens Studio Adapter
 
 # Tokens Studio Adapter
 
-Tokens Studio exports are close to Variable Contract format but may include Tokens Studio-specific metadata. This adapter normalizes Tokens Studio exports.
+Tokens Studio exports are close to Variables Contract format but may include Tokens Studio-specific metadata. This adapter normalizes Tokens Studio exports.
 
 ## Input format
 
diff --git a/docs/contract/types.md b/docs/contract/types.md
@@ -290,7 +290,7 @@ Rules:
     },
     "invalid-dimension": {
       "$type": "dimension",
-      "$value": "16"  // Missing unit
+      "$value": "16" // Missing unit
     }
   }
 }
@@ -383,4 +383,3 @@ A variable type is valid if:
 - Custom type definitions (use `$extensions` for metadata)
 - Type coercion or conversion
 - Runtime type checking libraries (use DTCG-compliant validators)
-
diff --git a/docs/examples/adapter-pipeline.md b/docs/examples/adapter-pipeline.md
@@ -219,4 +219,3 @@ Validate at each step:
 1. Figma export: JSON syntax, required fields
 2. Adapter output: Variable Contract compliance, naming convention
 3. Style Dictionary output: CSS syntax, all references resolved
-
diff --git a/docs/governance/roles/design-engineer.md b/docs/governance/roles/design-engineer.md
@@ -45,14 +45,14 @@ Design Engineer MUST demonstrate proficiency in:
 
 These skills can be verified:
 
-| Skill | Verification |
-|-------|--------------|
-| Figma component libraries | Show a component library you built. Walk through the structure. |
-| Storybook | Write a story file and MDX doc for a component. Explain the patterns. |
-| CSS | Debug a styling issue without dev tools hints. Explain the cascade. |
-| React | Build a component with TypeScript. Explain the architecture decisions. |
-| Design systems | Explain your naming convention. Walk through base/alias/component layers. |
-| Translation | Given a Figma component, explain how you would structure it in React. Given a React constraint, explain how you would communicate it to design. |
+| Skill                     | Verification                                                                                                                                    |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Figma component libraries | Show a component library you built. Walk through the structure.                                                                                 |
+| Storybook                 | Write a story file and MDX doc for a component. Explain the patterns.                                                                           |
+| CSS                       | Debug a styling issue without dev tools hints. Explain the cascade.                                                                             |
+| React                     | Build a component with TypeScript. Explain the architecture decisions.                                                                          |
+| Design systems            | Explain your naming convention. Walk through base/alias/component layers.                                                                       |
+| Translation               | Given a Figma component, explain how you would structure it in React. Given a React constraint, explain how you would communicate it to design. |
 
 If a candidate cannot demonstrate these skills, they are not ready for this role.
 
diff --git a/docs/introduction/comparison.md b/docs/introduction/comparison.md
@@ -8,17 +8,17 @@ How Variable Contract compares to other variable/token standards and why it wins
 
 ## Comparison matrix
 
-| Feature | Variable Contract | DTCG 2025.10 | Style Dictionary | Material Design | Adobe Spectrum |
-|---------|------------------|--------------|------------------|-----------------|----------------|
-| Format | DTCG 2025.10 | DTCG 2025.10 | Legacy + DTCG | Custom JSON | Custom JSON |
-| Governance | Yes | No | No | Partial | Partial |
-| Naming rules | Yes | No | No | Yes | Yes |
-| Validation | Yes | Format only | Format only | Partial | Partial |
-| Versioning | Yes | No | No | Yes | Yes |
-| Adapters | Yes | No | Tool-specific | No | No |
-| Tool-agnostic | Yes | Yes | No | No | No |
-| Designer-focused | Yes | No | No | Yes | Yes |
-| Developer-focused | Yes | No | Yes | Partial | Partial |
+| Feature           | Variable Contract | DTCG 2025.10 | Style Dictionary | Material Design | Adobe Spectrum |
+| ----------------- | ----------------- | ------------ | ---------------- | --------------- | -------------- |
+| Format            | DTCG 2025.10      | DTCG 2025.10 | Legacy + DTCG    | Custom JSON     | Custom JSON    |
+| Governance        | Yes               | No           | No               | Partial         | Partial        |
+| Naming rules      | Yes               | No           | No               | Yes             | Yes            |
+| Validation        | Yes               | Format only  | Format only      | Partial         | Partial        |
+| Versioning        | Yes               | No           | No               | Yes             | Yes            |
+| Adapters          | Yes               | No           | Tool-specific    | No              | No             |
+| Tool-agnostic     | Yes               | Yes          | No               | No              | No             |
+| Designer-focused  | Yes               | No           | No               | Yes             | Yes            |
+| Developer-focused | Yes               | No           | Yes              | Partial         | Partial        |
 
 ## Variable Contract vs DTCG 2025.10
 
@@ -197,4 +197,3 @@ See [Migration Strategy](/variables-contract/introduction/adoption/migration-str
 - Replacing Style Dictionary (we work with it)
 - Replacing design systems (we govern variables)
 - Tool-specific features (we're tool-agnostic)
-

Original file line number	Diff line number	Diff line change
`@@ -290,7 +290,7 @@ Rules:`
`290`	`290`	`},`
`291`	`291`	`"invalid-dimension": {`
`292`	`292`	`"$type": "dimension",`
`293`		`- "$value": "16" // Missing unit`
	`293`	`+ "$value": "16" // Missing unit`
`294`	`294`	`}`
`295`	`295`	`}`
`296`	`296`	`}`
`@@ -383,4 +383,3 @@ A variable type is valid if:`
`383`	`383`	- Custom type definitions (use `$extensions` for metadata)
`384`	`384`	`- Type coercion or conversion`
`385`	`385`	`- Runtime type checking libraries (use DTCG-compliant validators)`
`386`		`-`