Klaviyo: Ascent Design System Documentation Site

Executive Summary

The Ascent Design System project aims to create a comprehensive, public documentation site for Klaviyo's design system, replacing the current Confluence-based solution with a dynamic, static-site-generated platform using a headless CMS. This new system will significantly improve content organization, component visibility, and overall user experience while showcasing Klaviyo's design maturity to potential talent and investors. Key features include enhanced search functionality, live code demonstrations, strict access control, SEO optimization, integrated analytics, and seamless integration with existing tools. The project will be implemented in three phases over six months, culminating in a full-featured release that aims to improve internal user satisfaction, increase design system usage in product design R&D, and enhance engagement with the broader design system community.

The Problem Statement / User Stories

Describe in depth the problem. How was it discovered and proposed solution. User stories are good to have here.

The goal of a public custom design system documentation site is multifaceted, addressing both internal and external needs. Internally, we aim to streamline features, enhancements, and communication between product, design, and development teams. Externally, we want to showcase our mature design discipline, serving as a touchpoint for investors and prospective talent.

A comprehensive design system aids in consistency, collaboration, productivity, scalability, and quality across the entire Klaviyo product space. The current system includes Figma library UI kits, a React component library, design tokens with style-dictionary, voice and tone guidelines, and documentation in Confluence. However, without clear, accessible, and well-organized documentation to answer what, why, and how, a design system is incomplete.

Confluence, our current stopgap solution, is not organizing content effectively, has findability issues, and lacks features crucial for serving our diverse audience of product owners, designers, content designers, data scientists, leadership, and developers. We need a solution that addresses the following key problems:

1. Improved Content Organization and Findability: We require better fuzzy logic search, easier-to-use navigation (main and on-page), and a structure that makes it simple for users to locate the information they need quickly.
2. Enhanced Component Visibility and Access: We need to provide clear visibility of available UI components and their APIs, with live code demonstrations and better code API visibility.
3. Authentication and Access Control: The system must support different levels of authentication for CRUD operations, ensuring that only authorized users can make changes while maintaining appropriate access for various user roles.
4. SEO and Discoverability: To showcase our design maturity and attract talent, we need to ensure our design system documentation is discoverable on the web through proper SEO optimization.
5. Analytics and Feedback Mechanisms: We require integrated analytics and a robust feedback system to continuously improve our documentation based on user behavior and direct input.
6. Integration with Existing Tools: The new system should integrate seamlessly with our existing tools and workflows, including Figma, GitHub, Slack, and Jira, to support efficient collaboration and issue tracking.†
7. Scalability and Continuous Improvement: We need a flexible system that can grow with our needs, supporting the continuous addition and refinement of content and features.
8. Branding and User Experience: The documentation site should reflect Klaviyo's brand and demonstrate our commitment to excellent user experience, serving as a testament to our design and development expertise.

By addressing these issues, we aim to create a documentation site that not only serves our internal teams more effectively but also positions Klaviyo as a leader in design and development practices within the marketing tech sector.

User Stories

• As a Product Designer, I want to see what UI components are available for me to solve my feature or enhancement problem
• As a Software Engineer, I want to see what API's are available for the component I am implementing
• As a Product Designer on the market, I want to see that Klaviyo cares about design
• As a Product Designer, or other authorized user, I want to be able to preview, and update the documentation site with ease
• As the owner of the documentation site, I want strict access on who can and cannot access, or do CRUD actions on the headless CMS
• As a distinguished brand in the marketing tech sector, Klaviyo wants to show design maturity gaining confidence in the product with our continuous efforts to improve UX/UI/CX
• As a talented individual on the market, I want to see that Klaviyo takes design and development seriously when doing my research on whether or not to join the company

Goals and Non-Goals

Bulleted list of explicitly what we are, and aren't doing. Used to avoid scope creep.

Goals

• Create a dynamic SSG site with a headless CMS
  • Static site for the documentation site that builds on publish webhook from headless CMS.
  • Headless CMS with different levels of authentication for CRUD operations
• Include all existing UI kit components, migrating documentation and structure in Google Docs to the documentation site
• Feedback form for users to provide meaningful feedback on any page
• Deep linking to Figma library, GitHub, and Storybook for direct access to components
  • These links will only work for authenticated Figma, Storybook or GitHub users
• Ensure proper basic SEO meta and Schema.org tags for findability on the web ††
  • Set up Google Analytics
  • Set up Google Search Console
• Setting up a Slack and Jira for support, requests, etc.

Non-goals

• Due do the component library living in the monorepo, and not public
  • Our initial ship will not include code examples - to be scoped in a feature post launch
  • Our initial ship will not include links to a public component library
• Due to the Figma libraries not being public
  • Our initial ship will not include Figma embed UI components
• Not integrating into our monorepo due to the lift required by the backend engineering team
• Implementing a full commenting system per page
• Build out every section outlined in the sitemap prior to launch
  • Once we have 80% of the content, as per decided by the design system team, we'll launch and continue to add post launch
• Not doing blog integration

Key Metrics

What does success and failure look like? What can you track to gauge how things went?

• Internal consumers of the documentation site can find what they are looking for with greater ease
  • Quarterly surveys we're already doing gain 10% increase in happiness with the documentation site over the next three quarters
  • An increase in aspects of the design system being referenced when doing team R&D
• We have a live presence on Google that we can advertise when hiring designers, and developers
• Create engagement with the design system communities

Rollback Criteria

Think about when we stop doing this. Is it a trap door decision?

• This is not a trap door decision
  • In other words, we can go back to using Google Docs and Confluence if this should fail
• Technical difficulties with regards to the technology stack should be evaluate for graceful fallbacks
  • For instance if there is an issue with the headless CMS, we use Markdown files in Astro itself which we can later migrate
• If we're running into major set backs and it looks to be by out Beta time the GA release will miss it's target, we'll implement an intermediary solution like Knapsack, to move off Confluence and Google Docs

Timelines

When do you expect to have an alpha, beta, or general release? If it's a larger project, what milestones or checkpoints will we be tracking?

1 Month (Alpha)

• A repeatable local build environment
• Git repository on the enterprise GitHub account
• Live website on host Astro site with minimal theming
• 50% functionality in place

3 Months (Beta)

• Headless CMS in place and content structured for
  • Overview page layouts
  • Component page layouts
• CI/CD in place with the headless CMS
• Theme has incrementally gotten closer to our branding
• Training and onboarding for authenticated users to fill out content in their designated areas
• 75% functionality in place

6 Months (GA Release)

• All teams are ramped on on content production
• We're refining the layout and design, but it's on brand
• Adding nice-to-have features
• Set up a support channel on Slack for bugs/requests
  • Set up a area in Jira for tracking bugs/requests
  • Linking Jira to Slack channel for notifications
• 100% functionality in place

Designs / Mocks

Visuals to help aid in getting the message across. Low fidelity is fine here.

Sitemap

Technical Concerns / Outstanding Questions

Big open questions, or questions that cannot be answered until you start getting into the weeds.

• Headless CMS to use
  The following are recommended due to research and prior experience
• Sanity
• Directus
• Keystatic
• Deployment server (host)
  The following are recommended due to the speed in which we can get CI/CD up and running
  • Netlify
  • Vercel
• † For the initial GA release, we won't everything publicly available. There will be some extra steps for internal team members to access certain aspects. More seamless integration will come after GA release or we simply will not launch on time.
• †† Do we want to set up Hotjar for behavior tracking?
• Leaning towards Astro, or specifically Astro Starlight with a headless CMS for a team to easily update content
• The engineering team, generally, wants to move the app itself to Next.js
  • Do we want to consider that for the documentation site front-end since our company is full of React developers?
• Do we want to eventually pull this into the app monorepo?
  • our component library ever going to be abstracted for public consumption like our peers Shopify with Polaris ?

Future

• We'll want to make this a hybrid SSG/SSR site for dynamic features, like quick feedback thumbs
• We'd like to build out blogging functionality to so we can have a platform to distribute content
• Component library access for live code examples in the site