Shared UI Library (@repo/ui)
Relevant source files
The following files were used as context for generating this wiki page:
The @repo/ui package is a shared UI component library for the Adfluens application. It provides a collection of accessible, customizable, and reusable React components designed to enforce a consistent user experience across the platform. Built upon a foundation of Radix UI primitives, styled with Tailwind CSS, and managed using shadcn/ui patterns, the library is a critical part of the project's monorepo structure.
The library's visual identity is guided by "The Digital Prism" design system, which emphasizes an "Opinionated Minimalism" and a "Soft Brutalism" aesthetic. This approach favors structural clarity, high-contrast states, and a distinct visual language that avoids generic SaaS trends. The result is a type-safe, tree-shakeable, and highly customizable set of components that serve as the building blocks for the Adfluens web application.
Sources: packages/ui/README.md, DESIGN.md, packages/ui/src/index.ts:3-8
Architecture and Technology Stack
The @repo/ui library is built on a modern frontend stack, designed for a monorepo environment. Its architecture prioritizes accessibility, developer experience, and design consistency.
Sources: packages/ui/README.md, packages/ui/package.json
Core Technologies
- React: The library is built as a collection of React components.
- Radix UI: Provides the unstyled, accessible primitives for components like
Dialog,DropdownMenu, andTabs. This ensures WCAG compliance and robust keyboard navigation out of the box. - Tailwind CSS: A utility-first CSS framework used for styling all components. The styling is managed through a shared configuration in the
@repo/tailwind-configpackage. - shadcn/ui: The library follows the patterns and tooling of shadcn/ui. This means components are not installed as a traditional dependency but are added directly to the source tree, allowing for full customization.
- TypeScript: Ensures full type safety for all component props and utilities.
Sources: packages/ui/README.md:3-8, packages/ui/package.json:15-27, packages/ui/components.json:2-4
Dependency Structure
The following diagram shows how @repo/ui fits into the application's ecosystem. The web application consumes the UI library, which in turn relies on Radix primitives and Tailwind CSS for its foundation.
This diagram illustrates the dependency flow from the web application down to the core libraries.
Sources: apps/web/package.json:13, packages/ui/package.json:15-27, 30
Design System: "The Digital Prism"
The visual and interactive behavior of the UI library is dictated by the "The Digital Prism" design system, which is defined by a "Soft Brutalism" aesthetic.
Sources: DESIGN.md
Core Principles
- Opinionated Minimalism: The interface removes noise, not features. Every element serves a purpose.
- Editorial Precision: Information is dense but governed by strict hierarchy and typography.
- Tactile Digitalism: Controls feel mechanical and responsive, using distinct borders and high-contrast states.
Sources: DESIGN.md:19-25
Visual Language
- Borders: All structural elements like cards and inputs have a
1pxsolid border. - Radius: Radii are small and tight (
2px,4px,8px) to create a sharp, mechanical feel. - No Drop Shadows: The system strictly avoids blurred drop shadows. Instead, depth is created with hard "offset" borders or high-contrast outlines on hover.
- Texture: A subtle noise texture is overlaid on backgrounds to reduce "digital sterility."
Sources: DESIGN.md:90-97, packages/tailwind-config/shared-styles.css:302-309
Theming and Styling
Theming is managed through CSS variables defined in a shared Tailwind CSS configuration, allowing for consistent light and dark modes across the entire application.
Sources: packages/tailwind-config/shared-styles.css:4-100, DESIGN.md:41-76
Color Palette
The palette is high-contrast and bold, with specific roles for each color.
| Theme | Role | Color Name | Hex | CSS Variable |
|---|---|---|---|---|
| Light | Canvas | Alabaster | #FDFDFC | --background |
| Light | Surface | White | #FFFFFF | --card |
| Light | Ink | Carbon | #0A0A0A | --foreground |
| Light | Primary | International Orange | #FF4F00 | --primary |
| Light | Accent | Lime Acid | #CCFF00 | --accent |
| Dark | Canvas | Obsidian | #050505 | --background |
| Dark | Surface | Charcoal | #121212 | --card |
| Dark | Ink | Mist | #EDEDED | --foreground |
| Dark | Primary | International Orange | #FF4F00 | --primary |
| Dark | Accent | Lime Acid | #CCFF00 | --accent |
Sources: DESIGN.md:46-56, 61-71, packages/tailwind-config/shared-styles.css:103-140, 143-180
Typography
A distinct typographic scale is used to establish a unique brand voice.
- Display:
Bricolage Grotesquefor headlines (H1-H3) and key data points. - Body:
Instrument Sansfor UI text, paragraphs, and labels. - Monospace:
JetBrains Monofor code snippets and technical identifiers.
These fonts are loaded in the main index.html of the web application.
Sources: DESIGN.md:29-40, apps/web/index.html:24-46, packages/tailwind-config/shared-styles.css:13-15
Theme Implementation
The theme is implemented using CSS variables, which are swapped based on the presence of a .dark class on the <html> element.
This diagram shows how CSS variables are used to switch between light and dark themes.
Sources: packages/tailwind-config/shared-styles.css:102-183, apps/web/index.html:4-15
Components and Utilities
The library exports a comprehensive set of React components and utility functions.
Sources: packages/ui/src/index.ts, packages/ui/README.md:14-30
Available Components
The main entry point packages/ui/src/index.ts exports all available components.
| Component | Description |
|---|---|
Button | Primary action component with multiple variants. |
Card | Container component for content grouping. |
Input | Text input field with consistent styling. |
Label | Accessible form labels. |
Badge | Status indicators and labels. |
Skeleton | Loading state placeholders. |
Separator | Visual content dividers. |
Tabs | Tabbed navigation component. |
Tooltip | Contextual information popups. |
ScrollArea | Custom scrollable containers. |
Dialog | Modal dialogs. |
Select | Dropdown selection component. |
ThemeToggle | A set of components to switch between color themes. |
Sources: packages/ui/README.md:14-30, packages/ui/src/index.ts:12-55
Component Usage Example
Components are imported directly from @repo/ui and composed to build complex UI features, as seen in the VideoAnalyzer component.
// From: apps/web/src/features/ai/components/video-analyzer.component.tsx
import {
Button,
Card,
CardContent,
CardHeader,
CardTitle,
Input,
ScrollArea,
cn,
} from "@repo/ui";
// ...
<Card className="hover:shadow-md transition-shadow border-border/50">
<CardHeader className="pb-3">
<CardTitle className="text-xs font-bold uppercase tracking-wider flex items-center gap-2 text-muted-foreground">
<FileText className="w-4 h-4 text-blue-500" />
Executive Summary
</CardTitle>
</CardHeader>
<CardContent>
<p className="text-muted-foreground leading-relaxed text-sm border-l-2 border-blue-500 pl-4">
{analysis.summary}
</p>
</CardContent>
</Card>
Sources: apps/web/src/features/ai/components/video-analyzer.component.tsx:16-27, 215-229
Utilities
The library also exports helpful utility functions.
cn(...inputs): A function for conditionally merging Tailwind CSS classes. It combinesclsxandtailwind-merge.formatCompactNumber(num): Formats numbers to a compact notation (e.g.,12345->12.3K).formatRelativeTime(date): Formats a date into a relative time string (e.g., "2 months ago").
Sources: packages/ui/README.md:73-92, packages/ui/src/index.ts:10
Installation and Usage
As part of a pnpm monorepo, the @repo/ui package is consumed by other workspaces.
Installation
To use the UI library in another app within the monorepo (e.g., apps/web), add it as a workspace dependency.
// In apps/web/package.json
"dependencies": {
"@repo/ui": "workspace:*"
}
Sources: apps/web/package.json:13
Adding New Components
New components are added using the shadcn/ui CLI. This process adds the component's source code directly into the packages/ui/src/components directory, making it immediately available for modification.
This flowchart outlines the process for extending the UI library with new components.
Sources: packages/ui/README.md:98-103, packages/ui/components.json
Summary
The @repo/ui library is the cornerstone of the Adfluens application's frontend. It successfully centralizes UI development, enforces the unique "Digital Prism" design system, and provides a robust, type-safe, and accessible foundation for building features. By leveraging Radix UI, Tailwind CSS, and shadcn/ui patterns, it creates a developer-friendly environment that ensures a consistent and high-quality user experience.