visual-design-foundationsby Seth Hobson

Visual Design Foundations Skill.

A Claude Code and Codex skill for brand and design-system work: typography, color theory, spacing systems, and iconography for cohesive visuals.

Brand & Design Systems

Download OpenDesign View usage guide

wshobson/agents · plugins/ui-design/skills/visual-design-foundations/SKILL.mdSKILL.md

--- name: visual-design-foundations description: 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. --- ## When to Use This Skill ## Core Systems ## Quick Start: Design Tokens in Tailwind ## Typography Best Practices ## Color Theory ## Spacing Guidelines

Front matter and section headings read from the upstream file on 2026-09-14 · 7,218 characters in full

01 What it does

What the visual-design-foundations Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

This skill teaches how to build cohesive, accessible visual systems using typography scales, color theory, spacing systems, and iconography fundamentals. It covers establishing design tokens with modular type scales, 8-point grid spacing, semantic color palettes with WCAG contrast requirements, and icon sizing systems.

The skill provides concrete implementation patterns for Tailwind CSS, responsive fluid typography, dark mode theming with semantic tokens, and accessibility validation. It addresses common visual design challenges like inconsistent spacing, poor contrast, and arbitrary magic numbers by defining ratio-based scales and reusable token systems.

What it produces

Design token definitions in CSS custom properties or Tailwind config
Icon component with size variants

See the example prompt ↗

How It Works

01
Establish Modular Design Tokens
Define typography scales with ratio-based sizing (0.75rem to 3rem), 8-point grid spacing (4px to 64px), and semantic color tokens for brand, states, and neutrals.
02
Apply Responsive Typography
Use fluid typography with clamp() for viewport-responsive sizing and maintain optimal reading width at 65 characters maximum.
03
Implement Accessible Color Palettes
Build color systems that meet WCAG contrast ratios: 4.5:1 for body text, 3:1 for large text and UI components, with programmatic contrast checking.
04
Create Consistent Icon Systems
Define icon sizing scales from 12px to 32px with reusable components that accept size props and maintain flex-shrink-0 behavior.
05
Design Dark Mode with Semantic Tokens
Use semantic token naming by purpose rather than appearance, allowing theme switching via data attributes without component changes.
06
Maintain Vertical Rhythm
Apply consistent spacing rules to adjacent elements using defined scale values to create visual harmony throughout the interface.

02 Find your fit

When to Use the visual-design-foundations Skill

Use the visual-design-foundations skill in Claude Code or Codex when the job is brand and design-system work of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

Establishing design tokens for a new project
Creating or refining a spacing and sizing system
Building accessible color palettes
Designing icon systems and visual assets
Auditing designs for visual consistency

What to Provide

Theming specificationsRequirements for implementing dark mode or multi-theme systems with semantic token strategies

03 Inside the skill

Rules the visual-design-foundations Skill Gives Claude Code and Codex

4 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

Use 8-point Grid Spacing
All spacing values must follow multiples of 4px, from 0.25rem (4px) up to 4rem (64px), using the defined spacing scale tokens.
Apply Strict Line Height Ranges
Headings must use 1.1 to 1.3 line height, body text 1.5 to 1.7, and UI labels 1.2 to 1.4 for proper readability.
Cap Text Width at 65 Characters
Set max-width to 65ch for body text to maintain optimal reading width and prevent eye strain on wide screens.
Apply Component Spacing Ranges
Card padding must be 16-24px, section gaps 32-64px, form field gaps 16-24px, and icon-text gaps 8px using the spacing scale.

04 Put it to work

Install visual-design-foundations in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add visual-design-foundations to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal

npx skills add https://github.com/wshobson/agents --skill visual-design-foundations

Generic skills CLI form for plugins/ui-design/skills/visual-design-foundations/SKILL.md; the repository may document its own path.

Give the Skill a First Brand and design-system Work Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt

Create a design token system for [project name] with an 8-point spacing grid, modular typography scale from 12px to 48px, and an accessible color palette including primary brand color [hex value], semantic status colors for success/warning/error, and a complete neutral gray scale. Implement both light and dark mode variants using semantic token naming. Include Tailwind configuration and verification that all text combinations meet WCAG AA contrast requirements.

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

Verify all text and UI component color combinations meet WCAG contrast ratio requirements using programmatic checking
Test that font loading uses font-display swap to prevent layout shift
Ensure responsive typography scales smoothly across viewport sizes using clamp functions

In OpenDesign import visual-design-foundations from its SKILL.md link: Plugins → Add → Skill → Import from link, then pick it in the top bar.

Download OpenDesign Read the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author: Seth Hobson
Repository: github.com/wshobson/agents Branch main
Skill file: plugins/ui-design/skills/visual-design-foundations/SKILL.md Content checksum recorded at verification; commit 4236bb9
License: MIT From LICENSE.
Repository stars: 39,635 GitHub snapshot taken 2026-09-14 for the whole wshobson/agents repository, which contains 18 skills in this catalog. Not a rating or usage count for visual-design-foundations.
Verified by OpenDesign: 2026-09-14 Source file, path, license text and star count were checked. Not bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

When to Use This SkillLists scenarios like establishing tokens, building palettes, auditing consistency, and implementing dark mode
Core SystemsDefines modular typography scale, 8-point spacing grid, and semantic color token structure with CSS custom properties
Quick Start: Design Tokens in TailwindProvides Tailwind config example extending theme with custom fonts, sizes, colors, and spacing values
Typography Best PracticesCovers font pairing combinations, responsive fluid typography with clamp, and preventing layout shift during font loading
Color TheoryDetails WCAG contrast requirements, dark mode implementation strategy, and programmatic contrast ratio checking function
Spacing GuidelinesSpecifies component spacing ranges and demonstrates vertical rhythm patterns for prose content
IconographyDefines icon sizing system from 12px to 32px and provides TypeScript icon component implementation
Best PracticesSeven principles including establishing constraints, documenting decisions, testing accessibility, and using semantic naming
Common IssuesLists problems like inconsistent spacing, poor contrast, font overload, magic numbers, and missing dark mode planning

The Skill's Own Description

“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.”

Front-matter description from SKILL.md. The full file is about 7,218 characters. Read the full file on GitHub.

Visual Design Foundations

Run visual-design-foundations on a Real Brand and design-system Work Task.

Download OpenDesign, import visual-design-foundations from its SKILL.md link, paste the prompt above, and read the plan before the result.

Download OpenDesign Browse all skills