Reduce drift across Copilot instructions, skills, and design-token sources
- Dominant language
- TypeScript
- Stars
- 193k
- Forks
- 42.4k
- PR merge metrics
- PR metrics pending
Description
> [!NOTE]
> Planning follow-up. This issue tracks documentation architecture and generated-reference work; it does not propose changing the current design-token values.
## Problem
VS Code's `.github` instructions and skills intentionally provide different levels of context, but mutable facts are currently copied across several artifacts. Token values, allowed scales, role counts, snap rules, and examples can drift when one copy changes without all of the others.
Recent work in #335346 exposed the maintenance cost: changing the proposed icon-size vocabulary required updates in several documents and still left the auto-applied design-philosophy instruction describing the previous two-size model.
Existing examples show that this is broader than one PR:
- `.github/skills/ux-css-layout/SKILL.md` duplicates most of the detailed design-token tables while calling another file canonical and asking maintainers to keep the copy in sync.
- `.github/skills/ux-theming/SKILL.md` describes `padding: 8px 12px` as off-scale while the design-token instruction uses it as an on-scale example.
- The design-token instruction contains both "use the token variable wherever one exists" and "on-scale raw pixels are fine," leaving the intended review policy ambiguous.
- Runtime registrations, stylelint scales, known-variable lists, tests, instructions, and skills each contain overlapping representations of the same token families.
## Desired ownership
Use one source of truth for each kind of information:
| Information | Owner |
|---|---|
| Current token IDs, values, families, and concise descriptions | Machine-readable runtime data |
| Registration, emitted CSS names, validation, and generated references | Derived from the machine-readable data where layering permits |
| Design values and role-selection rationale | Design-philosophy guidance |
| Layout and composition techniques | CSS-layout guidance |
| Color, high-contrast, and focus behavior | Theming guidance |
| Always-loaded reminders | Short path-scoped instructions that route to the relevant source or skill |
Instructions and skills may repeat stable principles for routing and independent context, but should not manually enumerate mutable token tables or counts. If a complete human-readable token reference is useful, generate it from the machine-readable source and verify it in CI.
## Proposed investigation
1. Inventory duplicated mutable facts across `.github/instructions`, `.github/skills`, runtime registries, validators, tests, and known-variable data.
2. Decide whether `baseSizes.ts` can be the shared machine-readable source or whether a lower-level manifest is needed for build/runtime layering.
3. Derive registration, validation scales, known CSS variable names, and generated reference material where practical.
4. Reduce auto-applied instructions to stable guardrails and routing.
5. Remove detailed token-table mirrors from skills; retain decision logic and representative examples.
6. Add focused drift checks for any projections that must remain duplicated.
7. Clarify whether raw on-scale values are allowed or whether token variables are required.
## Non-goals
- Changing token values as part of the documentation cleanup.
- Requiring every skill to load every other skill.
- Eliminating all repetition; compact stable invariants can remain where independent context is important.
- Adding brittle full-prose snapshot tests.
## Acceptance criteria
- A documented ownership map exists for the affected instructions, skills, and runtime data.
- Current token IDs and values have one machine-readable source of truth.
- Exhaustive Markdown tables are removed or generated rather than manually synchronized.
- Auto-applied instructions do not snapshot mutable counts such as the number of icon-size roles.
- Known contradictions are resolved.
- CI detects drift for any generated or intentionally mirrored token data.
## Related
- #335354 - Predictable UI composition umbrella proposal
- #335346 - Candidate authoring-guidance PR that exposed the drift
Contributor guide
Research direction
Start by inventorying the duplicated facts in .github/instructions, .github/skills/ux-css-layout/SKILL.md, .github/skills/ux-theming/SKILL.md, runtime registries, validators, tests, and known-variable data. Read baseSizes.ts to assess whether it can be the machine-readable source. Done means an ownership map exists, mutable tables are generated or removed, contradictions are resolved, and CI detects required drift.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- build-system, documentation
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100