diff --git a/README.md b/README.md index ed855c5..267f341 100644 --- a/README.md +++ b/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 (`@`) 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 diff --git a/docs/spec.md b/docs/spec.md index 5995e54..41de6d7 100644 --- a/docs/spec.md +++ b/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 `@` syntax (for example, `@components/button.html` or `@tokens.json`), where `` 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 `

` (`##`) headings. An optional `

` 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: \ - width: \ +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 `` 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 | diff --git a/packages/cli/src/linter/index.test.ts b/packages/cli/src/linter/index.test.ts index ba12e98..7bd87ba 100644 --- a/packages/cli/src/linter/index.test.ts +++ b/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 \`\` 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']); + }); }); + diff --git a/packages/cli/src/linter/spec-gen/spec.mdx b/packages/cli/src/linter/spec-gen/spec.mdx index c9e417d..6a1f987 100644 --- a/packages/cli/src/linter/spec-gen/spec.mdx +++ b/packages/cli/src/linter/spec-gen/spec.mdx @@ -61,6 +61,10 @@ The `` 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 `@` syntax (for example, `@components/button.html` or `@tokens.json`), where `` 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 `

` (`##`) headings. An optional `

` 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 `` 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 |