Klaviyo Ascent Design System: Phone number input

Phone numbers aren't simple

A phone number input looks small until it has to work across countries, locales, validation states, and the rest of an app.

The component needed to give people a clear country choice, format the mask and placeholder for that country, and stay visually consistent with Klaviyo.

I spoke with stakeholders about the marketing team's earlier solutions and where they needed to go. That research made three priorities clear:

• Represent each country, with a default based on the app's locale
• Format the input mask and placeholder for the selected country
• Match the look and feel of the Klaviyo app

The goal was one component that product and marketing teams could use without solving the same problem twice.

Align the teams first

This started with a prioritized component list and Klaviyo's move into international markets. We already had a Number Input, but its variations were growing without phone number logic.

I mapped the people who needed a say: Product Design directors, Engineering Managers from the app and marketing teams, and Lead Product Designers with related experience. I interviewed them for requirements and user stories, then used Jira to keep progress visible.

While those conversations were getting scheduled, I built a FigJam from the existing Number Input. I marked what carried over and what did not. I also looked at how other design systems and communities handled phone number inputs.

I had built the Roll by ADP phone number React input before, so the tradeoffs looked familiar. Accurate phone number formatting often requires a large dependency. Correctness has a real performance cost.

Make it fit the system

I start fast in Figma. Early exploration does not need every Style and Variant in place. Refinement is where the work has to fit the system.

The Phone Input is a form control, like the Text Input, so I placed it in a Field to test it with other inputs, labels, descriptions, and error messages. I applied the relevant Styles and replaced parts with internal components where they already solved the problem.

The documentation then added:

• Visual examples of what to do and what not to do
• Variants: Relevant states, how they differ from the base, and the data they need
• Anatomy: Redlines and shared names for the parts that make the whole component

Finally, I cleaned up the Figma file. The components lived on the right page, with a documentation page for the relevant states and considerations.

The final handoff brought the component, its states, examples, and guidance into one place. The release process then called for a Figma library changelog update and announcements through email, Slack, direct messages, and team calls.