Contributing

Contributions to the Persona Design System (PDS) are an important way we keep our system evolving and aligned with the needs of our products.

Contributions can take several forms, which can include:

• Optimizing an existing component by making updates in Figma to improve usability or consistency.
• Updating a component in Figma to reflect new enhancements that have already been made in code.
• Proposing updates to component designs to better support a product use case or improve the overall experience.
• Contributing new icon designs or refinements to existing icons in the Icon & Asset Kit.
• Proposing designs for a new PDS component.

Each of these contributions ensures that PDS remains a living, collaborative system rather than a static library.

First, review existing components and patterns to check if one already meets your use case. If so, use the existing solution. If a new contribution is needed, follow the workflow below.

Any proposed UX enhancement or new component/pattern will go through a design review to confirm its necessity and ensure it’s a good fit for the Persona Design System (PDS).

1. Post in the #PDS Slack channel. This helps the design system team and other designers understand the context of your update and weigh in early. Share the issue you’re solving, why a new pattern or component may be needed, and the urgency (blocking, needed soon, or future consideration). Be sure to tag relevant product designers.
2. If needed, bring your proposal to Platform UI Office Hours for group review. Come prepared with:
   • Context and what’s been discussed so far
   • What the proposed pattern or component is
   • Why it’s needed, when it should be used
   • The impact on existing experiences
   • A suggested priority (P0 blocking, P1 needed soon, or P2 no dependencies).

By this stage, your contribution should already be reviewed and approved by the Platform Experience team. If development work is needed — such as creating a new component or updating an existing one in code — the work will be added to the Platform Experience backlog and prioritized accordingly. Flag high-priority needs early so timelines align with your project. Developers outside Platform Experience are also encouraged to contribute, which can help accelerate delivery. Work directly with your developers to confirm priority and their capacity to contribute.

1. Create a Linear issue with links to Figma designs and a clear description of what’s changing and why. Assign a priority.
2. If a non-Platform Experience developer will contribute the work, assign the issue to them. If Platform Experience should own it, leave the issue unassigned.
3. Notify the Platform Experience team in the #PDS Slack channel with a link to the issue, and flag if Platform Experience support is required.

If a contribution doesn’t involve frontend changes, or if its designs have already been reviewed and approved by the Platform Experience team, development can move forward.

1. Open a PDS pull request to introduce the change. Include documentation and usage rules, Storybook updates if relevant, a link to the Linear issue, and request Platform Experience as reviewers.
2. Address feedback and requested changes.
3. Merge once the pull request is approved.
4. Post in the #PDS Slack channel to confirm the change has been merged.