Building a Scalable UI Component Library

Context and Problem Statement

A mid-sized client in the e-commerce space faced challenges with maintaining UI consistency across their applications. Developers often spent excessive time recreating or customizing components, leading to inefficiencies and inconsistencies in the user experience. The client needed a scalable solution to streamline their development process and improve design alignment.

Goals

Standardized UI Components: Component library must be homogenous across applications. Research with end users showed that there is concern over the quality of the product when the UI is inconsistent.
Integration With Ecosystem: Component library must leverage existing React TSX-based codebase.
Friction Free Proofing: Designers must be able to easily review PRs without having to use git or directly with the codebase. Client mentioned bottleneck in design review process.
Developer Productivity: Must reduce development time for UI-integrated features by 50%. Measurement to be quantified by story points.
Accessibility Compliance: All components must meet WCAG 2.1 standards. Client is high-exposure to legal risk and has been sued in the past for non-compliance.
DevEx: Library must be immediately grokkable to new hires and easy to use for existing developers (my own requirement).

Approach

Audit and Technology Selection

Solutions vetted included:

ShadCN: Emphasizes direct code-access to components.
Tailwind CSS: Lingua franca of modern CSS.
Building from Scratch: High flexibility but time-consuming.
Tailwind UI: Prebuilt components using Tailwind CSS.
Chakra UI: Spiritual successor to Bootstrap but better looking.
Ant Design: Extremely popular flexible library.

Using Tailwind CSS to build components from scratch had the highest indication of success due to the client’s repetitive issues with a lack of flexibility in their existing solution. The time-cost associated with this solution made it untenable though.

ShadCN was selected as the best solution for the following reasons:

Components are downloaded directly into the codebase giving the end-user complete control over the internals.
Logical starting points for components. The out-of-the-box styling is minimal and unlikely to look dated a few years down the line.
The client’s existing codebase was already React TSX-based, making integration easier.
ShadCN uses Tailwind CSS so small, one-off modifications of components at time of invocation are simple.

Repository and Package Structure

Opted for a Turborepo-based monorepo structure to manage the component library and applications. This allowed for:

Shared Dependencies: Centralized management of dependencies across projects.
Smart Caching: Faster builds and tests by caching shared dependencies.
Parallel Execution: Tasks are run in parallel making workflows faster.
Ease-of-Use: Gone are the days of forcing Lerna to do what you want it to do. Turborepo requires no boilerplate to get up and running.
Ecosystem Fit: Works out of the box with TS, Jest and Webpack.
Framework Agnostic: Can be used with any front-end framework allowing for future flexibility.
Good Backing: Vercel has a boatload of money and resources so the project is well funded and constantly being optimized
Dev Tooling: Turborepo has it’s own LSP for editor hinting in its configuration JSON file. If you’ve worked much build tooling before, you know how much of a pain writing JSON config files can be without hinting.

Design Review and Proofing Workflow

Integrated Storybook into the local development environment for:

Interactive component documentation.
Real-time design proofing during code review.
Set up disposable environments for each pull request, allowing designers to preview and test components before merge.
Integration with Axe via Storybook’s a11y addon to ensure that all components meet WCAG 2.1 standards and clearly surface violations in Storybook for easy triage in development.

This storybook setup allowed designers to review design changes in PRs by visiting a short-lived (for the duration of the open PR) ephemeral URL. These temporary deployments were created automatically on PR open and linked automatically in the PR via GitHub Actions and then disposed of 48 hours after PR merge.

Results and Impact

Efficiency: Increased engineering velocity for UI-related features by 56% (quantified by story points and compared to the time period pre-intervention).
Collaboration: Enhanced designer-developer alignment with the Storybook proofing system.
Brand: Strengthened brand identity with consistent design elements and homogeneity of design across applications giving the end-user the feeling of a high-end, well designed product.
Accessibility: All components meet WCAG 2.1 standards with a perfect Google Lighthouse score when used on-page - a massive improvement over the client’s previous scores as low as the 60s.

Challenges and Lessons Learned

Challenge: Create a plan for implementing an intervention balanced between timeline, devex, design alignment, accessibility, and future-proofing.
Solution: Conduct thorough audit of existing systems. Extensively interview engineers and designers to uncover time bottlenecks and pain points. Interview high-level stakeholders to understand the business goals and constraints. Use this information to create a plan that is straightforward to execute. Provide as-needed consulting during rollout to ensure plan is implemented successfully.
Lesson Learned: Spending generous time upfront to understand the client’s needs and constraints from the level of junior ICs to the C-suite is crucial to creating a successful intervention. This ensures that the solution is not only correct for the current time but also builds a foundation of long-term technical excellence. This foundation is critical for recruiting the best talent and retaining them. In short, solve the business needs in a way that is sustainable and scalable.

If you are facing similar challenges in the UX and web application space, I would love to strategize how to build you something enduring and impactful.

Get In Touch