Xata Design System

Xata Design System - Component Library & Theme Architecture

Xata's console and marketing site share one component library and one theme package. When I joined, most shared UI still lived inside the website app and the theme authored its colors in hex. Over the year I consolidated that into a properly versioned design system with documentation and interaction tests, then used it to land a full rebrand as a token and variant swap rather than a rewrite.

Key Contributions:

• Consolidation: Moved shared visual, layout and text effect components out of the website app into @xata.io/components across a three part migration, parking uncertain components in a documented experimental folder rather than shipping them as public API.
• Storybook: Stood up Storybook with Xata theming, dark and light support and accessibility testing, then wrote stories across the full component surface in four batches.
• Test reliability: Hardened flaky interaction tests by querying elements through roles and accessible names instead of text.
• Component modernization: Ran four rounds of upgrades across the core set, bringing each component to current shadcn/ui and React patterns while preserving Xata's own variants.
• Form architecture: Migrated deprecated form primitives to a Controller plus Field pattern across onboarding, settings, backups, API keys and profile forms, standardizing labels, spacing and error presentation.
• Dependency consolidation: Replaced roughly a dozen individual Radix packages with the single unified radix-ui package, removing version skew risk between primitives.
• Token architecture: Rewrote the theme to author color tokens directly in OKLCH instead of converting from hex at build time, removing a step between source and output while producing byte identical CSS.
• Rebrand groundwork: Centralized every hand rolled heading onto shared components and introduced font weight tokens, so licensed display fonts could be enforced from the theme rather than per call site.
• CSS hygiene: Wrote a class checker pass over both apps that removed dead classes, caught two typos where the intended class had silently never applied, and purged a class that has never existed in Tailwind.
• Rebrand migration: Delivered phase one of the rebrand, migrating every core component to the new lyra variant with new typography tokens and updated call sites across both applications.

Technical Impact:

The system turned shared UI from something copied between apps into something versioned, documented and testable. The token work shows the payoff most clearly: because headings, weights and colors had already been routed through the theme, the rebrand landed as a variant and token change across two applications instead of a page by page redesign. Storybook additionally gave the team somewhere to review components in both themes before they reach a product surface.

Project Structure:

• @xata.io/components: shared primitives and composed components, with stories and interaction tests
• @xata.io/theme: OKLCH color tokens, typography and weight tokens, generated stylesheet
• @xata.io/utils: shared formatting and helper functions
• apps/design: documentation app hosting the type scale, tokens and Storybook