Build design tokens and component specs, hand designs to engineers with clear annotations, and measure and iterate after launch.

Design Systems & Developer Handoff

Create a cover note with the screen name, status (ready for dev), owner, and a link or reference to the user flow.

Place the screen with its states next to it: default, loading, empty or zero, error, and a version with very long content.

Add numbered markers beside each interactive element and a matching note in the margin describing its behaviour.

For every input, write the validation rule and the exact error message text.

Write the responsive rules: what stretches, wraps or stacks at a narrow width, and any maximum width.

List which system components and tokens the screen uses, and mark anything that is new or custom.

Ask someone (ideally a developer or a developer friend) to read only your annotations and list every question they still have. Answer each one in the file.

## Why it matters

"Handoff" sounds like a single moment when you throw a file over a wall. In good teams it is a conversation that starts early and continues through build. Still, at some point engineers need a design they can build from without guessing. Missing details turn into questions, delays and inconsistent results. Clear **specs and annotations** are how you answer the questions before they are asked.

## The core idea: answer what the picture cannot

Modern tools give developers measurements, colours and fonts automatically. In Figma, **Dev Mode** shows spacing, sizes, variables (tokens) and generated CSS for any layer. (Dev Mode is part of Figma's paid plans; on the free plan developers can still inspect layers with view access, and you can write the same information as annotations.) What tools cannot show is **intent**: behaviour, rules, edge cases and anything that changes over time.

So annotations should focus on:

- **Behaviour**: what happens on tap, hover, scroll, submit, success, failure.
- **States and edge cases**: empty, loading, error, long text, zero, one and many items, offline.
- **Responsive rules**: what stretches, what wraps, what stacks at small widths, breakpoints.
- **Content rules**: maximum lengths, truncation, formatting of dates and numbers.
- **Data and logic**: where values come from, sorting, validation rules.
- **Components and tokens used**: so developers reuse the system instead of rebuilding.
- **Accessibility**: covered in depth in lesson 3 of this module.

## A handoff-ready file

Organise the file so it is easy to navigate:

1. **A cover or index page** with the project name, status, owner, links to the ticket and research, and a changelog.
2. **Ready-for-dev sections.** Mark which frames are final. Figma lets you mark sections "Ready for dev"; otherwise a clear label works.
3. **The flow** at the top: the screens in order, with arrows, so the developer sees the journey.
4. **Each screen** with its states next to it: default, loading, empty, error, long content.
5. **Numbered annotations** beside the design, with matching notes in a margin. Avoid notes scattered over the artwork.
6. **Responsive versions** at the key breakpoints, or written rules.

## Worked example: annotating a sign-up form

```text
Screen: Create account (mobile, 360 wide; desktop 1280, form max-width 400, centred)

1  Email field (Input/Default from the system)
   Validate on blur: must contain @ and a domain. Error text: "Enter an email address
   like name@example.com". Do not clear the field on error.
2  Password field (Input/Password)
   Min 8 characters, show/hide toggle (accessible label "Show password").
   Strength hint updates as the user types; it never blocks submit on its own.
3  "Create account" (Button/Primary/Medium)
   Enabled at all times. On submit with errors: focus moves to the first invalid field,
   and a summary appears above the form.
   Loading: label "Creating account...", repeat clicks ignored.
4  Server error (Alert/Error, above form)
   "We couldn't create your account. Try again in a minute." Keep entered data.
5  Success -> navigate to "Check your email" screen (frame 2.3).
Long content: error text wraps; never truncate.
Tokens: spacing between fields space-4; label to input space-1.
```

Each note says what the design cannot. Measurements and colours come from the file or Dev Mode; there is no need to repeat them, except where a rule matters (max-width 400).

## Working with engineers

- **Involve them early.** Review rough flows with an engineer before polishing. They will spot technical constraints and cheaper alternatives.
- **Walk through the design** in a short meeting at handoff rather than only sending a link.
- **Agree on naming**: component names and token names in Figma should match the code.
- **Keep one source of truth.** If a decision changes in chat, update the file and the changelog.
- **Review the build.** Check the implemented version against the spec (often called design QA) and file small, specific issues with screenshots.

## Common mistakes

- **Only the happy path.** Error, empty and loading states are part of the design.
- **Redlining every pixel** when the tool already provides it, while forgetting behaviour.
- **Unclear status.** Developers build an exploration that was never final.
- **Detached components** in final frames, so developers cannot tell which system component to use.
- **Silent changes** after handoff with no changelog.
- **Annotations on top of the artwork** that hide the design.

## Quick recap

- Handoff is a continuing conversation; specs answer questions before they are asked.
- Tools show measurements; annotations show intent: behaviour, states, edge cases, responsive and content rules.
- Organise the file with an index, ready-for-dev sections, the flow, states and numbered notes.
- Involve engineers early, match naming, keep one source of truth and review the build.

## Try it

On the Do tab you will annotate one screen from your own project for engineering.


Prepare a design for engineering with clear annotations, measurements, states and edge cases, using Figma Dev Mode or written notes.

Specs and annotations

Figma tutorial: Collaboration and handoff in Dev Mode

Design to Development Handoff

## Why it matters

You do not need to be a developer to design for the web, but being able to read HTML and CSS changes how you work. You can inspect a live page to see why it does not match the design, suggest a precise fix ("padding is 10px, the spec says 24px"), understand what is cheap or expensive to build, and make small fixes yourself in a pull request if your team allows it. Many product designer job listings ask for "a working knowledge of HTML and CSS" for exactly these reasons.

## The core idea: structure, then style

**HTML** describes structure and meaning: this is a heading, this is a button, this is a list. **CSS** describes presentation: colour, size, spacing, layout.

```html
<div class="plan-card">
  <h2 class="plan-card__title">Team plan</h2>
  <button class="btn btn--primary" type="button">Choose plan</button>
</div>
```

- Elements (`div`, `h2`, `button`) are the building blocks. The element choice matters for accessibility: a real `<button>` is focusable and works with the keyboard; a `<div>` styled like a button is not.
- `class` attributes are labels CSS uses to find elements. Names like `plan-card__title` follow a common convention (BEM: block, element, modifier), which often mirrors design-system component names.

A CSS **rule** is a selector plus declarations:

```css
.plan-card {            /* selector: elements with class plan-card */
  padding: 24px;        /* property: value; */
  border-radius: 12px;
}
```

## Properties designers adjust most

| Design idea | CSS property | Example |
|---|---|---|
| Inner spacing | `padding` | `padding: 8px 16px;` (top/bottom 8, left/right 16) |
| Outer spacing | `margin` | `margin: 0 0 16px;` |
| Corner radius | `border-radius` | `border-radius: 12px;` |
| Text size and weight | `font-size`, `font-weight`, `line-height` | `font-weight: 600;` |
| Colour | `color` (text), `background` | `color: #374151;` |
| Minimum size | `min-height`, `min-width` | `min-height: 44px;` |
| Side-by-side layout | `display: flex` and `gap` | `display: flex; gap: 8px;` |

Two concepts explain most surprises:

- **The box model.** Every element is a box: content, then padding, then border, then margin. Padding is inside the border (it gets the background colour); margin is outside.
- **The cascade.** When several rules target the same element, the more specific selector wins, and among equals the later rule wins. If your change "does nothing", another rule is probably overriding it.

## Inspecting a live page

Every desktop browser has free developer tools. In Chrome, Edge or Firefox, right-click an element and choose **Inspect**.

1. The **Elements** (or Inspector) panel shows the HTML; hover to highlight boxes on the page.
2. The **Styles** panel shows the CSS rules that apply, with overridden values crossed out.
3. The **Computed** panel shows final values and a box-model diagram with padding and margin.
4. You can edit values live to try a fix. Nothing is saved; reloading resets it.

That is how you turn "the card looks cramped" into "the card's padding is 10px; the spec is 24px (`space-4`)".

## Worked example: matching a spec

A plan card was built from a spec but looks wrong. Inspecting it shows:

```css
.plan-card { padding: 10px; border-radius: 3px; }      /* spec: 24px, 12px */
.plan-card__title { font-weight: 400; }                 /* spec: 600 */
.plan-card__badge { color: #a3a3a3; background: #fff; } /* about 2.5:1, fails 4.5:1 */
.btn { padding: 4px 12px; }                             /* about 27px tall; spec 44px */
.plan-card__actions { }                                 /* buttons should sit in a row, 8px gap */
```

Fixes:

```css
.plan-card { padding: 24px; border-radius: 12px; }
.plan-card__title { font-weight: 600; }
.plan-card__badge { color: #374151; }                   /* about 10:1 on white */
.btn { min-height: 44px; padding: 8px 16px; }
.plan-card__actions { display: flex; gap: 8px; }
```

In a real codebase these values would be tokens (`var(--space-4)`), as in the tokens lesson.

## Common mistakes

- **Fixing with a `<div>`.** If something acts like a button, it should be a `<button>`; a link that goes somewhere should be an `<a href>`.
- **Using margin for inner spacing** (or the reverse). Inside the border is padding.
- **Fixed heights on text containers.** Text grows when users zoom or translate; prefer `min-height` and padding.
- **Pixel-pushing in DevTools and forgetting to write it down.** Changes vanish on reload; record the fix in the ticket.
- **Changing shared CSS** that other components use without checking with the team.

## Quick recap

- HTML gives structure and meaning; CSS gives presentation.
- A CSS rule is a selector plus property-value declarations; the cascade decides which rule wins.
- Know the box model: content, padding, border, margin.
- Use browser DevTools (Inspect) to find the real values and propose precise fixes.

## Try it

On the Do tab you will adjust a plan card's CSS so it matches its spec: padding, radius, weight, contrast, button height and layout.


Read the HTML structure and CSS rules behind a component and adjust spacing, type, contrast and layout to match a spec.

Reading HTML/CSS as a designer

HTML & CSS 101 for designers

Mark the landmarks: banner, navigation, main, complementary (if any) and footer.

Mark every heading with its level (H1, H2, H3) based on structure, not visual size. Check there is one H1 and no skipped levels.

Number every interactive element in the order the Tab key should reach it. Include a skip link if the page has repeated navigation.

Write the accessible name for every control, especially icon-only buttons, and rewrite any vague link text such as "Click here".

Mark each image as meaningful (write its alt text) or decorative.

Write the state and announcement rules for anything that changes without a page load, and the focus behaviour for any modal, menu or error.

If you annotated a live page, test it: press Tab through it and compare the real focus order with your numbers. Note every difference.

## Why it matters

Many accessibility problems are decided before a single line of code: a reading order that jumps around, an icon-only button with no name, a modal with no defined focus behaviour, an error shown only in red. If the design does not specify these things, developers have to guess, and guesses are often wrong. **Accessibility annotations** make the invisible parts of a design explicit, so assistive technology users get the experience you intended. You covered the principles in Accessible & Responsive Interfaces; this lesson is about writing them down for handoff.

## The core idea: annotate what sighted mouse users never see

Screen reader and keyboard users experience a page as a structure and a sequence, not a picture. Annotations describe that structure and sequence. The most common categories are:

**1. Headings.** Mark each heading's level (H1, H2, H3) based on structure, not visual size. One H1 per page; do not skip levels.

**2. Landmarks.** Mark regions: header (banner), navigation, main, complementary (aside), footer (contentinfo), and search or form regions where helpful. Screen reader users jump between landmarks.

**3. Focus order.** Number every interactive element in the order the Tab key should reach it. Normally this follows visual reading order (left to right, top to bottom in English). Note anything unusual, such as a skip link first.

**4. Accessible names.** Every control needs a name a screen reader can announce. Visible labels are best. For icon-only buttons, write the name ("Close dialog", "Search"). For links, make sure the text makes sense out of context ("View invoice 1042", not "Click here").

**5. Images.** Mark each image as meaningful (write the alt text) or decorative (empty alt, ignored).

**6. States and announcements.** Specify expanded/collapsed, selected, checked, current page and error states, and what is announced when something changes without a page load ("3 results found", "Saved").

**7. Focus management.** Where focus goes when a modal opens (into the dialog, usually its heading or first control), where it returns when it closes (the button that opened it), and where it moves after an error on submit (the first invalid field or an error summary).

**8. Interaction and other details.** Keyboard behaviour for custom widgets (arrow keys in tabs), touch target sizes, reduced-motion alternatives, and text that must not be in images.

## How to annotate

Use a consistent visual language: coloured markers off to the side of the design with a numbered legend. Free annotation kits are available in the Figma Community; some, such as kits published by large companies' accessibility teams, include ready-made stamps for headings, focus order and names. Paper works too: print the screen and mark it up.

## Worked example: a search results page

```text
Landmarks:  banner (logo + nav) | search (form) | main (results) | contentinfo (footer)
Headings:   H1 "Search results for 'desk'"   H2 per result title   H2 "Filters" (visually small)
Focus order:
  1 Skip to results (visible on focus)
  2 Logo link "Home"
  3-5 Nav links
  6 Search field (label "Search products")
  7 Search button (icon-only; name "Search")
  8 Filters toggle (button; aria-expanded true/false)
  9+ Result title links, in visual order; then Pagination
Names:      Heart icon on each result: "Save Oak desk to favourites" (includes product name)
Images:     Product photos: alt = product name; decorative divider: empty alt
Announce:   After filters change: "24 results" in a polite live region
Errors:     Empty search -> message under field, linked to it; focus stays in field
```

Two details are worth noticing. The heading "Filters" is visually small, but structurally it is an H2, so it is marked H2. And the heart icon's name includes the product name; ten identical "Save" buttons would be useless to a screen reader user listing all buttons.

## Working with developers

- Hand off annotations with the visual design, not after it.
- Agree on terms: use HTML and ARIA words developers know (button, link, `aria-expanded`), but prefer native HTML over ARIA when it does the job.
- Test the build with a keyboard (Tab, Shift+Tab, Enter, Space, Esc) and a free screen reader (NVDA on Windows, VoiceOver on Mac and iOS, TalkBack on Android) and compare with your annotations.

## Common mistakes

- **Heading levels by visual size.** Structure, not style, decides the level.
- **Focus order that ignores layout changes** at mobile widths, where columns stack.
- **"Button" as a name.** Every icon-only control needs a specific name.
- **Colour-only errors.** Add text and an icon, and link the message to its field.
- **No focus plan for modals and menus.** Focus gets lost behind the overlay.
- **Annotating after build.** By then, fixing structure is expensive.

## Quick recap

- Accessibility annotations describe structure and sequence: headings, landmarks, focus order, names, images, states and focus management.
- Mark heading levels by structure, give every control a specific accessible name, and plan focus for modals and errors.
- Use a consistent legend, hand off with the design, and verify with a keyboard and a screen reader.

## Try it

On the Do tab you will annotate a screen for focus order, headings, landmarks and accessible names.


Annotate headings, landmarks, focus order, accessible names and states so accessibility is designed, not left to chance.

Accessibility specs

Essential Accessibility Annotations for a Smoother Design to Development Handoff - axe-con 2023

WCAG 2.4.3 Focus Order

Annotate screens for engineering, read and adjust real HTML and CSS, and write accessibility specs for focus order and labels.