# Design Specifications

> Detailed documentation that translates designs into development instructions—the bridge between design and code.

*Tags: ux, artifacts, mid-level*

---



> [!info] Quick Definition
> Detailed documentation that translates designs into development instructions—the bridge between design and code.


## What are Design Specifications?

Design specifications are detailed documents that describe design intent precisely enough that developers can implement it without returning to designers for clarification. Specs cover everything: spacing (the button has 16px padding), colors (the primary blue is #0066FF), interactions (on hover, the button becomes 2% darker), and edge cases (disabled state shows 50% opacity).

Without specs, developers make assumptions. The button padding is 12px or 20px? The developer guesses. The hover color is slightly darker or slightly lighter? The developer guesses. Specifications eliminate guessing.

**One sentence punch:** A good spec is so precise that a designer and a developer never need to discuss the same decision twice.

## Why is it important?

- **Reduces Back-and-Forth:** Developers don't return asking "what color is this?" Specs have answered it. Feedback loops shorten. Development speeds up.
- **Ensures Consistency:** When a component is specified once and developers implement it in multiple places, they implement it identically. Without specs, interpretations vary.
- **Handles Edge Cases:** Designs often show happy paths. Specs must cover sad paths: what happens when text is very long? When the page loads slowly? When the network fails? Specs anticipate these.
- **Preserves Design Intent:** Six months after launch, a developer updates the button. Without specs, they don't know the padding was deliberate. With specs, intent is documented.

## What to Include in Design Specs

1. **Component Name and Purpose** — What is this component? When is it used?
2. **Visual Specifications** — Width, height, padding, margin, border radius. Exact numbers.
3. **Typography** — Font family, size, weight, line height, letter spacing. For multiple sizes (mobile/desktop), specify both.
4. **Color** — Hex codes, RGB values. Not "light blue"; use #0066FF.
5. **States** — Default, hover, active, disabled, loading. Show each state visually or describe precisely.
6. **Interactions** — What happens on click? Is there animation? Duration? Easing curve?
7. **Responsive Behavior** — How does this component adapt on mobile/tablet/desktop?
8. **Constraints and Rationale** — Why 16px padding? Because it matches the grid. Why this font size? Because it passes accessibility contrast ratios. Rationale prevents developers from "optimizing" away your decisions.

## How to Create Design Specs

1. **Export from Figma** — Use Figma's design handoff features or plugins. Inspect mode shows measurements automatically.
2. **Organize by Component** — One section per component. Atomic design hierarchy helps.
3. **Show Visual Examples** — Every spec should include an image or screenshot. Visual + written specs are clearer than written alone.
4. **Document Edge Cases** — "This component works for content up to 50 characters. For longer content, it truncates with ellipsis."
5. **Link to Code** — If code exists, link to the implementation. Specs and code should reference each other.
6. **Version Your Specs** — When specs change, update the version. Developers need to know which version was implemented.
7. **Make Specs Discoverable** — Host specs where developers work (Figma, Notion, GitHub). Don't hide them in a PDF nobody finds.

## Mentor Tips

- **First tip: Don't over-specify.** Specs exist to eliminate ambiguity, not to remove developer judgment. If a developer has a good reason to deviate, let them. But they should have a reason, not a guess.
- **Automate spec generation.** Tools like Zeroheight or Specify pull specs from Figma automatically. Manual spec writing is tedious and error-prone. Automation ensures specs stay in sync with designs.
- **Include rationale, not just measurements.** "This button has 44px height to meet touch target accessibility standards" is better than "44px height." Rationale helps developers understand constraints.
- **Involve developers in spec creation.** If developers contributed to spec format decisions, they're more likely to use specs. "We'll document this way" is more powerful than "You must follow these specs."

## Resources and Tools

- **Books:** "Frontend Architecture for Design Systems" by Micah Godbolt, "Design Systems" by Alla Kholmatova
- **Tools:** [[Figma]] with Inspect mode, Zeroheight, Specify, [[Notion]] for custom spec docs
- **Articles:** Design handoff guides on Nielsen Norman, spec documentation on [[UX Collective]]

---

Source: https://www.fernandoux.com/en/wiki/artifacts/design-specs/