Add consistency-by-default guidance for UI pattern decisions

[chryw]

Note

Planning follow-up. This proposes a lightweight authoring and review principle, not a requirement to copy existing UI, a broad migration, or an automatic lint rule.

Problem

VS Code is built by many teams across old and new UI generations. When adding or changing a visual or interaction pattern, two opposite failure modes are possible:

1. Unnecessary invention: a new local treatment is slightly different from an equivalent existing experience. Each difference adds customer learning load and creates another implementation to maintain.
2. Blind reuse: an existing implementation is treated as authoritative even when it is legacy, accidental, inaccessible, inconsistent with current design direction, or simply wrong for the new user need.

Current guidance says to reuse components and follow shared design ramps, but it does not provide a repeatable way to evaluate prior art, distinguish stable conventions from historical accidents, or explain when divergence is justified.

Recent work on #335583 illustrates both sides. Reusing the existing GitHub hover components avoided a new card language, but a broader comparison still found inherited choices that should not be propagated unchanged: an outdated title hierarchy, duplicate boundary padding, an unnecessary divider, and submenu chrome that differed from the standard popup containing it.

Proposed principle

Consistency by default, intentional divergence. Before introducing or changing a visual or interaction pattern, identify the closest analogous experiences and canonical guidance. Reuse shared semantics, behavior, and component contracts when their roles match, because unnecessary variation increases customer learning load. Treat existing implementations as evidence, not authority: do not preserve known debt, deprecated patterns, accessibility problems, or accidental styling. Diverge when a clear user need, accessibility requirement, simplification, or current design direction calls for it; make the reason explicit and decide whether the shared owner should evolve.

The goal is familiarity without stagnation: like things should behave alike unless a difference does useful work.

Suggested lightweight workflow

For UI work, proportionate to the size and risk of the change:

1. Name the role and user task. Compare surfaces that serve the same purpose, not merely elements that look similar.
2. Inspect representative prior art and canonical guidance. Prefer shared primitives, current design guidance, and actively maintained/recently accepted surfaces over an isolated historical example.
3. Separate invariants from accidents. Identify which semantics, interactions, accessibility behavior, ownership boundaries, and visual roles should stay consistent; do not copy incidental DOM or CSS.
4. Classify the decision. State what is reused, adapted, or new. For a small change this can be implicit in the diff or review description; larger explorations may benefit from a short provenance table.
5. Justify divergence. A new treatment should answer an unmet user need, remove complexity, improve accessibility, or advance an accepted design direction—not exist only because it was easy to implement locally.
6. Choose the right owner. If the improved behavior should apply to equivalent surfaces, evolve the shared component or contract when there is demonstrated production need. Otherwise keep a clearly scoped local exception.
7. Validate equivalent scenarios. Use production components and focused fixtures where useful; check the relevant density, theme, keyboard, and accessibility states rather than validating only the new happy path.

Resolving conflicting prior art

Existing code will often disagree. Use this evidence order as a review heuristic, not a mechanical ranking:

1. Accepted canonical design/accessibility guidance and explicit component contracts.
2. Shared primitives and actively maintained, recently reviewed comparable surfaces.
3. Local conventions in the feature area, when they do not conflict with the above.
4. Isolated legacy implementations, which are useful evidence but not precedent by default.

When no direction is clearly established, preserve behavior for narrow maintenance work and surface the uncertainty. For a genuinely new pattern, seek product/design input rather than selecting whichever old example is easiest to copy.

Guardrails

• Do not require exhaustive repository archaeology or a fixed number of examples.
• Do not make “most common” or “oldest” synonymous with correct.
• Do not force reuse, inheritance, or a shared abstraction when roles differ.
• Finding a related component does not imply it must be extended; a documented no-reuse conclusion is valid.
• Do not block experiments. Treat them as explicit experiments, keep them scoped, and use what is learned to decide whether a pattern should become shared.
• Do not require competitor research for routine UI changes.
• Do not duplicate mutable component inventories or token tables across instructions and skills.
• Keep automatic enforcement out of scope until repeated accepted work reveals a precise mechanically checkable rule.

Guidance placement

Coordinate with #335370's source-of-truth model:

• Add a short stable principle/router to the auto-applied design instruction.
• Keep the detailed workflow, examples, and feedback language in the canonical design-philosophy skill.
• Let layout, theming, accessibility, and component-fixture skills retain their domain-specific techniques rather than repeating this full checklist.

This is broader than #335346's candidate one relationship, one owner composition heuristic. That guidance is one example of applying the principle; this issue covers visual and interaction pattern decisions generally.

Acceptance criteria

• Canonical UI guidance states consistency by default, intentional divergence or an equivalent high-level principle.
• Guidance explicitly says existing code is evidence, not authority, and warns against copying legacy or accidental patterns.
• A lightweight, proportional prior-art workflow covers reuse, adaptation, new work, and justified exceptions.
• Guidance protects accessibility improvements, modernization, simplification, necessary product differences, and experimentation.
• The workflow discourages unnecessary local variants and customer learning load without requiring forced abstraction.
• The detailed workflow has one canonical owner and auto-applied instructions remain concise, consistent with Reduce drift across Copilot instructions, skills, and design-token sources #335370.

Related

• Predictable UI composition: relationship ownership #335354 — predictable UI composition umbrella and guardrails against over-engineering
• Document the UI composition ownership heuristic #335346 — candidate UI relationship-ownership guidance and prior-art audit example
• Add UI composition size tokens #335345 — shared composition-token foundation
• Reduce drift across Copilot instructions, skills, and design-token sources #335370 — instruction/skill source-of-truth and drift reduction
• sessions: add rich GitHub reference previews #335583 — GitHub reference-hover exploration that motivated the broader guidance

[chryw]

Learning context from the #335583 exploration

Adding this note as a handoff for a future session. The GitHub reference-hover exploration provided a useful concrete test of the proposed principle.

Finding prior art was necessary, but not sufficient

The exploration started by reusing the existing production issue/PR hover components rather than inventing a new card. That was the right first move, but the reused components still carried historical choices that did not hold up in the new composition:

• The standalone hover retained an 18px heading while the nested version used the calmer 13px utility-title role. Equivalent content changed hierarchy depending on whether one reference or a collection happened to exist.
• A divider inherited from the old card separated title and excerpt even though they formed one summary; removing it reduced chrome without losing meaning.
• Generic managed-hover padding combined with card-owned section padding, producing a double inset and preventing section boundaries from reaching the popup edge.
• The nested panel was already an ActionWidget, but an older submenu rule overrode the standard popup radius and shadow, making parent and child popup chrome subtly different.
• A 12px title-to-description gap remained after the divider was removed. Comparing with the current SessionSummaryHover pattern showed that the tighter 8px relationship was the established role.

The lesson is: do not stop after finding and reusing an existing component. Check how that component behaves in each host and distinguish its stable contract from inherited or accidental presentation.

Reuse that did hold up

The same exercise identified conventions worth reusing directly:

• fromNow(...) and the Sessions PR picker's updated {relative time} wording for glanceable recency.
• The standard ActionWidget popup border, outer-radius tier, menu background, and shadow.
• The 13px semibold utility-title role used by comparable Sessions metadata hovers.
• Existing ActionList listbox/dialog semantics and ActionBar focus behavior.
• Existing issue/PR state models, icons, link behavior, and PR branch-pill styling.
• Existing two-line clamp behavior for bounded workbench summaries.

This is why “existing code is evidence, not authority” is important: the result reused more of VS Code's shared language after selectively correcting the old component.

Customer-learning-load example

A single reference chip and an item inside a collection initially risked becoming two different experiences. The final direction used:

• the same identity, lifecycle, time, title, description, links, and branch information;
• the same title hierarchy and interaction semantics;
• different density only where the hosting composition required it.

A useful review question is:

If the same user concept appears through two paths, what difference does the user need to learn, and what useful job does that difference perform?

If the answer is “none,” the difference is probably drift.

Practical workflow that exposed the issues

A proportional pattern check can be concrete and lightweight:

1. Search for the existing component and all meaningful call sites, not just one screenshot.
2. Inspect one or more current analogous surfaces serving the same user task.
3. Compare semantic content, hierarchy, interaction, accessibility, density, boundary ownership, and popup chrome separately.
4. Render the actual production component in fixtures; do not copy or recompose it for the fixture.
5. Exercise real product paths where host composition matters. In this case, both a single chip and a collection were necessary.
6. Include stress states that reveal hidden assumptions: open/draft/closed/merged/not-planned, very long titles, long Markdown, light/dark, keyboard, and screen reader.
7. When something looks wrong, inspect computed ownership before applying CSS. The double padding and popup-chrome mismatch were caused by parent/child composition, not by the GitHub content itself.

This should remain proportional. Routine changes should not require a report, competitor survey, or exhaustive repository search.

Candidate concise auto-applied instruction

The detailed workflow belongs in the canonical design-philosophy skill, but the auto-applied instruction could stay close to one stable paragraph:

Consistency by default, intentional divergence. Before introducing or changing a visual or interaction pattern, inspect the closest analogous experiences and canonical guidance. Reuse shared semantics, behavior, and component contracts when their roles match; unnecessary variation increases customer learning load. Treat existing code as evidence, not authority: do not preserve known debt, deprecated patterns, accessibility problems, or accidental styling. Diverge when a clear user need, accessibility requirement, simplification, or current design direction calls for it, and make that reason explicit.

Possible shorter review prompt:

What is reused, what intentionally differs, and what user need earns the difference?

Suggested implementation boundaries

To stay aligned with #335370:

• Put the concise invariant/router in the auto-applied design instruction.
• Put the workflow, evidence hierarchy, examples, and feedback language in the design-philosophy skill.
• Let ux-css-layout, ux-theming, accessibility, and component-fixtures own their specialized techniques and link back rather than restating the complete workflow.
• Avoid mutable inventories of “approved components” or “good examples”; those would age quickly and recreate the drift problem.

Open decisions for the future work

• Should provenance be expected in PR descriptions only when a new pattern or intentional divergence is introduced, rather than for every UI edit?
• Should code-review guidance include the short prompt above, or would that create another duplicated owner?
• How should guidance describe “current” prior art without maintaining a brittle allowlist? A likely answer is to prefer canonical guidance, shared primitives, and recently reviewed analogous surfaces while treating isolated legacy examples cautiously.
• Should experiments use an explicit label or documentation convention, or is a clearly scoped PR description sufficient?

Related evidence and visuals remain in draft PR #335583 and its linked design report.