Evolving Design System Components

Evolving Design System Components

This skill grounds Component Library work in two Bitwarden governance pages: Creating new design patterns and Modifying an existing Design System component. Read the canonical pages via get_confluence_page before driving a real proposal — they evolve faster than this skill, and they link to template Figma files and engineering processes referenced below. Figma conventions (property ordering, naming) live in references/figma-conventions.md.

The two paths

There are two governance flows. They share a beginning but diverge.

• Creating a new pattern. A pattern that doesn't yet exist. Path forks at "is this a

Core Component, or a Recipe/Snowflake?" based on use cases and complexity.

• Modifying an existing component. A pattern that already exists. Always passes through

the UI Foundation team because instances across the product are affected.

The skill walks both. Confirm which one applies before recommending steps — they have different review gates.

Step 1: Search first, then propose

Before either path, check whether the pattern already exists. The most common false-positive of "we need a new component" is "this already exists in the library and the designer hadn't found it."

Use search_design_system and get_libraries from using-figma. If a near match is found, the question becomes whether to use it as-is, modify it (path B), or propose a new variant under it. If no match, proceed.

Step 2: Identify the need with the team

For both paths, the design team aligns first — before engineering is involved. From the Confluence pages:

• The designer identifies the need and creates a draft of the new or modified pattern in a

feature file.

• The designer shares with the design team — group iteration or independent draft followed

by team critique, depending on timeline.

• The design team reviews against three or four questions, depending on the path:

For a new pattern:

• What existing patterns have been considered? Why don't they work?
• What value does the new pattern bring?
• Does it follow existing design / brand guidelines?
• What are other use cases? Can it be used in multiple places?

For a modification:

• Does it improve visual appeal?
• Does it expand the use cases for the component?
• Is it in line with other UI patterns?
• How will it affect instances of the component across the product?
• What other components or patterns might be affected?

The team aligns on whether to move forward before the proposal goes further. There is a Figma template for new pattern discussion linked from the Creating-new-design-patterns page; surface it when the proposer doesn't have a discussion structure of their own.

Step 3 (new patterns only): Core vs. Recipe/Snowflake

This decision is made with the UI Foundation team — never unilaterally by the proposing designer.

• Core Component Library candidate. Many use cases, or too complex for a single feature

team to maintain. Becomes a first-class library component owned by UI Foundation.

• Recipe / Snowflake. Few use cases, or specific to a feature surface. Owned by the

feature team that built it. Still added to the Figma library so other designers can find it.

Schedule the conversation with UI Foundation. Walk the use cases. Defer to their call on ownership. The Confluence page references the engineering side at Creating a New Component — read that page when the Core path is taken.

Step 4: Build it in the Figma library

The Figma side of the process is opinionated. The conventions — property ordering, naming, required states, documentation pattern — are in references/figma-conventions.md. The high-level moves:

• Open the Tailwind Component Library Figma file.
• Create a new branch named after the component / pattern.
• Add the new (or modified) UI pattern as a Figma Component, on a dedicated page for new

components or in the existing component's page for modifications.

• For interactive components, ensure at minimum: default, hover, focus, active (where

applicable), disabled (where applicable).

• Name Figma properties per the CL API design docs

and existing Figma property patterns. Property order matters — see references/figma-conventions.md.

• Create a component-documentation frame next to the component with usage, behavior, variants,

and accessibility notes. Convention is to copy and adapt an existing component's docs rather than build from scratch.

• For modifications, leave a Figma comment on each changed component noting what changed.

Step 5: Review gates

• New patterns. Send the branch to the Design team for review.
• Modifications. Send the branch to the Design team AND review during a team sync.

At least 2 other designers must approve before merging.

• Review changes with the UI Foundation engineering team during a team sync.
• Create a Jira issue on the Component Library board if not already created. Prioritize with

UI Foundation engineering in the next sync.

Step 6: Merge timing — Figma vs. code

The default is wait to merge the Figma branch until engineering has updated the code so designers don't see UI in Figma that doesn't yet exist in product. But there are exceptions:

• Designers need the changes now. Add a warning badge to the component's docs in Figma

noting the engineering state, merge the Figma branch, and send an update to engineering teams in #team-eng-ui-foundation.

• Branch maintenance is too unwieldy. Same exception applies — merge with a warning and

announce.

Default to the disciplined order. Use the exception sparingly.

Composing with other skills

• `using-figma`. search_design_system and get_libraries for the pre-proposal search;

get_metadata and get_variable_defs for inspecting existing components; the Code Connect tools (get_code_connect_map, add_code_connect_map, get_context_for_code_connect) for the design-to-code linkage when promoting a pattern to a Core Component.

• `facilitating-design-critique`. The design team's alignment step in Step 2 is a critique

session, not a one-off message. When the proposer needs help structuring it, dispatch into the critique-facilitation skill.

• `navigating-design-jira-process`. The Component Library Jira board lives inside the

larger Product and Design Jira workflow. When the proposal generates engineering work, dispatch into the Jira-process skill for the right state moves.

Common traps

• Skipping the pre-proposal search. search_design_system first. Always.
• Designer-unilateral Core/Recipe call. The UI Foundation conversation is required for

this decision. Don't pre-decide.

• Property names that don't match the CL API conventions. Inconsistent naming breaks the

library's usability across the team. Read the CL API design doc rather than improvising.

• Skipping the warning badge on early merges. When the exception path is taken, the

warning badge in Figma plus the #team-eng-ui-foundation message is required, not optional.

• Merging Figma changes ahead of engineering with no comms. Designers downstream see UI

that doesn't exist in product and build on top of it.

Output format

When asked to help propose a pattern or modify a component:

1. Path — new pattern or modification. 2. Search results — what already exists in the library that's adjacent or overlapping. 3. Design team alignment plan — what to bring to critique, what questions the team should weigh. 4. Core vs. Recipe call (new patterns only) — the UI Foundation conversation framing. 5. Figma plan — branch name, page placement, required states, property order, docs frame. 6. Review path — designer approvals required, UI Foundation review, Component Library Jira issue. 7. Merge timing — default or exception, with the warning-badge and comms steps if exception.

Figma Conventions for Component Library Work

These conventions govern Figma-side work in the Bitwarden Tailwind Component Library. They are the design-team-facing surface of the CL API design docs at bitwarden.atlassian.net/wiki/spaces/EN/pages/619511828/Establish+common+language — when in doubt, that engineering-side page wins.

Branch naming

Name the branch after the component or pattern being added or modified. Match the kebab-case used in the engineering-side Tailwind component name if it exists (e.g., segmented-control, badge, bit-toast).

Page placement

New core components. Create a new page named after the component. Pages in the "Pages" section are kept alphabetical — drop the new page in at the right slot.

Modifications. Use the existing component's page; do not create a new page for a modification.

Recipes / Snowflakes. Add to the "Templates" page at the bottom of the Pages section, not to its own page.

Required interactive states

For interactive components, include at minimum:

• default
• hover
• focus
• active (when applicable)
• disabled (when applicable)

Missing states create handoff ambiguity. Default to including more rather than fewer.

Property order — the load-bearing convention

Figma property order is not arbitrary. Designers using the library scan properties from the top of the panel; consistent order across components makes the library usable. From the Creating-new-design-patterns Confluence page:

1. Variant 2. Size 3. Icon / Element 4. Misc / Block / Position / Quantity 5. Expanded 6. Selected / Active 7. State

The two anchors that matter most: Variant first, State last. If a property doesn't obviously fit one of these slots, look at adjacent components for precedent before inventing a new ordinal.

Property naming

Property names come from the CL API design docs. When the engineering-side name already exists, match it exactly. When introducing a new name, walk it through the docs first — coined-on-the-spot names diverge from the engineering API and create translation pain at code-mapping time.

Component documentation frame

Every component (and every modified component, for documentation updates) gets a documentation frame next to its main component. The pattern:

• Copy an existing component's docs frame as a starting point — preserves the layout, the

variable bindings, and the dark-theme variable swap.

• Replace all content with the new component's content. Sections: usage, behavior, variants,

accessibility.

• Create the docs frame as a component, named .<component-name>-docs (note the leading dot

to keep it sorted at the bottom of the components list).

• Update the docs component's variables to use the dark theme. This is intentional and

matches every other component's docs.

• Place the docs component next to the main component.
• Group the main component and its docs component together. Name the group `<component-name> -

storybook link don't ungroup`. The "don't ungroup" is literal — Storybook uses the group as the link target.

Comments on modifications

For modifications, leave a Figma comment on each changed component noting what changed. Comments survive the branch merge and give downstream designers context for what's new.

Warning badges on early-merge components

When the exception path is taken (Figma merges ahead of engineering), add a warning badge to the component's docs frame indicating engineering state. Remove the badge once engineering has caught up. Pair the badge with a message in #team-eng-ui-foundation.

Recipe / Snowflake annotations

Recipes don't get the full docs frame, but they should still carry:

• Variants defined in the design file (states, sizes, configurations).
• Annotations for component behavior and accessibility (focus order, ARIA roles, keyboard

shortcuts).

• Property naming per the same conventions above, even though the recipe lives on the

Templates page.

Work with the feature team's tech lead on the engineering build plan for a recipe — recipes are owned by the feature team, not by UI Foundation, so the Jira stories live in the feature team's project, not the Component Library project.