design-philosophy
VS Code Design Philosophy
This skill is the canonical VS Code design philosophy — the single source of truth for how we reason about UI, for both developers and agents.
As more and more of the UI is implemented via agents and tooling, the pixels increasingly take care of themselves, and the scarce, human part becomes the design judgment behind them.
This is about shifting left - talking about UI in design terms, not pixels, and having that conversation early. When something looks off, "this is 8px, should be 6px" fixes one number; "this surface is rounded at the wrong elevation tier" names the rule, so the fix lands everywhere and we catch it on a mockup or screenshot rather than in code review. The aim is to agree on what the UI should be and why, in language a designer and an engineer can share - the implementation (which token, which file) tends to follow once the design is settled.
How to read this: three layers
The hardest part of any design language is getting from "this feels off" to a clear, shared fix everyone agrees on. This bridges that in three steps, each explaining the one below it:
| Layer | What it is | Example |
|---|---|---|
| Values | what we want people to feel, and why it's at stake | Focused |
| Principles | evaluative rules you can hold a design up against, phrased as a question | "One thing leads; the rest supports" - where does the eye go first? |
| Moves | the concrete mechanics, each with a rule for which one and why | demote the secondary panel to a recessed background token / a quieter type role |