Documentation template
Nine required sections enforced by the docs build. A component page missing accessibility or content rules fails the build rather than shipping incomplete.
- doc/section
- doc/example
- doc/prop-table
Design SystemsSignal
Component documentation developers actually read
A well-built component library with adoption problems that turned out to be documentation problems.
- Design system
- Documentation
- Accessibility
- Client
- Signal
- Discipline
- Design Systems
- Engagement
- Design system and audit
- Platforms
- Web
- Duration
- 10 weeks
- Delivered
- 2025
01The problem
What we walked into
Signal makes developer tooling, and had already built a solid component library. Adoption inside their own product teams had stalled at around forty percent, and the assumption was that the components were missing features.
The audit found the opposite. The components were good. The documentation was an auto-generated props table per component, with no guidance on when to use one, what states it supported, or how to make it accessible. Developers could not tell whether a component solved their problem, so they built a local one, which was faster than finding out.
There was also no answer to the most common question, which was what to do when no component fits. So people forked.
02Goals
What the work had to achieve
Agreed in the first fortnight, written down, and used to settle every argument afterwards.
- G01
Answer when, not just how
Every component page should open with what it is for and what to use instead when it is not the right fit.
- G02
Make the accessible path the default path
The correct usage should be the copy-paste example, so doing it right requires no extra reading.
- G03
Give forking a legitimate route
A documented process for proposing a component beats an undocumented culture of building one quietly.
- G04
Keep docs current by construction
Documentation that drifts is worse than none. Examples must run against the real library rather than being pasted screenshots.
03UI approach
The decisions that shaped the interface
Four moves that did most of the work. Everything else on the project followed from them.
- 01
A fixed page structure
Every component page follows the same nine sections in the same order: purpose, when not to use, anatomy, live example, variants, states, accessibility, content rules, related components. Predictability is what makes reference docs skimmable.
- 02
Live examples over screenshots
Each example renders the real component with editable props, so the documentation cannot drift from the library and the example is always copy-pasteable.
- 03
Accessibility written per component
Roles, labels, focus order, keyboard behaviour and screen reader expectations documented specifically, not as a general page nobody opens.
- 04
A visible request path
A request queue with public status, so proposing a component is a recognised action with a visible outcome rather than a message into a channel.
04Components and design system
What got built underneath
The reusable parts, and the tokens they were built from. This is the layer that keeps the interface consistent after we leave.
Live example frame
An editable playground rendering the real component, with prop controls generated from the type definitions and a copy button for the resulting code.
- example/canvas
- example/controls
- example/copy
Accessibility annotation set
A visual language for marking focus order, landmarks and labels on anatomy diagrams, used consistently across all 44 component pages.
- annotate/focus
- annotate/label
- annotate/landmark
05Outcomes
What changed after release
Measured by the client, on their own reporting, over the period noted against each figure.
- Internal component adoption
- 40% → 87%Internal component adoptionMeasured across product teams six months after the docs relaunch.
- Component pages rebuilt
- 44Component pages rebuiltAll following the same nine-section structure.
- Locally forked components
- −64%Locally forked componentsCounted across the four main product repositories.
- Required sections per page
- 9Required sections per pageEnforced by the documentation build.
Not one component was changed during the engagement. The library had been fine the whole time.
We were about to spend a quarter rebuilding components that did not need rebuilding.
06Gallery
Screens and system, laid out
Layout diagrams of the interface as delivered, with a note on what each one is doing.
- 01 / 04
Component page
The nine-section structure, opening with purpose and when not to use this.
Interface layout diagram from the Signal project.
- 02 / 04
Live example frame
The real component rendered with editable props and a copy button for the resulting code.
Interface layout diagram from the Signal project.
- 03 / 04
Accessibility annotations
Focus order, landmarks and labels marked consistently across all 44 pages.
Interface layout diagram from the Signal project.
- 04 / 04
Request queue
Component proposals with public status, giving forking a legitimate alternative.
Interface layout diagram from the Signal project.
07Take it with you
The one-page version
Everything above, condensed to plain text. Copy it into a brief, or download it to circulate internally.
Case study summary
Plain text, ready to paste into a brief or a board pack. Saves as baseline-studio-signal-component-library-summary.txt.
BASELINE STUDIO / CASE STUDY SUMMARY
================================================================
Client: Signal
Project: Component documentation developers actually read
Discipline: Design Systems
Engagement: Design system and audit
Platforms: Web
Duration: 10 weeks
Year: 2025
OVERVIEW
================================================================
Signal had a well-built component library stuck at forty percent internal adoption. An audit found the components were sound and the documentation was an auto-generated props table, so developers could not tell whether a component solved their problem and built local ones instead.
We defined a nine-section documentation template enforced by the docs build, replaced screenshots with live examples rendering the real component with editable props, wrote accessibility specifications per component rather than as a general page, and created a public component request queue to give forking a legitimate alternative.
Delivered across 10 weeks: an adoption audit across four product repositories, 44 rebuilt component pages, a live example frame with generated prop controls, an accessibility annotation language, and a documented request and promotion process.
Results: internal adoption up from 40 to 87 percent, locally forked components down 64 percent, 44 pages rebuilt to one structure, and nine required sections enforced at build time. No component code was changed during the engagement.
OUTCOMES
================================================================
40% → 87% Internal component adoption
Measured across product teams six months after the docs relaunch.
44 Component pages rebuilt
All following the same nine-section structure.
−64% Locally forked components
Counted across the four main product repositories.
9 Required sections per page
Enforced by the documentation build.
CONTACT
================================================================
Baseline Studio
studio@baseline.design
+1 (415) 555 0142
Figures describe a specific product, team and period, and are
published to explain the work rather than to predict a result.05Start a project
Working on something similar?
Tell us where your product is getting stuck. We will tell you honestly whether this is the kind of problem we are good at, and what we think it would take.
- Prefer email
- studio@baseline.design
- Current availability
- Taking on two engagements for the coming quarter.
- Typical reply time
- Two working days, from a partner rather than a form.
