Shared UI Components Library
Relevant source files
The following files were used as context for generating this wiki page:
The Shared UI Components Library is a central repository of reusable user interface elements designed to ensure visual consistency and development efficiency across the ATMOS ecosystem. It serves as the project's design system, providing a standardized set of components that follow a unified theme and behavioral pattern.
This library is categorized as a Layer 3 component within the project's documentation hierarchy, focusing on specific work instructions for developers and designers. It works in tandem with the @atmos/shared package, which handles non-UI utilities, while this library focuses exclusively on the visual layer.
Sources: DOCUMENTATION.md:21-28, DOCUMENTATION.md:92-95, packages/shared/README.md:144-147
Architecture and Design System
The library is built on a foundation of CSS variables and utility-first styling, ensuring that all components share a common design language. It utilizes a theme-aware system that supports both light and dark modes through a predefined set of HSL color variables.
Styling Foundation
The core styling is defined in a global CSS file that establishes the color palette, border radii, and animations. This system uses CSS variables to allow for easy theme switching and consistent spacing.
The diagram shows how global style definitions provide the tokens used by individual components.
Sources: packages/ui/src/styles/globals.css:1-50, packages/ui/AGENTS.md:1-10
Theme Configuration
The design system defines specific semantic roles for colors, such as primary, secondary, accent, and destructive.
| Variable | Purpose | Light Mode (HSL) | Dark Mode (HSL) |
|---|---|---|---|
--background | Main app background | 0 0% 100% | 222.2 84% 4.9% |
--foreground | Primary text color | 222.2 84% 4.9% | 210 40% 98% |
--primary | Primary action color | 222.2 47.4% 11.2% | 210 40% 98% |
--destructive | Error/Danger actions | 0 84.2% 60.2% | 0 62.8% 30.6% |
--radius | Component corner rounding | 0.5rem | 0.5rem |
Sources: packages/ui/src/styles/globals.css:5-103
Core Components
The library follows a modular approach where each component is isolated in its own file, typically utilizing class-variance-authority (CVA) for managing style variants and clsx or tailwind-merge for class composition.
Button Component
The Button component is a primary example of the library's implementation pattern. It supports multiple visual variants and sizes through a structured configuration.
This flowchart illustrates the logic for determining the final CSS classes applied to a Button based on its props.
Sources: packages/ui/src/components/ui/button.tsx:1-45
Implementation Details
The Button uses a slot component pattern, allowing it to act as a wrapper for other elements while maintaining button-like styling and behavior.
const buttonVariants = vca(
"inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1",
{
variants: {
variant: {
default: "bg-primary text-primary-foreground shadow hover:bg-primary/90",
destructive: "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
outline: "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
},
size: {
default: "h-9 px-4 py-2",
sm: "h-8 rounded-md px-3 text-xs",
lg: "h-10 rounded-md px-8",
icon: "h-9 w-9",
},
},
defaultVariants: {
variant: "default",
size: "default",
},
}
)
Sources: packages/ui/src/components/ui/button.tsx:7-38
Usage and Integration
Developers interacting with the Shared UI library should refer to the component-specific AGENTS.md for work instructions. The library is intended to be used by various applications in the apps/ directory, such as the web dashboard or landing page.
Best Practices
- Consistency: Always use the predefined CSS variables from
globals.cssrather than hardcoding HSL values. - Variants: Use the
variantandsizeprops provided by the components to handle different UI states. - Separation: Keep business logic in the
apps/or@atmos/sharedpackage, and keep pure visual logic within this UI library.
Sources: DOCUMENTATION.md:121-127, packages/shared/README.md:144-150, packages/ui/AGENTS.md:1-5
Conclusion
The Shared UI Components Library is a critical infrastructure piece of the ATMOS project. By centralizing visual elements and styling logic in packages/ui, the project maintains a high standard of UI/UX while allowing developers to quickly assemble complex interfaces from a library of well-tested, themeable components.