cbs-ui

v1.1.11

Published

8 months ago

A comprehensive React component library built with Next.js and CSS Modules

Downloads

0High
0Medium
0Low

jhernandezm

react nextjs component-library ui typescript css-modules design-system

CBS UI - Modern React Component Library

A comprehensive, themeable React component library built with Next.js, TypeScript, and CSS Modules. CBS UI provides a robust foundation for building modern web applications with consistent design patterns and excellent developer experience.

🚀 Key Features

🎨 Multi-Theme System: 9 built-in themes with light/dark mode support
🔧 Utility-First Design: 50+ utility props for rapid styling
📱 Responsive by Default: Mobile-first responsive design system
♿ Accessibility First: WCAG 2.1 compliant components
⚡ Performance Optimized: Tree-shakable, minimal bundle impact
🎭 Animation Ready: Built-in motion support
🔒 Type Safe: Full TypeScript support with excellent DX

📦 Installation

npm install @cbs/ui
# or
yarn add @cbs/ui
# or
pnpm add @cbs/ui

🎯 Quick Start

1. Import Styles

/* app/globals.css */
@import '@cbs/ui/styles';

2. Setup Theme Provider

// app/layout.tsx
import { ThemeProvider, themes } from '@cbs/ui';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider themes={themes} defaultTheme="bonita">
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

3. Use Components

// app/page.tsx
import { Button, Text, Box, Card } from '@cbs/ui';

export default function HomePage() {
  return (
    <Box padding="6" backgroundColor="background-root">
      <Text as="hero" marginBottom="4" color="text-base">
        Welcome to CBS UI
      </Text>

      <Card padding="6" shadow="md">
        <Text as="body" marginBottom="4">
          Build beautiful interfaces with our comprehensive component library.
        </Text>

        <Button variant="primary" size="md">
          Get Started
        </Button>
      </Card>
    </Box>
  );
}

🎨 Theme System

Available Themes

CBS UI includes 9 professionally designed themes:

| Theme | Style | Description | | -------------------- | ------------- | ------------------------------ | | Bonita (default) | Clean | Modern, minimalist design | | Bollypop | Vibrant | Playful, colorful interface | | Gradient | Gradient | Beautiful gradient backgrounds | | Elegant | Sophisticated | Premium, refined aesthetics | | Futuristic | Tech | High-tech, futuristic look | | Neumorphism | Soft | Soft, elevated elements | | Dark Kitchen | Dark | Dark theme for content apps | | Neobrutalism | Bold | Raw, bold design language | | Liquid Glass | Glass | Glass morphism effects |

Theme Switching

import { useTheme } from '@cbs/ui';

function ThemeSwitcher() {
  const { theme, changeTheme, toggleDarkMode } = useTheme();

  return (
    <Box display="flex" gap="2">
      <Button onClick={() => changeTheme('bonita')}>Bonita</Button>
      <Button onClick={() => changeTheme('gradient')}>Gradient</Button>
      <Button onClick={() => changeTheme('neobrutalism')}>Neobrutalism</Button>
      <Button onClick={toggleDarkMode}>Toggle Dark Mode</Button>
    </Box>
  );
}

Custom Themes

const customTheme = {
  style: 'default',
  currentMode: 'light',
  themeName: 'custom',
  effects: {
    glass: {
      blur: 'blur(10px)',
      opacity: 0.2,
      color: 'rgba(255, 255, 255, 0.1)'
    }
  },
  components: {
    button: {
      variants: {
        variant: 'primary',
        size: 'md',
        radius: 'md',
        shadow: 'sm'
      }
    }
  }
};

<ThemeProvider themes={{ ...themes, custom: customTheme }} defaultTheme="custom">
  <YourApp />
</ThemeProvider>;

🔧 Utility Props System

CBS UI provides 50+ utility props for rapid styling without writing CSS:

Layout Utilities

<Box
  display="flex" // flex, grid, block, none
  flexDirection="column" // row, column
  justifyContent="center" // flex-start, center, flex-end, space-between
  alignItems="center" // flex-start, center, flex-end, stretch
  gap="4" // Spacing between flex items
  flexWrap="wrap" // wrap, nowrap
>
  Content
</Box>

Spacing Utilities

<Box
  // Full names
  margin="4" // All sides
  marginX="auto" // Horizontal (left + right)
  marginY="2" // Vertical (top + bottom)
  padding="6" // All sides
  paddingX="4" // Horizontal
  paddingY="2" // Vertical
  // Short aliases
  mt="lg" // marginTop
  mb="sm" // marginBottom
  pt="4" // paddingTop
  pb="2" // paddingBottom
>
  Content
</Box>

Color Utilities

<Box
  color="text-base" // Text color
  backgroundColor="primary-light" // Background color
  borderColor="primary-main" // Border color
  // Palette colors
  color="blue-500" // Direct palette access
  backgroundColor="gray-100" // Direct palette access
>
  Content
</Box>

Typography Utilities

<Box
  fontSize="heading" // hero, heading, body, label, badge
  fontWeight="bold" // light, normal, medium, bold
>
  Typography content
</Box>

Border & Shadow Utilities

<Box
  border="1" // Border width
  borderStyle="solid" // solid, dashed, dotted
  borderRadius="4" // Border radius
  shadow="md" // none, xs, sm, md, lg, xl, 2xl
>
  Content
</Box>

📱 Responsive Design

Responsive Props

<Box
  // Responsive values
  padding={{ xs: '2', md: '4', lg: '6' }}
  fontSize={{ xs: 'body', md: 'heading', lg: 'hero' }}
  flexDirection={{ xs: 'column', md: 'row' }}
  width={{ xs: '100%', md: '50%', lg: '33%' }}
>
  Responsive content
</Box>

Breakpoints

xs: 480px (mobile)
sm: 768px (tablet)
md: 1024px (desktop)
lg: 1280px (large desktop)

🎭 Animation & Motion

Built-in Motion Support

<Box
  animate={{ opacity: [0, 1], y: [20, 0] }}
  transition={{ duration: 0.5 }}
  whileHover={{ scale: 1.05 }}
  whileTap={{ scale: 0.95 }}
>
  Animated content
</Box>

Component Animations

<Button variant="primary" whileHover={{ scale: 1.05 }} whileTap={{ scale: 0.95 }}>
  Animated button
</Button>

♿ Accessibility

Built-in Accessibility Features

Semantic HTML: Proper element mapping
ARIA Support: Automatic ARIA attributes
Keyboard Navigation: Full keyboard support
Focus Management: Proper focus indicators
Screen Reader: Comprehensive labeling
Color Contrast: WCAG 2.1 compliant ratios

Accessibility Examples

// Automatic semantic HTML
<Text as="heading">This renders as <h1></Text>
<Text as="body">This renders as <p></Text>

// Proper button semantics
<Button
  variant="primary"
  aria-label="Submit form"
  aria-describedby="form-description"
>
  Submit
</Button>

🔧 Advanced Usage

Component Composition

// Compose components with utility props
<Card padding="6" shadow="lg" borderRadius="8" backgroundColor="background-root">
  <Text as="title" marginBottom="4" color="text-base" fontSize="heading">
    Composed Card
  </Text>

  <Text as="body" marginBottom="4" color="text-base" fontSize="body">
    Card content with consistent styling
  </Text>

  <Button variant="primary" size="md" marginTop="4">
    Action
  </Button>
</Card>

Custom Styling

// Use CSS modules for custom styles
import styles from './custom-card.module.css';

<Card className={styles.customCard}>
  Custom styled content
</Card>

// CSS module targeting component classes
.customCard {
  --card-background-color: var(--color-primary-light);
  --card-border-color: var(--color-primary-main);
}

Performance Optimization

// Memoize components for performance
const MemoizedCard = React.memo(Card);

// Use React.memo for expensive components
const ExpensiveComponent = React.memo(({ data }) => (
  <Box>
    {data.map((item) => (
      <Card key={item.id}>{item.content}</Card>
    ))}
  </Box>
));

🛠️ Development

Building the Library

# Install dependencies
npm install

# Development mode
npm run dev

# Build library
npm run build

# Build types
npm run build:types

# Clean build
npm run clean

Development Setup

# Clone repository
git clone https://github.com/cbs-systems/cbs-ui.git

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Build library
npm run build

📄 License

MIT License - see LICENSE for details.

Built with ❤️ by CBS Systems