CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

design-philosophy

The VS Code 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.

Quality

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

71%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body delivers genuinely actionable, highly specific design-system guidance — exact tokens, ramps, tiers, decision rules, and worked examples that model the full observation-to-fix workflow. Its weaknesses are length and monolithic structure: rhetorical/rationale padding, redundant restatements of the 'lead with the feeling' rule, and specialized sections (unavailable-features policy, fix verification) inlined in SKILL.md that would be better as one-level-deep reference files.

Suggestions

Move the 'Make unavailable features understandable' subsection (with its source-file example table) and the 'Does the fix feel right in use?' verification guidance into a references/ file, keeping a 2–3 line summary with a clearly-signaled link in SKILL.md.

Trim or cut the rhetorical passages ('Why these four?' tensions narrative, the 'shifting left' intro paragraph) — they explain why the values exist but add ~40 lines that don't change how the skill is applied.

Consolidate the redundant 'lead with the feeling' guidance: the values-section aside, the 'Lead with the feeling, not the fix' table, and the numbered feedback ordering all restate the same rule — keep one canonical statement and one table.

DimensionReasoningScore

Conciseness

Most content is skill-specific and earns its place (decision rules, token tables, worked examples, phrasebook), but at ~370 lines there is genuine padding: rhetorical passages like 'As more and more of the UI is implemented via agents...' and the 'It's fair to ask: who would ever want a UI that isn't calm...' rationale section, plus redundancy — the 'lead with the feeling' guidance appears in the values section, the feedback section, and its own 'Lead with the feeling, not the fix' table, and the phrasebook repeats the 'A bug here sounds like...' phrasing already embedded in each move. It is above anchor 2 (not 'several unnecessary explanations' of things Claude already knows) but below anchor 4 because whole sections could be tightened or cut.

3 / 5

Actionability

For an instruction-only skill the guidance is fully concrete: exact token names (--vscode-cornerRadius-small/medium/large/circle), the enumerated spacing ramp (0,2,4,...,40), named type roles (heading1–3, body1–2, label1–3) with exactly two weights (400/600), icon sizes 16/12 with the *Compact glyph rule, one-stroke 1px, four named reveal-on-intent behaviors, and a do/don't phrasebook — plus worked examples covering common cases (busy panel, flat settings row, mismatched dialogs, bouncing panel) and links to real source implementations. Per the rubric's code-vs-instruction note, absence of code is not penalized when guidance is this actionable.

5 / 5

Workflow Clarity

The core procedure is explicit and well-sequenced: 'name the feeling, find the principle it breaks, then reach for the move', a 5-step feedback ordering (feeling → surface → principle → move → number), worked examples modeling it, and a substantial verification section ('Try the thing, not its description', 'Make sure you're seeing the state you mean', 'Show the fix you actually shipped', check reduced motion and themes). It sits at anchor 4 rather than 5 because the sequence is distributed across several sections rather than one consolidated workflow, and there are no explicit error-recovery loops for cases where the first named principle turns out wrong.

4 / 5

Progressive Disclosure

The file is well-structured internally (clear headers, anchor links, tables), but there is no bundle at all — everything lives in one ~370-line SKILL.md. Content that clearly belongs in reference files is inlined, notably the 'Make unavailable features understandable' policy subsection with its table of four source-file examples and the long 'Does the fix feel right in use?' verification guidance. External references (../ux-css-layout/SKILL.md, ../ux-theming/SKILL.md, design-tokens.instructions.md, source files) are clearly signaled, but they point outside the skill rather than splitting this skill's own bulk. That matches anchor 3: real structure, but content that should be separate is inline.

3 / 5

Total

15

/

20

Passed

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: it explicitly and concretely answers both what the skill provides and when to use it, with natural trigger language ('this feels off', 'deciding a radius, spacing, type role...') and a clearly-scoped VS Code niche. The only minor gaps are a few missing synonyms (padding, corner, font) that keep trigger coverage just short of comprehensive.

DimensionReasoningScore

Specificity

The description names concrete capabilities — 'a shared Values→Principles→Moves vocabulary for reasoning about UI in design terms instead of raw pixels' and 'translating a "this feels off" observation into a concrete, principled fix' — plus specific decision targets (radius, spacing, type role, icon size, border, color, motion). It stops short of anchor 5 because the 'what' is a single framework/vocabulary rather than multiple distinct concrete operations, and it doesn't reach the comprehensiveness of the 5-anchor examples.

4 / 5

Completeness

Both halves are explicit: the 'what' ('a shared Values→Principles→Moves vocabulary for reasoning about UI in design terms instead of raw pixels') and a concrete, multi-clause 'Use when...' covering design/build/review/feedback, specific token decisions, and translating vague observations into principled fixes. This matches the anchor-5 pattern of clearly answering both what and when with concrete trigger phrases; nothing significant is only implied.

5 / 5

Trigger Term Quality

Natural phrases a user or reviewer would actually say are well covered: 'designing, building, reviewing, or giving feedback on any visual surface', 'this feels off', and concrete nouns like radius, spacing, icon size, border, color, and motion. It falls short of anchor 5 because common synonyms are missing — e.g. 'padding', 'corner/rounding', 'font', 'mockup', 'screenshot' — so a few natural trigger phrasings wouldn't match.

4 / 5

Distinctiveness Conflict Risk

The opening 'The VS Code design philosophy' establishes a clear niche, and the triggers (radius, spacing ramp, type role, icon size, elevation) are specific to this design system. It is clearly distinguishable from generic UI, CSS, or theming skills, with minimal conflict risk — at most minor overlap with sibling VS Code design skills, which the 'design terms instead of raw pixels' framing further separates.

5 / 5

Total

18

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 14 suspicious

Warning

Total

15

/

16

Passed

Repository

microsoft/vscode

Path

.github/skills/design-philosophy/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.