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
- 01Interaction feedback and states
- 02Visual hierarchy and layout guidance
- 03Typography and color principles
- 04Dark mode, shadows, and overlays
- 05Precise UI vocabulary for AI coding assistants
Use cases
- 01Reviewing interface interaction states
- 02Choosing typography, color, and spacing
- 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-principlesAfter installing, type/ux-design-principlesin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
text/affordances-signifiers.mdcolor-theory.mddark-mode.mdengineering-rules.mdfeedback-states.mdglossary.mdgrids-layouts-spacing.mdicons-buttons.mdmicro-interactions.mdoverlays.mdshadows.mdtypography.mdvisual-hierarchy.mdDetails
From the project READMEUX 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
| Chapter | Core Concept | Quick Rule |
|---|---|---|
| Affordances & Signifiers | UI communicates how it works through appearance | Good UI teaches itself |
| Visual Hierarchy | Size, position, color control what users see first | Most important = largest + boldest + top |
| Grids, Layouts & Spacing | Structure and breathing room | Whitespace > rigid grids |
| Typography | Font choices, sizing, letter spacing | One sans-serif font, max 6 sizes |
| Color Theory | Brand color + semantic colors + ramps | Color with purpose, not decoration |
| Dark Mode | Depth via lightness, not shadows | Lighter cards on dark backgrounds |
| Shadows | Elevation and depth on light mode | Low opacity, high blur |
| Icons & Buttons | Sizing, padding, ghost buttons | Match icon size to line-height |
| Feedback & States | Every element needs multiple states | 4 states minimum per button |
| Micro-interactions | Motion that confirms and delights | Confirm actions with animation |
| Overlays | Gradients and blur over images | Linear 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
- Every interaction needs a response — no silent state changes ever
- Contrast creates hierarchy — big vs small, colorful vs gray, bold vs regular
- Whitespace is design — let elements breathe; 32px between sections default
- Color carries meaning — blue=trust, red=danger, yellow=warning, green=success
- One font is enough — pick one sans-serif, vary by weight and size
- Match icon size to line-height — body line-height 24px = icons 24px
- If the shadow is the first thing you notice, it's too strong
- Images always improve hierarchy — add color, aid scanning, draw the eye
- Dark mode = lighter surfaces for elevation, not shadows
- Linear gradient beats solid overlay — preserves image, readable text