Component documentation

Problem statement

The writing team often published component documentation and guidance weeks after a component was published to the UI kit. The team was working in tools disconnected from the design team. Additionally, there was no standard structure for component documentation on the Dell Design System website, and common elements within components were named inconsistently.

Approach

To work more closely with our designers and to provide a single historical reference for each component, we transitioned all writing into Figma. This reduced siloed workflows, eliminating the need for handoff meetings.

Our first step was to analyze different design systems to see how they structured their information architecture.

We reviewed 11 additional design systems. The table contains a reduced view.

Results

We determined some similarities among design systems:

  1. Usage is a common label for component documentation. Usage and design are used interchangeably.

  2. The kind of information found in Usage documentation includes: rules of use/guidelines, size, alignment, do´s and dont´s, demo, variations, and color.

  3. There is no clear pattern of implementation documentation across design systems regarding information architecture.

  4. The the kind of information published within a technical or code page includes Installation, changelog, properties, implementation, and live demo. Sometimes guidelines and accessibility appear.

  5. Accessibility, when included, references specific guidelines (color, alignment) from WCAG 2.1.

We also determined that there isn’t a standard structure for what information is included or how that information is structured, which led us to sketch a few different options and ask our users.

Once the general architecture was determined, I created a reusable component documentation template in Figma according to our design system’s taxonomy and terminology. I hid additional subsections and variations within the template’s layers panel for increased flexibility. I aligned all headers, body text, and captions to our font ramp to reduce my team’s time spent on set up. The purpose of the template was twofold:

  1. To create a consistent and repeatable structure for component documentation. This allows writers to add visual assets where needed, provide captions when applicable, and ultimately focus on writing rather than formatting in Figma. Embedded definitions with examples consolidated all necessary reference material within the page for easy review.

  2. Transitioning into Figma meant writers were more involved in the design process, allowing for better collaboration, increased publishing efficiency, and a unified delivery of each component once developed.

    • This increased touchpoints between designers and developers. Writers were helping designers name layers according to the system’s taxonomy, and aligning the names of properties and controls between the Figma UI kit and Storybook (developer documentation).

View published components:

Next steps

  • Consolidate technical documentation within the code tab on the website. Currently, all developer documentation resides in multiple, disconnected Storybook sites. There is a separate Storybook for each framework, including Vanilla, React, Angular, and data visualization (Vanilla).

  • Improve iframes’ interaction to behave more like a live demo, where users can toggle between frameworks, change properties, and review behaviors. Allow users to copy code snippets.

  • Enhance visual assets to include animation, especially around usage examples that show transitions, sequencing, or system feedback.