Setting Up Shadcn/ui A Step-by-Step Guide To Building A Reusable UI Component Library

In this comprehensive guide, we will walk you through the process of setting up a shared UI component library using shadcn/ui with Viable brand colors. This step-by-step tutorial is designed to help developers create a reusable and consistent UI component library, ensuring a cohesive look and feel across your applications. By the end of this guide, you will have a fully functional component library that adheres to WCAG guidelines, supports dark mode, and is built with full TypeScript support.

📁 Target Directory: /packages/ui/

We will be working within the /packages/ui/ directory to create our shared UI component library. This directory structure helps maintain a clean separation of concerns, making it easier to manage and scale your project. Keeping the UI components in a dedicated directory ensures that they can be easily shared and reused across different parts of your application or even in multiple projects.

When setting up a shared UI component library, it's crucial to choose the right directory structure. By isolating the UI components in /packages/ui/, you create a modular and maintainable codebase. This separation allows for better collaboration among developers, as changes to the UI components won't directly impact other parts of the application. Furthermore, a dedicated directory facilitates easier testing and documentation of the UI components, contributing to the overall quality and usability of your library.

The target directory /packages/ui/ serves as the central hub for all your UI components. This structured approach makes it simpler to manage dependencies, apply version control, and automate the build process. Adopting a well-organized directory structure is a best practice in modern web development, promoting code reusability and reducing the risk of conflicts. Therefore, adhering to this convention is a key step in building a robust and scalable UI component library.

🎯 Task Objective: Create a Shared UI Component Library

The main objective of this guide is to create a shared UI component library using shadcn/ui with Viable brand colors. This library will serve as a central repository for all UI components, ensuring consistency and reusability across your applications. By leveraging shadcn/ui, we can take advantage of pre-built, accessible components that can be easily customized to match our brand’s aesthetic. This approach not only speeds up the development process but also guarantees a high level of quality and adherence to accessibility standards.

Creating a shared UI component library is a crucial step in building scalable and maintainable applications. It promotes a design system approach, where UI elements are treated as reusable building blocks. This methodology ensures a consistent user experience across different parts of your application and reduces redundancy in code. By centralizing UI components, you can easily update and maintain them, ensuring that changes are reflected uniformly throughout your project.

Our goal is to create a library that not only meets the functional requirements but also aligns with the Viable brand’s visual identity. This involves configuring brand colors, typography, and other stylistic elements to create a cohesive and professional look. The library will include a set of base components such as Buttons, Cards, Inputs, Selects, and Dialogs, which are commonly used across most applications. Each component will be designed to be flexible and customizable, allowing developers to adapt them to specific use cases while maintaining the overall design consistency. Ultimately, this shared UI component library will streamline the development process, improve the user experience, and enhance the maintainability of your applications.

📋 Acceptance Criteria

To ensure the successful creation of our UI component library, we have established a clear set of acceptance criteria. These criteria outline the key features and functionalities that the library must possess to be considered complete and production-ready. Each criterion addresses a specific aspect of the library, from initial setup to component creation and configuration.

• Initialize shadcn/ui with Next.js compatibility: The first step is to properly initialize shadcn/ui within our Next.js project. This involves installing the necessary dependencies and configuring shadcn/ui to work seamlessly with Next.js’s routing and rendering mechanisms. Next.js compatibility ensures that our components can take full advantage of server-side rendering and other performance optimizations.

• Configure brand colors (primary: #33B6CC, accent: #F4B6C2, neutral: #4D4D4D): A crucial aspect of our UI library is its visual identity. We need to configure the brand colors to match Viable’s design guidelines. The primary color is set to #33B6CC, the accent color to #F4B6C2, and the neutral color to #4D4D4D. These colors will be used consistently across all components to create a unified look and feel.

• Create base components: Button, Card, Input, Select, Dialog: Our library should include a set of essential base components that are commonly used in web applications. These components include Buttons, Cards, Inputs, Selects, and Dialogs. Each component should be designed to be flexible, accessible, and customizable, allowing developers to adapt them to various use cases.

• Setup Tailwind CSS with custom theme: We will be using Tailwind CSS for styling our components. It’s important to set up Tailwind CSS with a custom theme that incorporates our brand colors and other design tokens. This ensures that our components are styled consistently and are easy to customize.

• Add framer-motion animations: To enhance the user experience, we will add framer-motion animations to our components. Framer-motion is a powerful library for creating smooth and engaging animations in React applications. By incorporating framer-motion, we can add subtle animations and transitions to our components, making them more interactive and visually appealing.

• Export all components with proper TypeScript types: Our library will be built with TypeScript to ensure type safety and improve developer experience. All components should be exported with proper TypeScript types, making it easier for developers to use them in their applications. Type definitions provide valuable information about the component’s props and behavior, reducing the likelihood of errors.

🔧 Technical Requirements

To ensure our UI component library meets the highest standards of quality and usability, we have outlined a set of technical requirements. These requirements specify the technologies and versions we will be using, as well as key features that the library must support. Adhering to these technical requirements will help us create a robust, maintainable, and accessible UI component library.

• shadcn/ui latest version: We will be using the latest version of shadcn/ui to take advantage of the newest features, bug fixes, and performance improvements. Staying up-to-date with the latest version ensures that our library benefits from the ongoing development and enhancements of shadcn/ui.

• Tailwind CSS v3: Our styling will be based on Tailwind CSS v3, which provides a utility-first approach to CSS. Tailwind CSS allows us to rapidly style our components using a set of pre-defined classes, ensuring consistency and reducing the need for custom CSS. Version 3 of Tailwind CSS includes significant performance improvements and new features, making it an ideal choice for our project.

• Support for dark mode: A crucial requirement for modern web applications is support for dark mode. Our UI component library must be designed to seamlessly adapt to both light and dark color schemes. This involves using CSS variables and conditional styling to ensure that our components look great in any environment. Dark mode support enhances the user experience and is an essential feature for accessibility.

• Full TypeScript support: We will be building our library with TypeScript to provide type safety and improve developer experience. TypeScript helps catch errors early in the development process and makes our code more maintainable. Full TypeScript support means that all components and utilities in our library will be written with TypeScript, and proper type definitions will be provided for all exported modules.

💻 Claude Instructions

To guide the development process, we have provided a set of instructions specifically tailored for Claude, our AI assistant. These instructions outline the specific tasks and constraints that Claude should adhere to while creating the UI component library. By providing clear and concise instructions, we can ensure that Claude’s contributions align with our project goals and technical requirements.

• Work ONLY within /packages/ui/: Claude is instructed to work exclusively within the /packages/ui/ directory. This constraint ensures that all generated code and files are placed in the correct location, maintaining the project’s directory structure and modularity. Working within the designated directory helps keep the codebase organized and prevents accidental modifications to other parts of the application.

• Create a proper package.json with name ‘@viable/ui’: Claude is responsible for creating a package.json file for our UI component library. This file will include essential metadata such as the library’s name (@viable/ui), version, dependencies, and scripts. A properly configured package.json is crucial for managing the library’s dependencies and publishing it to a package registry like npm.

• Ensure all components are accessible and follow WCAG guidelines: Accessibility is a top priority for our UI component library. Claude is instructed to ensure that all components are designed and implemented to be accessible to users with disabilities. This involves following the Web Content Accessibility Guidelines (WCAG), which provide a set of best practices for creating accessible web content. Accessible components include proper semantic HTML, ARIA attributes, and keyboard navigation support.

In summary, setting up a UI component library with shadcn/ui requires careful planning and execution. By following this step-by-step guide, you can create a reusable, consistent, and accessible component library that enhances your development workflow and improves the user experience. From initializing the project and configuring brand colors to creating base components and ensuring accessibility, each step is crucial in building a robust and maintainable library. With the help of tools like shadcn/ui and Tailwind CSS, and adhering to best practices like WCAG guidelines and TypeScript support, you can create a UI component library that meets the highest standards of quality and usability. Remember, the key to a successful component library is not just functionality, but also consistency, accessibility, and maintainability. By focusing on these aspects, you can create a valuable asset that streamlines your development process and enhances the overall user experience of your applications.