Component documentation in Figma

Context

As we work towards design and code parity and evolve our contribution guidelines, we must define where each type of design system asset should reside. In this case, this entails documenting components and describing how they are represented in the Figma Component Library.

Problem

Currently, some of the design system component documentation available in the Figma Component Library, rather than Supernova (octopus.design). Documented items include component definitions, usage, design token mappings, variants, and interaction details:

Often, this information is only available in Figma, lowering its discoverability. The lack of clarity on whether documentation is expected to reside in Figma or not creates unnecessary overhead for designers proposing contributions to the design system, as most of this information would be easily portrayed using tools in Supernova.

Lastly, duplicating information across multiple platforms leads to unnecessary maintenance overhead and potential miscommunications when items aren’t updated consistently across the board when changes are introduced. While Component headers and Component markup helpers can be useful in portraying component names, design tokens or variants, they rapidly go out of date when changes are introduced.

Proposed solution

The following solutions will be documented in Contributing to Figma guidelines once implemented in our Component Library.

Single location for component documentation

We propose that all component documentation should be maintained in Supernova (octopus.design). This approach reduces the overhead of a design system contribution, ensuring Figma remains the primary source of design assets, rather than documentation. Supernova provides us with tools for visualizing variants and properties, eliminating the need to create bespoke matrices in Figma to achieve the same goal.

Below we outline the information that a designer should provide about a component in Figma and Supernova.

Figma

1. Component header.
2. Component preview (source).
3. Sub-components (source, if applicable).
4. Component name.
5. Component description.
6. Link to documentation (Supernova).

Supernova

1. Component Anatomy (portrayed via Supernova Assets image and additional content).
2. Component usage descriptions, interaction details or anything else that requires textual description (no matter how long).
3. Component Variants (using Figma Component block).
4. Component Properties (using Figma Component Properties block).

Portraying properties such as design token usage is not necessary, as it can be easily inspected through Figma’s design panel and Dev Mode.

---

Revised component presentation in Figma

We propose that only minimal necessary component information should be represented in Figma. That way, we avoid information duplication, reduce the workload for contributions and establish one source for documenting components. The information included in Figma is:

• Component name (presented once)
• Component grouping
• Component status in its lifecycle

All reflected via the use of a Component header, without additional annotations.

Before

After

---

Considerations for design to development handover

In some cases, as component is being is about to be built, it’s necessary for a designer to communicate certain states or interaction details to a developer to ensure high-quality delivery. Because we are minimizing the amount of documentation present in Figma resources (which previously had a map of all state combinations and some interaction details) this information will have to be relayed during design to development handover outside of the Figma Component Library context.

As a designer, we have to relay all critical information to the developer before build commences. We recommend doing so by with the combination of following:

• Handover session,
• Document outlining states and interaction (that isn’t communicated by created component),
• Using Supernova Assets → Components → Usage Guidelines → Do and Don’t imagery to convey use cases.