mcpField
U
ux-design-principles

ux-design-principles

github.com/blink-newDesign & UI40 installs
Repository

About ux-design-principles

ux-design-principles is a UI/UX reference for designers and engineers, covering interaction feedback, visual hierarchy, layouts, typography, color, and other design topics. It also provides vocabulary and rules for describing interface changes to AI coding assistants.

Key features

  1. 01Interaction feedback and states
  2. 02Visual hierarchy and layout guidance
  3. 03Typography and color principles
  4. 04Dark mode, shadows, and overlays
  5. 05Precise UI vocabulary for AI coding assistants

Use cases

  1. 01Reviewing interface interaction states
  2. 02Choosing typography, color, and spacing
  3. 03Describing UI changes to an AI coding assistant

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/blink-new/claude --skill ux-design-principles

After installing, type/ux-design-principlesin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

text/
affordances-signifiers.md
color-theory.md
dark-mode.md
engineering-rules.md
feedback-states.md
glossary.md
grids-layouts-spacing.md
icons-buttons.md
micro-interactions.md
overlays.md
shadows.md
typography.md
visual-hierarchy.md

Details

From the project README

UX Design Principles

Source: "Every UI/UX Concept Explained in Under 10 Minutes" — Kole Jain (March 2026, 138K views) Figma files: https://www.kolejain.com/resources?scrollTo=every-ui-concept

The One Rule That Governs Everything

"When a user does anything, there should be a response."

Every interaction — click, hover, focus, error, load, success — must have a visible, purposeful response. This is the single most important principle in UI/UX design.


Chapter Map

ChapterCore ConceptQuick Rule
Affordances & SignifiersUI communicates how it works through appearanceGood UI teaches itself
Visual HierarchySize, position, color control what users see firstMost important = largest + boldest + top
Grids, Layouts & SpacingStructure and breathing roomWhitespace > rigid grids
TypographyFont choices, sizing, letter spacingOne sans-serif font, max 6 sizes
Color TheoryBrand color + semantic colors + rampsColor with purpose, not decoration
Dark ModeDepth via lightness, not shadowsLighter cards on dark backgrounds
ShadowsElevation and depth on light modeLow opacity, high blur
Icons & ButtonsSizing, padding, ghost buttonsMatch icon size to line-height
Feedback & StatesEvery element needs multiple states4 states minimum per button
Micro-interactionsMotion that confirms and delightsConfirm actions with animation
OverlaysGradients and blur over imagesLinear gradient then progressive blur

For Engineers: How to Talk to AI Assistants

Use precise vocabulary when describing UI to an AI coding assistant:

BAD:  "Make the button look better"
GOOD: "Add hover, active/pressed, and disabled states. Use ghost button style
       (transparent background, border only) as secondary CTA next to primary."

BAD:  "Fix the dark mode"
GOOD: "In dark mode: elevate card by lightening surface relative to background,
       remove box-shadow, lower border opacity, reduce chip saturation/brightness."

BAD:  "Add some animation"
GOOD: "Add micro-interaction on copy button: slide up a 'Copied!' chip on click
       that auto-dismisses after 1.5s. This confirms the action."

BAD:  "Fix the spacing"
GOOD: "Apply 4-point grid: all spacing values must be multiples of 4.
       32px between top-level sections, group related items with 8-16px."

See text/engineering-rules.md for the full quick-reference.


The 10 Design Laws

  1. Every interaction needs a response — no silent state changes ever
  2. Contrast creates hierarchy — big vs small, colorful vs gray, bold vs regular
  3. Whitespace is design — let elements breathe; 32px between sections default
  4. Color carries meaning — blue=trust, red=danger, yellow=warning, green=success
  5. One font is enough — pick one sans-serif, vary by weight and size
  6. Match icon size to line-height — body line-height 24px = icons 24px
  7. If the shadow is the first thing you notice, it's too strong
  8. Images always improve hierarchy — add color, aid scanning, draw the eye
  9. Dark mode = lighter surfaces for elevation, not shadows
  10. Linear gradient beats solid overlay — preserves image, readable text

Deep Dives

Comments

Markdown supported