Atlas Design System

Framework-agnostic design token library for consistent UI development

Vue.js React Nuxt.js Next.js Vanilla JS Tailwind CSS

🎨 Design Tokens Showcase

Explore our design tokens through interactive showcases and documentation.

📋 Complete Tokens Reference

Browse all available design tokens including colors, spacing, typography, and more.

🎯 CSS Layers Demo

See how CSS layers organize our design tokens for better maintainability and performance.

⚡ Tailwind Integration

Learn how to integrate Atlas design tokens with Tailwind CSS for rapid development.

📦 Installation 

npm install @atlas/ds
# or
yarn add @atlas/ds
# or
pnpm add @atlas/ds

Note: This package has no dependencies or peer dependencies. It's designed to be lightweight and framework-agnostic.

🎨 CSS Import Methods

Method 1: CSS Variables (Recommended)

/* In your main CSS file (e.g., tailwind.css, main.css, app.css) */
@import '@atlas/ds/variables-css';

Method 2: Tailwind-Compatible CSS Variables 

/* For Tailwind CSS with RGB color values */
@import '@atlas/ds/variables-tw';

Method 3: In Tailwind CSS File

/* In your tailwind.css file */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Import Atlas design tokens */
@import '@atlas/ds/variables-css';

🟢 Vue.js Setup

Option 1: In main.js

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import '@atlas/ds/variables-css'; // Import design tokens

createApp(App).mount('#app');

Option 2: In main CSS file

/* src/assets/main.css */
@import '@atlas/ds/variables-css';

/* Your custom styles */
body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

Option 3: In vite.config.js (for Vite projects) 

// vite.config.js
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [vue()],
  css: {
    preprocessorOptions: {
      css: {
        additionalData: `@import '@atlas/ds/variables-css';`,
      },
    },
  },
});

⚛️ React Setup

Option 1: In index.js/index.tsx

// src/index.js or src/index.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import '@atlas/ds/variables-css'; // Import design tokens

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);

Option 2: In main CSS file

/* src/index.css or src/App.css */
@import '@atlas/ds/variables-css';

/* Your custom styles */
body {
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

Option 3: In Vite config (for Vite projects) 

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  css: {
    preprocessorOptions: {
      css: {
        additionalData: `@import '@atlas/ds/variables-css';`,
      },
    },
  },
});

🟡 Nuxt.js Setup

Option 1: In nuxt.config.js

// nuxt.config.js
export default defineNuxtConfig({
  css: ['@atlas/ds/variables-css'],
});

Option 2: In app.vue

<!-- app.vue -->
<template>
  <NuxtPage />
</template>

<style>
  @import '@atlas/ds/variables-css';
</style>

Option 3: In assets directory

/* assets/css/main.css */
@import '@atlas/ds/variables-css';

/* Your custom styles */

Then import in nuxt.config.js: 

export default defineNuxtConfig({
  css: ['~/assets/css/main.css'],
});

🔵 Next.js Setup

Option 1: In _app.js/_app.tsx

// pages/_app.js or pages/_app.tsx
import '@atlas/ds/variables-css';
import '../styles/globals.css';

export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

Option 2: In app/layout.tsx (App Router)

// app/layout.tsx
import '@atlas/ds/variables-css';
import './globals.css';

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

Option 3: In globals.css

/* styles/globals.css or app/globals.css */
@import '@atlas/ds/variables-css';

/* Your custom styles */
html, body {
  padding: 0;
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

📜 JavaScript/TypeScript Usage

Import Theme Utilities

// Import the entire theme
import { theme } from '@atlas/ds';

// Import specific sections
import { colors, spacing, typography } from '@atlas/ds';

Using Theme Values Programmatically

import { theme, colors, spacing } from '@atlas/ds';

// Use theme values programmatically
const primaryColor = theme.colors.primary[500];
const spacingValue = theme.spacing[16];

// Or import specific sections
const brandColor = colors.primary[500];
const padding = spacing[16];

🎨 CSS Usage Examples

Using CSS Variables

.my-component {
  background-color: var(--surface-primary);
  color: var(--content-primary);
  padding: var(--spacing-16);
  border-radius: var(--radius-8);
  font-size: var(--text-style-body-medium-size-rem);
}

Using with Tailwind CSS (Optional)

.my-element {
  /* Using custom color palette */
  background-color: rgb(var(--primary-500));
  /* With opacity */
  background-color: rgb(var(--primary-500) / 0.5);
}

/* Using custom spacing */
.my-component {
  padding: theme('spacing.16');
  margin: theme('spacing.24');
}

⚙️ Tailwind Configuration (Optional)

Method 1: Import Entire Theme (Recommended) 

import { theme } from '@atlas/ds';

/** @type {import('tailwindcss').Config} */
export default {
  content: ['./src/**/*.{js,ts,jsx,tsx,vue}'],
  theme: {
    extend: {
      colors: theme.colors,
      spacing: theme.spacing,
      borderRadius: theme.borderRadius,
      boxShadow: theme.boxShadow,
      fontSize: theme.typography,
    },
  },
  plugins: [],
};

Method 2: Import Specific Sections

import {
  colors,
  spacing,
  typography,
  borderRadius,
  boxShadow,
} from '@atlas/ds';

/** @type {import('tailwindcss').Config} */
export default {
  content: ['./src/**/*.{js,ts,jsx,tsx,vue}'],
  theme: {
    extend: {
      colors,
      spacing,
      fontSize: typography,
      borderRadius,
      boxShadow,
    },
  },
  plugins: [],
};

📦 Available Exports

CSS Files

@atlas/ds/variables-css    // CSS variables format
@atlas/ds/variables-tw     // Tailwind-compatible CSS with RGB values
@atlas/ds/variables-scss   // SCSS variables format
@atlas/ds/variables-js     // JavaScript variables format

JavaScript/TypeScript Exports

theme        // Complete theme object with all design tokens
colors       // Color palette (base colors, semantic colors)
spacing      // Spacing scale
borderRadius // Border radius values
borderWidth  // Border width values
boxShadow    // Shadow values
grid         // Grid system values
typography   // Typography scale

🚀 Cache Busting Strategies

For Bundled Projects (React, Vue, Nuxt, Next.js):
Import CSS globally in your main entry file. The design system automatically generates hashed filenames, and the bundler will process the CSS to ensure proper loading.

// In your main entry file (main.js, index.js, app.vue, etc.)
import '@atlas/ds/variables-css';

For Static HTML Projects:
The design system automatically generates hashed filenames, but you may want to manually update the version query parameter in your HTML file after each design system update to bust CSS cache:
<link rel="stylesheet" href="@atlas/ds/variables-css.css?v=1.2.3">
Note: Assets are automatically hashed by the design system, so only CSS cache busting is needed.

🌐 Browser Support

This package uses CSS custom properties (CSS variables) and requires modern browser support:
• Chrome 49+ • Firefox 31+ • Safari 9.1+ • Edge 16+