oneslash-design-system

Getting Started

A comprehensive guide to properly configure and use the oneslash-design-system in your Next.js project. This documentation covers installation, configuration, and best practices.

Installation

Install the design system in your project:

npm install oneslash-design-system

Tailwind Configuration

⚠️ Version-specific instructions

The configuration method differs between versions. Make sure to follow the correct instructions for your version.

For v1.2.18 and later (Current)

In version 1.2.18+, use the design tokens directly. Update your tailwind.config.ts:

import type { Config } from "tailwindcss";
  const designTokens = require('oneslash-design-system/tokens');

  const config: Config = {
    darkMode: 'class',
    content: [
      "./pages/**/*.{js,ts,jsx,tsx,mdx}",
      "./components/**/*.{js,ts,jsx,tsx,mdx}",
      "./app/**/*.{js,ts,jsx,tsx,mdx}",
      // IMPORTANT: Include design system components
      "./node_modules/oneslash-design-system/**/*.{js,jsx}",
    ],
    theme: {
      extend: {
        colors: {
          // Light: text colors
          'light-text-primary': designTokens.colors.light.text.primary,
          'light-text-secondary': designTokens.colors.light.text.secondary,
          'light-text-disabled': designTokens.colors.light.text.disabled,
          'light-text-contrast': designTokens.colors.light.text.contrast,
          // Dark: text colors
          'dark-text-primary': designTokens.colors.dark.text.primary,
          'dark-text-secondary': designTokens.colors.dark.text.secondary,
          'dark-text-disabled': designTokens.colors.dark.text.disabled,
          'dark-text-contrast': designTokens.colors.dark.text.contrast,
          // Accent colors (light & dark)
          'light-accent-main': designTokens.colors.light.accent.main,
          'light-accent-dark': designTokens.colors.light.accent.dark,
          'light-accent-light': designTokens.colors.light.accent.light,
          'dark-accent-main': designTokens.colors.dark.accent.main,
          'dark-accent-dark': designTokens.colors.dark.accent.dark,
          'dark-accent-light': designTokens.colors.dark.accent.light,
          // Primary colors (light & dark)
          'light-primary-main': designTokens.colors.light.primary.main,
          'light-primary-dark': designTokens.colors.light.primary.dark,
          'light-primary-light': designTokens.colors.light.primary.light,
          'dark-primary-main': designTokens.colors.dark.primary.main,
          'dark-primary-dark': designTokens.colors.dark.primary.dark,
          'dark-primary-light': designTokens.colors.dark.primary.light,
          // Secondary colors (light & dark)
          'light-secondary-main': designTokens.colors.light.secondary.main,
          'light-secondary-dark': designTokens.colors.light.secondary.dark,
          'light-secondary-light': designTokens.colors.light.secondary.light,
          'dark-secondary-main': designTokens.colors.dark.secondary.main,
          'dark-secondary-dark': designTokens.colors.dark.secondary.dark,
          'dark-secondary-light': designTokens.colors.dark.secondary.light,
          // Semantic colors: Error (light & dark)
          'light-error-main': designTokens.colors.light.error.main,
          'light-error-dark': designTokens.colors.light.error.dark,
          'light-error-light': designTokens.colors.light.error.light,
          'dark-error-main': designTokens.colors.dark.error.main,
          'dark-error-dark': designTokens.colors.dark.error.dark,
          'dark-error-light': designTokens.colors.dark.error.light,
          // Semantic colors: Warning (light & dark)
          'light-warning-main': designTokens.colors.light.warning.main,
          'light-warning-dark': designTokens.colors.light.warning.dark,
          'light-warning-light': designTokens.colors.light.warning.light,
          'dark-warning-main': designTokens.colors.dark.warning.main,
          'dark-warning-dark': designTokens.colors.dark.warning.dark,
          'dark-warning-light': designTokens.colors.dark.warning.light,
          // Semantic colors: Info (light & dark)
          'light-info-main': designTokens.colors.light.info.main,
          'light-info-dark': designTokens.colors.light.info.dark,
          'light-info-light': designTokens.colors.light.info.light,
          'dark-info-main': designTokens.colors.dark.info.main,
          'dark-info-dark': designTokens.colors.dark.info.dark,
          'dark-info-light': designTokens.colors.dark.info.light,
          // Semantic colors: Success (light & dark)
          'light-success-main': designTokens.colors.light.success.main,
          'light-success-dark': designTokens.colors.light.success.dark,
          'light-success-light': designTokens.colors.light.success.light,
          'dark-success-main': designTokens.colors.dark.success.main,
          'dark-success-dark': designTokens.colors.dark.success.dark,
          'dark-success-light': designTokens.colors.dark.success.light,
          // Background colors (light & dark)
          'light-background-default': designTokens.colors.light.background.default,
          'light-background-accent100': designTokens.colors.light.background.accent100,
          'light-background-accent200': designTokens.colors.light.background.accent200,
          'light-background-accent300': designTokens.colors.light.background.accent300,
          'dark-background-default': designTokens.colors.dark.background.default,
          'dark-background-accent100': designTokens.colors.dark.background.accent100,
          'dark-background-accent200': designTokens.colors.dark.background.accent200,
          'dark-background-accent300': designTokens.colors.dark.background.accent300,
          // Action colors (light & dark)
          'light-action-active': designTokens.colors.light.action.active,
          'light-action-hover': designTokens.colors.light.action.hover,
          'light-action-selected': designTokens.colors.light.action.selected,
          'light-action-disabled': designTokens.colors.light.action.disabled,
          'dark-action-active': designTokens.colors.dark.action.active,
          'dark-action-hover': designTokens.colors.dark.action.hover,
          'dark-action-selected': designTokens.colors.dark.action.selected,
          'dark-action-disabled': designTokens.colors.dark.action.disabled,
          // Misc colors
          'light-misc-divider': designTokens.colors.light.misc.divider,
          'dark-misc-divider': designTokens.colors.dark.misc.divider,
        },
        fontSize: {
          h1: designTokens.typography.h1.size,
          h2: designTokens.typography.h2.size,
          h3: designTokens.typography.h3.size,
          h4: designTokens.typography.h4.size,
          h5: designTokens.typography.h5.size,
          h6: designTokens.typography.h6.size,
          subtitle1: designTokens.typography.subtitle1.size,
          subtitle2: designTokens.typography.subtitle2.size,
          body1: designTokens.typography.body1.size,
          body2: designTokens.typography.body2.size,
          caption: designTokens.typography.caption.size,
        },
        fontWeight: {
          h1: designTokens.typography.h1.weight,
          h2: designTokens.typography.h2.weight,
          h3: designTokens.typography.h3.weight,
          h4: designTokens.typography.h4.weight,
          h5: designTokens.typography.h5.weight,
          h6: designTokens.typography.h6.weight,
          subtitle1: designTokens.typography.subtitle1.weight,
          subtitle2: designTokens.typography.subtitle2.weight,
          body1: designTokens.typography.body1.weight,
          body2: designTokens.typography.body2.weight,
          caption: designTokens.typography.caption.weight,
        },
        lineHeight: {
          h1: designTokens.typography.h1.lineHeight,
          h2: designTokens.typography.h2.lineHeight,
          h3: designTokens.typography.h3.lineHeight,
          h4: designTokens.typography.h4.lineHeight,
          h5: designTokens.typography.h5.lineHeight,
          h6: designTokens.typography.h6.lineHeight,
          subtitle1: designTokens.typography.subtitle1.lineHeight,
          subtitle2: designTokens.typography.subtitle2.lineHeight,
          body1: designTokens.typography.body1.lineHeight,
          body2: designTokens.typography.body2.lineHeight,
          caption: designTokens.typography.caption.lineHeight,
        },
        letterSpacing: {
          h1: designTokens.typography.h1.letterSpacing,
          h2: designTokens.typography.h2.letterSpacing,
          h3: designTokens.typography.h3.letterSpacing,
          h4: designTokens.typography.h4.letterSpacing,
          h5: designTokens.typography.h5.letterSpacing,
          h6: designTokens.typography.h6.letterSpacing,
          subtitle1: designTokens.typography.subtitle1.letterSpacing,
          subtitle2: designTokens.typography.subtitle2.letterSpacing,
          body1: designTokens.typography.body1.letterSpacing,
          body2: designTokens.typography.body2.letterSpacing,
          caption: designTokens.typography.caption.letterSpacing,
        },
        spacing: {
          small: designTokens.spacing.small,
          medium: designTokens.spacing.medium,
          large: designTokens.spacing.large,
        },
      },
    },
    plugins: [require('tailwind-scrollbar')],
  };

  export default config;

Why this changed: Version 1.2.18 updated the package exports. The tailwind.config.js file is no longer exported, so you must use the tokens export instead.

For versions before v1.2.18 (Legacy)

const designSystemConfig =
  require('oneslash-design-system/dist/tailwind.config.js');

  module.exports = {
    content: [
      "./pages/**/*.{js,jsx}",
      "./components/**/*.{js,jsx}",
      "./app/**/*.{js,jsx}",
      "./node_modules/oneslash-design-system/**/*.{js,jsx}",
    ],
    darkMode: 'class',
    theme: {
      ...designSystemConfig.theme,
      extend: {
        ...designSystemConfig.theme.extend,
      },
    },
  }

Key configuration requirements:

Must include node_modules/oneslash-design-system/**/*.{js,jsx} in content paths
Must set darkMode: 'class' for theme switching
Import design tokens using oneslash-design-system/tokens

Global Styles Configuration

Update your main CSS file (e.g., app/globals.css):

@tailwind base;
  @tailwind components;
  @tailwind utilities;

  @layer base {
    body {
      font-family: 'Inter', sans-serif;
      @apply text-light-text-primary dark:text-dark-text-primary;
      @apply bg-light-background-default dark:bg-dark-background-default;
    }
  }

This sets the default text and background colors globally, so you don't need to apply them to every element.

Theme Context Setup

Create a theme context for handling light/dark mode switching. Create contexts/ThemeContext.tsx:

'use client';
  import { createContext, useContext, useEffect, useState } from 'react';

  type Theme = 'light' | 'dark';

  interface ThemeContextType {
    theme: Theme;
    toggleTheme: () => void;
  }

  const ThemeContext = createContext<ThemeContextType | undefined>(undefined);

  export function ThemeProvider({ children }: { children: React.ReactNode }) {
    const [theme, setTheme] = useState<Theme>('light');
    const [mounted, setMounted] = useState(false);

    useEffect(() => {
      setMounted(true);
      const savedTheme = localStorage.getItem('theme') as Theme;
      if (savedTheme) {
        setTheme(savedTheme);
      } else if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
        setTheme('dark');
      }
    }, []);

    useEffect(() => {
      if (mounted) {
        const root = document.documentElement;
        if (theme === 'dark') {
          root.classList.add('dark');
        } else {
          root.classList.remove('dark');
        }
        localStorage.setItem('theme', theme);
      }
    }, [theme, mounted]);

    const toggleTheme = () => {
      setTheme(prev => prev === 'light' ? 'dark' : 'light');
    };

    return (
      <ThemeContext.Provider value={{ theme, toggleTheme }}>
        {children}
      </ThemeContext.Provider>
    );
  }

  export function useTheme() {
    const context = useContext(ThemeContext);
    if (context === undefined) {
      throw new Error('useTheme must be used within a ThemeProvider');
    }
    return context;
  }

Then wrap your app with the ThemeProvider in your root layout:

import { ClerkProvider } from "@clerk/nextjs";
  import { ThemeProvider } from '@/contexts/ThemeContext'

  export default function RootLayout({ children }) {
    return (
      <ClerkProvider>
        <html lang="en" suppressHydrationWarning>
          <body className="antialiased">
            <ThemeProvider>
              {children}
            </ThemeProvider>
          </body>
        </html>
      </ClerkProvider>
    )
  }

Quick Checklist

oneslash-design-system is installed
tailwind.config.ts imports tokens and includes all color/typography settings
Design system path is in Tailwind content array
darkMode: 'class' is set in Tailwind config
Global CSS includes text color and background utilities in @layer base
Inter font is loaded
ThemeContext is created and wraps your app
Dev server restarted after config changes

Component Usage Example

Import and use components in your React application:

import Button from
  'oneslash-design-system/components/button';

  function App() {
    return (
      <Button
        color="primary"
        size="medium"
        variant="filled"
        onClick={handleClick}
      >
        Click Me
      </Button>
    );
  }

Next Steps

Explore the design system's foundational elements:

Typography - Complete type scale, font setup, and usage patterns
Colors - Comprehensive color palettes for light and dark themes
Spacing - Consistent spacing scale and layout utilities
Components - Browse 26+ components with interactive examples