Harden contract and schema rules #12
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
This PR enhances the Variable Design Standard (VDS) documentation by adding explicit requirement sections, consolidating terminology, and standardizing formatting conventions across contract and schema documentation files.
Changes:
- Added "Requirements" sections to clarify MUST/SHOULD rules at the beginning of major documentation pages
- Standardized list formatting from dash separators to colons (e.g.,
- item - descriptionto- item: description) - Changed terminology from "Mode consistency" to "Mode key sets" and "intentional variants" to "named variants" for clarity
- Added "Failure modes" sections to illustrate consequences of ignoring rules
- Added "No mapped layer" section to anatomy.md defining the three-layer constraint
- Standardized section heading capitalization (e.g., "Validation checklist" to "Validation Checklist")
- Updated title formatting from "Contract - X" to "Contract: X" for consistency
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/schema/index.md | Updated list formatting to use colons and clarified validator language |
| docs/contract/variable-contract.md | Added example, failure modes section, and updated UI frameworks terminology |
| docs/contract/types.md | Added Requirements section and updated list formatting with colons |
| docs/contract/references.md | Added Requirements section and standardized list formatting |
| docs/contract/naming.md | Updated title formatting and added Requirements section |
| docs/contract/modes.md | Changed terminology to "mode key sets", added Requirements section and validation checklist (creates duplicate sections) |
| docs/contract/groups.md | Added Requirements section and standardized heading capitalization |
| docs/contract/dtcg-alignment.md | Added Requirements section, examples, and validation checklist |
| docs/contract/composite-types.md | Added Requirements section, failure modes, and validation checklist (creates duplicate sections) |
| docs/contract/anatomy.md | Updated title formatting, added "No mapped layer" section with extensive guidance, and added "Contract posture" section |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Property-level references: | ||
|
|
||
| - `{variable.fontFamily}` - font family | ||
| - `{variable.fontSize}` - font size | ||
| - `{variable.fontWeight}` - font weight | ||
| - `{variable.letterSpacing}` - letter spacing | ||
| - `{variable.lineHeight}` - line height | ||
| - `{variable.fontFamily}`: font family | ||
| - `{variable.fontSize}`: font size | ||
| - `{variable.fontWeight}`: font weight | ||
| - `{variable.letterSpacing}`: letter spacing | ||
| - `{variable.lineHeight}`: line height |
There was a problem hiding this comment.
The "Property-level references" section appears after the "Out of scope" section, which breaks the logical document flow. This content belongs earlier in the Typography section, near the example code or immediately following it. Consider moving this section to appear before the "Failure modes" section or integrating it into the Typography type description above.
| - Keep alias values direct. One alias hop from base is the default. | ||
| - Do not add a mapped collection in a design tool panel. Use alias modes or file selection. | ||
| - Use CSS cascade layers to select brand output at consumption time. | ||
| - File selection rule selects brands and modes by file selection. |
There was a problem hiding this comment.
This sentence is redundant and unclear: "File selection rule selects brands and modes by file selection." The phrase "file selection" appears twice unnecessarily. Consider revising to something clearer like "Brand and mode selection happens via the file tree structure" or "The file tree determines which brands and modes are selected."
| - File selection rule selects brands and modes by file selection. | |
| - Brand and mode selection is determined by the file tree structure. |
| ## Failure modes | ||
|
|
||
| If mode rules are ignored: | ||
|
|
||
| - Mode keys differ across variables in the same collection | ||
| - Mode values are missing for a required key | ||
| - Theme switching breaks in generated outputs | ||
|
|
||
| ## Validation checklist | ||
|
|
||
| - [ ] Mode keys match across a collection | ||
| - [ ] Mode keys are lowercase strings | ||
| - [ ] Mode values are valid for the variable type | ||
| - [ ] Mode values are either literals or references | ||
|
|
There was a problem hiding this comment.
This creates duplicate "Failure modes" and "Validation checklist" sections in this file. There are already existing sections with these same headings later in the file (around lines 307-324 in the updated version). Having duplicate section headings will confuse readers and is poor document structure. Consider either removing these duplicate sections or consolidating them with the existing ones.
| ## Failure modes | ||
|
|
||
| If composite rules are ignored: | ||
|
|
||
| - Missing required fields for a composite type | ||
| - Property-level references point to incompatible types | ||
| - Consumers cannot render the composite correctly | ||
|
|
||
| ## Validation checklist | ||
|
|
||
| - [ ] Each composite includes all required fields for its type | ||
| - [ ] Each field value matches the expected primitive type | ||
| - [ ] Property-level references resolve to matching fields | ||
|
|
There was a problem hiding this comment.
This creates duplicate "Failure modes" and "Validation checklist" sections in this file. There are already existing sections with these same headings later in the file (around lines 425-442 in the updated version). Having duplicate section headings will confuse readers and is poor document structure. Consider either removing these duplicate sections or consolidating them with the existing ones.
| ## Failure modes | |
| If composite rules are ignored: | |
| - Missing required fields for a composite type | |
| - Property-level references point to incompatible types | |
| - Consumers cannot render the composite correctly | |
| ## Validation checklist | |
| - [ ] Each composite includes all required fields for its type | |
| - [ ] Each field value matches the expected primitive type | |
| - [ ] Property-level references resolve to matching fields |
No description provided.