@heer.dev/una-theme-kit

v3.1.0

Published

4 months ago

Pure CSS theme kit with CSS variables, fluid typography, and zero dependencies. Maximum power, tons of glitter, made for unicorns.

0High
0Medium
0Low

heer.dev

css css-variables theme theme-kit design-system dark-mode light-mode fluid-typography css-framework no-build zero-dependencies

UNA Theme Kit

A minimal, variable-driven CSS theme kit for building accessible and customizable web interfaces.

Features

🎨 CSS Variable-Driven - Customize everything through CSS custom properties
🌓 Light & Dark Themes - Built-in theme support with easy switching
♿ Accessibility First - Semantic HTML, proper contrast, respects motion preferences
📦 Lightweight - Under 10KB, zero dependencies
🎯 Framework Agnostic - Works with React, Vue, Angular, or plain HTML
🚀 Modern CSS - Fluid typography, custom scrollbars, smooth animations

Installation

npm

npm install una-theme-kit

CDN

<link rel="stylesheet" href="https://unpkg.com/una-theme-kit/css/base.css">

Quick Start

1. Import UNA CSS base

Using a bundler (Webpack, Vite, Parcel, etc.):

/* In your main CSS file (e.g., styles.css) */
@import 'una-theme-kit/css/base.css';

Using plain HTML:

<!-- From node_modules (if you have a dev server) -->
<link rel="stylesheet" href="/node_modules/una-theme-kit/css/base.css">

<!-- Or from CDN (easiest for static sites) -->
<link rel="stylesheet" href="https://unpkg.com/una-theme-kit/css/base.css">

2. Copy and customize the CSS variables

Copy the contents of starter.css (or view it below) into your own CSS file and customize the values to match your design:

/* Your custom variables (copy from starter.css and customize) */
:root {
  /* Layout */
  --max-width: 1280px;
  
  /* Typography */
  --family-1: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', sans-serif;
  --family-2: Georgia, 'Times New Roman', serif;
  
  /* Fluid font sizes */
  --font-size-0: clamp(0.75rem, 0.4vw + 0.65rem, 0.9rem);
  --font-size-1: clamp(0.875rem, 0.45vw + 0.75rem, 1rem);
  --font-size-2: clamp(1rem, 0.5vw + 0.85rem, 1.125rem);
  --font-size-3: clamp(1.25rem, 0.7vw + 1rem, 1.75rem);
  --font-size-4: clamp(2rem, 4vw + 1rem, 4rem);
  
  /* Line heights */
  --line-height-0: 1;
  --line-height-1: 1.2;
  --line-height-2: 1.6;
  --line-height-3: 2;
  
  /* Component heights */
  --height-1: 40px;
  --height-2: 48px;
  --height-3: 64px;
  
  /* Spacing */
  --space-1: 0.5rem;
  --space-2: 1rem;
  --space-3: 2rem;
  --space-around: var(--space-3) var(--space-1);
  
  /* Transitions & Animations */
  --transition-fast: 0.2s ease-in-out;
  --transition-slow: 0.4s ease-in-out;
  --animation-fast: 0.3s ease-in-out forwards;
  --animation-slow: 0.6s ease-in-out forwards;
  --animation-fast-infinite: 0.3s ease-in-out 0s infinite;
  --animation-slow-infinite: 0.6s ease-in-out 0s infinite;
  
  /* Optional */
  --border-radius: 0;
}

/* Light theme */
.light {
  --color-1: hsl(210, 100%, 50%);
  --color-2: hsl(280, 70%, 55%);
  --color-3: hsl(160, 70%, 45%);
  --on-color: hsl(0, 0%, 100%);
  
  --background-1: hsl(0, 0%, 96%);
  --background-2: hsl(0, 0%, 100%);
  --background-3: hsl(0, 0%, 98%);
  --background-4: hsl(0, 0%, 100%);
  
  --on-background: hsl(0, 0%, 15%);
  --on-background-light: hsl(0, 0%, 45%);
  --on-background-dark: hsl(0, 0%, 5%);
  --on-background-inverted: hsl(0, 0%, 95%);
  
  --border-1: hsl(0, 0%, 88%);
  --border-2: hsl(0, 0%, 75%);
  
  --error: hsl(0, 70%, 50%);
  --warning: hsl(40, 90%, 50%);
  --success: hsl(140, 60%, 45%);
  
  --scrollbar-track: hsl(0, 0%, 95%);
  --scrollbar-thumb: hsl(0, 0%, 70%);
}

/* Dark theme */
.dark {
  --color-1: hsl(210, 100%, 60%);
  --color-2: hsl(280, 70%, 65%);
  --color-3: hsl(160, 70%, 55%);
  --on-color: hsl(0, 0%, 10%);
  
  --background-1: hsl(0, 0%, 10%);
  --background-2: hsl(0, 0%, 14%);
  --background-3: hsl(0, 0%, 18%);
  --background-4: hsl(0, 0%, 8%);
  
  --on-background: hsl(0, 0%, 90%);
  --on-background-light: hsl(0, 0%, 65%);
  --on-background-dark: hsl(0, 0%, 98%);
  --on-background-inverted: hsl(0, 0%, 15%);
  
  --border-1: hsl(0, 0%, 25%);
  --border-2: hsl(0, 0%, 40%);
  
  --error: hsl(0, 70%, 60%);
  --warning: hsl(40, 90%, 60%);
  --success: hsl(140, 60%, 55%);
  
  --scrollbar-track: hsl(0, 0%, 12%);
  --scrollbar-thumb: hsl(0, 0%, 35%);
}

3. Apply a theme class to your HTML

<body class="light">
  <!-- Your content -->
</body>

4. Use the CSS variables in your styles

.my-component {
  background: var(--background-2);
  color: var(--on-background);
  padding: var(--space-2);
  border: 1px solid var(--border-1);
  transition: var(--transition-fast);
}

Usage Examples

React / Vue / Angular (with bundler)

// In your main entry file (e.g., main.jsx, App.jsx, or main.ts)
import 'una-theme-kit/css/base.css';
import './your-custom-variables.css'; // Your copied starter.css variables

function App() {
  const [theme, setTheme] = useState('light');
  
  return (
    <div className={theme}>
      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
        Toggle Theme
      </button>
      <h1>Hello World</h1>
    </div>
  );
}

Plain HTML / Static Site

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My App with UNA Theme Kit</title>
  
  <!-- Import UNA CSS from node_modules -->
  <link rel="stylesheet" href="node_modules/una-theme-kit/css/base.css">
  
  <!-- Or from CDN -->
  <!-- <link rel="stylesheet" href="https://unpkg.com/una-theme-kit/css/base.css"> -->
  
  <style>
    /* Your custom variables */
    :root {
      --max-width: 1280px;
      --font-size-0: clamp(0.75rem, 0.4vw + 0.65rem, 0.9rem);
      /* ... copy all variables from starter.css ... */
    }
    
    .light {
      --color-1: hsl(210, 100%, 50%);
      /* ... copy light theme variables ... */
    }
    
    .dark {
      --color-1: hsl(210, 100%, 60%);
      /* ... copy dark theme variables ... */
    }
    
    /* Your custom styles */
    .card {
      background: var(--background-2);
      padding: var(--space-2);
      border: 1px solid var(--border-1);
    }
  </style>
</head>
<body class="light">
  <h1>Hello World</h1>
  <button>Click me</button>
  <div class="card">A styled card</div>
</body>
</html>

CSS Variables Reference

Colors

--color-1, --color-2, --color-3 - Brand colors
--on-color - Text color on colored backgrounds
--background-1, --background-2, --background-3, --background-4 - Background shades
--on-background, --on-background-light, --on-background-dark - Text colors
--on-background-inverted - Inverted text color
--border-1, --border-2 - Border colors
--error, --warning, --success - Status colors
--scrollbar-track, --scrollbar-thumb - Scrollbar colors

Typography

--family-1 - Primary font stack (sans-serif)
--family-2 - Secondary font stack (serif)
--font-size-0 - Extra small (caption, labels)
--font-size-1 - Small (secondary text)
--font-size-2 - Body text (default)
--font-size-3 - Headings (h2-h6)
--font-size-4 - Hero text (h1, display)
--line-height-0 - Tight (1)
--line-height-1 - Compact (1.2)
--line-height-2 - Comfortable (1.6)
--line-height-3 - Spacious (2)

Spacing

--space-1 - Small (0.5rem / 8px)
--space-2 - Medium (1rem / 16px)
--space-3 - Large (2rem / 32px)
--space-around - Responsive container padding

Layout

--max-width - Maximum content width (1280px)
--height-1 - Small component height (40px)
--height-2 - Medium component height (48px)
--height-3 - Large component height (64px)
--border-radius - Corner rounding (0 = sharp)

Animations

--transition-fast - Quick transitions (0.2s)
--transition-slow - Slower transitions (0.4s)
--animation-fast - Quick animations (0.3s)
--animation-slow - Slower animations (0.6s)
--animation-fast-infinite - Quick looping animations
--animation-slow-infinite - Slow looping animations

Customization

Override any variable in your own CSS to customize the theme:

:root {
  /* Make everything purple */
  --color-1: hsl(280, 70%, 55%);
  
  /* Increase spacing */
  --space-2: 1.5rem;
  
  /* Add rounded corners */
  --border-radius: 8px;
  
  /* Use a different font */
  --family-1: 'Inter', sans-serif;
}

Theme Switching

Manual Toggle

// Toggle between light and dark
const body = document.body;
body.classList.toggle('light');
body.classList.toggle('dark');

Respect System Preference

/* Default to light */
body {
  @extend .light;
}

/* Auto dark mode based on system preference */
@media (prefers-color-scheme: dark) {
  body {
    @extend .dark;
  }
}

Save User Preference

// Get saved theme or default to light
const theme = localStorage.getItem('theme') || 'light';
document.body.classList.add(theme);

// Toggle and save
function toggleTheme() {
  const current = document.body.classList.contains('light') ? 'light' : 'dark';
  const next = current === 'light' ? 'dark' : 'light';
  
  document.body.classList.remove(current);
  document.body.classList.add(next);
  localStorage.setItem('theme', next);
}

What's Included

UNA Theme Kit includes these CSS modules:

base.css - Combines all modules below
_reset.css - Modern CSS reset
_typography.css - Headings, paragraphs, links, lists
_buttons.css - Button styles and states
_form.css - Inputs, textareas, selects, checkboxes, radios
_animation.css - Fade-in and drop-in animations
_scrollbars.css - Custom scrollbar styling (WebKit browsers)
_utilities.css - Motion preference utilities
starter.css - Reference CSS variables (copy to your project)

Browser Support

Chrome/Edge (latest)
Firefox (latest)
Safari 15+

Requires CSS custom properties (CSS variables) support.

License

MIT