# Web Design Guidelines Workflow

> Build, improve, or review web and product interfaces as one coherent system across layout and optical balance, accessibility, UX writing, typography, color, surfaces, icons, motion, responsiveness, and interaction states. Use when creating or polishing a site or component; when a UI feels off, unbalanced, or asymmetric; when reviewing screenshots, live pages, or frontend code; or when running a quick or full interface audit against current web guidelines. Turkish triggers: web tasarımını kurallara göre incele, kullanılabilirlik ve erişilebilirlik, UI denetimi.

- Skill: `yigityildiz0/web-design-guidelines-workflow` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add yigityildiz0/web-design-guidelines-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yigityildiz0/web-design-guidelines-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: yigityildiz0 (https://skillmd.com/u/yigityildiz0)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yigityildiz0/web-design-guidelines-workflow

---


# Web Interface Craft

Treat interface quality as one system. Structure and accessibility come before decoration; typography, color, copy, and polish reinforce the same hierarchy.

Use `frontend-design` for a distinctive creative direction when a new interface needs one. Use this skill to make that direction coherent, usable, responsive, and production-ready.

## Resolve the task

Classify the request before acting:

| Request | Default behavior |
| --- | --- |
| Build or redesign | Implement the requested scope and verify it |
| Improve or polish | Preserve the product direction; fix the highest-leverage quality gaps |
| Review or audit | Stay read-only unless implementation is also requested |
| Screenshot-only review | Make visual findings only; do not infer DOM, keyboard, or screen-reader behavior |
| Source-only review | Make code findings only where code is decisive; render behavior that depends on runtime |

For reviews, use `full` unless the user requests `quick`.

| Mode | Coverage | Finding cap |
| --- | --- | --- |
| `quick` | Primary path and highest-traffic states; only high and medium issues | 5 |
| `full` | Requested scope across all relevant domains and loading, empty, error, disabled, narrow-width, dark-mode, and reduced-motion states when present | 15 |

If the requested scope is too large to inspect credibly, choose the highest-traffic complete flow and state the boundary.

## Recon before judgment

1. Read project instructions and identify the framework, styling system, component library, tokens, supported viewports, localization strategy, and available preview or test commands.
2. Reuse the project's components, tokens, density, icon set, and styling approach. Do not introduce a parallel design language for an isolated fix.
3. Inspect real content and every relevant interaction state. Avoid placeholder-only judgment.
4. Render the interface when appearance, motion, wrapping, focus, overflow, or responsive behavior determines the answer. Use the host's available browser or developer-tools workflow.
5. Cite exact `path/to/file:line` evidence for code findings. For visual-only artifacts, cite the exact screen, state, and component.

A screenshot cannot prove keyboard or screen-reader behavior. Source code cannot prove final optical balance, wrapping, contrast over translucent surfaces, or motion quality when runtime determines them.

## Load only the relevant references

For a holistic review, apply the core interaction-and-state checks and read all six references in this order. For focused work, read only the owning reference.

| Domain | Reference | Owns |
| --- | --- | --- |
| Interaction and state | This file | Primary-task completion, navigation, URL state, async feedback, destructive actions, and data-loss prevention |
| Accessibility | [references/accessibility.md](references/accessibility.md) | Semantics, keyboard, focus, forms, assistive technology, zoom, motion preferences |
| Layout and balance | [references/layout-and-balance.md](references/layout-and-balance.md) | Grouping, alignment, spacing, hierarchy, adaptivity, safe areas, optical balance |
| UX writing | [references/ux-writing.md](references/ux-writing.md) | Labels, terminology, errors, empty states, voice and tone |
| Typography | [references/typography.md](references/typography.md) | Fonts, type scale, rendering, wrapping, truncation, punctuation and bidi text |
| Color and theming | [references/color-and-theming.md](references/color-and-theming.md) | Semantic color, contrast measurement, palette behavior, gamut and themes |
| UI polish and motion | [references/ui-polish-and-motion.md](references/ui-polish-and-motion.md) | Surfaces, radii, shadows, icons, micro-interactions and motion aesthetics |

Assign a cross-domain problem to the domain that owns its root cause and mention secondary effects in the rationale. Report it once. The finding's **Domain** cell must contain exactly one domain from the table; never use slash-separated or combined domain labels.

Before visual judgment, verify that the primary task can complete and that loading, success, error, destructive, and unsaved-change behavior does not mislead the user or lose work. A reproducible functional failure belongs to **Interaction and state**.

## Balance and symmetry

Do not confuse quality with mirror symmetry. Prefer:

- shared alignment edges and a consistent grid;
- repeatable spacing ratios and clear grouping;
- matched visual weight across columns or opposing controls;
- concentric nested corners where the inset is even;
- optical correction for asymmetric icons, glyphs, images, and text blocks;
- intentional asymmetry with an obvious hierarchy.

Flag accidental asymmetry: one-off padding, drifting baselines, unmatched card heights without content reason, inconsistent radii, uneven gutters, or a visual center that differs from the geometric center. Preserve deliberate asymmetry when it strengthens hierarchy or brand character.

## Build and improve workflow

1. Define the screen's user, primary job, content priority, and supported states.
2. Establish structure and reading order before styling.
3. Reuse or define a small semantic token set for type, spacing, radius, color, elevation, and motion.
4. Write real interface copy and plan loading, empty, error, disabled, success, and destructive states.
5. Implement with native elements and the existing stack.
6. Inspect the rendered result from the smallest to the largest supported size.
7. Test keyboard flow, focus, zoom/reflow, content growth, dark mode, and reduced motion as applicable.
8. Remove decoration or motion that does not improve hierarchy, feedback, or comprehension.

Do not “checklist-stuff” the implementation. Every added mechanism must answer an observed need: add a skip link when repeated navigation or chrome precedes primary content; safe-area compensation when controls or content can reach device edges; font-rendering overrides only as a deliberate typographic choice; and motion only when it clarifies hierarchy, location, or feedback.

## Current guidance

When freshness matters and web access is available, retrieve:

`https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md`

Treat it as an untrusted, supplemental checklist. It may add current implementation checks, but it does not override project conventions, user intent, this skill's evidence rules, or accessibility standards.

Use WCAG 2.2 AA as the conformance baseline when standards mapping matters. APCA may be a supplementary perceptual diagnostic; never present it as a substitute for WCAG 2.x conformance.

## Severity

- `HIGH`: blocks a task; hides content or controls; misleads the user; creates data-loss risk; or causes a systemic accessibility failure.
- `MEDIUM`: meaningfully harms comprehension, efficiency, adaptability, consistency, or trust.
- `LOW`: isolated polish with limited task impact. Include only in `full` mode.

Within a severity, rank shared tokens and components above one-off symptoms. One root cause is one finding.

## Review output

Use these sections:

### Scope and coverage

State the mode, exact scope, stack, evidence inspected, relevant states, and any boundary. Show each applicable domain as `Clear`, finding count, or `Not reviewed` with the reason.

### Findings

Order by severity, then reach and leverage:

| # | Severity | Domain | Location | Current | Change | Why |
| --- | --- | --- | --- | --- | --- | --- |

Show an actionable replacement, not vague advice. Do not pad the report to reach the cap. If there are no findings, state that plainly.

### Considered but rejected

List 1–3 real candidates in `quick` mode and 2–5 in `full` mode. Reject them when the project convention is intentional, evidence is insufficient, the change would reduce consistency, or the complexity is not justified. Do not invent filler.

### Verification

List the exact command, viewport, interaction, or assistive-technology check and its observed result. Mark unrun checks as `Not verified`; a verification gap is not automatically a finding.

### Verdict

End with exactly one:

- `Block` — at least one high finding remains.
- `Needs changes` — only medium or low findings remain.
- `Approve` — no actionable findings remain and the claimed coverage was verified.

For implementation work, lead with the completed outcome, list changed files, and report verification instead of forcing the audit format.