Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/wodsmith/thewodapp/blob/main/README.md) - [apps/wodsmith/package.json](https://github.com/wodsmith/thewodapp/blob/main/apps/wodsmith/package.json) - [apps/wodsmith/tailwind.config.ts](https://github.com/wodsmith/thewodapp/blob/main/apps/wodsmith/tailwind.config.ts) - [apps/wodsmith/components.json](https://github.com/wodsmith/thewodapp/blob/main/apps/wodsmith/components.json) - [apps/wodsmith/src/app/layout.tsx](https://github.com/wodsmith/thewodapp/blob/main/apps/wodsmith/src/app/layout.tsx) - [apps/wodsmith/src/components/ui/sheet.tsx](https://github.com/wodsmith/thewodapp/blob/main/apps/wodsmith/src/components/ui/sheet.tsx) - [apps/wodsmith/src/components/ai-elements/tool.tsx](https://github.com/wodsmith/thewodapp/blob/main/apps/wodsmith/src/components/ai-elements/tool.tsx) - [AGENTS.md](https://github.com/wodsmith/thewodapp/blob/main/AGENTS.md)

# UI Component System The WODsmith application's UI is built upon a modern, responsive, and maintainable component system. It leverages a combination of utility-first CSS, a set of unstyled, accessible primitives, and a collection of pre-built but customizable components. This architecture, centered around Next.js and React, facilitates the rapid development of a consistent and high-quality user interface that supports features like dark/light mode and mobile-first design. The core of the system is the integration of Tailwind CSS for styling and Shadcn UI for component structure. This approach provides the flexibility of utility classes while offering the convenience of pre-composed React components, which are directly integrated into the project's source code for full ownership and customization. ## Core Technologies and Libraries The UI system is built on a foundation of several key libraries that work together to provide styling, components, and interactivity. *Sources: [README.md:52-54](), [apps/wodsmith/package.json:44-118](), [AGENTS.md:43-47]()* ### Technology Stack The following diagram illustrates the hierarchical relationship of the main UI technologies. ```mermaid graph TD A[Next.js 15 / React 19] --> B{UI Foundation}; B --> C[Tailwind CSS]; B --> D[Shadcn UI]; D --> E[Radix UI Primitives]; D --> F[cva / tailwind-merge]; C --> F; subgraph "Base Components" E end subgraph "Styling & Variants" C F end ``` This diagram shows that the application uses Next.js and React as the core framework. The UI layer is composed of Shadcn UI, which itself is built upon accessible Radix UI primitives. Styling is handled by Tailwind CSS, with `class-variance-authority` (cva) and `tailwind-merge` providing advanced class management for component variants. ### Key Dependencies The following table lists the essential npm packages that constitute the UI component system. | Package | Description | | :--- | :--- | | `react` / `react-dom` | The core UI library for building components. | | `next` | The React framework providing the App Router and Server Components architecture. | | `tailwindcss` | A utility-first CSS framework for styling. | | `@radix-ui/*` | A collection of unstyled, accessible UI primitives (e.g., Dialog, Popover, Select). | | `class-variance-authority` | A library for creating type-safe component variants with Tailwind CSS. | | `clsx` / `tailwind-merge` | Utilities for constructing and merging Tailwind CSS class names. | | `lucide-react` | A library of simply designed icons. | | `next-themes` | Manages theme switching (e.g., dark/light mode) in Next.js applications. | | `shadcn-ui` | A collection of reusable components built with Radix UI and Tailwind CSS. | | `sonner` | A library for displaying toast notifications. | *Sources: [apps/wodsmith/package.json:44-118](), [README.md:52-54]()* ## Styling and Theming The project employs a comprehensive styling and theming strategy that supports both a consistent design language and user-configurable themes like dark and light mode. ### Tailwind CSS Configuration Styling is primarily handled by Tailwind CSS. The configuration in `apps/wodsmith/tailwind.config.ts` extends the default Tailwind theme with custom colors, fonts, and animations, ensuring a unique brand identity. Key aspects of the configuration include: - **Dark Mode**: Enabled via the `class` strategy, which works with `next-themes`. - **Custom Theme**: Defines application-specific colors (e.g., `primary`, `secondary`, `destructive`), border radiuses, and keyframe animations. - **Plugins**: Uses `tailwindcss-animate` to add animation utilities. *Sources: [apps/wodsmith/tailwind.config.ts](), [apps/wodsmith/src/app/layout.tsx:40-43]()* ### Theme Provider Theme management is centralized through the `ThemeProvider` component from `next-themes`. This provider is wrapped around the entire application in the root layout, enabling global theme state management. ```tsx // File: apps/wodsmith/src/app/layout.tsx:50-54 {children} ``` The `ThemeProvider` is configured with: - `attribute="class"`: Toggles themes by adding a `dark` class to the `` element. - `defaultTheme="dark"`: Sets the default theme to dark mode. - `enableSystem`: Allows the theme to sync with the user's operating system preference. *Sources: [apps/wodsmith/src/app/layout.tsx:50-54](), [AGENTS.md:95-96]()* ## Component Architecture The application follows the principles of **Shadcn UI**, where components are not installed from an external library but are instead added directly to the source code. This gives developers full control over the code. *Sources: [apps/wodsmith/components.json](), [apps/wodsmith/src/components/ui/sheet.tsx](), [README.md:162-163]()* ### Shadcn UI Configuration The `components.json` file configures the Shadcn UI CLI, defining how and where components are added to the project. ```json // File: apps/wodsmith/components.json { "$schema": "https://ui.shadcn.com/schema.json", "style": "default", "rsc": true, "tsx": true, "tailwind": { "config": "apps/wodsmith/tailwind.config.ts", "css": "apps/wodsmith/src/app/globals.css", "baseColor": "slate", "cssVariables": true }, "aliases": { "components": "@/components", "utils": "@/lib/utils" } } ``` This configuration specifies the paths for the Tailwind config, the global CSS file, and aliases for components and utility directories. *Sources: [apps/wodsmith/components.json](), [AGENTS.md:100-101]()* ### Base and Composite Components The component architecture can be seen as a two-layer system: 1. **Base Components (`src/components/ui`)**: These are the foundational building blocks provided by Shadcn UI, such as `Button`, `Card`, `Input`, and `Sheet`. They are typically built on top of Radix UI primitives for accessibility and functionality. 2. **Composite Components**: These are application-specific components that assemble one or more base components to create more complex UI elements. An example of a base component is `Sheet`, which uses Radix UI's `Dialog` primitive and `class-variance-authority` (cva) to define variants. ```tsx // File: apps/wodsmith/src/components/ui/sheet.tsx:30-45 const sheetVariants = cva( "fixed z-50 gap-4 bg-background p-6 shadow-lg transition ease-in-out data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:duration-500", { variants: { side: { top: "inset-x-0 top-0 border-b data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top", bottom: "inset-x-0 bottom-0 border-t data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom", left: "inset-y-0 left-0 h-full w-3/4 border-r data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left sm:max-w-sm", right: "inset-y-0 right-0 h-full w-3/4 border-l data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right sm:max-w-sm", }, }, defaultVariants: { side: "right", }, }, ) ``` *Sources: [apps/wodsmith/src/components/ui/sheet.tsx:30-45]()* A composite component, like `Tool` from `ai-elements`, combines multiple base components (`Collapsible`, `Badge`) and icons to build a specific UI feature. ```tsx // File: apps/wodsmith/src/components/ai-elements/tool.tsx:59-74 export const ToolHeader = ({ className, title, type, state, ...props }: ToolHeaderProps) => (

{title ?? type.split("-").slice(1).join("-")} {getStatusBadge(state)}

) ``` *Sources: [apps/wodsmith/src/components/ai-elements/tool.tsx:59-74]()* ## Global UI Providers The root layout (`apps/wodsmith/src/app/layout.tsx`) is responsible for initializing global providers that are essential for the UI system to function correctly across the entire application. The following diagram shows the providers wrapping the main application content. ```mermaid graph TD RootLayout --> ThemeProvider; ThemeProvider --> TooltipProvider; TooltipProvider --> Toaster; Toaster --> AppContent[children]; ``` - **`NextTopLoader`**: Displays a loading bar at the top of the page during navigation. - **`ThemeProvider`**: Manages the application's theme (dark/light mode). - **`TooltipProvider`**: Configures default behavior for all tooltips in the app. - **`Toaster`**: Provides a context for displaying `sonner` toast notifications. *Sources: [apps/wodsmith/src/app/layout.tsx:48-59]()* ## Conclusion The UI component system in WODsmith is a well-structured and modern architecture that prioritizes developer experience, maintainability, and visual consistency. By combining the power of Tailwind CSS for styling, Radix UI for accessibility, and the Shadcn UI methodology for component ownership, the project is equipped with a flexible and scalable foundation for building a rich user interface. The clear separation of concerns, from global providers down to individual component variants, ensures that the UI can evolve efficiently with the application's needs.