Overview
Annotations provide extra information that helps designers, developers, and other stakeholders understand a design and its components.
Thorough annotations give enough detail to explain the design without overwhelming the reader.
Strive for a balance between essential information and potential edge cases.
Document Structures
When you work with the same development team across multiple handovers, use a consistent structure.
Over time, this builds shared understanding between design and development. You can refine this structure as you go to maintain a clear and balanced approach.
Before adding annotations, decide what you need to explain and how to do so clearly and effectively. Ask yourself:
- How many variations are there in my design? (for example, screens or component variants)
- Are there overlaps with other projects that can be referenced, such as component variants or similar flows?
- Does anything change depending on the device or viewport size?
- Are there any edge cases that need to be highlighted?
- Are there styles that differ from our current design system or branding?
- Are we using new components, branding, or content that the development team has not seen before?
Example Documentation Template
The Component library annotation template covers the most common needs. It includes:
- Overview – describe what you are creating, such as the top-level flow or key component variations
- Key variations – highlight changes such as error paths, examples from other projects, or updates to components
- States – explain specific component states and any style differences
- Dimensions and styles – include expected sizes and design tokens for key elements
- Typography and real data – show how real content behaves (for example, text wrapping, API data, or long and short text); include extremes to help developers and testers plan for variations
- Responsive variations – although our work is mobile-first, show how pages or components should appear in other viewports
- Edge cases and highlighted functionality – group and call out any specific areas that need extra attention
Over time, your team will develop its own structure, but you can use existing annotation files as a starting point.
Example of our component annotation files
Creating Annotation Files
Creating annotation files may seem time-consuming, but the effort helps reduce rework during development.
Project files
Annotations in a project file should be placed on their own page. Label the page with a 📐 and, if your team prefers, include the Jira ticket ID. This setup is described in our File Structure and Setup documentation.
Component Annotations
Create component annotations in a project specific to the Compound component library
Each component should have its own annotation file named after the component being designed or updated.
If the component does not exist yet, duplicate the annotation template to create a new file.
If it’s an update, create a new branch — this will be merged when the updated component is released.
Reviewing Annotations
Before sharing your annotations, review them carefully:
- Ask a colleague to peer review this file — can they understand what to build from the information provided?
- Start drafting early — writing things down often reveals missing scenarios
- Remove repetition — explaining the same thing twice can cause confusion
- Leave enough white space around redlines to make dimensions clear
- Use design tokens alongside to avoid confusion about colours or styles