ValueBridge Design System

This package contains the design system for ValueBridge learning platform. It includes UI components, color schemes, typography, and utility functions that can be used to build consistent user interfaces across multiple applications.

Features

• 🎨 Comprehensive color palette with light and dark mode support
• 📏 Consistent spacing and typography
• 🧩 Reusable UI components
• 🔧 Utility functions for common operations
• 🌙 Built-in dark mode support

Installation

From NPM Registry

The ValueBridge Design System is available on npm as a scoped package:

# Using npm
npm install @valuebridge/design-system

# Using yarn
yarn add @valuebridge/design-system

# Using pnpm
pnpm add @valuebridge/design-system

From Source

You can also install directly from source:

# Clone the repository
git clone <repository-url>

# Navigate to the design system directory
cd design-system-export

# Install dependencies using the installation script
./install-deps.sh

# Build the package
npm run build

# Link it locally for development
npm link

Then in your project:

npm link @valuebridge/design-system

Common Issues and Troubleshooting

Build Errors

If you encounter "command not found" errors when running build scripts, use the included dependency installation script:

./install-deps.sh

This script ensures all dependencies are properly installed and configured, especially the build tools like tsup.

Setup

1. Update your tailwind.config.js

const { tailwindConfig } = require('@valuebridge/design-system/tailwind.config.js');

/** @type {import('tailwindcss').Config} */
module.exports = {
  // Spread the design system's tailwind config
  ...tailwindConfig,
  // You can extend or override the configuration
  content: [
    ...tailwindConfig.content,
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
    './app/**/*.{js,ts,jsx,tsx}',
    // Include the design system components
    './node_modules/@valuebridge/design-system/dist/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    ...tailwindConfig.theme,
    extend: {
      ...tailwindConfig.theme.extend,
      // Add any custom theme extensions here
    },
  },
};

2. Import the CSS

In your global CSS file (e.g., globals.css):

@import '@valuebridge/design-system/src/globals.css';

/* Your additional global styles */

3. Initialize the Design System (optional)

If you want to use the design system's utilities, initialize it in your app:

// In your _app.tsx or layout.tsx
import { initializeDesignSystem } from '@valuebridge/design-system';

export default function App({ Component, pageProps }) {
  // Initialize with options
  const designSystem = initializeDesignSystem({
    darkMode: true, // Enable dark mode by default
  });

  return <Component {...pageProps} />;
}

Usage

Components

import { Button, Card, CardContent, CardHeader, CardTitle } from '@valuebridge/design-system';

export default function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>My Card</CardTitle>
      </CardHeader>
      <CardContent>
        <p>Card content goes here</p>
        <Button>Click Me</Button>
      </CardContent>
    </Card>
  );
}

Utility Functions

import { cn, createSlug } from '@valuebridge/design-system';

// Conditionally apply classes
const className = cn('base-class', {
  'conditional-class': isConditionTrue,
});

// Create a URL-friendly slug
const slug = createSlug('My Article Title');
// Output: "my-article-title"

CSS Classes

The design system provides a set of pre-defined CSS classes for common UI patterns:

<div className="content-container">
  <h1 className="concept-title">Introduction to Design Systems</h1>
  <div className="definition-block">
    <h4>Definition</h4>
    <p>A design system is a collection of reusable components...</p>
  </div>
  <div className="key-point">
    <div className="key-point-icon">✓</div>
    <div className="key-point-text">Ensures consistency across products</div>
  </div>
</div>

Customization

You can customize the design system by:

1. Overriding the Tailwind configuration
2. Creating your own component wrappers
3. Extending the existing components with your own variants

Dark Mode

The design system supports dark mode out of the box. Use the dark: prefix for Tailwind classes to specify dark mode variants:

<div className="bg-white dark:bg-slate-900 text-gray-800 dark:text-gray-100">
  Dark mode compatible content
</div>

To toggle dark mode programmatically:

import { initializeDesignSystem } from '@valuebridge/design-system';

const { toggleDarkMode } = initializeDesignSystem();

// In a click handler
function handleToggleDarkMode() {
  const isDarkMode = toggleDarkMode();
  console.log('Dark mode is now:', isDarkMode ? 'on' : 'off');
}

Publishing to NPM

If you want to publish this design system to the npm registry, refer to the Publishing Guide for detailed instructions.

License

This design system is intended for use within ValueBridge projects only.