visual-design-foundations

Name: visual-design-foundations - Agent Skill
Rating: 5.0 (26449 reviews)
Author: wshobson

26,449

Apply typography, color theory, spacing systems, and iconography principles to create cohesive visual designs. Use when establishing design tokens, building style guides, or improving visual hierarchy and consistency.

Download Folder View on GitHub

CLI Install

Recommended

Use the skills CLI to install this skill with one command. Auto-detects all installed AI assistants.

Method 1 - skills CLI

npx skills i wshobson/agents/plugins/ui-design/skills/visual-design-foundations

Method 2 - openskills (supports sync & update)

npx openskills install wshobson/agents

Auto-detects Claude Code, Cursor, Codex CLI, Gemini CLI, and more. One install, works everywhere.

Installation Path

Download and extract to one of the following locations:

~/.claude/skills/visual-design-foundations/

SKILL.md

references

Skill Instructions

Back

Run with Cloud Agent

No setup needed. Let our cloud agents run this skill for you.

Select Provider

Select Model

Claude Sonnet 4.5

$0.20/task

Best for coding tasks

Environment setup included

Visual Design Foundations

Build cohesive, accessible visual systems using typography, color, spacing, and iconography fundamentals.

When to Use This Skill

Establishing design tokens for a new project
Creating or refining a spacing and sizing system
Selecting and pairing typefaces
Building accessible color palettes
Designing icon systems and visual assets
Improving visual hierarchy and readability
Auditing designs for visual consistency
Implementing dark mode or theming

Core Systems

1. Typography Scale

Modular Scale (ratio-based sizing):

:root {
  --font-size-xs: 0.75rem; /* 12px */
  --font-size-sm: 0.875rem; /* 14px */
  --font-size-base: 1rem; /* 16px */
  --font-size-lg: 1.125rem; /* 18px */
  --font-size-xl: 1.25rem; /* 20px */
  --font-size-2xl: 1.5rem; /* 24px */
  --font-size-3xl: 1.875rem; /* 30px */
  --font-size-4xl: 2.25rem; /* 36px */
  --font-size-5xl: 3rem; /* 48px */
}

Line Height Guidelines:

Text Type	Line Height
Headings	1.1 - 1.3
Body text	1.5 - 1.7
UI labels	1.2 - 1.4

2. Spacing System

8-point grid (industry standard):

:root {
  --space-1: 0.25rem; /* 4px */
  --space-2: 0.5rem; /* 8px */
  --space-3: 0.75rem; /* 12px */
  --space-4: 1rem; /* 16px */
  --space-5: 1.25rem; /* 20px */
  --space-6: 1.5

3. Color System

Semantic color tokens:

:root {
  /* Brand */
  --color-primary: #2563eb;
  --color-primary-hover: #1d4ed8;
  --color-primary-active: #1e40af;
 
  /* Semantic */
  --color-success: #16a34a;
  --color-warning: #ca8a04;
  --color-error: #dc2626;

Quick Start: Design Tokens in Tailwind

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: ["Inter", "system-ui", "sans-serif"],
        mono: ["JetBrains Mono", "monospace"],
      },
      fontSize: {
        xs: ["0.75rem"

Typography Best Practices

Font Pairing

Safe combinations:

Heading: Inter / Body: Inter (single family)
Heading: Playfair Display / Body: Source Sans Pro (contrast)
Heading: Space Grotesk / Body: IBM Plex Sans (geometric)

Responsive Typography

/* Fluid typography using clamp() */
h1 {
  font-size: clamp(2rem, 5vw + 1rem, 3.5rem);
  line-height: 1.1;
}
 
p {
  font-size: clamp(1rem, 2vw +

Font Loading

/* Prevent layout shift */
@font-face {
  font-family: "Inter";
  src: url("/fonts/Inter.woff2") format("woff2");
  font-display: swap;
  font-weight: 400 700;
}

Color Theory

Contrast Requirements (WCAG)

Element	Minimum Ratio
Body text	4.5:1 (AA)
Large text (18px+)	3:1 (AA)
UI components	3:1 (AA)
Enhanced	7:1 (AAA)

Dark Mode Strategy

:root {
  --bg-primary: #ffffff;
  --bg-secondary: #f9fafb;
  --text-primary: #111827;
  --text-secondary: #6b7280;
  --border: #e5e7eb;
}
 
[data-theme="dark"] {
  --bg-primary: #111827;
  --bg-secondary

Color Accessibility

// Check contrast programmatically
function getContrastRatio(foreground: string, background: string): number {
  const getLuminance = (hex: string) => {
    const rgb = hexToRgb(hex);
    const

Spacing Guidelines

Component Spacing

Card padding:      16-24px (--space-4 to --space-6)
Section gap:       32-64px (--space-8 to --space-16)
Form field gap:    16-24px (--space-4 to --space-6)
Button padding:    8-16px vertical, 16-24px horizontal
Icon-text gap:     8px (--space-2)

Visual Rhythm

/* Consistent vertical rhythm */
.prose > * + * {
  margin-top: var(--space-4);
}
 
.prose > h2 + * {
  margin-top: var(--space-2);
}
 
.prose > * + h2 {
  margin-top:

Iconography

Icon Sizing System

:root {
  --icon-xs: 12px;
  --icon-sm: 16px;
  --icon-md: 20px;
  --icon-lg: 24px;
  --icon-xl: 32px;
}

Icon Component

interface IconProps {
  name: string;
  size?: "xs" | "sm" | "md" | "lg" | "xl";
  className?: string;
}
 
const sizeMap = {
  xs: 12,
  sm:

Best Practices

Establish Constraints: Limit choices to maintain consistency
Document Decisions: Create a living style guide
Test Accessibility: Verify contrast, sizing, touch targets
Use Semantic Tokens: Name by purpose, not appearance
Design Mobile-First: Start with constraints, add complexity
Maintain Vertical Rhythm: Consistent spacing creates harmony
Limit Font Weights: 2-3 weights per family is sufficient

Common Issues

Inconsistent Spacing: Not using a defined scale
Poor Contrast: Failing WCAG requirements
Font Overload: Too many families or weights
Magic Numbers: Arbitrary values instead of tokens
Missing States: Forgetting hover, focus, disabled
No Dark Mode Plan: Retrofitting is harder than planning