[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M78GXCXSWPCK57BNFWEPVGZH":3,"skill-same:01M78GXCXSWPCK57BNFWEPVGZH":44},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M78GXCXSWPCK57BNFWEPVGZH","design-philosophy",null,"The VS Code (and so Ganttee) design philosophy — a shared Values→Principles→Moves vocabulary for reasoning about UI in design terms instead of raw pixels. Use when designing, building, reviewing, or giving feedback on any visual surface; when deciding a radius, spacing, type role, icon size, border, color, or motion; or when translating a \"this feels off\" observation into a concrete, principled fix.","sergehas\u002Fganttee","sergehas","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F55877559?v=4","01M78GWP103XC9MZP2826NNTF3","01M78GWP22QVFBQNG8FAPPHE7Z",1,"AGPL-3.0","https:\u002F\u002Fgithub.com\u002Fsergehas\u002Fganttee\u002Fblob\u002Fdevelop\u002F.github\u002Fskills\u002Fdesign-philosophy\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: design-philosophy\ndescription:\n  The VS Code (and so Ganttee) design philosophy — a shared Values→Principles→Moves vocabulary for\n  reasoning about UI in design terms instead of raw pixels. Use when designing, building, reviewing,\n  or giving feedback on any visual surface; when deciding a radius, spacing, type role, icon size,\n  border, color, or motion; or when translating a \"this feels off\" observation into a concrete,\n  principled fix.\n---\n\n# VS Code Design Philosophy\n\nThis skill is the **canonical VS Code design philosophy** — the single source of truth for how we\nreason about UI, for both developers and agents.\n\nAs more and more of the UI is implemented via agents and tooling, the pixels increasingly take care\nof themselves, and the scarce, human part becomes the design judgment behind them.\n\nThis is about _shifting left_ - talking about UI in design terms, not pixels, and having that\nconversation early. When something looks off, \"this is 8px, should be 6px\" fixes one number; \"this\nsurface is rounded at the wrong _elevation tier_\" names the rule, so the fix lands everywhere and we\ncatch it on a mockup or screenshot rather than in code review. The aim is to agree on _what the UI\nshould be and why_, in language a designer and an engineer can share - the implementation (which\ntoken, which file) tends to follow once the design is settled.\n\n---\n\n## How to read this: three layers\n\nThe hardest part of any design language is getting from _\"this feels off\"_ to a clear, shared fix\neveryone agrees on. This bridges that in three steps, each explaining the one below it:\n\n| Layer          | What it is                                                               | Example                                                                           |\n| -------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |\n| **Values**     | what we want people to _feel_, and why it's at stake                     | _Focused_                                                                         |\n| **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?_             |\n| **Moves**      | the concrete mechanics, each with a rule for _which one and why_         | _demote the secondary panel to a recessed background token \u002F a quieter type role_ |\n\nRead top-down when you're learning the system, and bottom-up when you're fixing a bug: name the\n**feeling**, find the **principle** it breaks, then reach for the **move** that restores it.\n\n> **Worked example - a busy panel**\n>\n> - **See:** a panel feels busy and keeps pulling your eye off the editor.\n> - **Feeling:** not _Calm_, not _Focused_.\n> - **Principle:** breaks _Quiet at rest_ (it carries a permanent fill it shouldn't) and _One thing\n>   leads_ (secondary chrome competing with the editor).\n> - **Move:** drop the panel to a recessed\u002Ftransparent background token, reveal its border only on\n>   hover, and demote its labels to a quieter type role.\n\n---\n\n## The values: what we design for\n\nThese four values name what we want people to _feel_ using VS Code - they're the top layer, the\nthing every principle and move below is ultimately in service of. Learn them and you can describe\nalmost any bug. Each is a _feeling_ the UI should give; each is upheld by one or more **principles**\nbelow. Reach for the value first, the principle second, the move last.\n\n| Value          | Means                                                                                | When it's broken it feels…                    | Principles |\n| -------------- | ------------------------------------------------------------------------------------ | --------------------------------------------- | ---------- |\n| **Calm**       | quiet at rest, uncluttered; room to breathe; soft, not sharp; plain-spoken and human | busy, noisy, cramped, jagged, cryptic, shouty | 1, 2, 3    |\n| **Focused**    | clear hierarchy; one thing leads, the rest supports                                  | flat, samey, the eye has nowhere to go        | 4, 5       |\n| **Consistent** | everything sits on the same ramps and tiers                                          | random, off-grid, drifting                    | 5, 6       |\n| **Delightful** | small moments that _do a job_ - guide, confirm, orient                               | lifeless, abrupt, or gimmicky                 | 7          |\n\n> Say _\"this feels noisy, it's not **Calm**\"_ before _\"the background should be transparent.\"_ The\n> value points everyone at the same principle.\n\n### Why these four?\n\nIt's fair to ask: who would ever _want_ a UI that isn't calm, focused, consistent, and delightful?\nThat's exactly the point. These aren't differentiators we're claiming over other products - they're\nthe qualities most **under threat in a tool like ours**, and naming them is how we defend them. We\nchose them because they're the values VS Code (and so Ganttee) is structurally inclined to _lose_:\n\n- **Calm** is the first casualty of an IDE. VS Code (and so Ganttee) is information-dense and lived\n  in for hours; every feature team has a good reason to add one more affordance, and the sum is\n  noise. Calm is the value that pushes back on our own gravity.\n- **Focused** matters because our surfaces are _deep_. A screen full of equally-weighted,\n  equally-valid controls is the default failure mode of a power tool. Naming focus forces us to\n  decide what leads.\n- **Consistent** has the largest surface area to defend. VS Code (and so Ganttee) is built by many\n  hands over many years; drift is the natural state. Consistency is less an aspiration than a\n  maintenance discipline.\n- **Delightful** is the one we deliberately **ration**. It earns its place only by doing a job\n  (Principle 7). We name it not to add more polish but to keep it honest, so delight guides and\n  confirms rather than decorates.\n\nAnd each value names a real **tension**, not a free win - which is what makes it a choice worth\nstating rather than a platitude:\n\n- **Calm** trades against **density** - how much do we surface at rest?\n- **Focused** trades against **equal access** - what do we demote so one thing can lead?\n- **Consistent** trades against the **genuinely special case** - when is a difference earned rather\n  than drift?\n- **Delightful** trades against **restraint** - when does a flourish cross into noise?\n\nSo the useful question isn't _\"would we ever not want these?\"_ but _\"which one is this surface\ntrading away, and did we mean to?\"_ When a value really must yield - say, a critical warning that\n_should_ break calm to seize attention - that's a deliberate, named exception, not a reason to drop\nthe value.\n\n---\n\n## Principles\n\nPrinciples are **evaluative**: each one is a question you can ask of any surface, and the answer\ntells you whether the design is right - independent of any pixel value. They're grouped by the value\nthey uphold.\n\n---\n\n### Calm\n\n#### 1. Quiet at rest, present on intent\n\n> **Ask:** _is anything shouting when nothing is happening?_\n\nChrome should recede until you engage it. A surface carrying a permanent fill, border, or focus ring\nit hasn't earned is competing with the user's content for attention it doesn't need. The modern look\nis **restrained**: things reveal themselves _on intent_ - hover, focus, interaction - and sit\nquietly otherwise.\n\nWhen this is wrong it sounds like _\"this is loud at rest \u002F should be quiet until hover\"_ or _\"the\nfocus ring is firing on click\"_ - a behavioral description, not a color value.\n\n_Carried out by:_ [reveal-on-intent behaviors](#reveal-on-intent), [one stroke](#one-stroke),\n[theme color](#theme-color).\n\n#### 2. Room to breathe\n\n> **Ask:** _does this feel cramped, tight, or jagged?_\n\nCalm UI is generous and soft. Space isn't wasted; it's what lets the eye rest and groups things\nwithout drawing a single line. Edges are rounded rather than sharp. When a surface feels boxed-in or\nbusy, the fix is usually more breathing room on the spacing ramp, not smaller content.\n\n_Carried out by:_ [the spacing ramp](#spacing-ramp), [elevation tiers](#elevation-tiers) (rounded,\nnot sharp).\n\n#### 3. The interface explains itself, plainly and kindly\n\n> **Ask:** _could someone understand this at a glance, without guessing?_\n\nThe UI should read like a person talking. Prefer a word to a mystery glyph; write in sentence case;\nkeep the tone human. A lone unlabeled icon, or a Title-Cased Marketing Headline, makes the user work\nharder than they should - never cryptic, never shouting.\n\n_Carried out by:_ [words & casing](#words-casing).\n\n> **Worked example - a boxed-in toolbar**\n>\n> - **See:** a toolbar sits on a solid filled bar, separator lines between every button, the buttons\n>   pushed up against each other.\n> - **Feeling:** not _Calm_ - busy and boxed-in.\n> - **Principle:** breaks _Quiet at rest_ (the fill and separators are permanent chrome that hasn't\n>   earned its place) and _Room to breathe_ (buttons jammed together).\n> - **Move:** let the bar read transparent at rest, drop the separators (one stroke - and here the\n>   answer is _no_), and space the buttons out on the ramp.\n\n### Focused\n\n#### 4. One thing leads; the rest supports\n\n> **Ask:** _where does the eye go first - and is anything secondary competing with it?_\n\nEvery view should have a clear **center of attention** - the one thing the eye should land on first.\nKeep secondary information _out_ of that spot: demote it with a quieter type role, a recessed\nsurface, or a smaller icon, so the thing that matters leads and everything else supports it. A view\nwhere everything has equal weight is _flat_ - the eye has nowhere to go.\n\n_Carried out by:_ [type roles](#type-ramp), [elevation tiers](#elevation-tiers),\n[icon size by context](#icon-sizes).\n\n#### 5. Elevation is encoded, not eyeballed\n\n> **Ask:** _does this surface's roundness match how far it floats above what's beneath it?_\n\nHow rounded - and how raised - a surface is _means something_: it tells you where the surface sits\nin the stack. A floating overlay reads as more rounded than a control sitting flat inside a pane.\nRadius is chosen by the surface's role in the hierarchy, never by taste. (This serves both\n**Focused** and **Consistent**.)\n\n_Carried out by:_ [elevation tiers](#elevation-tiers---round-by-role-not-by-literal),\n[reveal-on-intent](#reveal-on-intent-behaviors) (scroll shadows).\n\n> **Worked example - a flat settings row**\n>\n> - **See:** a settings row shows its label, its help text, and a \"Reset\" action all at the same\n>   size and weight.\n> - **Feeling:** not _Focused_ - flat; the eye doesn't know where to land.\n> - **Principle:** breaks _One thing leads_ - nothing is the center of attention.\n> - **Move:** lift the label to the leading type role, demote the help text to `body2`, and make\n>   \"Reset\" a quiet secondary action so the row reads top-down.\n\n### Consistent\n\n#### 6. Sameness signals sameness\n\n> **Ask:** _do two like things look identical - and is any difference here intentional?_\n\nEquivalent elements must look equivalent, because they pull from the same named scale. When two\nsimilar things differ, that difference should _mean_ something; accidental drift is the enemy. This\nis why every size, radius, weight, and color is a **named token with a role**, not a literal - the\nliteral is only ever a stand-in for the token it lands on.\n\n_Carried out by:_ every move below - they _are_ the shared scales. See especially\n[design tokens](#design-tokens), [the spacing ramp](#spacing-ramp), [the type ramp](#type-ramp),\n[icon sizes](#icon-sizes), [one stroke](#one-stroke).\n\n> **Worked example - two mismatched dialogs**\n>\n> - **See:** two dialogs open side by side; one has 8px corners, the other 6px - both are floating\n>   overlays.\n> - **Feeling:** not _Consistent_ - the UI feels like it's drifting.\n> - **Principle:** breaks _Sameness signals sameness_ (two equivalent surfaces look different for no\n>   reason) and _Elevation is encoded_ (an overlay belongs on the Outer tier).\n> - **Move:** point both at the Outer radius token; the 6px was a literal someone typed instead of\n>   naming the tier.\n\n### Delightful\n\n#### 7. Delight earns its keep\n\n> **Ask:** _what does this help the user do?_\n\nMotion, reveals, and finishing touches are welcome - but each must **do a job**: guide the eye,\nconfirm an action, orient the user, or smooth a jump. If there's no answer to the question, it's\ndecoration, and decoration reads as noise (back to **Calm**). Keep it subtle, short, and\ninterruptible; honor `prefers-reduced-motion`; never animate for its own sake.\n\nA delight bug sounds like _\"this transition is doing nothing for me\"_ (cut it) or _\"this jump is\ndisorienting - it needs a functional transition\"_ (add one) - not a duration or easing value to\nfiddle with.\n\n_Carried out by:_ [reveal-on-intent behaviors](#reveal-on-intent).\n\n> **Worked example - a bouncing panel**\n>\n> - **See:** a side panel slides in with a 600ms bounce every time you toggle it.\n> - **Feeling:** not _Delightful_ (gimmicky) and not _Calm_ (slow and shouty).\n> - **Principle:** breaks _Delight earns its keep_ - the bounce isn't doing a job, and the toggle is\n>   already obvious.\n> - **Move:** if nothing needs orienting, cut the animation; if the panel's arrival genuinely needs\n>   explaining, replace it with a short, subtle, interruptible fade that honors\n>   `prefers-reduced-motion`.\n\n---\n\n## The moves: the mechanical toolbox\n\nMoves are the **concrete mechanics** - the tokens, ramps, and tiers. On their own they're just lists\nof allowed values; what makes each one usable is the **decision rule** that says _which value, and\nwhy_, plus the **principle** it serves. When you reach for a move, lead with the rule, not the\nliteral.\n\nThis is the one section that touches implementation - and even here, the goal is to keep the\n_conversation_ about design. Treat the Moves as the **shared vocabulary that lets an agreed design\nbe built consistently**, not as the opening move in a review. Reach for them _after_ you've named\nthe feeling and the principle, never instead of it.\n\nThe full size-token reference is in\n[design-tokens.instructions.md](..\u002F..\u002Finstructions\u002Fdesign-tokens.instructions.md).\n\n\u003Ca id=\"design-tokens\">\u003C\u002Fa>\n\n### Tokens are the source of truth, not the pixel\n\nDesign-system spacing, radii, type roles, and colors should use a named token or ramp where one\nexists. Raw literals remain valid for structural measurements.\n\n- **Decision rule:** when something looks wrong, find the token it should be expressing and reason\n  about _that_ - not the literal.\n- **Serves:** _Sameness signals sameness_ (6).\n\n> An `8px` corner isn't \"8px.\" It's an **Outer surface radius** that someone typed as a literal.\n> Name the role and the fix follows.\n\n\u003Ca id=\"elevation-tiers\">\u003C\u002Fa>\n\n### Elevation tiers - round by role, not by literal\n\nCorner radius encodes **how far a surface floats above the one beneath it**. Every rounded thing\nbelongs to exactly one tier:\n\n| Tier        | Radius | Token                          | What it is                                                   |\n| ----------- | ------ | ------------------------------ | ------------------------------------------------------------ |\n| **Control** | 4px    | `--vscode-cornerRadius-small`  | interactible elements - buttons, inputs, list rows, tabs     |\n| **Inner**   | 6px    | `--vscode-cornerRadius-medium` | non-control containers sitting _inside_ a surface            |\n| **Outer**   | 8px    | `--vscode-cornerRadius-large`  | floating \u002F overlay surfaces - menus, hovers, dialogs, toasts |\n\nPills (radius ≈ half the height) are **fully round** (`--vscode-cornerRadius-circle`), not \"a big\nradius.\"\n\n- **Decision rule:** pick the tier by the surface's **role in the stack**, not by how the corner\n  looks. A bug here sounds like _\"this overlay is rounded at the control tier,\"_ never _\"this needs\n  more border-radius.\"_\n- **Serves:** _Elevation is encoded_ (5), _Room to breathe_ (2).\n\n\u003Ca id=\"spacing-ramp\">\u003C\u002Fa>\n\n### The spacing ramp - on-scale or off-scale\n\nPadding, margin, and gap come from the **spacing ramp** (0, 2, 4, 6, 8, 10, 12, 16, 20, 24, 28, 32,\n36, 40).\n\n- **Decision rule:** a value either lands _on_ the ramp or it doesn't. Off-scale values (3, 5, 7,\n  14, 26…) break the rhythm; snap to the nearest step, ties rounding up. Report rhythm bugs as\n  _\"this is off the spacing ramp,\"_ not _\"add a couple of pixels.\"_\n- **Serves:** _Room to breathe_ (2), _Sameness signals sameness_ (6).\n\n\u003Ca id=\"type-ramp\">\u003C\u002Fa>\n\n### The type ramp - roles and two weights, not free sizes\n\nText styles are **roles**, not arbitrary sizes: `heading1–3`, `body1–2`, `label1–3`. There are\nexactly **two weights** - `regular` (400) and `semiBold` (600). There is no medium (500). \"Strong\"\nis not a bigger size; it is the _same role token at `semiBold`_.\n\n- **Decision rule:** choose the role by the text's **rank in the hierarchy**, not by eyeballing a\n  size. A heading that looks weak is _\"the wrong type role\"_ or _\"missing the semiBold weight,\"_ not\n  _\"bump the font to 14.\"_ A `500` anywhere is **off the ramp**.\n- **Serves:** _One thing leads_ (4), _Sameness signals sameness_ (6).\n\n\u003Ca id=\"icon-sizes\">\u003C\u002Fa>\n\n### Icon sizes - two sizes, chosen by context\n\nCodicons are **16px (base)** or **12px (compact)** - nothing in between; `14px` is always a bug. At\nthe compact size, also swap to the `*Compact` glyph (`Codicon.close` → `Codicon.closeCompact`) so\nthe icon is _optically_ tuned, not just scaled.\n\n- **Decision rule:** size tracks the **density and rank of the context**. Use **base (16px)** for\n  standalone or primary actions and comfortable click targets; use **compact (12px)** for dense\n  rows, inline glyphs, and secondary chrome where the icon rides alongside text. So the answer to\n  \"16 or 12?\" is _\"what is this icon's role here?\"_ - not a taste call. Say _\"this icon should be\n  compact,\"_ not _\"shrink it a bit.\"_\n- **Serves:** _One thing leads_ (4), _Sameness signals sameness_ (6).\n\n\u003Ca id=\"one-stroke\">\u003C\u002Fa>\n\n### One stroke\n\nThe standard border\u002Fseparator stroke is **1px** (`--vscode-strokeThickness`).\n\n- **Decision rule:** whether an ordinary border is present is a **yes\u002Fno** decision. Preserve\n  thicker semantic or accessibility strokes, such as focus indicators.\n- **Serves:** _Quiet at rest_ (1), _Sameness signals sameness_ (6).\n\n\u003Ca id=\"theme-color\">\u003C\u002Fa>\n\n### Color comes from the theme\n\nEvery color is a `--vscode-*` theme token, so the UI tracks the active theme and high-contrast\nmodes.\n\n- **Decision rule:** a hardcoded hex is a bug by construction. Color bugs are _\"wrong theme token\"_\n  (or _\"a token that disappears in light\u002FHC\"_), never a hex value to nudge.\n- **Serves:** _Quiet at rest_ (1), _Sameness signals sameness_ (6).\n\n\u003Ca id=\"reveal-on-intent\">\u003C\u002Fa>\n\n### Reveal-on-intent behaviors\n\nChrome that used to carry a permanent fill now reads transparent at rest and only reveals on\ninteraction. Each behavior also _does a job_, so they pull double duty:\n\n- `commandCenter` - transparent at rest; shows its background\u002Fborder on hover, so a pointer\n  _confirms_ the thing it's over.\n- `statusBar` - neutralized to the window; only the **background** changes on hover, the foreground\n  stays put.\n- `keyboardFocusOnly` - the focus ring appears for **keyboard** focus (`:focus-visible`), not on\n  mouse click, so the affordance shows exactly when it's useful.\n- `scrollShadows` - content _fades_ under a surface edge instead of being cut at a hard line, so you\n  feel there's _more_ beyond the fold.\n\n- **Serves:** _Quiet at rest_ (1), _Delight earns its keep_ (7), and (scroll shadows) _Elevation is\n  encoded_ (5).\n\n\u003Ca id=\"words-casing\">\u003C\u002Fa>\n\n### Words & casing\n\n**Prefer a text label to an icon.** A word is read; an icon is _guessed_. Reach for a glyph only\nwhen its meaning is near-universal (close, search) or space is genuinely scarce - otherwise label\nthe thing, or pair icon + label when you need both recognition and recall. A lone mystery glyph is\nthe bug, not a badly-chosen one: _\"this action is unlabeled - give it a word,\"_ not _\"find a clearer\nicon.\"_\n\n**Write in sentence case.** Labels, buttons, menus, and messages capitalize the first word and\nproper nouns only - _\"Start new session,\"_ not _\"Start New Session.\"_ It's calmer, friendlier, and\nquicker to scan. Report it as _\"this is Title Case - make it sentence case,\"_ a tone fix, not a\nreword.\n\n> **⚠️ Known conflict - reconcile later.** This sentence-case guidance is the intended modern-UI\n> direction, but it **contradicts** the repo-wide coding guideline that mandates title-style\n> capitalization for command labels, buttons, and menu items (see\n> [coding-guidelines.instructions.md](..\u002F..\u002Finstructions\u002Fcoding-guidelines.instructions.md), \"UI\n> labels\"). The two conventions have not yet been reconciled. Until they are, **follow the existing\n> title-case rule for shipped, non-experimental UI**, and apply sentence case only within surfaces\n> that have explicitly adopted the modern UI direction. TODO: agree a single casing convention and\n> update whichever doc loses.\n\n- **Serves:** _The interface explains itself_ (3).\n\n---\n\n## The phrasebook: describe the bug, name the principle\n\nLead with the **role \u002F tier \u002F ramp**, not the number - then name the principle so the fix lands\neverywhere, not just here. The number is a symptom.\n\n| ❌ Don't say                             | ✅ Do say                                                                                                             | Principle                   |\n| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------- |\n| \"border-radius should be 6, not 8\"       | \"this is an **Inner** surface rounded at the **Outer** tier\"                                                          | 5 · Elevation               |\n| \"this menu corner is too sharp\"          | \"this **overlay** should be on the **Outer** radius tier\"                                                             | 5 · Elevation               |\n| \"add 2px of padding\"                     | \"this content is **off the spacing ramp** \u002F needs ramp breathing room\"                                                | 2 · Room to breathe         |\n| \"make this 14px\"                         | \"this should use the **`label1` \u002F `body1` type role**\"                                                                | 4 · One thing leads         |\n| \"the title looks thin\"                   | \"the heading is **missing the `semiBold` weight**\"                                                                    | 4 · One thing leads         |\n| \"font-weight 500 here\"                   | \"**500 is off the ramp** - snap to `semiBold` (600)\"                                                                  | 6 · Sameness                |\n| \"shrink this icon a touch\"               | \"this icon should be the **compact (12px) size + `*Compact` glyph**\"                                                  | 4 · One thing leads         |\n| \"this icon is 14px\"                      | \"codicons are **16 or 12 only** - pick base or compact\"                                                               | 6 · Sameness                |\n| \"this ordinary border is too thick\"      | \"standard borders are **one stroke (1px)** - this should\u002Fshouldn't have one; preserve thicker focus\u002Fsemantic strokes\" | 1 · Quiet at rest           |\n| \"change this grey hex\"                   | \"this is the **wrong theme token** \u002F it **vanishes in light\u002FHC**\"                                                     | 6 · Sameness                |\n| \"the command center has a box around it\" | \"chrome should be **quiet at rest, reveal on hover**\"                                                                 | 1 · Quiet at rest           |\n| \"the focus outline shows when I click\"   | \"the ring is **keyboard-focus only** (`:focus-visible`)\"                                                              | 1 · Quiet at rest           |\n| \"the list is cut off at the bottom\"      | \"the surface is **missing its scroll-shadow fade**\"                                                                   | 7 · Delight \u002F 5 · Elevation |\n| \"the pane header has a line \u002F hard edge\" | \"pane headers are **rounded, separator-less section titles**\"                                                         | 1 · Quiet at rest           |\n\n---\n\n## Giving and receiving feedback\n\n**Describe the design, not the pixel.** When you name the rule that's broken, the fix lands\neverywhere it's broken - not just in the one spot you happened to notice.\n\nWhen something looks wrong, say it in this order:\n\n1. **The feeling** - which of the four values is it missing? _Calm, Focused, Consistent,\n   Delightful._\n2. **The surface** - what and where? _\"the sidebar pane header,\" \"the Save dialog.\"_\n3. **The principle it breaks** - the rule behind the feeling.\n4. **The move that would fix it** - the mechanic that restores it.\n5. **Only then, if useful, the number** - _\"shows 4px, looks like it wants 6px.\"_\n\n> **Example** \"The activity bar doesn't feel **Calm** - it's loud at rest. The icons carry a\n> permanent fill that's competing with the editor (_Quiet at rest, present on intent_). Could the\n> fill reveal on hover instead? It reads about 2px too tight as well, but the fill is the real\n> thing.\"\n\nWhen you compile design feedback into a review list, rank and render each item with the shared\nseverity scale in\n[reporting-standard.instructions.md](..\u002F..\u002Finstructions\u002Freporting-standard.instructions.md) (🟣\ncritical → 🔵 nice to have, in that order).\n\n### Lead with the feeling, not the fix\n\nThe word points everyone at the same principle, even before anyone agrees on a pixel:\n\n| Say this first                                                | Not this                          |\n| ------------------------------------------------------------- | --------------------------------- |\n| \"this doesn't feel **Calm** - it's noisy at rest\"             | \"make the background transparent\" |\n| \"this isn't **Focused** - the eye has nowhere to land\"        | \"make the title bigger\"           |\n| \"this feels **inconsistent** - these two dialogs don't match\" | \"change the radius to 6\"          |\n| \"this transition isn't **Delightful**, it's just decoration\"  | \"make the animation faster\"       |\n\n### What makes feedback hard to act on\n\nThese aren't wrong, they're just _incomplete_ - they fix one spot and drift back out of sync:\n\n- **A bare number.** _\"This should be 6px.\"_ Which token? Why? Name the role and the fix lands\n  everywhere.\n- **A taste claim with no rule.** _\"I don't like this corner.\"_ Tie it to a value or principle so\n  it's a shared standard, not a preference.\n- **A fix with no feeling.** _\"Make it transparent.\"_ Maybe - but say what's wrong first (_\"it's\n  loud at rest\"_), so we fix the cause, not just this instance.\n- **Several things at once.** Split _\"this panel is busy, off-grid, and the icon's wrong\"_ into\n  three, each with its own value.\n\n### Practical notes\n\n- **Attach the surface.** A screenshot or a short clip (for motion) plus the name of the view beats\n  a paragraph of description. Circle the spot.\n- **One observation per thread.** Keep each piece of feedback to a single surface + value, so it can\n  be discussed and resolved on its own.\n- **Light vs. dark vs. high-contrast.** If something only breaks in one theme, say so - that usually\n  points at a _theme token_ problem, not a color choice.\n- **Reduced motion.** For animation feedback, note whether you have `prefers-reduced-motion` on; a\n  transition should still make sense without it.\n","# VS Code Design Philosophy\n\nThis skill is the **canonical VS Code design philosophy** — the single source of truth for how we\nreason about UI, for both developers and agents.\n\nAs more and more of the UI is implemented via agents and tooling, the pixels increasingly take care\nof themselves, and the scarce, human part becomes the design judgment behind them.\n\nThis is about _shifting left_ - talking about UI in design terms, not pixels, and having that\nconversation early. When something looks off, \"this is 8px, should be 6px\" fixes one number; \"this\nsurface is rounded at the wrong _elevation tier_\" names the rule, so the fix lands everywhere and we\ncatch it on a mockup or screenshot rather than in code review. The aim is to agree on _what the UI\nshould be and why_, in language a designer and an engineer can share - the implementation (which\ntoken, which file) tends to follow once the design is settled.\n\n---\n\n## How to read this: three layers\n\nThe hardest part of any design language is getting from _\"this feels off\"_ to a clear, shared fix\neveryone agrees on. This bridges that in three steps, each explaining the one below it:\n\n| Layer          | What it is                                                               | Example                                                                           |\n| -------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |\n| **Values**     | what we want people to _feel_, and why it's at stake                     | _Focused_                                                                         |\n| **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?_             |\n| **Moves**      | the concrete mechanics, each with a rule for _which one and why_         | _demote the secondary panel to a recessed background token \u002F a quieter type role_ |\n\nRead top-down when you're learning the system, and bottom-up when you're fixing a bug: name the\n**feeling**, find the **principle** it breaks, then reach for the **move** that restores it.\n\n> **Worked example - a busy panel**\n>\n> - **See:** a panel feels busy and keeps pulling your eye off the editor.\n> - **Feeling:** not _Calm_, not _Focused_.\n> - **Principle:** breaks _Quiet at rest_ (it carries a permanent fill it shouldn't) and _One thing\n>   leads_ (secondary chrome competing with the editor).\n> - **Move:** drop the panel to a recessed\u002Ftransparent background token, reveal its border only on\n>   hover, and demote its labels to a quieter type role.\n\n---\n\n## The values: what we design for\n\nThese four values name what we want people to _feel_ using VS Code - they're the top layer, the\nthing every principle and move below is ultimately in service of. Learn them and you can describe\nalmost any bug. Each is a _feeling_ the UI should give; each is upheld by one or more **principles**\nbelow. Reach for the value first, the principle second, the move last.\n\n| Value          | Means                                                                                | When it's broken it feels…                    | Principles |\n| -------------- | ------------------------------------------------------------------------------------ | --------------------------------------------- | ---------- |\n| **Calm**       | quiet at rest, uncluttered; room to breathe; soft, not sharp; plain-spoken and human | busy, noisy, cramped, jagged, cryptic, shouty | 1, 2, 3    |\n| **Focused**    | clear hierarchy; one thing leads, the rest supports                                  | flat, samey, the eye has nowhere to go        | 4, 5       |\n| **Consistent** | everything sits on the same ramps and tiers                                          | random, off-grid, drifting                    | 5, 6       |\n| **Delightful** | small moments that _do a job_ - guide, confirm, orient                               | lifeless, abrupt, or gimmicky                 | 7          |\n\n> Say _\"this feels noisy, it's not **Calm**\"_ before _\"the background should be transparent.\"_ The\n> value points everyone at the same principle.\n\n### Why these four?\n\nIt's fair to ask: who would ever _want_ a UI that isn't calm, focused, consistent, and delightful?\nThat's exactly the point. These aren't differentiators we're claiming over other products - they're\nthe qualities most **under threat in a tool like ours**, and naming them is how we defend them. We\nchose them because they're the values VS Code (and so Ganttee) is structurally inclined to _lose_:\n\n- **Calm** is the first casualty of an IDE. VS Code (and so Ganttee) is information-dense and lived\n  in for hours; every feature team has a good reason to add one more affordance, and the sum is\n  noise. Calm is the value that pushes back on our own gravity.\n- **Focused** matters because our surfaces are _deep_. A screen full of equally-weighted,\n  equally-valid controls is the default failure mode of a power tool. Naming focus forces us to\n  decide what leads.\n- **Consistent** has the largest surface area to defend. VS Code (and so Ganttee) is built by many\n  hands over many years; drift is the natural state. Consistency is less an aspiration than a\n  maintenance discipline.\n- **Delightful** is the one we deliberately **ration**. It earns its place only by doing a job\n  (Principle 7). We name it not to add more polish but to keep it honest, so delight guides and\n  confirms rather than decorates.\n\nAnd each value names a real **tension**, not a free win - which is what makes it a choice worth\nstating rather than a platitude:\n\n- **Calm** trades against **density** - how much do we surface at rest?\n- **Focused** trades against **equal access** - what do we demote so one thing can lead?\n- **Consistent** trades against the **genuinely special case** - when is a difference earned rather\n  than drift?\n- **Delightful** trades against **restraint** - when does a flourish cross into noise?\n\nSo the useful question isn't _\"would we ever not want these?\"_ but _\"which one is this surface\ntrading away, and did we mean to?\"_ When a value really must yield - say, a critical warning that\n_should_ break calm to seize attention - that's a deliberate, named exception, not a reason to drop\nthe value.\n\n---\n\n## Principles\n\nPrinciples are **evaluative**: each one is a question you can ask of any surface, and the answer\ntells you whether the design is right - independent of any pixel value. They're grouped by the value\nthey uphold.\n\n---\n\n### Calm\n\n#### 1. Quiet at rest, present on intent\n\n> **Ask:** _is anything shouting when nothing is happening?_\n\nChrome should recede until you engage it. A surface carrying a permanent fill, border, or focus ring\nit hasn't earned is competing with the user's content for attention it doesn't need. The modern look\nis **restrained**: things reveal themselves _on intent_ - hover, focus, interaction - and sit\nquietly otherwise.\n\nWhen this is wrong it sounds like _\"this is loud at rest \u002F should be quiet until hover\"_ or _\"the\nfocus ring is firing on click\"_ - a behavioral description, not a color value.\n\n_Carried out by:_ [reveal-on-intent behaviors](#reveal-on-intent), [one stroke](#one-stroke),\n[theme color](#theme-color).\n\n#### 2. Room to breathe\n\n> **Ask:** _does this feel cramped, tight, or jagged?_\n\nCalm UI is generous and soft. Space isn't wasted; it's what lets the eye rest and groups things\nwithout drawing a single line. Edges are rounded rather than sharp. When a surface feels boxed-in or\nbusy, the fix is usually more breathing room on the spacing ramp, not smaller content.\n\n_Carried out by:_ [the spacing ramp](#spacing-ramp), [elevation tiers](#elevation-tiers) (rounded,\nnot sharp).\n\n#### 3. The interface explains itself, plainly and kindly\n\n> **Ask:** _could someone understand this at a glance, without guessing?_\n\nThe UI should read like a person talking. Prefer a word to a mystery glyph; write in sentence case;\nkeep the tone human. A lone unlabeled icon, or a Title-Cased Marketing Headline, makes the user work\nharder than they should - never cryptic, never shouting.\n\n_Carried out by:_ [words & casing](#words-casing).\n\n> **Worked example - a boxed-in toolbar**\n>\n> - **See:** a toolbar sits on a solid filled bar, separator lines between every button, the buttons\n>   pushed up against each other.\n> - **Feeling:** not _Calm_ - busy and boxed-in.\n> - **Principle:** breaks _Quiet at rest_ (the fill and separators are permanent chrome that hasn't\n>   earned its place) and _Room to breathe_ (buttons jammed together).\n> - **Move:** let the bar read transparent at rest, drop the separators (one stroke - and here the\n>   answer is _no_), and space the buttons out on the ramp.\n\n### Focused\n\n#### 4. One thing leads; the rest supports\n\n> **Ask:** _where does the eye go first - and is anything secondary competing with it?_\n\nEvery view should have a clear **center of attention** - the one thing the eye should land on first.\nKeep secondary information _out_ of that spot: demote it with a quieter type role, a recessed\nsurface, or a smaller icon, so the thing that matters leads and everything else supports it. A view\nwhere everything has equal weight is _flat_ - the eye has nowhere to go.\n\n_Carried out by:_ [type roles](#type-ramp), [elevation tiers](#elevation-tiers),\n[icon size by context](#icon-sizes).\n\n#### 5. Elevation is encoded, not eyeballed\n\n> **Ask:** _does this surface's roundness match how far it floats above what's beneath it?_\n\nHow rounded - and how raised - a surface is _means something_: it tells you where the surface sits\nin the stack. A floating overlay reads as more rounded than a control sitting flat inside a pane.\nRadius is chosen by the surface's role in the hierarchy, never by taste. (This serves both\n**Focused** and **Consistent**.)\n\n_Carried out by:_ [elevation tiers](#elevation-tiers---round-by-role-not-by-literal),\n[reveal-on-intent](#reveal-on-intent-behaviors) (scroll shadows).\n\n> **Worked example - a flat settings row**\n>\n> - **See:** a settings row shows its label, its help text, and a \"Reset\" action all at the same\n>   size and weight.\n> - **Feeling:** not _Focused_ - flat; the eye doesn't know where to land.\n> - **Principle:** breaks _One thing leads_ - nothing is the center of attention.\n> - **Move:** lift the label to the leading type role, demote the help text to `body2`, and make\n>   \"Reset\" a quiet secondary action so the row reads top-down.\n\n### Consistent\n\n#### 6. Sameness signals sameness\n\n> **Ask:** _do two like things look identical - and is any difference here intentional?_\n\nEquivalent elements must look equivalent, because they pull from the same named scale. When two\nsimilar things differ, that difference should _mean_ something; accidental drift is the enemy. This\nis why every size, radius, weight, and color is a **named token with a role**, not a literal - the\nliteral is only ever a stand-in for the token it lands on.\n\n_Carried out by:_ every move below - they _are_ the shared scales. See especially\n[design tokens](#design-tokens), [the spacing ramp](#spacing-ramp), [the type ramp](#type-ramp),\n[icon sizes](#icon-sizes), [one stroke](#one-stroke).\n\n> **Worked example - two mismatched dialogs**\n>\n> - **See:** two dialogs open side by side; one has 8px corners, the other 6px - both are floating\n>   overlays.\n> - **Feeling:** not _Consistent_ - the UI feels like it's drifting.\n> - **Principle:** breaks _Sameness signals sameness_ (two equivalent surfaces look different for no\n>   reason) and _Elevation is encoded_ (an overlay belongs on the Outer tier).\n> - **Move:** point both at the Outer radius token; the 6px was a literal someone typed instead of\n>   naming the tier.\n\n### Delightful\n\n#### 7. Delight earns its keep\n\n> **Ask:** _what does this help the user do?_\n\nMotion, reveals, and finishing touches are welcome - but each must **do a job**: guide the eye,\nconfirm an action, orient the user, or smooth a jump. If there's no answer to the question, it's\ndecoration, and decoration reads as noise (back to **Calm**). Keep it subtle, short, and\ninterruptible; honor `prefers-reduced-motion`; never animate for its own sake.\n\nA delight bug sounds like _\"this transition is doing nothing for me\"_ (cut it) or _\"this jump is\ndisorienting - it needs a functional transition\"_ (add one) - not a duration or easing value to\nfiddle with.\n\n_Carried out by:_ [reveal-on-intent behaviors](#reveal-on-intent).\n\n> **Worked example - a bouncing panel**\n>\n> - **See:** a side panel slides in with a 600ms bounce every time you toggle it.\n> - **Feeling:** not _Delightful_ (gimmicky) and not _Calm_ (slow and shouty).\n> - **Principle:** breaks _Delight earns its keep_ - the bounce isn't doing a job, and the toggle is\n>   already obvious.\n> - **Move:** if nothing needs orienting, cut the animation; if the panel's arrival genuinely needs\n>   explaining, replace it with a short, subtle, interruptible fade that honors\n>   `prefers-reduced-motion`.\n\n---\n\n## The moves: the mechanical toolbox\n\nMoves are the **concrete mechanics** - the tokens, ramps, and tiers. On their own they're just lists\nof allowed values; what makes each one usable is the **decision rule** that says _which value, and\nwhy_, plus the **principle** it serves. When you reach for a move, lead with the rule, not the\nliteral.\n\nThis is the one section that touches implementation - and even here, the goal is to keep the\n_conversation_ about design. Treat the Moves as the **shared vocabulary that lets an agreed design\nbe built consistently**, not as the opening move in a review. Reach for them _after_ you've named\nthe feeling and the principle, never instead of it.\n\nThe full size-token reference is in\n[design-tokens.instructions.md](..\u002F..\u002Finstructions\u002Fdesign-tokens.instructions.md).\n\n\u003Ca id=\"design-tokens\">\u003C\u002Fa>\n\n### Tokens are the source of truth, not the pixel\n\nDesign-system spacing, radii, type roles, and colors should use a named token or ramp where one\nexists. Raw literals remain valid for structural measurements.\n\n- **Decision rule:** when something looks wrong, find the token it should be expressing and reason\n  about _that_ - not the literal.\n- **Serves:** _Sameness signals sameness_ (6).\n\n> An `8px` corner isn't \"8px.\" It's an **Outer surface radius** that someone typed as a literal.\n> Name the role and the fix follows.\n\n\u003Ca id=\"elevation-tiers\">\u003C\u002Fa>\n\n### Elevation tiers - round by role, not by literal\n\nCorner radius encodes **how far a surface floats above the one beneath it**. Every rounded thing\nbelongs to exactly one tier:\n\n| Tier        | Radius | Token                          | What it is                                                   |\n| ----------- | ------ | ------------------------------ | ------------------------------------------------------------ |\n| **Control** | 4px    | `--vscode-cornerRadius-small`  | interactible elements - buttons, inputs, list rows, tabs     |\n| **Inner**   | 6px    | `--vscode-cornerRadius-medium` | non-control containers sitting _inside_ a surface            |\n| **Outer**   | 8px    | `--vscode-cornerRadius-large`  | floating \u002F overlay surfaces - menus, hovers, dialogs, toasts |\n\nPills (radius ≈ half the height) are **fully round** (`--vscode-cornerRadius-circle`), not \"a big\nradius.\"\n\n- **Decision rule:** pick the tier by the surface's **role in the stack**, not by how the corner\n  looks. A bug here sounds like _\"this overlay is rounded at the control tier,\"_ never _\"this needs\n  more border-radius.\"_\n- **Serves:** _Elevation is encoded_ (5), _Room to breathe_ (2).\n\n\u003Ca id=\"spacing-ramp\">\u003C\u002Fa>\n\n### The spacing ramp - on-scale or off-scale\n\nPadding, margin, and gap come from the **spacing ramp** (0, 2, 4, 6, 8, 10, 12, 16, 20, 24, 28, 32,\n36, 40).\n\n- **Decision rule:** a value either lands _on_ the ramp or it doesn't. Off-scale values (3, 5, 7,\n  14, 26…) break the rhythm; snap to the nearest step, ties rounding up. Report rhythm bugs as\n  _\"this is off the spacing ramp,\"_ not _\"add a couple of pixels.\"_\n- **Serves:** _Room to breathe_ (2), _Sameness signals sameness_ (6).\n\n\u003Ca id=\"type-ramp\">\u003C\u002Fa>\n\n### The type ramp - roles and two weights, not free sizes\n\nText styles are **roles**, not arbitrary sizes: `heading1–3`, `body1–2`, `label1–3`. There are\nexactly **two weights** - `regular` (400) and `semiBold` (600). There is no medium (500). \"Strong\"\nis not a bigger size; it is the _same role token at `semiBold`_.\n\n- **Decision rule:** choose the role by the text's **rank in the hierarchy**, not by eyeballing a\n  size. A heading that looks weak is _\"the wrong type role\"_ or _\"missing the semiBold weight,\"_ not\n  _\"bump the font to 14.\"_ A `500` anywhere is **off the ramp**.\n- **Serves:** _One thing leads_ (4), _Sameness signals sameness_ (6).\n\n\u003Ca id=\"icon-sizes\">\u003C\u002Fa>\n\n### Icon sizes - two sizes, chosen by context\n\nCodicons are **16px (base)** or **12px (compact)** - nothing in between; `14px` is always a bug. At\nthe compact size, also swap to the `*Compact` glyph (`Codicon.close` → `Codicon.closeCompact`) so\nthe icon is _optically_ tuned, not just scaled.\n\n- **Decision rule:** size tracks the **density and rank of the context**. Use **base (16px)** for\n  standalone or primary actions and comfortable click targets; use **compact (12px)** for dense\n  rows, inline glyphs, and secondary chrome where the icon rides alongside text. So the answer to\n  \"16 or 12?\" is _\"what is this icon's role here?\"_ - not a taste call. Say _\"this icon should be\n  compact,\"_ not _\"shrink it a bit.\"_\n- **Serves:** _One thing leads_ (4), _Sameness signals sameness_ (6).\n\n\u003Ca id=\"one-stroke\">\u003C\u002Fa>\n\n### One stroke\n\nThe standard border\u002Fseparator stroke is **1px** (`--vscode-strokeThickness`).\n\n- **Decision rule:** whether an ordinary border is present is a **yes\u002Fno** decision. Preserve\n  thicker semantic or accessibility strokes, such as focus indicators.\n- **Serves:** _Quiet at rest_ (1), _Sameness signals sameness_ (6).\n\n\u003Ca id=\"theme-color\">\u003C\u002Fa>\n\n### Color comes from the theme\n\nEvery color is a `--vscode-*` theme token, so the UI tracks the active theme and high-contrast\nmodes.\n\n- **Decision rule:** a hardcoded hex is a bug by construction. Color bugs are _\"wrong theme token\"_\n  (or _\"a token that disappears in light\u002FHC\"_), never a hex value to nudge.\n- **Serves:** _Quiet at rest_ (1), _Sameness signals sameness_ (6).\n\n\u003Ca id=\"reveal-on-intent\">\u003C\u002Fa>\n\n### Reveal-on-intent behaviors\n\nChrome that used to carry a permanent fill now reads transparent at rest and only reveals on\ninteraction. Each behavior also _does a job_, so they pull double duty:\n\n- `commandCenter` - transparent at rest; shows its background\u002Fborder on hover, so a pointer\n  _confirms_ the thing it's over.\n- `statusBar` - neutralized to the window; only the **background** changes on hover, the foreground\n  stays put.\n- `keyboardFocusOnly` - the focus ring appears for **keyboard** focus (`:focus-visible`), not on\n  mouse click, so the affordance shows exactly when it's useful.\n- `scrollShadows` - content _fades_ under a surface edge instead of being cut at a hard line, so you\n  feel there's _more_ beyond the fold.\n\n- **Serves:** _Quiet at rest_ (1), _Delight earns its keep_ (7), and (scroll shadows) _Elevation is\n  encoded_ (5).\n\n\u003Ca id=\"words-casing\">\u003C\u002Fa>\n\n### Words & casing\n\n**Prefer a text label to an icon.** A word is read; an icon is _guessed_. Reach for a glyph only\nwhen its meaning is near-universal (close, search) or space is genuinely scarce - otherwise label\nthe thing, or pair icon + label when you need both recognition and recall. A lone mystery glyph is\nthe bug, not a badly-chosen one: _\"this action is unlabeled - give it a word,\"_ not _\"find a clearer\nicon.\"_\n\n**Write in sentence case.** Labels, buttons, menus, and messages capitalize the first word and\nproper nouns only - _\"Start new session,\"_ not _\"Start New Session.\"_ It's calmer, friendlier, and\nquicker to scan. Report it as _\"this is Title Case - make it sentence case,\"_ a tone fix, not a\nreword.\n\n> **⚠️ Known conflict - reconcile later.** This sentence-case guidance is the intended modern-UI\n> direction, but it **contradicts** the repo-wide coding guideline that mandates title-style\n> capitalization for command labels, buttons, and menu items (see\n> [coding-guidelines.instructions.md](..\u002F..\u002Finstructions\u002Fcoding-guidelines.instructions.md), \"UI\n> labels\"). The two conventions have not yet been reconciled. Until they are, **follow the existing\n> title-case rule for shipped, non-experimental UI**, and apply sentence case only within surfaces\n> that have explicitly adopted the modern UI direction. TODO: agree a single casing convention and\n> update whichever doc loses.\n\n- **Serves:** _The interface explains itself_ (3).\n\n---\n\n## The phrasebook: describe the bug, name the principle\n\nLead with the **role \u002F tier \u002F ramp**, not the number - then name the principle so the fix lands\neverywhere, not just here. The number is a symptom.\n\n| ❌ Don't say                             | ✅ Do say                                                                                                             | Principle                   |\n| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------- |\n| \"border-radius should be 6, not 8\"       | \"this is an **Inner** surface rounded at the **Outer** tier\"                                                          | 5 · Elevation               |\n| \"this menu corner is too sharp\"          | \"this **overlay** should be on the **Outer** radius tier\"                                                             | 5 · Elevation               |\n| \"add 2px of padding\"                     | \"this content is **off the spacing ramp** \u002F needs ramp breathing room\"                                                | 2 · Room to breathe         |\n| \"make this 14px\"                         | \"this should use the **`label1` \u002F `body1` type role**\"                                                                | 4 · One thing leads         |\n| \"the title looks thin\"                   | \"the heading is **missing the `semiBold` weight**\"                                                                    | 4 · One thing leads         |\n| \"font-weight 500 here\"                   | \"**500 is off the ramp** - snap to `semiBold` (600)\"                                                                  | 6 · Sameness                |\n| \"shrink this icon a touch\"               | \"this icon should be the **compact (12px) size + `*Compact` glyph**\"                                                  | 4 · One thing leads         |\n| \"this icon is 14px\"                      | \"codicons are **16 or 12 only** - pick base or compact\"                                                               | 6 · Sameness                |\n| \"this ordinary border is too thick\"      | \"standard borders are **one stroke (1px)** - this should\u002Fshouldn't have one; preserve thicker focus\u002Fsemantic strokes\" | 1 · Quiet at rest           |\n| \"change this grey hex\"                   | \"this is the **wrong theme token** \u002F it **vanishes in light\u002FHC**\"                                                     | 6 · Sameness                |\n| \"the command center has a box around it\" | \"chrome should be **quiet at rest, reveal on hover**\"                                                                 | 1 · Quiet at rest           |\n| \"the focus outline shows when I click\"   | \"the ring is **keyboard-focus only** (`:focus-visible`)\"                                                              | 1 · Quiet at rest           |\n| \"the list is cut off at the bottom\"      | \"the surface is **missing its scroll-shadow fade**\"                                                                   | 7 · Delight \u002F 5 · Elevation |\n| \"the pane header has a line \u002F hard edge\" | \"pane headers are **rounded, separator-less section titles**\"                                                         | 1 · Quiet at rest           |\n\n---\n\n## Giving and receiving feedback\n\n**Describe the design, not the pixel.** When you name the rule that's broken, the fix lands\neverywhere it's broken - not just in the one spot you happened to notice.\n\nWhen something looks wrong, say it in this order:\n\n1. **The feeling** - which of the four values is it missing? _Calm, Focused, Consistent,\n   Delightful._\n2. **The surface** - what and where? _\"the sidebar pane header,\" \"the Save dialog.\"_\n3. **The principle it breaks** - the rule behind the feeling.\n4. **The move that would fix it** - the mechanic that restores it.\n5. **Only then, if useful, the number** - _\"shows 4px, looks like it wants 6px.\"_\n\n> **Example** \"The activity bar doesn't feel **Calm** - it's loud at rest. The icons carry a\n> permanent fill that's competing with the editor (_Quiet at rest, present on intent_). Could the\n> fill reveal on hover instead? It reads about 2px too tight as well, but the fill is the real\n> thing.\"\n\nWhen you compile design feedback into a review list, rank and render each item with the shared\nseverity scale in\n[reporting-standard.instructions.md](..\u002F..\u002Finstructions\u002Freporting-standard.instructions.md) (🟣\ncritical → 🔵 nice to have, in that order).\n\n### Lead with the feeling, not the fix\n\nThe word points everyone at the same principle, even before anyone agrees on a pixel:\n\n| Say this first                                                | Not this                          |\n| ------------------------------------------------------------- | --------------------------------- |\n| \"this doesn't feel **Calm** - it's noisy at rest\"             | \"make the background transparent\" |\n| \"this isn't **Focused** - the eye has nowhere to land\"        | \"make the title bigger\"           |\n| \"this feels **inconsistent** - these two dialogs don't match\" | \"change the radius to 6\"          |\n| \"this transition isn't **Delightful**, it's just decoration\"  | \"make the animation faster\"       |\n\n### What makes feedback hard to act on\n\nThese aren't wrong, they're just _incomplete_ - they fix one spot and drift back out of sync:\n\n- **A bare number.** _\"This should be 6px.\"_ Which token? Why? Name the role and the fix lands\n  everywhere.\n- **A taste claim with no rule.** _\"I don't like this corner.\"_ Tie it to a value or principle so\n  it's a shared standard, not a preference.\n- **A fix with no feeling.** _\"Make it transparent.\"_ Maybe - but say what's wrong first (_\"it's\n  loud at rest\"_), so we fix the cause, not just this instance.\n- **Several things at once.** Split _\"this panel is busy, off-grid, and the icon's wrong\"_ into\n  three, each with its own value.\n\n### Practical notes\n\n- **Attach the surface.** A screenshot or a short clip (for motion) plus the name of the view beats\n  a paragraph of description. Circle the spot.\n- **One observation per thread.** Keep each piece of feedback to a single surface + value, so it can\n  be discussed and resolved on its own.\n- **Light vs. dark vs. high-contrast.** If something only breaks in one theme, say so - that usually\n  points at a _theme token_ problem, not a color choice.\n- **Reduced motion.** For animation feedback, note whether you have `prefers-reduced-motion` on; a\n  transition should still make sense without it.\n",{"name":5,"description":7},"develop","3656175f11e1e311838b52d29a39d3173c74e3d8",".github\u002Fskills\u002Fdesign-philosophy",0,"https:\u002F\u002Fgithub.com\u002Fsergehas\u002Fganttee","https:\u002F\u002Fgithub.com\u002Fsergehas","2026-11-08 07:43:24",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add sergehas\u002Fganttee --skill design-philosophy",{"tool":36,"command":37},"bunx","bunx skills add sergehas\u002Fganttee --skill design-philosophy",{"tool":39,"command":40},"pnpm","pnpm dlx skills add sergehas\u002Fganttee --skill design-philosophy","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsergehas\u002Fganttee\u002Fblob\u002Fdevelop\u002F.github\u002Fskills\u002Fdesign-philosophy\u002FSKILL.md",true,[],[45,52,59,66,73,80],{"skillNo":46,"name":47,"nameZh":6,"description":48,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":49,"categories":50,"keywords":51,"publishedAt":18},"01M78GZ7BMMQP5DJ1AQ6355P0K","writing-for-agents","Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.","https:\u002F\u002Fgithub.com\u002Fsergehas\u002Fganttee\u002Fblob\u002Fdevelop\u002F.github\u002Fskills\u002Fwriting-for-agents\u002FSKILL.md",[],[],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":18},"01M78GZ5SJJ8G7SB4VPERDM1B7","wait-what","Stop. That last message did not land: re-pitch it.","https:\u002F\u002Fgithub.com\u002Fsergehas\u002Fganttee\u002Fblob\u002Fdevelop\u002F.github\u002Fskills\u002Fwait-what\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":18},"01M78GZ16YCV8G87V26BVTJZ2H","ux-css-layout","VS Code (and so Ganttee) CSS conventions, file organization, class naming, standard sizes, scrollable content, responsive layout, and text overflow\u002Fellipsis patterns. Use when writing CSS, building layouts, or fixing text truncation issues.","https:\u002F\u002Fgithub.com\u002Fsergehas\u002Fganttee\u002Fblob\u002Fdevelop\u002F.github\u002Fskills\u002Fux-css-layout\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":18},"01M78GYYTPF0Z3SY412PCND261","to-questionnaire","Turn a decision you can't fully answer into a questionnaire for someone else to fill in.","https:\u002F\u002Fgithub.com\u002Fsergehas\u002Fganttee\u002Fblob\u002Fdevelop\u002F.github\u002Fskills\u002Fto-questionnaire\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":18},"01M78GYVE71DN5EZ5ZFWTGFHZ2","tdd","Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions \"red-green-refactor\", or wants integration tests.","https:\u002F\u002Fgithub.com\u002Fsergehas\u002Fganttee\u002Fblob\u002Fdevelop\u002F.github\u002Fskills\u002Ftdd\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":18},"01M78GYQFC5GFHC544FYDZBVYV","spec-router","Detect which spec-lifecycle agent a request needs (drafting, reviewing, implementing, or test planning a feature spec) and suggest the handoff — never acts without confirmation. Use whenever a message mentions a spec\u002Ffeature-spec file, a roadmap status, or spec review\u002Fimplementation\u002F draft\u002Ftest-plan intent, even without an explicit @agent mention.","https:\u002F\u002Fgithub.com\u002Fsergehas\u002Fganttee\u002Fblob\u002Fdevelop\u002F.github\u002Fskills\u002Fspec-router\u002FSKILL.md",[],[]]