@popgrids/theme

A simplified design system focused on theme variables without Tailwind CSS dependencies.

Features

• Modern CSS variables using OKLCH colors
• Framework adapters for React, Lit, and vanilla JavaScript
• Zero dependencies on utility class frameworks

Installation

npm install @popgrids/theme

Usage

Direct CSS Import

/* Import just the CSS variables */
@import "@popgrids/theme/variables.css";

/* Use in your CSS */
.my-element {
  color: var(--color-brand-midnight-900);
  padding: var(--spacing-4);
}

React

import { useTheme, css } from "@popgrids/theme/react";

function MyComponent() {
  // Hook approach
  useTheme();

  return (
    <div
      style={{
        color: "var(--color-brand-midnight-900)",
        padding: "var(--spacing-4)",
      }}
    >
      My themed component
    </div>
  );
}

// CSS-in-JS approach
const styles = {
  container: css`
    color: var(--color-brand-midnight-900);
    padding: var(--spacing-4);
  `,
};

Lit

import { LitElement, html } from "lit";
import { themeStyles, getVariable } from "@popgrids/theme/lit";

class MyElement extends LitElement {
  // Import all theme variables
  static styles = [themeStyles];

  // You can also access variables programmatically
  get primaryColor() {
    return getVariable("--color-brand-midnight-900");
  }

  render() {
    return html`
      <div>
        <p>Using CSS variables directly in styles</p>
        <button>Styled button</button>

        <p>Using variables in dynamic properties</p>
        <span style="color: ${this.primaryColor}">
          Dynamic color application
        </span>
      </div>
    `;
  }
}

With Tailwind v4 (CSS-first approach)

Tailwind v4 introduces a CSS-first approach that works perfectly with our theme. You can use the @theme directive to map our variables to Tailwind:

/* Import the theme variables */
@import "@popgrids/theme/variables.css";

/* Layer organization for Tailwind v4 */
@layer reset, base, theme, components, utilities;

/* Map PopGrids theme variables to Tailwind */
@theme {
  /* Colors */
  --color-primary-500: var(--color-brand-midnight-900);
  --color-primary-600: var(--color-brand-midnight-800);

  /* Text colors */
  --color-text: var(--color-grayscale-900);
  --color-text-muted: var(--color-grayscale-500);

  /* Typography */
  --font-sans: var(--font-sans);

  /* Spacing */
  --spacing-4: var(--spacing-4);

  /* Border radius */
  --radius-md: var(--radius-md);
}

In your minimal tailwind.config.js:

/** @type {import('tailwindcss').Config} */
export default {
  content: ["./src/**/*.{js,jsx,ts,tsx}"],
  plugins: [], // Add any plugins you need
};

Legacy Tailwind Configuration

For older Tailwind versions (pre-v4), configure Tailwind to use the theme variables:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          midnight: {
            900: "var(--color-brand-midnight-900)",
            800: "var(--color-brand-midnight-800)",
          },
          // ... other colors
        },
      },
      spacing: {
        // Map spacing variables if needed
        4: "var(--spacing-4)",
        // ... other spacing
      },
    },
  },
  // ...
};