frontend-design

Files (2)

• SKILL.md
• design-brief.md · references/

SKILL.md (first lines)

# Frontend Design

You already know how to design. These are reminders for the places where
agent-built interfaces most often fall short. The brief and the project's
`DESIGN.md` win over anything here. Make each visual choice serve the person
using the page and the page's one job.

## Before You Build

- Name the user, the outcome they need, and the page's single job. Design the
  smallest complete workflow first, including its empty, loading, error and
  success states, before you choose a shell or navigation.
- When improving existing UI, look at it running first (`eyes-on`). Keep the
  conventions that work and change the few things with the most impact.
- Ask only when an unknown would change the workflow, content priority, or
  visual direction. Otherwise state the assumption and proceed.
- Write a short plan before a new screen or redesign: the direction in a few
  concrete words, the structural system, the type voices and their jobs, the
  colour roles, and the one signature element you will spend boldness on.
- Choose the direction from the subject and the brief, not from habit. When
  the brief pins a direction, execute it fully and precisely. When an axis is
  free, ask whether your choice would appear unchanged for an unrelated
  product; if it would, find a reason in this subject or change it.

## Keep A Design Record

`DESIGN.md` in the target project is the durable record of design decisions.
Read it before a material decision. Create it at the first substantial design
consultation, and update it when feedback, testing or review changes a
decision. Record the decision and its reason, not the conversation. Use
[the `DESIGN.md` template](references/design-brief.md) for a substantial flow
or redesign. Project palettes, typefaces and signature elements belong there,
not in this skill.

When someone is choosing a palette, let them compare a few named candidates on
a real screen of the product (a local-only switcher), then keep only the
winner's tokens.

## Structure

- Give the content a structural system to sit in: a column, a grid, rules or
  a spacing rhythm, and make every section obey it, with the same spacing
  between sections and no stray empty bands. Visible structure can carry a
  page with very little decoration. Hold one shape language (corner radius,
  border weight) across every component, chips, tags and badges included.
- When items repeat (cards, rows, plans), every item shows the same fields in
  the same order, so people compare instead of re-reading.
- The primary action matches the page's job and leads to the thing the page
  is about. On a long page, repeat it at the end. Keep the first view lean:
  the page's job, the primary action and the key overview stay above the
  fold; anything else (contact, sharing, social, extra facts) goes lower.
- Give persistent information (navigation, current location, status) a
  stable position, and keep sticky or fixed chrome from covering content,
  headings or focused elements. Offset in-page targets for it.
- Keep text at a readable measure. On wide screens, use the spare width for
  navigation or deliberate space, not longer lines.
- A loading, empty or refreshed state keeps the settled state's box. Nothing
  the user can select moves when data arrives. Media reserves its aspect
  ratio.
- Feedback and indicators never reflow the text they describe.

## Type

- Use a small number of type voices, each with one job (for example display,
  reading, and a utility voice for labels, data and controls). Give each text
  role one repeatable treatment. When the brief or design record assigns a
  voice to a role (navigation, tags, buttons), apply it, casing included,
  everywhere that role appears: side navigation, tags, secondary controls and
  narrow layouts.
- Small labels that carry meaning still pass contrast. Make them quieter with
  size, weight or case, not faint grey. Keep the faintest tones for rules,
  ticks and decoration.
- When a label does not fit, shorten the words. Do not truncate meaning.
- Headings add information beyond a section's number or label rather than
  repeating it. Keep multi-line headings from stranding one short word.

## Colour

- Keep most of the surface neutral and give colour a job: action, state, or
  identity. One family per job.
- State colours mean state and stay the same on every item. Identity colours
  identify. Never let an identity colour read as a warning or error, and never
  colour state by identity.
- When sibling items each get an identity colour, choose the set together and
  check it side by side in both themes. Every pair should read as clearly
  different at a glance (aim for roughly ΔE 25), apart from the state colours,
  and saturated enough to read as a colour, not as ink. Neighbours in a
  spectrum (blue, indigo, violet) read as one family. When hue separation runs
  out, separate by lightness, shape, label or placement rather than forcing
  more hues. An item's identity (colour, type voice) carries everywhere the
  item appears: overview strips, navigation and its own card. Where it colours
  text, darken the light-theme variant until that text passes.
- Colour is never the only signal for status, selection or errors. When
  colour, shape or size encodes something that isn't self-evident, say what it
  means on the page with a short key or legend.
- Build both a light and a dark theme and follow `prefers-color-scheme`. If
  there is a theme toggle, remember the choice and switch without a flash.
- Design the dark theme rather than inverting it: lift accents so they hold
  contrast on dark, flip the primary emphasis, keep hairlines dim but
  visible, raise surfaces instead of relying on shadows, then recheck every
  label against the accessibility bar.

## Wayfinding

- On a long page or flow, help people answer: how far am I, where am I, and
  what comes next. One element can carry progress, contents and navigation
  together.
- Navigation aids carry real information and are operable. Section names in
  them are real links whose labels match the headings, the current one is
  marked (`aria-current`), and they sit early in the tab order. Any control
  that moves the reader (a progress scale, a minimap) also has a keyboard
  path. Do not draw an indicator that looks interactive and is not.
- When you build a section rail or contents list, make sure it includes:
  previous and next placed around the list, as links like the section items;
  the state of each section shown with words ("here", "next", "read") or
  proportion, not only a paler tone; every label at 4.5:1 or better; and after
  a jump, focus moved into the target section so keyboard and screen-reader
  users land where they asked to go.
- Keep numbering and names consistent between headings, navigation and

From AnthonyPoschen/agent-skills, MIT.

More from AnthonyPoschen/agent-skills