Klaviyo: Ascent Design System documentation site

Start with the mess

Ascent already had the parts of a design system: Figma UI kits, a React component library, design tokens built with Style Dictionary, voice and tone guidance, and documentation across Confluence and Google Docs.

The problem was not a lack of material. It was finding the right material and knowing whether it was current. A design system is incomplete when people cannot answer what exists, why to use it, and how to use it.

Write down who needs it

The site had to serve product owners, designers, content designers, data scientists, engineers, and leadership. A public site could also show prospective teammates how Klaviyo approached design and development.

The primary user stories were direct:

• As a Product Designer, I want to find the components available for the problem I am solving.
• As a Software Engineer, I want to find the API for the component I am implementing.
• As a contributor, I want to preview and update documentation without fighting the publishing system.
• As the site owner, I want access controls that define who can view, create, edit, and publish content.

Make the first release small enough

The proposal called for a static site connected to a headless CMS. Publishing in the CMS would trigger a new build. The first release would bring the existing component guidance into one structure, add search and feedback, and link people to Figma, GitHub, and Storybook when they had access.

In scope

• A public, searchable documentation site
• Controlled editing and publishing through a headless CMS
• Component guidance moved from Confluence and Google Docs
• Links to the tools where design and code work already lived
• Basic SEO, analytics, and a feedback form
• A support path through Slack and Jira

Out of scope

• Public code examples before the component library was ready for public access
• Embedded Figma components while the libraries stayed private
• Moving the site into the app monorepo before the engineering team could support it
• A full comment system or blog at launch
• Waiting for every page. The design system team could launch when 80 percent of the agreed content was ready.

Choose measures before building

The spec proposed a 10 percent increase in documentation satisfaction across the next three quarterly surveys. It also called for tracking search behavior, feedback, component references during product research, and visits to the public site.

Those measures still needed baselines and owners. Writing them down exposed that work before anyone treated a page view as proof of success.

Keep the exit open

This was a reversible decision. If the new site failed, teams could keep using Confluence and Google Docs while we fixed it. If the CMS caused trouble, Astro could serve Markdown files until the content was moved.

The proposed release plan named deliverables instead of one big date:

• One month: A repeatable local build, a repository, and a hosted site frame.
• Three months: A connected CMS, content models for overview and component pages, a closer brand fit, and contributor training.
• Six months: Working content routines, a support path, and a general release when the agreed content threshold was met.

Map the site before the pages

The sitemap made the content model visible. It gave the team something concrete to question before we spent time polishing pages.

Leave open questions open

A useful spec does not pretend every choice is settled. This one kept the hard questions in view:

• Which headless CMS fits the content and access model?
• Should the site use Astro or Starlight, or follow the app team's interest in Next.js?
• Which parts can be public at launch, and which must stay private?
• When can the component library and Figma libraries support live examples?
• Should the site ever move into the app monorepo?
• What behavior data is useful without becoming noise?

That is why the spec mattered. It showed what the team could agree on, what we were excluding, and which decisions still needed an owner.