microsoft/vscode/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:

Read top-down when you're learning the system, and bottom-up when you're fixing a bug: name the feeling, find the principle it breaks, then reach for the move that restores it.

Worked example - a busy panel

- See: a panel feels busy and keeps pulling your eye off the editor.

- Feeling: not Calm, not Focused.

- Principle: breaks Quiet at rest (it carries a permanent fill it shouldn't) and One thing leads (secondary chrome competing with the editor).

- Move: drop the panel to a recessed/transparent background token, reveal its border only on hover, and demote its labels to a quieter type role.

The values: what we design for

These four values name what we want people to feel using VS Code - they're the top layer, the thing every principle and move below is ultimately in service of. Learn them and you can describe almost any bug. Each is a feeling the UI should give; each is upheld by one or more principles below. Reach for the value first, the principle second, the move last.

Say *"this feels noisy, it's not Calm" before "the background should be transparent."* The value points everyone at the same principle.

Why these four?

It's fair to ask: who would ever want a UI that isn't calm, focused, consistent, and delightful? That's exactly the point. These aren't differentiators we're claiming over other products - they're the qualities most under threat in a tool like ours, and naming them is how we defend them. We chose them because they're the values VS Code is structurally inclined to lose:

• Calm is the first casualty of an IDE. VS Code is information-dense and lived in for hours; every feature team has a good reason to add one more affordance, and the sum is noise. Calm is the value that pushes back on our own gravity.
• Focused matters because our surfaces are deep. A screen full of equally-weighted, equally-valid controls is the default failure mode of a power tool. Naming focus forces us to decide what leads.
• Consistent has the largest surface area to defend. VS Code is built by many hands over many years; drift is the natural state. Consistency is less an aspiration than a maintenance discipline.
• Delightful is the one we deliberately ration. It earns its place only by doing a job (Principle 7). We name it not to add more polish but to keep it honest, so delight guides and confirms rather than decorates.

And each value names a real tension, not a free win - which is what makes it a choice worth stating rather than a platitude:

• Calm trades against density - how much do we surface at rest?
• Focused trades against equal access - what do we demote so one thing can lead?
• Consistent trades against the genuinely special case - when is a difference earned rather than drift?
• Delightful trades against restraint - when does a flourish cross into noise?

So the useful question isn't "would we ever not want these?" but "which one is this surface trading away, and did we mean to?" When a value really must yield - say, a critical warning that should break calm to seize attention - that's a deliberate, named exception, not a reason to drop the value.

Principles

Principles are evaluative: each one is a question you can ask of any surface, and the answer tells you whether the design is right - independent of any pixel value. They're grouped by the value they uphold.

Calm

1. Quiet at rest, present on intent

Ask: is anything shouting when nothing is happening?

Chrome should recede until you engage it. A surface carrying a permanent fill, border, or focus ring it hasn't earned is competing with the user's content for attention it doesn't need. The modern look is restrained: things reveal themselves on intent - hover, focus, interaction - and sit quietly otherwise.

Quiet is not hidden. A control can recede without becoming a guessing game: you should still be able to find it, reach it, and see where keyboard focus has landed. Judge calm by how the surface feels to use, not just how little it draws.

When this is wrong it sounds like "this is loud at rest / should be quiet until hover" or "the focus ring is firing on click" - a behavioral description, not a color value.

Carried out by: reveal-on-intent behaviors, one stroke, theme color.

2. Room to breathe

Ask: does this feel cramped, tight, or jagged?

Calm UI is generous and soft. Space isn't wasted; it's what lets the eye rest and groups things without drawing a single line. Edges are rounded rather than sharp. When a surface feels boxed-in or busy, the fix is usually more breathing room on the spacing ramp, not smaller content.

Breathing room is there to serve the work, not squeeze it out. More padding isn't always more calm - especially in a narrow pane or a dense layout. Give the content room to breathe as well as the chrome.

Carried out by: the spacing ramp, elevation tiers (rounded, not sharp).

3. The interface explains itself, plainly and kindly

Ask: could someone understand this at a glance, without guessing?

The UI should read like a person talking. Prefer a word to a mystery glyph; write in sentence case; keep the tone human. A lone unlabeled icon, or a Title-Cased Marketing Headline, makes the user work harder than they should - never cryptic, never shouting.

An explanation should last as long as it's needed. If a field needs a label, its purpose shouldn't disappear when you start typing or wait behind a hover. A clear screen-reader name matters too; neither replaces the other. Gestures need the same kindness: a visible invitation and a keyboard alternative, not a blank patch you have to know to drag.

And an invitation should be honest. A grab hand says "you can move this" - does that move make sense in the layout the user can see? Moving a pane beside another, detaching it, and moving the window are different promises. Make the intended one clear, and make sure the gesture delivers it.

Carried out by: words & casing.

Make unavailable features understandable

Users look for features they have seen in release notes, documentation, or promotion. Silently removing an otherwise relevant option when policy, account entitlement, setup, or version requirements prevent its use makes the product feel broken. Prefer keeping it discoverable but disabled, with a concise, truthful reason and a useful next step.

• Distinguish blocked by organization policy, requires sign-in/upgrade/update, not supported here, and still loading using authoritative state; absence from a list alone is not evidence of policy.
• Reuse existing disabled-row styling and the briefcase indicator for managed policy. Provide a visible reason or independently actionable Learn why link; do not make hover the only way to discover the explanation.
• Presentation must not grant access: block pointer, keyboard, and stale-menu activation while keeping explanatory links operable. Follow the accessibility guidance.
• This is not a blanket rule to expose everything. Preserve explicit feature-hiding choices (including disabled AI), unsupported provider capabilities, and unreleased feature gates. Explain unavailable features where they are relevant without inventing support or exposing sensitive policy values.

Reuse these patterns rather than copying entire implementations:

Worked example - a boxed-in toolbar

- See: a toolbar sits on a solid filled bar, separator lines between every button, the buttons pushed up against each other.

- Feeling: not Calm - busy and boxed-in.

- Principle: breaks Quiet at rest (the fill and separators are permanent chrome that hasn't earned its place) and Room to breathe (buttons jammed together).

- Move: let the bar read transparent at rest, drop the separators (one stroke - and here the answer is no), and space the buttons out on the ramp.

Focused

4. One thing leads; the rest supports

Ask: where does the eye go first - and is anything secondary competing with it?

Every view should have a clear center of attention - the one thing the eye should land on first. Keep secondary information out of that spot: demote it with a quieter type role, a recessed surface, or a smaller icon, so the thing that matters leads and everything else supports it. A view where everything has equal weight is flat - the eye has nowhere to go.