docs(spec): formalize external @-references in DESIGN.md

README.md

@@ -170,6 +170,15 @@ Valid component properties: `backgroundColor`, `textColor`, `typography`, `round
 
 Variants (hover, active, pressed) are expressed as separate component entries with a related key name.
 
+The components section may use external references (`@<relative-path>`) to point to further elaboration of the component kit, such as component templates in HTML or component source code in JSX:
+
+```markdown
+## Components
+
+- **Buttons** → `@components/button.html` — `button-primary`, `button-secondary`, `button-tertiary`, `button-icon`
+- **Cards** → `@components/card.html` — `card-elevated`, `card-outlined`
+```
+
 ### Consumer Behavior for Unknown Content
 
 | Scenario | Behavior |
@@ -178,6 +187,7 @@ Variants (hover, active, pressed) are expressed as separate component entries wi
 | Unknown color token name | Accept if value is valid |
 | Unknown typography token name | Accept as valid typography |
 | Unknown component property | Accept with warning |
+| External `@`-reference in prose | Preserve; resolve referenced file on demand |
 | Duplicate section heading | Error; reject the file |
 
 ## CLI Reference

docs/spec.md

@@ -97,6 +97,10 @@ Hex notation (`#RRGGBB`) remains the recommended default for simplicity and broa
 
 **Token References**: A token reference must be wrapped in curly braces, and contain an object path to another value in the YAML tree. For most token groups, the reference must point to a primitive value (e.g., `colors.primary-60`), not a group (e.g., `colors`). Within the `components` section, references to composite values (e.g., `{typography.label-md}`) are permitted.
 
+# External References
+
+Any prose in `DESIGN.md` may reference external files using the `@<relative-path>` syntax (for example, `@components/button.html` or `@tokens.json`), where `<relative-path>` is resolved relative to the directory containing `DESIGN.md`.
+
 # Sections
 
 Every `DESIGN.md` follows the same structure. Sections can be omitted if they're not relevant to your project, but those present should appear in the sequence listed below. All sections use `<h2>` (`##`) headings. An optional `<h1>` heading may appear for document titling purposes but is not parsed as a section.
@@ -340,6 +344,18 @@ Each component has a set of properties that are themselves design tokens:
 - height: \<Dimension\>
 - width: \<Dimension\>
 
+The components section may use [external references](#external-references) to point to further elaboration of the component kit, such as component templates in HTML or component source code in JSX.
+
+```markdown
+## Components
+
+Component implementations live as individual HTML sticker sheet files in `components/`. Each file contains the canonical, styled HTML components with `<!-- COMPONENT: name -->` comment markers. Read each file before use.
+
+- **Buttons** → `@components/button.html` — `button-primary`, `button-secondary`, `button-tertiary`, `button-icon`
+- **Cards** → `@components/card.html` — `card-elevated`, `card-outlined`
+- **Input Fields** → `@components/input-field.html` — `input-default`, `input-error`, `input-disabled`
+```
+
 ## Do's and Don'ts
 
 This section provides practical guidelines and common pitfalls. These act as guardrails when creating designs.
@@ -374,4 +390,5 @@ When a DESIGN.md consumer encounters content not defined by this spec:
 | 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` |
+| External `@`-reference in prose | Preserve; resolve referenced file on demand | `@components/button.html`, `@tokens.json` |
 | Duplicate section heading | Error; reject the file | Two `## Colors` headings |

packages/cli/src/linter/index.test.ts

@@ -163,4 +163,50 @@ motion:
     );
     expect(unknownKeyFindings).toEqual([]);
   });
+
+  it('processes a DESIGN.md with external @components/*.html references without errors or orphaned-token warnings', () => {
+    const content = `---
+name: Kindred Spirit
+
+colors:
+  primary: "#647D66"
+  secondary: "#A3B8A5"
+
+typography:
+  headline-lg:
+    fontFamily: Google Sans Display
+    fontSize: 42px
+    fontWeight: 500
+    lineHeight: 50px
+---
+
+## Overview
+
+The palette uses a deep "Evergreen" primary for health-sector credibility.
+
+## Colors
+
+- **Primary (#647D66):** Deep Evergreen for primary actions.
+- **Secondary (#A3B8A5):** Soft sage for secondary surfaces.
+
+## Typography
+
+- **Headline Large:** Google Sans Display at 42px.
+
+## Components
+
+Component implementations live as individual HTML sticker sheet files in \`components/\`. Each file contains the canonical, styled HTML components with \`<!-- COMPONENT: name -->\` comment markers. Read each file before use.
+
+- **Buttons** → \`@components/button.html\` — \`button-primary\`, \`button-secondary\`, \`button-tertiary\`, \`button-icon\`
+- **Cards** → \`@components/card.html\` — \`card-elevated\`, \`card-outlined\`
+- **Input Fields** → \`@components/input-field.html\` — \`input-default\`, \`input-error\`, \`input-disabled\`
+`;
+
+    const result = lint(content);
+
+    expect(result.summary.errors).toBe(0);
+    expect(result.summary.warnings).toBe(0);
+    expect(result.designSystem.sections).toEqual(['Overview', 'Colors', 'Typography', 'Components']);
+  });
 });
+

packages/cli/src/linter/spec-gen/spec.mdx

@@ -61,6 +61,10 @@ The `<scale-level>` placeholder represents a named level in a sizing or spacing
   ```
 **Token References**: A token reference must be wrapped in curly braces, and contain an object path to another value in the YAML tree. For most token groups, the reference must point to a primitive value (e.g., `colors.primary-60`), not a group (e.g., `colors`). Within the `components` section, references to composite values (e.g., `{typography.label-md}`) are permitted.
 
+# External References
+
+Any prose in `DESIGN.md` may reference external files using the `@<relative-path>` syntax (for example, `@components/button.html` or `@tokens.json`), where `<relative-path>` is resolved relative to the directory containing `DESIGN.md`.
+
 # Sections
 
 Every `DESIGN.md` follows the same structure. Sections can be omitted if they're not relevant to your project, but those present should appear in the sequence listed below. All sections use `<h2>` (`##`) headings. An optional `<h1>` heading may appear for document titling purposes but is not parsed as a section.
@@ -256,6 +260,18 @@ Each component has a set of properties that are themselves design tokens:
 
 {componentSubTokenList()}
 
+The components section may use [external references](#external-references) to point to further elaboration of the component kit, such as component templates in HTML or component source code in JSX.
+
+```markdown
+## Components
+
+Component implementations live as individual HTML sticker sheet files in `components/`. Each file contains the canonical, styled HTML components with `<!-- COMPONENT: name -->` comment markers. Read each file before use.
+
+- **Buttons** → `@components/button.html` — `button-primary`, `button-secondary`, `button-tertiary`, `button-icon`
+- **Cards** → `@components/card.html` — `card-elevated`, `card-outlined`
+- **Input Fields** → `@components/input-field.html` — `input-default`, `input-error`, `input-disabled`
+```
+
 ## Do's and Don'ts
 
 This section provides practical guidelines and common pitfalls. These act as guardrails when creating designs.
@@ -286,4 +302,5 @@ When a DESIGN.md consumer encounters content not defined by this spec:
 | 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` |
+| External `@`-reference in prose | Preserve; resolve referenced file on demand | `@components/button.html`, `@tokens.json` |
 | Duplicate section heading | Error; reject the file | Two `## Colors` headings |