Pine Design System

Design system infrastructure for product teams, platform adoption, and AI-assisted workflows.

Pine is Kajabi's multi-platform design system supporting 40+ engineers across 6 product teams. My work focused on the systems that help teams adopt Pine: web components, design tokens, accessibility standards, migration guidance, documentation, governance, developer workflows, and Pine MCP.

40+
engineers supported
6
product teams
40
components
4-repo
design system architecture

Architecture Model

A four-repo system with a migration bridge.

Pine needed to support current product teams, legacy migration, documentation, tokens, and AI-assisted development without turning every adoption problem into a one-off support thread.

  • ds-tokens
  • pine
  • pine-mcp
  • kajabi-products
  • legacy Sage migration bridge
System decision

The architecture had to support production components, token distribution, AI-readable knowledge, product integration, and legacy migration at the same time.

Cross-team adoption

The work required more than publishing components. It meant helping engineers, designers, and product teams align on APIs, migration paths, accessibility expectations, documentation, and the moments where standards should become workflow checks.

  1. ds-tokens
  2. pine
  3. kajabi-products
  4. pine-mcp
  5. AI assistants

How Pine Works

Key system workflows behind governance, adoption, and scale.

Pine is not one workflow. It is a set of repeatable paths that connect documentation, validation, migration, tokens, product teams, and AI-assisted development.

Pine goes beyond documentation.

Documentation -> Validation -> Enforcement

Documentation alone does not create consistency. Pine reinforces standards through validation, migration tooling, and AI-assisted workflows that help teams make the right decision at the moment work happens.

  1. Documentation
  2. Lint Rules
  3. Migration Tooling
  4. AI Validation
  5. Adoption
Pine MCP changes AI-assisted development.

Detect -> Context -> Generate -> Validate

Rather than treating AI as a separate workflow, Pine MCP exposes design system knowledge directly to AI assistants so generated code aligns with established components, tokens, accessibility standards, and implementation patterns.

  1. User Request
  2. Detect Pine Context
  3. Retrieve Design System Guidance
  4. Generate UI
  5. Validate Against Pine
  6. Fix Issues
  7. Ship
Design decisions travel into production.

Design -> Tokens -> Components -> Product

A shared token architecture creates a direct path from design decisions to production implementation.

  1. Figma
  2. Tokens Studio
  3. Style Dictionary
  4. Pine Components
  5. Product Teams
Migration works as adoption strategy.

Legacy -> Bridge -> Pine

Migration was treated as a product problem, not a rewrite project. Teams could move incrementally without stopping feature development.

  1. Legacy Sage
  2. Compatibility Layer
  3. Migration Guidance
  4. Pine Components
  5. Shared Standards
Teaching and systems use the same adoption model.

Build -> Teach -> Scale

Teaching and design systems share the same goal: helping people understand and apply a model consistently.

  1. Build Systems
  2. Teach Systems
  3. Create Documentation
  4. Enable Adoption
  5. Scale Teams

Architecture

Pine is product infrastructure, not only a component library.

First, Pine had to work across product surfaces, technology stacks, and adoption paths.

Problem
Kajabi product surfaces span multiple stacks and generations of UI. A design system that only works in one framework would not travel far enough.
Decision
Structure Pine around web components, shared docs, tokenized styling, and consumer integrations so teams can adopt the system across product contexts.
Tradeoff
Web components require more care around accessibility, framework wrappers, and documentation than a single-framework component package.
Outcome
Pine can serve as a cross-platform system for product teams instead of a narrow implementation library.
Pine documentation getting started page showing install guidance, first component rendering, and token usage.
Getting Started documentation gives engineers a clear path from install to first component to tokenized styling.

Migration Strategy

Moving teams to Pine was as important as building Pine.

A design system only matters when teams can move real product work into it without stopping delivery.

Problem
Teams were carrying forward Sage-era layout habits, raw HTML, utility classes, and hardcoded styling into new UI.
Decision
Frame migration as a mental model shift: component-first, semantic content, props for spacing, and tokens for color.
Tradeoff
Gradual migration is slower than a rewrite, but it is safer for a large product surface with active teams.
Outcome
Teams get a practical bridge from legacy UI to Pine without blocking product work on a full rewrite.
Pine Sage to Pine migration guide showing a mental model shift and quick mapping table from legacy markup to Pine approaches.
Migration docs map legacy Sage and raw HTML habits to Pine equivalents so teams can modernize incrementally.

Design Tokens

Tokens turn raw color decisions into semantic product language.

Once teams had an adoption path, consistency needed to live in the language of the system.

Problem
Without a shared naming model, tokens become another set of hardcoded values with unclear ownership and inconsistent usage.
Decision
Use a layered naming convention that separates namespace, base, context, and modifier so tokens can scale from core values to component APIs.
Tradeoff
A stricter naming model asks teams to learn the system before moving quickly, but it makes long-term adoption more predictable.
Outcome
Teams get a shared vocabulary for color, state, context, and component styling instead of one-off naming.
Pine token naming convention documentation showing namespace, base, context, and modifier examples.
Naming conventions define how token names move from generic primitives to component-level decisions.

Token Mapping

Mapping references help teams migrate from raw values to semantic tokens.

Token adoption needed a reference that connected old implementation habits to new product meaning.

Problem
Engineers need to know which semantic token replaces a raw color or legacy value when updating existing UI.
Decision
Document token mappings with the use case attached, not just the token name.
Tradeoff
Mapping tables add maintenance overhead, but they reduce guesswork and make token adoption more self-serve.
Outcome
Token migration becomes a clearer implementation path rather than a scavenger hunt through color names.
Pine token mapping reference showing core tokens, semantic tokens, and use cases for text and background colors.
Token mapping references connect core values to semantic usage so teams know which token fits a product decision.

Developer Experience

Component docs make API decisions visible at the point of use.

Adoption also depended on docs that helped engineers make the right implementation decision while building.

Problem
Component adoption slows down when engineers have to infer variants, states, or implementation details from scattered examples.
Decision
Document components with live examples, variants, state guidance, and implementation tabs.
Tradeoff
Better docs require ongoing upkeep, but they reduce repeated design system support requests.
Outcome
Engineers can choose the right component behavior faster and with fewer one-off UI decisions.
Pine button documentation showing primary, secondary, tertiary, and accent button examples with React and web component tabs.
Button examples show variants, disabled states, icon usage, and implementation tabs for React and web components.

Accessibility

Accessibility guidance is part of the component contract.

As Pine became the path for product UI, accessibility had to be part of the component contract instead of a late review step.

Problem
Accessibility breaks when it is treated as a checklist after product UI has already been composed.
Decision
Move accessibility expectations into Pine docs and component guidance so engineers see them while they build.
Tradeoff
Central guidance cannot replace product-level testing, but it creates a stronger baseline for every team.
Outcome
Teams have a shared accessibility standard tied to the design system rather than scattered tribal knowledge.
Pine accessibility guide in light mode showing WCAG Level AA guidance, keyboard navigation principles, and ARIA patterns.
The accessibility guide documents keyboard navigation, ARIA patterns, labels, and component-specific expectations.

Dark Mode + Accessibility

The same accessibility guidance has to hold across themes.

Theme support made the accessibility contract more visible across contrast, focus, and component states.

Problem
Theme support can expose weak contrast, unclear focus, and component assumptions that only worked in light mode.
Decision
Keep accessibility guidance visible in both light and dark contexts so themed UI is part of the design system standard.
Tradeoff
Every theme increases validation cost, but theme-aware guidance prevents teams from treating dark mode as a visual skin.
Outcome
Accessibility standards stay connected to real component rendering across themes.
Pine accessibility guide in dark mode showing the same keyboard navigation and ARIA guidance in a dark theme.
Dark theme documentation makes contrast, focus, and component states easier to validate across modes.

Migration Artifact

FormikPine changed the unit of migration.

Form migration stalled when teams had to rewrite an entire form state contract just to adopt Pine inputs.

Old workflow

Migrate the whole form

Product teams had to replace Sage form components and revisit Formik wiring in one large migration.

System bridge

FormikPine adapter

FormikPine translated existing Formik state into Pine web component events and prop conventions.

New workflow

Migrate one field

Teams could move field by field inside normal product work instead of waiting for a dedicated rewrite.

Why it matters

The migration path became small enough for product teams to adopt without pausing feature delivery.

UX Artifact

Combobox dropdowns stopped getting clipped in modals.

This is the product-facing side of design system work: one component fix removes a recurring interaction bug for every consumer.

User problem

Options were hidden

Scrollable modals clipped combobox dropdowns, so users could type into the field but could not reliably see or select options.

Decision

Portal the dropdown

Render the dropdown at the document body so it escapes modal overflow without requiring product teams to restructure their markup.

Outcome

The bug class disappears

Comboboxes inside current and future modals can show their option lists without one-off modal overrides.

Why it matters

Small component-level craft turned into product-wide interaction consistency.

Outcomes

The work made Pine easier to adopt, govern, and extend.

The strongest design system work often disappears into the product. These artifacts show the infrastructure behind that adoption: docs, token rules, component examples, migration guidance, accessibility standards, and AI workflow support.

  • Established Pine as product infrastructure across product teams.
  • Made component, token, accessibility, migration, and developer workflow decisions easier to find.
  • Created a clearer path from legacy Sage patterns to Pine components and tokens.
  • Extended design system adoption into AI-assisted development workflows through Pine MCP.
View Pine Design SystemView Pine MCPBack to work