Shared shadcn/ui Component Library
Relevant source files
The following files were used as context for generating this wiki page:
The Shared shadcn/ui Component Library is a centralized package within the Poneglyph monorepo, located at packages/ui. It serves as the primary source of truth for UI primitives and design tokens used across the project's applications, particularly the Next.js web frontend. By housing shadcn/ui primitives in a shared workspace, the project ensures visual consistency and reduces code duplication across different modules.
Sources: README.md:12-12, README.md:73-75
Architecture and Integration
The library is structured as a dedicated workspace package named @Poneglyph/ui. It is integrated into the monorepo using Turborepo and is consumed by applications like apps/web via workspace dependencies.
The following diagram illustrates how the shared UI package is distributed across the Poneglyph monorepo:
The diagram shows the @Poneglyph/ui package providing components directly to the web application while sharing configuration with other workspaces.
Sources: package.json:3-10, apps/web/package.json:17-17, packages/ui/package.json:2-2
Configuration and Design Tokens
The library's behavior is governed by a components.json file, which follows the shadcn/ui CLI specification. This configuration defines the style (base-lyra), icon library (tabler), and path aliases for importing components.
| Option | Value | Description |
|---|---|---|
| Style | base-lyra | The base shadcn/ui style used. |
| Tailwind CSS | src/styles/globals.css | The entry point for global styles and design tokens. |
| Base Color | neutral | The default color palette base. |
| Icon Library | tabler | The primary icon set used for components. |
| RSC Support | true | Components are configured for React Server Components. |
Sources: packages/ui/components.json:3-15
Component Structure and Exports
The library organizes its code into several sub-directories within src, which are exposed via the package.json exports field. This allows applications to import specific categories of UI logic.
Export Mapping
Applications import components using the @Poneglyph/ui namespace.
| Export Path | Physical Path | Purpose |
|---|---|---|
./components/* | ./src/components/*.tsx | Reusable UI primitives (Buttons, Badges, etc.). |
./globals.css | ./src/styles/globals.css | Tailwind base styles and CSS variables. |
./lib/* | ./src/lib/*.ts | Shared utility functions (e.g., cn for tailwind-merge). |
./hooks/* | ./src/hooks/*.ts | Shared React hooks for UI logic. |
Sources: packages/ui/package.json:5-11, README.md:46-48
The cn Utility
The library provides a core utility for conditional class merging, found in @Poneglyph/ui/lib/utils. It combines clsx and tailwind-merge to handle complex Tailwind CSS class interactions dynamically.
// Example usage in layout.tsx
import { cn } from "@Poneglyph/ui/lib/utils";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" className={cn("font-sans", geist.variable, spaceGroteskHeading.variable)}>
{/* ... */}
</html>
);
}
Sources: apps/web/src/app/layout.tsx:32-34, packages/ui/package.json:22-29
Core Dependencies
The shared UI library relies on a specific set of foundational libraries to provide animation, accessibility, and styling capabilities.
- Styling: Tailwind CSS,
class-variance-authority(for component variants), andtailwind-merge. - Accessibility/Primitives:
@base-ui/reactand Radix UI primitives (imported inapps/web). - Icons:
@tabler/icons-reactandlucide-react. - Animation:
motion(Framer Motion) andtw-animate-css.
Sources: packages/ui/package.json:16-29, apps/web/package.json:18-29
Implementation in Applications
Applications utilize the shared library by importing components and applying the global styles in their root layout.
Component Consumption Flow
The following sequence shows how a component from the shared library is rendered within the web application:
The diagram outlines the dependency flow from styles and utilities to the final rendered component in the application.
Sources: apps/web/src/app/layout.tsx:3-8, apps/web/src/app/dashboard/components/article-card.tsx:1-5
Adding New Components
To expand the library, the project uses the shadcn CLI directed at the packages/ui directory. This ensures that new primitives are added to the shared package rather than an individual app's local components.
# Command to add new shared primitives
npx shadcn@latest add accordion dialog popover sheet table -c packages/ui
Sources: README.md:40-42
Summary
The Shared shadcn/ui Component Library is the visual backbone of Poneglyph. By utilizing a workspace-based architecture, it provides a scalable way to manage UI primitives, ensuring that design tokens and core components like Buttons and Badges remain consistent across the monorepo. It leverages modern tools like Tailwind CSS, Tabler Icons, and Turborepo to provide a high-performance developer experience while maintaining strict architectural separation.