feat: data-driven Color and Dimension type definitions (fixes #97)

docs/spec.md

@@ -9,7 +9,7 @@ A DESIGN.md file contains two parts: An optional YAML frontmatter, and a markdow
 
 # Design Tokens
 
-DESIGN.md may embed design tokens in a structured format. The system that we use to describe design tokens is inspired by the
+DESIGN.md may embed design tokens in a structured format. The system that we use to describe design tokens is inspired by the
 [Design Token JSON spec](https://www.designtokens.org/tr/2025.10/format/#abstract). Specifically, we adopt the concept of typed token groups (colors, typography, spacing) and the `{path.to.token}` reference syntax for cross-referencing values.
 
 These tokens are easily converted from or to `tokens.json`, Figma variables, and Tailwind theme configs.
@@ -41,31 +41,31 @@ typography:
 Below is the schema for the design tokens defined in the front matter:
 
 ```yaml
-version: <string>          # optional, current version: "alpha"
-name: <string>
-description: <string>      # optional
-colors:
-  <token-name>: <Color>
-typography:
-  <token-name>: <Typography>
-rounded:
-  <scale-level>: <Dimension>
-spacing:
-  <scale-level>: <Dimension | number>
-components:
-  <component-name>:
+version: <string>          # optional, current version: "alpha"
+name: <string>
+description: <string>      # optional
+colors:
+  <token-name>: <Color>
+typography:
+  <token-name>: <Typography>
+rounded:
+  <scale-level>: <Dimension>
+spacing:
+  <scale-level>: <Dimension | number>
+components:
+  <component-name>:
     <token-name>: <string|token reference>
 ```
 
 The `<scale-level>` placeholder represents a named level in a sizing or spacing scale. Common level names include `xs`, `sm`, `md`, `lg`, `xl`, and `full`. Any descriptive string key is valid.
 
 **Color**: A color value is any valid CSS color string. Supported formats include:
 
-* Hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`
-* Named colors: `red`, `cornflowerblue`, `transparent`
-* Functional: `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`
-* Wide-gamut: `oklch()`, `oklab()`, `lch()`, `lab()`
-* Mixing: `color-mix(in srgb, ...)`
+- Hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`
+- Named colors: `red`, `cornflowerblue`, `transparent`
+- Functional: `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`
+- Wide-gamut: `oklch()`, `oklab()`, `lch()`, `lab()`
+- Mixing: `color-mix(in srgb, ...)`
 
 All color values are internally converted to sRGB for WCAG contrast checking. The original format is preserved for display and export.
 
@@ -119,25 +119,25 @@ When there are multiple color palettes, the design system may assign a semantic
 Example:
 
 ```markdown
-## Colors
-
-The palette is rooted in high-contrast neutrals and a single, evocative accent color.
-
-- **Primary (#1A1C1E):** A deep ink used for headlines and core text to provide
-  maximum readability and a sense of permanence.
-- **Secondary (#6C7278):** A sophisticated slate used primarily for utilitarian
-  elements like borders, captions, and metadata.
-- **Tertiary (#B8422E):** A vibrant earthy red as the sole driver for
-  interaction, used exclusively for primary actions and critical highlights.
-- **Neutral (#F7F5F2):** A warm limestone that serves as the foundation for all
+## Colors
+
+The palette is rooted in high-contrast neutrals and a single, evocative accent color.
+
+- **Primary (#1A1C1E):** A deep ink used for headlines and core text to provide
+  maximum readability and a sense of permanence.
+- **Secondary (#6C7278):** A sophisticated slate used primarily for utilitarian
+  elements like borders, captions, and metadata.
+- **Tertiary (#B8422E):** A vibrant earthy red as the sole driver for
+  interaction, used exclusively for primary actions and critical highlights.
+- **Neutral (#F7F5F2):** A warm limestone that serves as the foundation for all
   pages, providing a softer, more organic feel than pure white.
 ```
 
 ### Design Tokens
 
 The `colors` section defines all color design tokens. The color tokens should be derived from the key color palettes defined in the markdown prose. The exact mapping from color palettes to color tokens may follow any consistent naming convention.
 
-It is a
+It is a
 map\<string, Color>, that maps the name of the color token to its value.
 
 ```yaml
@@ -159,25 +159,25 @@ A common naming convention for typography levels is to use semantic categories s
 Example:
 
 ```markdown
-## Typography
-
-The typography strategy leverages two distinct weights of **Public Sans** for
-the narrative and **Space Grotesk** for technical data.
-
-- **Headlines:** Set in Public Sans Semi-Bold to establish an institutional
-  and trustworthy voice.
-- **Body:** Public Sans Regular at 16px ensures contemporary professionalism
-  and long-form readability.
-- **Labels:** Space Grotesk is used for all technical data, timestamps, and
-  metadata. Its geometric construction evokes the precision of a digital
+## Typography
+
+The typography strategy leverages two distinct weights of **Public Sans** for
+the narrative and **Space Grotesk** for technical data.
+
+- **Headlines:** Set in Public Sans Semi-Bold to establish an institutional
+  and trustworthy voice.
+- **Body:** Public Sans Regular at 16px ensures contemporary professionalism
+  and long-form readability.
+- **Labels:** Space Grotesk is used for all technical data, timestamps, and
+  metadata. Its geometric construction evokes the precision of a digital
   stopwatch. Labels are strictly uppercase with generous letter spacing.
 ```
 
 ### Design Tokens
 
 The `typography` section defines the precise font properties for the typography design tokens.
 
-It is a
+It is a
 map\<string, Typography>
 
 ```yaml
@@ -212,30 +212,30 @@ Many design systems follow a grid-based layout. Others, like Liquid Glass, use m
 Example:
 
 ```markdown
-## Layout
-
-The layout follows a **Fluid Grid** model for mobile devices and a
-**Fixed-Max-Width Grid** for desktop (max 1200px).
-
+## Layout
+
+The layout follows a **Fluid Grid** model for mobile devices and a
+**Fixed-Max-Width Grid** for desktop (max 1200px).
+
 A strict 8px spacing scale (with a 4px half-step for micro-adjustments) is used to maintain a consistent rhythm. Components are grouped using "containment" principles, where related items are housed in cards with generous internal padding (24px) to emphasize the soft, approachable nature of the brand.
 ```
 
 ### Design Tokens
 
 The spacing section defines the spacing design tokens. These may include spacing units that are useful for implementing the layout model. For example, a fixed grid layout may have spacing units for column spans, gutters, and margins.
 
-It is a
+It is a
 map\<string, Dimension | number> that maps the spacing scale identifier to a dimension value or a unitless number (e.g., column counts or ratios).
 
 ```yaml
-spacing:
-  base: 16px
-  xs: 4px
-  sm: 8px
-  md: 16px
-  lg: 32px
-  xl: 64px
-  gutter: 24px
+spacing:
+  base: 16px
+  xs: 4px
+  sm: 8px
+  md: 16px
+  lg: 32px
+  xl: 64px
+  gutter: 24px
   margin: 32px
 ```
 
@@ -248,9 +248,9 @@ This section describes how visual hierarchy is conveyed based on the design styl
 Example:
 
 ```markdown
-## Elevation & Depth
-
-Depth is achieved through **Tonal Layers** rather than heavy shadows. The
+## Elevation & Depth
+
+Depth is achieved through **Tonal Layers** rather than heavy shadows. The
 background uses a soft off-white or very light green, while primary content sits on pure white cards.
 ```
 
@@ -261,26 +261,26 @@ This section describes how visual elements are shaped.
 Example:
 
 ```markdown
-## Shapes
-
-The shape language is defined by **Architectural Sharpness**. All interactive
-elements, containers, and inputs utilize a minimal **4px corner radius**. This
-provides just enough softness to feel modern while maintaining a rigid,
+## Shapes
+
+The shape language is defined by **Architectural Sharpness**. All interactive
+elements, containers, and inputs utilize a minimal **4px corner radius**. This
+provides just enough softness to feel modern while maintaining a rigid,
 engineered aesthetic.
 ```
 
 ### Design Tokens
 
-The `rounded` section defines the design tokens for rounded corners used in
+The `rounded` section defines the design tokens for rounded corners used in
 buttons, cards, and other rectangular shapes.
 
 It is a map\<string, Dimension>.
 
 ```yaml
-rounded:
-  sm: 4px
-  md: 8px
-  lg: 12px
+rounded:
+  sm: 4px
+  md: 8px
+  lg: 12px
   full: 9999px
 ```
 
@@ -333,11 +333,11 @@ Each component has a set of properties that are themselves design tokens:
 This section provides practical guidelines and common pitfalls. These act as guardrails when creating designs.
 
 ```markdown
-## Do's and Don'ts
-
-- Do use the primary color only for the single most important action per screen
-- Don't mix rounded and sharp corners in the same view
-- Do maintain WCAG AA contrast ratios (4.5:1 for normal text)
+## Do's and Don'ts
+
+- Do use the primary color only for the single most important action per screen
+- Don't mix rounded and sharp corners in the same view
+- Do maintain WCAG AA contrast ratios (4.5:1 for normal text)
 - Don't use more than two font weights on a single screen
 ```
 
@@ -355,11 +355,11 @@ The following names are commonly used across design systems. They are not requir
 
 When a DESIGN.md consumer encounters content not defined by this spec:
 
-| Scenario | Behavior | Example |
-|---|---|---|
-| Unknown section heading | Preserve; do not error | `## Iconography` |
-| Unknown color token name | Accept if value is valid | `surface-container-high: '#ede7dd'` |
-| Unknown typography token name | Accept as valid typography | `telemetry-data` |
-| Unknown spacing value | Accept; store as string if not a valid dimension | `grid-columns: '5'` |
-| Unknown component property | Accept with warning | `borderColor` |
+| Scenario | Behavior | Example |
+|---|---|---|
+| Unknown section heading | Preserve; do not error | `## Iconography` |
+| Unknown color token name | Accept if value is valid | `surface-container-high: '#ede7dd'` |
+| Unknown typography token name | Accept as valid typography | `telemetry-data` |
+| Unknown spacing value | Accept; store as string if not a valid dimension | `grid-columns: '5'` |
+| Unknown component property | Accept with warning | `borderColor` |
 | Duplicate section heading | Error; reject the file | Two `## Colors` headings |