visual-design

---
name: visual-design
description: "Design the visual layer of a web interface to the standard of a mature product design system. Use when the task sets type scale and font loading, the spacing scale, grid, breakpoints and density, colour tokens and dark mode, radius and elevation, iconography, chart styling, or the navigation, hero and footer; and when an interface looks generic and needs the look fixed. Enforces anti-generic rules with a reason each: no eyebrow or kicker labels above headings, no gradient text, no default purple-to-blue gradients, no emoji icons, no reflex glass, centring or three-card grid, no fake logos, metrics or filler. Owns scripts/ui_tells.py, which scans HTML, JSX, TSX, Vue, Svelte and Astro for those tells. Triggers on design system, type scale, design tokens, dark mode, it looks AI-generated, make it look professional, eyebrow heading, review the design. For sourcing licensed kits use ui-compose. For building components use frontend-build. For animation use motion-design. For interface copy use ux-writing."
license: MIT
metadata:
  version: 1.0.1
  suite: ai-skill
---

# Visual design

A page built fast by a model has a recognisable look: a small uppercase label sitting above every
heading, a purple-to-blue gradient on the hero, text filled with a gradient, three icon cards in a
row, everything centred, a few emoji standing in for icons, and grey boxes where real content should
be. None of those choices was made for a reason. This skill replaces reflexes with decisions about
type, space, colour, layout and imagery, each tied to a standard a real design team uses, so the
result looks designed rather than generated.

## When to use and when to stay off

Run when the task is the visual layer of a web interface: the type scale and line length, how fonts
load without shifting layout, the spacing scale and grid, breakpoints and density, colour tokens and
dark mode, radius and elevation, icon style, imagery and art direction, chart styling, or the
navigation, hero and footer. Also run when an interface already exists and the complaint is that it
looks generic or machine-made.

Stay off, and route instead, when:

- The task is sourcing the actual components, kits, icons and fonts, with their licences. Use `ui-compose`.
- The task is building the components in code: data states, forms, rendering strategy, client performance. Use `frontend-build`.
- The task is animation, transitions or scroll behaviour. Use `motion-design`.
- The task is the words on the buttons, labels and headings. Use `ux-writing`.
- The task is a logo or identity mark. Use `brand-logo`.
- The task is a 3D scene. Use `web-3d`.

The user says "stop", "I've decided", or "just execute": comply at once and stay off for the rest of
the session unless asked again.

## Non-negotiables

These override everything else in this file.

1. No eyebrow or kicker. Never place a small, often uppercase or letter-spaced label or pill directly above a heading. It is the clearest machine-output tell and adds no information the heading does not already carry. Put the qualifier in the heading or drop it.
2. Every visual value comes from a token, not a literal. Colour, space, radius, type size and shadow are named scale steps. A one-off hex or pixel value in a component is a defect to fix, not a style.
3. Colour pairs that carry text or meaning meet WCAG 2.2 contrast: 4.5:1 for body text, 3:1 for large text and for non-text such as icons and input borders. Measure it, never judge by eye.
4. No invented content standing in for real content: no fake company logos, no made-up testimonials or metrics, no lorem-ipsum filler, no placeholder image host. Use the real content, or a labelled empty state, never filler dressed as truth.
5. Facts about platform support, token values and standards are verified live this session against the source and dated. A design system's own documentation is the source for its tokens, not memory.
6. Decorative colour choices are not accessibility claims. Meeting contrast is a floor, not proof the design is accessible; state what was measured and what a human still has to check.

## Procedure

Token definitions and worked scales are in `references/tokens.md`. Page and section layout patterns are
in `references/layout-patterns.md`. The screenshot and comparison review is in
`references/review-protocol.md`.

### Step 1, fix the reference and the constraints

Name two public design systems to work against, by link, before touching a value. Use them for how a
mature team sizes type, spaces a grid and builds a colour ramp, not for copying a look:

- Material 3, [m3.material.io](https://m3.material.io) (open tokens, type scale, elevation, shape).
- IBM Carbon, [carbondesignsystem.com](https://www.carbondesignsystem.com) (type set, 2x grid, spacing).
- Atlassian, [atlassian.design/design-system](https://atlassian.design/design-system).
- GOV.UK, [design-system.service.gov.uk](https://design-system.service.gov.uk) (restraint, readability).
- Apple Human Interface Guidelines, [developer.apple.com/design](https://developer.apple.com/design).
- Fluent 2, [fluent2.microsoft.design](https://fluent2.microsoft.design).

Brand sites are layout and quality references only. Never copy their code or assets, and never reach
for a tool that lifts another site's markup. Record the brand, the page and what you are learning from
it (a spacing rhythm, a density, a restraint), not a screenshot to trace.

Write down the constraints that decide the rest: the brand's existing colours and type if any, the
content density the product needs, the primary breakpoints, light only or light and dark, and the
accessibility target (default to WCAG 2.2 AA).

### Step 2, set type

Choose a type scale with a fixed ratio rather than ad hoc sizes. A modular scale (for example 1.2 for
dense product UI, 1.25 for marketing) from a base of 16px gives steps a person can tell apart. Define
the steps as tokens and use only those.

Hold body line length between 45 and 75 characters by capping the text measure, not the viewport.
Set line height looser for body (around 1.5) and tighter for large headings (around 1.1 to 1.25).

Load fonts without shifting layout: `font-display: swap` with a matched fallback and
`size-adjust`, or self-hosted fonts preloaded. Subset to the characters and weights used. For Indian
scripts confirm the face covers the script and its conjuncts, and never synthesise bold or italic.
`references/tokens.md` has the type scale table and the fallback-matching method.

### Step 3, set space, grid and density

Use one spacing scale built from a base unit (4px is the common base; 8px for looser layouts) so every
gap is a multiple of it. Space belongs to the layout, applied with gap and padding tokens, not as
margins scattered on components.

Define breakpoints from the content, not from device names, and pick a column grid per range. Decide
density deliberately: a data-heavy admin screen and a marketing page want different row heights and
padding, and that is a token set, not a guess per component.

### Step 4, build colour tokens and dark mode

Build colour in two layers. A reference ramp holds the raw steps of each hue; semantic tokens
(surface, text, border, primary, danger, and their on-colours) point at ramp steps and are the only
names a component uses. Dark mode is a second mapping of the same semantic names, not a filter over the
light one.

Define the ramp in OKLCH so lightness and chroma are controllable and steps are even;
OKLCH is Baseline and widely supported (Chrome 111+, Safari 15.4+, Firefox 113+, around 95% of users as
of October 2026). Ship an sRGB fallback for the long tail. Check every text and non-text pair against
its background with the contrast script or a checker, in both modes, and record the ratios.
`references/tokens.md` has the ramp construction and the semantic token list.

### Step 5, set radius, elevation, icons and imagery

Pick a small radius set (for example 0, 6, 12px and full) and apply it by role, not per element.
Build elevation as a short, named shadow scale where higher means more blur and a larger offset, used
to show layering, not decoration. Nest radii correctly: an inner element's radius is the outer radius
minus the padding.

Choose one icon family and one weight, sized and aligned to the type, never a mix of styles and never
emoji standing in for icons. For imagery, decide an art direction (real product shots, a consistent
illustration style, or photography with a colour treatment) and hold to it; do not mix stock styles.
Style charts to the same tokens: a limited categorical palette that stays distinct for colour-blind
viewers, direct labels over legends where it fits, and no 3D or heavy gridlines.

### Step 6, lay out the page and run the tells check

Lay out navigation, hero, content and footer from `references/layout-patterns.md`. Resist the reflex
layouts: not everything is centred, a feature section is not automatically three icon cards, and a
hero does not need a gradient.

Run the structural checker over the markup and fix what it finds before review:

```
python3 scripts/ui_tells.py --strict src/
```

It flags eyebrow or kicker labels above headings, gradient text, default purple-to-blue gradients,
emoji in markup text, placeholder image hosts and lorem-ipsum filler, with severities. Then run the screenshot
review in `references/review-protocol.md`: capture 375, 768, 1280 and 1920px, check alignment and
vertical rhythm, and compare against the two references chosen in step 1.

## Self-audit

- No eyebrow, kicker, overline or pill sits directly above any heading.
- Every colour, space, radius, type size and shadow in the components is a token, with no stray literals.
- Body text sits between 45 and 75 characters per line, with a fixed type scale behind every size.
- Fonts load without a layout shift, and the fallback is size-matched.
- Dark mode is a second mapping of the semantic tokens, and contrast was measured in both modes with the ratios recorded.
- No gradient text, no default purple-to-blue gradient, no emoji icons, and no reflex glass, centring or three-card grid.
- No fake logo, testimonial, metric, lorem-ipsum filler or placeholder image host anywhere.
- `scripts/ui_tells.py --strict` passes on the markup, and screenshots at all four widths were reviewed against the two references.

## What this cannot do

It cannot source the components, kits, icons or fonts, or clear their licences; that is `ui-compose`.
It styles what that skill brings in.

It cannot judge contrast by eye or guarantee an interface is accessible. The script and a checker
measure colour pairs; a full accessibility pass (focus order, screen-reader labels, keyboard
operation, motion) is separate and larger.

It cannot invent a brand. Given no colours, type or voice, it proposes a neutral, accessible default
and says so, rather than presenting a guess as a brand decision.

It does not decide whether an image or font licence permits the intended use. For a font used in a
logo or a paid product, and for any stock or AI-generated image, ask an intellectual-property lawyer:
"Does this licence permit this specific commercial use, this modification and this distribution?"

• SKILL.md 11 KB
• references/layout-patterns.md 5 KB
• references/review-protocol.md 3 KB
• references/tokens.md 8 KB
• scripts/ui_tells.py 18 KB