Instruction file imported from itkdm/kode (.github/instructions/design-philosophy.instructions.md). Copyright stays with the author.

Design philosophy

When you touch a visual surface, reason about it in design terms, not pixels. Design-system spacing, radii, type roles, and colors use named tokens/ramps where available. Raw literals remain valid for structural measurements or when no token exists.

Work in three layers - name the feeling, find the principle it breaks, then reach for the move that restores it:

• Values (how it should feel): Calm · Focused · Consistent · Delightful
• Principles (questions to ask):
  1. Quiet at rest, present on intent - is anything shouting when nothing's happening?
  2. Room to breathe - does this feel cramped, tight, or jagged?
  3. The interface explains itself - could someone understand this at a glance?
  4. One thing leads; the rest supports - where does the eye go first?
  5. Elevation is encoded, not eyeballed - does roundness match how far the surface floats?
  6. Sameness signals sameness - do two like things look identical, and is any difference intentional?
  7. Delight earns its keep - what does this help the user do?
• Moves (the mechanics): elevation tiers (Control 4 / Inner 6 / Outer 8; pills fully round), the spacing ramp, the type ramp (roles + regular/semiBold only, no 500), two icon sizes (16 base / 12 compact), a 1px token for standard strokes, --vscode-* theme color, reveal-on-intent chrome, prefer a word to a mystery glyph.

Reach for a move only after naming the feeling and the principle - never instead. Describe a bug by its role/tier/ramp ("this overlay is rounded at the control tier"), not its number ("border-radius should be 6").

Full reference (values, principles, moves, worked examples, phrasebook, and feedback guidance): the design-philosophy skill. Token mechanics: design-tokens.instructions.md.