visual-design-foundations

Overview of visual-design-foundations skill

What visual-design-foundations is for

The visual-design-foundations skill helps an agent turn vague UI design goals into a more coherent visual system using practical foundations: typography scales, color systems, spacing tokens, and iconography rules. It is most useful when you need structure fast, not just inspiration—especially for design tokens, style guide setup, visual hierarchy cleanup, or a first-pass UI system for product work.

Best fit users and projects

This visual-design-foundations skill is a strong fit for:

• product designers defining a baseline system
• frontend engineers creating design tokens in CSS
• teams standardizing spacing, type, and semantic colors
• AI-assisted UI design workflows that need repeatable rules

It is less about producing polished final mockups and more about giving your interface a defensible foundation that can be implemented consistently.

What makes this skill different from a generic prompt

A normal “make this UI look better” prompt often stays subjective. visual-design-foundations is better when you want the model to reason from systems:

• modular typography scales instead of arbitrary font sizes
• 8-point spacing logic instead of ad hoc padding values
• semantic color tokens instead of one-off hex choices
• accessible hierarchy guidance instead of purely aesthetic feedback

The included references add useful implementation detail, especially around OKLCH color scales, semantic token layering, and ratio-based typography.

What users usually care about first

Before installing visual-design-foundations, most users want to know:

1. whether it outputs reusable tokens or just advice
2. whether it helps with accessibility and dark mode
3. whether it can guide UI cleanup without a full design system team
4. whether the examples are close enough to frontend implementation to be actionable

On those points, the skill looks practical: the source includes concrete CSS token patterns and supporting reference files worth reading before relying on the first output.

How to Use visual-design-foundations skill

Install context for visual-design-foundations

Install the skill from the wshobson/agents repository:

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

Because the upstream skill does not ship helper scripts, your main value comes from how well you invoke it and whether you read the reference docs before asking for a full system.

Read these files first

If you want to use visual-design-foundations install time well, read in this order:

1. plugins/ui-design/skills/visual-design-foundations/SKILL.md
2. plugins/ui-design/skills/visual-design-foundations/references/typography-systems.md
3. plugins/ui-design/skills/visual-design-foundations/references/color-systems.md
4. plugins/ui-design/skills/visual-design-foundations/references/spacing-iconography.md

Why this order:

• SKILL.md gives the usage scope
• typography and color references contain the strongest implementation signals
• spacing and iconography helps convert abstract guidance into tokens and component spacing rules

What input the skill needs to work well

The visual-design-foundations usage quality depends heavily on the inputs you provide. Give the agent:

• product type: SaaS dashboard, mobile app, marketing site, admin tool
• platform: web, iOS, Android, cross-platform
• brand tone: clinical, playful, premium, utilitarian
• current constraints: existing brand color, font, component library, accessibility target
• deliverable needed: token set, style guide, audit, hierarchy revision, dark mode system
• implementation format: CSS variables, Tailwind tokens, design spec, Figma-ready naming

Without those, the skill will default to generic “good design” advice.

Turn a rough goal into a strong prompt

Weak prompt:

• “Use visual-design-foundations for my app.”

Better prompt:

• “Use visual-design-foundations to define a visual system for a B2B analytics dashboard. I need a typography scale, semantic color tokens, spacing tokens, and icon guidelines. Primary users are analysts working long sessions, so readability matters more than visual novelty. Keep existing brand hue near blue, support light and dark themes, and output implementation-ready CSS custom properties plus rationale.”

This is better because it defines:

• context
• user needs
• constraints
• outputs
• tradeoffs

Ask for outputs in layers

A good workflow is to request the result in this sequence:

1. visual principles and constraints
2. typography system
3. spacing system
4. color token system
5. iconography rules
6. component-level application examples

That sequence matches the structure of the skill and reduces low-quality one-shot outputs.

Use the references to force implementation-ready answers

The reference files suggest what the skill handles best:

• references/typography-systems.md: modular scale ratios, line-height logic, CSS custom properties
• references/color-systems.md: perceptual scales, semantic tokens, OKLCH examples
• references/spacing-iconography.md: 8-point grid, component spacing tokens, icon sizing consistency

If you explicitly ask the model to use those patterns, you are more likely to get reusable tokens rather than vague art direction.

Strong prompt pattern for visual-design-foundations for UI Design

Use a prompt shape like this:

• Goal
• Product context
• Visual tone
• Accessibility requirements
• Existing constraints
• Requested output format
• Examples of screens or components to prioritize

Example:

• “Apply visual-design-foundations for UI Design to a healthcare patient portal. Keep the UI calm and trustworthy, preserve our teal brand direction, meet WCAG-friendly contrast expectations, and propose a type scale, semantic colors, spacing tokens, and icon sizing rules. Then show how these choices affect form fields, tables, alerts, and navigation.”

What the skill is especially good at

In practice, visual-design-foundations guide value is highest when you need:

• a first-pass token system
• a consistency audit lens
• accessible color structuring
• hierarchy cleanup for dense interfaces
• dark mode starting rules
• implementable CSS variables

It is especially useful for moving from “design feels inconsistent” to “here is a governed system.”

Where it may feel thin

This skill is not a full UI kit generator. Based on the repo structure, it does not include:

• automated validation tools
• component-specific scripts
• design file exports
• screenshot analysis workflows
• deep brand strategy frameworks

If your need is highly visual exploration, marketing art direction, or bespoke motion-heavy design, this may be too foundational on its own.

Practical workflow after first output

After the first run:

1. keep the token names that fit your codebase
2. challenge any color pairings against real accessibility targets
3. test the type scale on actual table, form, and card layouts
4. reduce token count if the model over-produces variants
5. ask for a revised pass using your chosen base size, ratio, and brand hue

This second pass is usually where visual-design-foundations usage becomes production-relevant.

visual-design-foundations skill FAQ

Is visual-design-foundations good for beginners?

Yes, if you already know basic UI terms. The skill gives structure around typography, color, spacing, and iconography, so it can teach by output. But beginners should still sanity-check contrast, sizing, and implementation decisions rather than copying everything verbatim.

Does visual-design-foundations produce code or just principles?

It can support both, but its strongest evidence is implementation-oriented examples such as CSS custom properties and token structures. Expect better results when you ask explicitly for CSS variables, semantic token naming, or design-system-ready output.

Is this better than a normal UI design prompt?

Usually yes when your problem is consistency, hierarchy, or token design. A generic prompt can generate attractive suggestions, but visual-design-foundations skill is more useful when you need a repeatable system that engineering can implement.

Can I use visual-design-foundations for audits?

Yes. It is well suited to auditing an existing interface for:

• inconsistent spacing
• weak type hierarchy
• non-semantic color use
• icon size drift
• poor readability in dense layouts

Provide screenshots or a written inventory of current tokens and components for a better audit.

Does it help with dark mode?

Yes, indirectly. The color reference material includes semantic token thinking and structured scales, which makes dark mode easier to derive. It is better at setting up a themeable system than at producing polished dark mode visuals from zero context.

When should I not use visual-design-foundations?

Skip visual-design-foundations if your main need is:

• high-fidelity visual exploration
• brand storytelling and creative direction
• advanced motion design
• illustration systems
• one-off landing page polish with no design-system goal

In those cases, a more brand- or art-direction-focused workflow will fit better.

How to Improve visual-design-foundations skill

Give constraints before asking for solutions

The biggest quality boost for visual-design-foundations comes from constraints. Specify:

• base font size
• preferred type scale ratio if known
• brand hue or existing palette
• accessibility target
• density preference: compact, balanced, spacious
• component priorities

That forces the model to make grounded tradeoffs.

Ask for semantic tokens, not raw values only

Many first outputs fail because they stop at raw hex colors and font sizes. Ask for:

• primitive tokens
• semantic tokens
• component usage guidance

For example:

• primitive: blue-500
• semantic: color-action-primary
• usage: button background, active nav state, focus ring

This makes visual-design-foundations guide outputs much easier to adopt.

Prevent overdesigned type scales

A common failure mode is an exaggerated scale that looks elegant in isolation but breaks real product screens. Improve results by telling the agent:

• body text size range
• smallest acceptable text
• whether your interface is data-dense
• whether headings should stay restrained

For dashboards and forms, conservative scales often outperform dramatic ones.

Keep spacing tied to component reality

Another common miss is a clean token ladder that does not map well to actual UI patterns. Ask the model to show spacing rules for:

• form fields
• cards
• tables
• modals
• page sections
• button padding

This turns the 8-point system from theory into decisions you can test.

Make color outputs safer and more useful

To improve visual-design-foundations for UI Design, ask the agent to separate:

• brand colors
• surface colors
• text colors
• status colors
• interactive states

Also ask it to explain where contrast risk is highest, such as tinted surfaces, disabled states, or subtle borders. This usually produces more trustworthy palettes than asking for “modern colors.”

Ask for one revision with fewer tokens

First outputs often include too many steps or semantic roles. A productive second prompt is:

• “Reduce this system to the minimum viable token set for version 1 while preserving accessibility and consistency.”

That helps teams adopt the skill faster.

Compare recommendations against your stack

If you use Tailwind, CSS variables, or a formal design token pipeline, ask the agent to map outputs into that structure. visual-design-foundations install value increases when the output matches your real implementation path instead of staying abstract.

Improve output with concrete before-and-after tasks

Instead of asking broadly for a visual system, ask the skill to improve a specific screen:

• “Here are the current font sizes, spacing values, and colors on our settings page. Use visual-design-foundations to normalize them into a coherent system and explain what changes first.”

That creates sharper, more testable recommendations than open-ended system design.

Use iteration to separate foundation from styling

A reliable workflow is:

1. first pass: foundations only
2. second pass: map to tokens
3. third pass: apply to components
4. fourth pass: refine tone and brand expression

This keeps visual-design-foundations usage focused on its real strength: system quality before decoration.