Paste

Twilio is a communications platform that provides software and developer tools for companies to build customer engagement applications

Design System Name

• Paste

Design System team size

• 3-5

Design System team make-up

• Designers
• Engineers
• UX writer

Governance model

• Hybrid
• Centralized

Level of documentation

Level of detail 

• Behaviours
• UX rules
• UI rules
• Tone and voice
• Usage guidelines
• Writing guidelines
• Accessibility guidelines
• Content guidelines
• Tech guidelines
• Options
• States
• Related patterns
• API
• Props
• Implementation
• Research

Brand elements

• Logo
• Colors
• Fonts
• Icons
• Spacing
• Layouts & grids
• Radius
• Shadows
• Borders
• Content, data visualization, localization

Components

• Actions (buttons, links, etc)
• Alerts (pop-up, snackbar, toaster, etc)
• Content and lists (cards, accordion, divider, etc)
• Forms (radio, checkbox, dropdown, inputs, etc)
• Navigation (header, footer, tabs, etc)
• Status (progress bar, badges, loader, etc)
• Utilities (to accomplish specific tasks)

Documentation architecture overview

• Multiple levels (through left navigation) with some pages tagged based on product or audience (eng and design). We also have Github Discussions for informal documentation (Q+A).
• Categories for Introduction, Foundations/Brand (color, content, layout, etc), Patterns, Components, Roadmap, and special use cases (theming, customization, etc)

Who document

• Designers
• Engineers
• Brand

Documentation process

We start documentation at the kickoff stage for every component and pattern (based on our roadmap schedule) through a template we created. It’s a required part of every new piece of work, and we scale its comprehensiveness based on the stage of the component. For example, the documentation for “alpha” components are mainly basic engineering implementation guidelines.

We have a template for components and patterns, and start each project based on our roadmap backlog. A single team member or contributor leads each project and its documentation, so they’re responsible for writing it and getting it peer reviewed. Each documentation page is reviewed by the design systems team and our UX writer. A Request for Comment is sent out to engineers and designers throughout the company for their review, too. Design and engineering development happens in parallel with documentation-writing, so that all 3 workstreams influence each other.

Maintenance and contribution

We make updates easy to submit by any role, not just engineers. For example, our content designer (works part-time on our team) creates PRs directly in Github. When people are contributing or creating new patterns/components, we make sure their final step is to publish them either on the Paste website or Twilio’s internal product docs, so that the documentation is accessible to everyone, not just whoever has access to the original Google doc. Documentation and content review is part of each PR review, and when we plan work, we make sure related guidelines or component pages are considered if they’re affected by new work.

In the past, when we had more staff, we ran biweekly design systems committee meetings with design and engineering representatives across Twilio product areas. Committee members gave feedback on documentation, design, and component API, and participated in collaborative design sessions for new components. Now we post Requests for Comment on Github Discussions and Slack for anyone to give feedback. We also work with contributors who are willing to spend 50% of their time on our team to contribute a component or pattern. We have a section on our doc site with “Contributing” guidelines to set expectations.

On the design part

The documentation structure has evolved based on consumer feedback (through our biannual survey), so we’ve been emphasizing showing more examples and do’s/don’ts. This generally helps people make the right decisions with content and spacing among components, and shows existing compositions they can extrapolate from. Since most components have preselected and restricted colors, fonts, and spacing within components, the documentation is mainly focused on helping people choose the right variants and components (e.g., buttons vs. anchors) for their use cases, which is the majority of questions we get (outside of bug reports).

On the tech part

Our documentation provides interactive examples, code snippets, installation guidelines, and a props table. We also link out to Storybook (which has even more examples) and the source code in Github for each component. These code snippets are paired with design guidelines, so that engineers can collaborate more efficiently with the designers on their team.

Overall

Documentation is focused on helping people choose the right variants and components for their use cases, which is the majority of questions we get (outside of bug reports). We want to teach people how software interfaces work functionally so that folks aren’t choosing components by visuals. Choice of component is based on task, the data you want to communicate, and the required operation and state your UI is in, throughout the human computer interaction. We also use Github Discussions for Q&A, so people can reference past answers to common questions about deciding what component to use. During the kickoff and peer review process, we also ask designers and engineers to provide existing use cases of components and patterns in their product area. We make sure that the documentation and design covers these common use cases.