Proposing a Component

When proposing a new component (or significant changes to an existing one), it’s vital to evaluate how it fits into the design system and what user problem it solves. We use contribution size matrix, component types, grouping and discovery sessions to help achieve these goals.

Types of Components

We define the following component types to help us have a shared language and understanding of whether a component belongs in the design system:

Component Grouping

We group components based on their function, which makes it easier for contributors to categorise new proposals and for consumers to find appropriate components for their needs:

Component Naming

People with different roles and team focus use component names to communicate effectively. For that reason, the names must be concise, meaningful, and easy to pronounce. Consistent and descriptive naming is essential for our design system’s clarity, scalability, and maintainability as it creates a shared language for cross-functional collaboration.

General Principles

Make it understandable

Names should be easily understandable to all team members. Aim for what a component does or represents, not how it’s implemented or styled (function over form).

Make it consistent

Always follow the naming convention guidelines. Consistency helps establish a shared language across disciplines and makes design systems predictable and resilient.

Make it generic when reusable, specific when purpose-built

If a component is designed to be used across many contexts, choose a more abstract name. If it’s tightly scoped, be specific. In most design system scenarios, components should be highly reusable.

Avoid conflicts

Ensure no naming conflicts and names aren’t too similar to existing components. A name should always be distinguishable.

Guidelines

• Noun rather than verb: Components are not actions, they are objects. Use nouns instead of verbs.

• Name components based on their function or role: Describe what the component does or what it represents, not how it looks like.

• Meaningful: Not over-specific, not overly abstract.
• Short: Maximum of 2 words (3 is allowed in edge case scenarios).
• Pronounceable: Easy to talk about, spell and type correctly.
• PascalCase: All the words (including the first one) are capitalised, and there are no spaces.

• Avoiding abbreviations and acronyms: Don’t use them unless they are well known to all team members with differing roles.

• Avoiding technology specific terms: Don’t use names that are reserved in code or hint to a technology, tool, or framework use that might change over time (e.g. ReactPopover, React).
• Consistent state naming: State names should match between design and implementation. Rely on user-facing state naming corresponding to HTML attributes.
• Consistent file and folder names: Folder names in code should match the component name, e.g:

                                                        
                                                        
                                                            /Button
                                                          Button.tsx
                                                          Button.spec.tsx
                                                        
                                                            

Naming examples

Naming references

Component Discovery

Component Discovery is a session between team members making a proposed change to the design system (usually led by a designer accompanied by at least one engineer) and design members of the Frontend Foundations Team.

During Component Discovery, a designer presents proposed changes (Medium or Heavy contribution: new component or significant component modification) and provides additional context about the scope of their work (for example, a new feature or a redesign of an existing interface). The Frontend Foundations team is a sounding board for component usage and will provide feedback on whether the proposed change should be proposed as a formal contribution or an existing solution should be used.

The outcome of a Component Discovery session is:

• an understanding of what effort is required to commit to a change
• a decision to submit a formal Component Proposal to the design system
• a decision to conduct more research to re-validate your design solution
• a decision to use an existing component

Why do a component discovery?

• It helps drive quality through thoughtful decision-making
• It keeps code and UI debt at bay
• Keeps our design system up to date
• Helps manage a consistent and good quality UI
• Reduces potential rework in the build phase

Who to invite to component discovery?

Component Discovery is a session between the contributing team and Frontend Foundations. At minimum, a Product Designer and an Engineer from both teams should be present.

When to run component discovery?

The best time to run a Component Discovery session is after you have understood the problem and have some wireframes (or Figma previews) to share. At the very latest, before you entirely commit to the solution you are building and pass your designs to an engineer for implementation:

When wouldn’t you need to run component discovery?

Component Discovery sessions are expected for all Medium and Heavy contributions to the design system. For Fix and Light contributions, the session is not mandatory.

Component structure in Figma

We have guidelines for how we build components in Figma to help us bridge the gap between design and engineering, one of the persisting, long term challenges of our design system. When components are easy to use and customize for people’s needs, we increase productivity and decrease time spent ironing out potential confusion. Lastly, with clear, widespread standards confidence in making contributions to the design system rises.

Follow the Contributing to Figma guidelines when making changes to components in Figma.