Copilot instructions

1---
2description: Design-system size tokens (spacing, corner radius, font size, codicon size, stroke). Use when writing or editing CSS to size, space, or round UI — prefer the `--vscode-*` token vars over hardcoded px values.
3applyTo: src/vs/**/*.css
4---
5 
6# Design tokens for sizing, spacing & radii
7 
8> **These tokens are the *moves*, not the reasoning.** They implement the
9> **design philosophy** (Values → Principles → Moves): reach for a token *after*
10> naming the feeling and the principle it serves - a radius is an *elevation
11> tier*, a font is a *type role*, not a number. See the
12> [`design-philosophy` skill](../skills/design-philosophy/SKILL.md) for the full
13> vocabulary, worked examples, and how to give UI feedback in design terms.
14 
15VS Code ships a design-system **size** ramp. These tokens are registered in
16[baseSizes.ts](../../src/vs/platform/theme/common/sizes/baseSizes.ts) (and the
17agents font ramp in [sizes.ts](../../src/vs/sessions/common/sizes.ts)) and are
18emitted as `--vscode-*` CSS variables. **When generating or editing CSS, use the
19token variable instead of a raw `px` value** wherever a token exists for that
20value. This keeps new UI visually consistent with the design system.
21 
22> Every `--vscode-*` size var you reference must already exist in
23> [vscode-known-variables.json](../../build/lib/stylelint/vscode-known-variables.json)
24> (`"sizes"` array, alphabetically sorted) or stylelint/hygiene fails. Adding a
25> *new* token means adding it both in `baseSizes.ts` and that JSON file.
26 
27## Spacing — padding, margin, gap
28 
29Use for `padding`, `margin`, `gap`, and fixed `width`/`height` of spacers.
30The numeric token name is the value in tenths of a px (`size200` = 20px).
31 
32| px | Variable |
33|----|----------|
34| 0  | `--vscode-spacing-sizeNone` |
35| 2  | `--vscode-spacing-size20` |
36| 4  | `--vscode-spacing-size40` |
37| 6  | `--vscode-spacing-size60` |
38| 8  | `--vscode-spacing-size80` |
39| 10 | `--vscode-spacing-size100` |
40| 12 | `--vscode-spacing-size120` |
41| 16 | `--vscode-spacing-size160` |
42| 20 | `--vscode-spacing-size200` |
43| 24 | `--vscode-spacing-size240` |
44| 28 | `--vscode-spacing-size280` |
45| 32 | `--vscode-spacing-size320` |
46| 36 | `--vscode-spacing-size360` |
47| 40 | `--vscode-spacing-size400` |
48 
49```css
50/* token   */          padding: var(--vscode-spacing-size80) var(--vscode-spacing-size120);
51/* also ok */          padding: 8px 12px;   /* on-scale raw px is fine */
52/* avoid   */          padding: 5px 7px;    /* off-scale - breaks rhythm */
53```
54 
55**What matters is the value, not the token.** Adopting the `var()` is optional —
56a raw px value is fine **as long as it lands on the scale** (0, 2, 4, 6, 8, 10,
5712, 16, 20, 24, 28, 32, 36, 40). What breaks visual rhythm is an **off-scale**
58value (3, 5, 7, 14, 26px…). Snap those to the nearest scale value (ties round
59**up**), e.g. `5px → 6px`, `3px → 4px`, `1px → 2px`, `26px → 28px`. Each length
60of a shorthand is checked independently (`0 5px → 0 6px`). `auto`, `%`,
61`em`/`rem`, and any `var()`/`calc()` expression are left untouched.
62 
63## Corner radius — `border-radius`
64 
65| px | Variable | Use |
66|----|----------|-----|
67| 2  | `--vscode-cornerRadius-xSmall` | very compact elements |
68| 4  | `--vscode-cornerRadius-small` | controls (buttons, inputs) |
69| 6  | `--vscode-cornerRadius-medium` | base / inner surfaces |
70| 8  | `--vscode-cornerRadius-large` | prominent / outer surfaces |
71| 12 | `--vscode-cornerRadius-xLarge` | very prominent surfaces |
72| 9999 | `--vscode-cornerRadius-circle` | fully rounded (pills, dots) |
73 
74**Snap map** for off-scale literals (ties round **up**):
75`2→xSmall`, `3,4→small`, `5,6→medium`, `7,8→large`, `10,11,12→xLarge`,
76`14,16,18,20→xLarge`, `999→circle`.
77 
78- **Pills** (radius ≈ half the element height, e.g. `28h`/`14r`, `36h`/`18r`,
79  `22×22`/`11r`) → `--vscode-cornerRadius-circle`, **not** xLarge. The
80  literal-nearest token would square them and lose the fully-rounded intent.
81- **Leave untouched:** `50%`, `0`, `0px`, `inherit`, and any `calc()`/`var()`
82  expression. Preserve `!important`.
83 
84## Font size — `font-size`
85 
86Generic UI ramp — pair a **size** token with a **weight** token; "Strong"
87reuses the matching size token + `fontWeight.semiBold`, **never** a separate
88"strong" size:
89 
90| px | Size var | Weight |
91|----|----------|--------|
92| 26 | `--vscode-fontSize-heading1` | semiBold |
93| 18 | `--vscode-fontSize-heading2` | semiBold |
94| 13 | `--vscode-fontSize-heading3` | semiBold |
95| 13 | `--vscode-fontSize-body1` | regular |
96| 11 | `--vscode-fontSize-body2` | regular |
97| 12 | `--vscode-fontSize-label1` | regular |
98| 11 | `--vscode-fontSize-label2` | regular |
99| 10 | `--vscode-fontSize-label3` | regular |
100 
101**Deprecated** — the legacy `--vscode-bodyFontSize*` tokens are deprecated. Use
102the generic ramp above instead:
103 
104| Deprecated | px | Use instead |
105|------------|----|-------------|
106| `--vscode-bodyFontSize` | 13 | `--vscode-fontSize-body1` |
107| `--vscode-bodyFontSize-small` | 12 | `--vscode-fontSize-label1` |
108| `--vscode-bodyFontSize-xSmall` | 11 | `--vscode-fontSize-body2` |
109 
110Agents window ramp (`src/vs/sessions/**`) — identical values, `agents-`-prefixed
111(pair size with a weight token, **never** add a separate "strong" size):
112 
113| px | Size var | Weight |
114|----|----------|--------|
115| 26 | `--vscode-agents-fontSize-heading1` | semiBold |
116| 18 | `--vscode-agents-fontSize-heading2` | semiBold |
117| 13 | `--vscode-agents-fontSize-heading3` | semiBold |
118| 13 | `--vscode-agents-fontSize-body1` | regular |
119| 11 | `--vscode-agents-fontSize-body2` | regular |
120| 12 | `--vscode-agents-fontSize-label1` | regular |
121| 11 | `--vscode-agents-fontSize-label2` | regular |
122| 10 | `--vscode-agents-fontSize-label3` | regular |
123 
124Weights: `--vscode-agents-fontWeight-regular` (400),
125`--vscode-agents-fontWeight-semiBold` (600). The ramp is **400/600 only** — there
126is no medium (500). "Strong" = same size token + `semiBold`. See
127[Font weight](#font-weight--font-weight) below.
128 
129## Font weight — `font-weight`
130 
131Both the generic and agents ramps use a **two-weight ramp** — there are no other
132weights. Pair every text style with one of these:
133 
134| weight | Generic var | Agents var | Use |
135|--------|-------------|------------|-----|
136| 400 | `--vscode-fontWeight-regular` | `--vscode-agents-fontWeight-regular` | body, labels, metadata |
137| 600 | `--vscode-fontWeight-semiBold` | `--vscode-agents-fontWeight-semiBold` | headings, "strong" emphasis |
138 
139- **No medium (500).** `font-weight: 500` is **off the ramp** — snap it to
140  `semiBold` (600). The same goes for `700`/`bold` and any other numeric weight:
141  round to the nearer of 400/600.
142- **"Strong" is not a separate size.** A "Body 1 Strong" / "Label 2 Strong"
143  style reuses the matching `--vscode-fontSize-*` (or `--vscode-agents-fontSize-*`)
144  token paired with `semiBold`. Never introduce a separate strong *size* token.
145- `normal` ≡ 400 → `regular`. **Leave untouched:** `inherit`, `lighter`,
146  `bolder`, and any `var()`/`calc()` expression. Preserve `!important`.
147 
148```css
149/* avoid */            font-weight: 500;   /* not on the 400/600 ramp */
150/* prefer */           font-weight: var(--vscode-fontWeight-semiBold);
151```
152 
153## Codicon size — icon `font-size`
154 
155Codicons are **only ever 16px or 12px**. There is no in-between size — never use
156`14px` (or any other value) for a codicon. Pick the base or the compact token:
157 
158| px | Variable | Use |
159|----|----------|-----|
160| 16 | `--vscode-codiconFontSize` (base) | default icon size |
161| 12 | `--vscode-codiconFontSize-compact` | dense/inline chrome |
162 
163If a design or existing CSS sizes a codicon at 14px, treat it as a bug: snap it to
16416 (default) or 12 (compact) and flag it.
165 
166When sizing an icon at the **compact** 12px size, also swap the registered glyph
167to its `*Compact` variant (e.g. `Codicon.close` → `Codicon.closeCompact`) so the
168icon is visually optimized for the small size. CSS `font-size` alone only scales
169the icon — it does not change to the compact glyph. Only swap the glyph when no
170CSS selector targets the original glyph class (e.g. `.codicon-close`), otherwise
171update that selector too. Some icons (agent, vm, info, lock) have no compact
172variant — keep the regular glyph at the compact size.
173 
174## Stroke — border width
175 
176The design system has a **single** stroke thickness: 1px. Any `border`/`outline`
177width of 1px should use the token.
178 
179| px | Variable |
180|----|----------|
181| 1  | `--vscode-strokeThickness` |
182 
183```css
184/* prefer */           border: var(--vscode-strokeThickness) solid var(--vscode-widget-border);
185/* avoid  */           border: 1px solid var(--vscode-widget-border);
186```
187 
188Applies to the `border: 1px solid <color>` shorthand and `border-width: 1px`.
189Other widths have no token — leave them as-is.
190 
191## `.monaco-editor-background` must be opaque
192 
193`.monaco-editor-background` must use a fully opaque color — making it
194`transparent` (or any partial alpha) is forbidden. Monaco reuses this layer to
195carve the reverse-rounded notches out of text selections, so a non-opaque
196background introduces subtle rendering bugs (blocky selection corners) and
197performance problems. To blend an embedded editor into its surface, keep
198`.monaco-editor` transparent and paint `.monaco-editor-background` with the
199container's solid background color.
200