Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Visual Design Foundations · itamarzand88 | DecimalAI

itamarzand88/visual-design-foundations

SkillScore73Maintained

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.

design-mediaby itamarzand88

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Design & UX Review pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/itamarzand88-visual-design-foundations/SKILL.md

decimalai skills pull itamarzand88-visual-design-foundations --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/itamarzand88-visual-design-foundations/SKILL.md https://app.decimal.ai/s/itamarzand88-visual-design-foundations/SKILL.md

Raw file: /s/itamarzand88-visual-design-foundations/SKILL.md ↗ · machine-readable summary at /s/itamarzand88-visual-design-foundations.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 51d ago

Yes — +5% lift · at higher cost+103% tokens0% turns73% of whole cases pass with skill (16/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-04	✗→✓	▲ Improved	96%	0%
case-15	✗→✓	▲ Improved	109%	0%
case-20	✓→✗	▼ Worse	101%	0%
case-14	✓→✓	＝ Same ✓	60%	0%
case-05	✓→✓	＝ Same ✓	92%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/2/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

itamarzand88 / awesome-agent-conventions

conventions/skill-md/examples/design-creative/wshobson-visual-design-foundations/SKILL.md

View on GitHub ↗

License MITImported 8/2/2026Version v1

Skill contents

SKILL.md

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):

css
: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):

css
: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.5rem; /* 24px */
  --space-8: 2rem; /* 32px */
  --space-10: 2.5rem; /* 40px */
  --space-12: 3rem; /* 48px */
  --space-16: 4rem; /* 64px */
}

3. Color System

Semantic color tokens:

css
:root {
  /* Brand */
  --color-primary: #2563eb;
  --color-primary-hover: #1d4ed8;
  --color-primary-active: #1e40af;

  /* Semantic */
  --color-success: #16a34a;
  --color-warning: #ca8a04;
  --color-error: #dc2626;
  --color-info: #0891b2;

  /* Neutral */
  --color-gray-50: #f9fafb;
  --color-gray-100: #f3f4f6;
  --color-gray-200: #e5e7eb;
  --color-gray-300: #d1d5db;
  --color-gray-400: #9ca3af;
  --color-gray-500: #6b7280;
  --color-gray-600: #4b5563;
  --color-gray-700: #374151;
  --color-gray-800: #1f2937;
  --color-gray-900: #111827;
}

Quick Start: Design Tokens in Tailwind

js
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: ["Inter", "system-ui", "sans-serif"],
        mono: ["JetBrains Mono", "monospace"],
      },
      fontSize: {
        xs: ["0.75rem", { lineHeight: "1rem" }],
        sm: ["0.875rem", { lineHeight: "1.25rem" }],
        base: ["1rem", { lineHeight: "1.5rem" }],
        lg: ["1.125rem", { lineHeight: "1.75rem" }],
        xl: ["1.25rem", { lineHeight: "1.75rem" }],
        "2xl": ["1.5rem", { lineHeight: "2rem" }],
      },
      colors: {
        brand: {
          50: "#eff6ff",
          500: "#3b82f6",
          600: "#2563eb",
          700: "#1d4ed8",
        },
      },
      spacing: {
        // Extends default with custom values
        18: "4.5rem",
        88: "22rem",
      },
    },
  },
};

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

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

p {
  font-size: clamp(1rem, 2vw + 0.5rem, 1.125rem);
  line-height: 1.6;
  max-width: 65ch; /* Optimal reading width */
}

Font Loading

css
/* 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

css
:root {
  --bg-primary: #ffffff;
  --bg-secondary: #f9fafb;
  --text-primary: #111827;
  --text-secondary: #6b7280;
  --border: #e5e7eb;
}

[data-theme="dark"] {
  --bg-primary: #111827;
  --bg-secondary: #1f2937;
  --text-primary: #f9fafb;
  --text-secondary: #9ca3af;
  --border: #374151;
}

Color Accessibility

tsx
// Check contrast programmatically
function getContrastRatio(foreground: string, background: string): number {
  const getLuminance = (hex: string) => {
    const rgb = hexToRgb(hex);
    const [r, g, b] = rgb.map((c) => {
      c = c / 255;
      return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
    });
    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
  };

  const l1 = getLuminance(foreground);
  const l2 = getLuminance(background);
  const lighter = Math.max(l1, l2);
  const darker = Math.min(l1, l2);

  return (lighter + 0.05) / (darker + 0.05);
}

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

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

.prose > h2 + * {
  margin-top: var(--space-2);
}

.prose > * + h2 {
  margin-top: var(--space-8);
}

Iconography

Icon Sizing System

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

Icon Component

tsx
interface IconProps {
  name: string;
  size?: "xs" | "sm" | "md" | "lg" | "xl";
  className?: string;
}

const sizeMap = {
  xs: 12,
  sm: 16,
  md: 20,
  lg: 24,
  xl: 32,
};

export function Icon({ name, size = "md", className }: IconProps) {
  return (
    <svg
      width={sizeMap[size]}
      height={sizeMap[size]}
      className={cn("inline-block flex-shrink-0", className)}
      aria-hidden="true"
    >
      <use href={`/icons.svg#${name}`} />
    </svg>
  );
}

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

Illustrative Want to see what itamarzand88/visual-design-foundations would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/7/2026, 23:00 UTC · 22 cases

Lift

+5%

73% vs 68%

Agent turns

1.0 vs 1.0

Tokens

+103%

5,195.64 vs 2,561.86

fail → pass · 2pass → pass · 14fail → fail · 5pass → fail · 1

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-14 We need a standard set of CSS custom properties for icon sizing across buttons, table rows, and headers. Rather than arbitrary pixel dimensions in each SVG component, what variable scale from xs to xl should we establish?	pass→pass	13,737	7,818	-43%	1	1	0%	2,822	4,519	+60%	0	0	—
case-01 I am starting a new web application and need a clean CSS custom properties file for our visual tokens. Please write a `:root` stylesheet defining a modular typography scale, an 8pt-based spacing framework, and semantic color definitions for primary actions, feedback states, and neutrals.	fail→fail	14,955	15,423	+3%	1	1	0%	4,591	7,376	+61%	0	0	—
case-02 Our team is standardizing design tokens in Tailwind CSS for an enterprise dashboard. Can you generate a complete `tailwind.config.js` file extending the core theme with explicit font family choices, modular font size definitions with line height rules, brand color palettes, and custom spacing entries?	fail→fail	18,113	17,239	-5%	1	1	0%	4,139	7,002	+69%	0	0	—
case-03 I am building a UI component library and need a cohesive theme setup that handles dark mode via data attributes, alongside a programmatic accessibility helper. Please output the CSS custom properties for both light and dark modes, plus a TypeScript function that calculates the contrast ratio between foreground and background hex values.	fail→fail	12,044	14,123	+17%	1	1	0%	3,496	6,669	+91%	0	0	—
case-04 We are defining fundamental CSS variables for typography across our web applications. Should we use arbitrary pixel names like --text-small, or a structured variable naming scheme for font sizes? We typically start headings at 48px and shrink down. Provide a CSS :root snippet.	fail→pass	11,237	9,619	-14%	1	1	0%	2,643	5,188	+96%	0	0	—
case-05 When setting up typography in CSS for body articles vs section headings, devs on our team often use a flat line-height of 1.5 across everything. What specific line-height ranges should be assigned to headings versus body text?	pass→pass	10,746	9,445	-12%	1	1	0%	2,481	4,768	+92%	0	0	—
case-06 We want to construct a spacing scale using CSS custom properties. Some engineers proposed incrementing by 5px (--space-5, --space-10). Is an 8-point grid better, and what rem values map to --space-1, --space-4, and --space-8?	pass→pass	11,946	8,882	-26%	1	1	0%	2,838	4,885	+72%	0	0	—
case-07 We are setting up color variables for our enterprise CSS system. Should we name them by appearance like --blue-600 and --red-500, or use functional names? Provide the CSS :root block with specific hex values for primary, success, warning, error, and info.	fail→fail	9,158	11,591	+27%	1	1	0%	2,064	5,887	+185%	0	0	—
case-08 We are choosing font pairings for a modern marketing site. Designers suggested pairing two heavy serif fonts together. What are safe, established typeface pairing strategies for modern UI?	fail→fail	11,667	10,918	-6%	1	1	0%	2,303	5,024	+118%	0	0	—
case-09 We need responsive styling for our top-level header and primary paragraphs to scale smoothly between mobile and desktop viewports without writing dozens of breakpoint media queries. How should we write the CSS for h1 and p elements, and what is the target max-width for paragraph readability?	pass→pass	8,288	6,686	-19%	1	1	0%	1,722	4,344	+152%	0	0	—
case-10 Users are complaining about invisible text rendering delays while our custom font loading finishes on slow mobile connections. How should we configure @font-face CSS for Inter to eliminate layout shifts and prevent invisible text?	pass→pass	11,659	9,795	-16%	1	1	0%	2,387	5,068	+112%	0	0	—
case-11 We are conducting an accessibility check on our design tokens according to WCAG requirements. What are the minimum required contrast ratios for standard body text versus large text or UI components?	pass→pass	9,356	5,866	-37%	1	1	0%	1,784	3,980	+123%	0	0	—
case-12 Our developers are using random pixel margins (e.g. 11px, 27px, 53px) across UI cards and page layouts. What are recommended standard spacing token ranges for card padding and section gaps?	pass→pass	12,304	10,945	-11%	1	1	0%	2,756	5,243	+90%	0	0	—
case-13 In our long-form blog articles, elements like subheadings and body paragraphs feel randomly spaced out. How can we maintain a consistent vertical rhythm between sibling elements and headings using CSS lobotomized owl or sibling combinators?	pass→pass	13,391	13,328	-0%	1	1	0%	2,576	5,484	+113%	0	0	—
case-15 Please write a React Icon component interface and implementation using SVG sprite symbols (`/icons.svg#name`). It needs a size prop supporting xs, sm, md, lg, xl mapped to standard pixel dimensions, defaulting to md.	fail→pass	8,859	7,022	-21%	1	1	0%	2,038	4,262	+109%	0	0	—
case-16 We are establishing core design guidelines for our frontend team. What are essential rules regarding font weight limits, mobile responsiveness strategy, and naming conventions for color tokens?	pass→pass	13,297	14,880	+12%	1	1	0%	2,596	5,845	+125%	0	0	—
case-17 Our design audit revealed multiple visual inconsistencies across our React web application. What common anti-patterns cause visual disorder and accessibility failures in web UIs?	pass→pass	16,268	17,822	+10%	1	1	0%	2,716	6,103	+125%	0	0	—
case-18 We need a standard grayscale CSS custom property palette ranging from ultra-light background grays to dark text grays. Please generate the `:root` definitions for --color-gray-50 through --color-gray-900 using standard Tailwind hex values.	pass→pass	4,769	4,243	-11%	1	1	0%	1,071	3,677	+243%	0	0	—
case-19 Our compact button labels and navigation badges look distorted when using body line-height (1.6). What line-height range is standard for UI labels and compact controls?	pass→pass	10,796	8,227	-24%	1	1	0%	2,038	4,322	+112%	0	0	—
case-20 We are building a responsive dashboard dashboard grid. How do I configure CSS Grid track sizes with `grid-template-columns: repeat(auto-fit, minmax(250px, 1fr))` to prevent track blowout when inner items overflow?	pass→fail	13,283	11,305	-15%	1	1	0%	2,408	4,847	+101%	0	0	—
case-21 How do I optimize raw vector SVG path data using SVGO command line flags to trim decimal precision and remove XML metadata without altering visual shapes?	pass→pass	12,905	10,027	-22%	1	1	0%	2,284	4,536	+99%	0	0	—
case-22 We are rendering dynamic charts using HTML5 Canvas 2D API context. How do we handle high-DPI retina displays using `window.devicePixelRatio` so drawings don't appear blurry?	pass→pass	13,237	12,830	-3%	1	1	0%	2,608	5,275	+102%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted. The headline lift of +5 percentage points is the difference between those two pass rates over the 22 comparable cases. 1 case got worse with the skill loaded, and it is included in that figure.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 68.2%
Pass rate with the skill: 72.7%
Cases attempted: 22
Cases counted toward lift: 22
Cases that regressed: 1
Skill version measured: v1
Run completed: 8/7/2026, 23:00 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-04

Prompt

We are defining fundamental CSS variables for typography across our web applications. Should we use arbitrary pixel names like --text-small, or a structured variable naming scheme for font sizes? We typically start headings at 48px and shrink down. Provide a CSS :root snippet.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run73

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+108% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 51 days ago

Other measured skills in the registry, with their headline benchmark lift.