Shadcn UI & Tailwind v4
Relevant source files
The following files were used as context for generating this wiki page:
KudosWall utilizes a modern design system architecture centered around Shadcn UI and Tailwind CSS v4. This system is housed primarily within the packages/ui workspace, serving as a shared HSL-based design system and React primitive library for the entire monorepo. The goal of this architecture is to provide high-fidelity, accessible, and performant UI components that support complex features like glassmorphic interfaces and zero-layout-shift widgets.
The UI layer is tightly integrated with the project's performance goals, leveraging Tailwind v4's capabilities to serve edge-optimized assets and CSS-first rendering. This ensures that testimonial widgets and marketing pages maintain sub-100ms loading times while offering extensive white-labeling and customization options for Pro-tier users.
Sources: README.md:16, README.md:109, AGENTS.md:95
Architecture and Monorepo Integration
The UI system follows a decoupled workspace pattern governed by Turborepo. The packages/ui package acts as the base layer for all visual elements, which are then consumed by the primary application in apps/web.
Workspace Dependency Flow
The following diagram illustrates how the UI package interacts with other modules in the KudosWall ecosystem:
The UI package provides shared HSL design system primitives and React components.
Sources: README.md:103-125
Component Design and implementation
Components are built using Shadcn UI primitives, which are customized and extended within the project. The system emphasizes "CSS-first" design tokens to ensure visual consistency and high performance.
Key Component: Button
The Button component serves as a primary example of the Shadcn-based architecture, utilizing class-variance-authority (cva) to manage styles and Tailwind CSS for utility-first styling.
| Variant | Description | Implementation Detail |
|---|---|---|
| Default | Primary action button | Uses HSL-based primary background |
| Destructive | Warning or delete actions | Red-themed destructive background |
| Outline | Secondary actions | Bordered with transparent background |
| Ghost | Subtle actions | Hover-only background visibility |
| Link | Navigation-style | Text-primary with underline on hover |
Sources: packages/ui/src/components/button.tsx:7-25
Configuration (components.json)
The Shadcn UI CLI configuration specifies the structure of the UI package, ensuring that components are correctly located and utilize the designated Tailwind variables.
{
"style": "default",
"rsc": true,
"tsx": true,
"tailwind": {
"config": "tailwind.config.ts",
"css": "src/styles/globals.css",
"baseColor": "neutral",
"cssVariables": true
},
"aliases": {
"components": "@/components",
"ui": "@/components/ui",
"lib": "@/lib",
"hooks": "@/hooks"
}
}
Sources: packages/ui/components.json:2-23
Tailwind v4 & Performance Optimization
KudosWall leverages Tailwind CSS v4 to achieve specific performance and design goals, particularly for public-facing widgets.
Optimization Strategies
- Zero Layout Shift: Widgets use advanced CSS-first rendering to ensure pages do not "jump" during testimonial loading.
- Edge Delivery: UI assets are served from a global edge to ensure sub-100ms loading times.
- Lazy Loading: For embeddable widgets, player components and heavy assets are lazy-loaded, loading only when they enter the viewport.
Sources: apps/web/src/lib/comparisons.tsx:109-115, apps/web/src/lib/comparisons.tsx:735-741
Customization and White-labeling
For Pro-tier users, the UI system allows for extensive runtime customization. The EmbedPage dynamically overrides Tailwind styles based on database settings or URL parameters.
Code Quality and Formatting
The project enforces strict standards for UI code to maintain consistency across the monorepo.
- Formatting: Managed by Prettier with a dedicated Tailwind CSS plugin to ensure utility class order consistency.
- Execution: Automated git hooks via Lefthook run
bun run formatand type checks before commits. - Accessibility: Use of semantic HTML and correct ARIA roles for all interactive Shadcn components is required.
Sources: AGENTS.md:7-13, AGENTS.md:75-77
Conclusion
The combination of Shadcn UI and Tailwind v4 provides KudosWall with a scalable, type-safe design system. By centralizing UI logic in packages/ui and utilizing modern CSS strategies, the platform achieves a balance between deep user customization (white-labeling) and extreme performance (edge-optimized rendering).