Plutonium Theming

Plutonium Design Token System

Plutonium uses a comprehensive CSS design token system for consistent, themeable UI components. This system provides CSS custom properties and reusable component classes that automatically support light and dark modes.

CSS Design Tokens

Design tokens are defined in src/css/tokens.css and provide the foundation for all UI styling.

Surface & Background Colors

/* Light mode */
--pu-body: #f8fafc;              /* Page background */
--pu-surface: #ffffff;            /* Main surface (cards, panels) */
--pu-surface-alt: #f1f5f9;        /* Alternate surface (headers) */
--pu-surface-raised: #ffffff;     /* Elevated elements */
--pu-surface-overlay: rgba(255, 255, 255, 0.95);

/* Dark mode (.dark class) */
--pu-body: #0f172a;
--pu-surface: #1e293b;
--pu-surface-alt: #0f172a;
--pu-surface-raised: #334155;
--pu-surface-overlay: rgba(30, 41, 59, 0.95);

Text Colors

/* Light mode */
--pu-text: #0f172a;               /* Primary text */
--pu-text-muted: #64748b;         /* Secondary text */
--pu-text-subtle: #94a3b8;        /* Tertiary/disabled text */

/* Dark mode */
--pu-text: #f8fafc;
--pu-text-muted: #94a3b8;
--pu-text-subtle: #64748b;

Border Colors

/* Light mode */
--pu-border: #e2e8f0;             /* Standard borders */
--pu-border-muted: #f1f5f9;       /* Subtle borders */
--pu-border-strong: #cbd5e1;      /* Emphasized borders */

/* Dark mode */
--pu-border: #334155;
--pu-border-muted: #1e293b;
--pu-border-strong: #475569;

Form Tokens

--pu-input-bg: #ffffff;           /* Input background */
--pu-input-border: #e2e8f0;       /* Input border */
--pu-input-focus-ring: theme(colors.primary.500);
--pu-input-placeholder: #94a3b8;  /* Placeholder text */

Card Tokens

--pu-card-bg: #ffffff;
--pu-card-border: #e2e8f0;

Shadow System

--pu-shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.03), 0 1px 3px 0 rgb(0 0 0 / 0.05);
--pu-shadow-md: 0 2px 4px -1px rgb(0 0 0 / 0.04), 0 4px 6px -1px rgb(0 0 0 / 0.06);
--pu-shadow-lg: 0 4px 6px -2px rgb(0 0 0 / 0.03), 0 10px 15px -3px rgb(0 0 0 / 0.08);

Border Radius

--pu-radius-sm: 0.375rem;         /* 6px */
--pu-radius-md: 0.5rem;           /* 8px */
--pu-radius-lg: 0.75rem;          /* 12px */
--pu-radius-xl: 1rem;             /* 16px */
--pu-radius-full: 9999px;         /* Fully rounded */

Spacing

--pu-space-xs: 0.25rem;           /* 4px */
--pu-space-sm: 0.5rem;            /* 8px */
--pu-space-md: 1rem;              /* 16px */
--pu-space-lg: 1.5rem;            /* 24px */
--pu-space-xl: 2rem;              /* 32px */

Transitions

--pu-transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
--pu-transition-normal: 200ms cubic-bezier(0.4, 0, 0.2, 1);
--pu-transition-slow: 300ms cubic-bezier(0.4, 0, 0.2, 1);

Component Classes

Component classes are defined in src/css/components.css and provide ready-to-use styled components.

Buttons

Base class with size variants:

.pu-btn        /* Base button styles */
.pu-btn-md     /* Medium size (default) */
.pu-btn-sm     /* Small size */
.pu-btn-xs     /* Extra small size */

Solid variants (with hover lift animation):

.pu-btn-primary    /* Primary action */
.pu-btn-secondary  /* Secondary action */
.pu-btn-danger     /* Destructive action */
.pu-btn-success    /* Success action */
.pu-btn-warning    /* Warning action */
.pu-btn-info       /* Informational action */
.pu-btn-accent     /* Accent action */

Other variants:

.pu-btn-ghost      /* Minimal, text-like */
.pu-btn-outline    /* Bordered, transparent background */

Soft variants (tinted backgrounds for secondary contexts):

.pu-btn-soft-primary
.pu-btn-soft-danger
.pu-btn-soft-success
.pu-btn-soft-warning
.pu-btn-soft-info
.pu-btn-soft-secondary
.pu-btn-soft-accent

Usage:

<%= form.submit "Save", class: "pu-btn pu-btn-md pu-btn-primary" %>
<%= form.submit "Delete", class: "pu-btn pu-btn-md pu-btn-danger" %>
<%= form.submit "Disable", class: "pu-btn pu-btn-md pu-btn-warning" %>

Form Inputs

.pu-input          /* Base input styles */
.pu-input-invalid  /* Error state */
.pu-input-valid    /* Valid state */

Usage:

<%= form.text_field :name, class: "pu-input #{errors? ? 'pu-input-invalid' : ''}" %>

Labels & Text

.pu-label          /* Form labels */
.pu-label-required /* Adds red asterisk after label */
.pu-hint           /* Helper text below inputs */
.pu-error          /* Error messages */

Usage:

<%= form.label :email, class: "pu-label" %>
<span class="pu-error">Email is required</span>

Checkboxes

.pu-checkbox       /* Styled checkbox/radio */

Usage:

<%= form.check_box :remember_me, class: "pu-checkbox" %>

Cards

.pu-card           /* Card container with border, shadow, radius */
.pu-card-body      /* Card content padding */

Panels

.pu-panel-header      /* Panel header with background */
.pu-panel-title       /* Panel title text */
.pu-panel-description /* Panel description text */

Tables

.pu-table-wrapper     /* Scrollable container with card styling */
.pu-table             /* Base table styles */
.pu-table-header      /* Header row */
.pu-table-header-cell /* Header cell */
.pu-table-body-row    /* Body row with hover */
.pu-table-body-row-selected /* Selected row */
.pu-table-body-cell   /* Body cell */
.pu-selection-cell    /* Checkbox column */

Toolbar

.pu-toolbar        /* Toolbar container with gradient */
.pu-toolbar-text   /* Toolbar text */
.pu-toolbar-actions /* Toolbar action buttons */

Empty State

.pu-empty-state             /* Centered container */
.pu-empty-state-icon        /* Icon styling */
.pu-empty-state-title       /* Title text */
.pu-empty-state-description /* Description text */

Ruby Component Classes

The Plutonium::UI::ComponentClasses module provides Ruby constants for consistent class usage.

Location: lib/plutonium/ui/component_classes.rb

Button Classes

ComponentClasses::Button::BASE          # "pu-btn"
ComponentClasses::Button::SIZE_DEFAULT  # "pu-btn-md"
ComponentClasses::Button::SIZE_SM       # "pu-btn-sm"
ComponentClasses::Button::SIZE_XS       # "pu-btn-xs"

ComponentClasses::Button::VARIANTS[:primary]   # "pu-btn-primary"
ComponentClasses::Button::VARIANTS[:danger]    # "pu-btn-danger"
ComponentClasses::Button::SOFT_VARIANTS[:primary] # "pu-btn-soft-primary"

# Helper method
ComponentClasses::Button.classes(variant: :primary, size: :default, soft: false)
# => "pu-btn pu-btn-md pu-btn-primary"

Form Classes

ComponentClasses::Form::INPUT         # "pu-input"
ComponentClasses::Form::INPUT_INVALID # "pu-input pu-input-invalid"
ComponentClasses::Form::INPUT_VALID   # "pu-input pu-input-valid"
ComponentClasses::Form::LABEL         # "pu-label"
ComponentClasses::Form::HINT          # "pu-hint"
ComponentClasses::Form::ERROR         # "pu-error"
ComponentClasses::Form::BUTTON        # "pu-btn pu-btn-md pu-btn-primary"

Table Classes

ComponentClasses::Table::WRAPPER          # "pu-table-wrapper"
ComponentClasses::Table::BASE             # "pu-table"
ComponentClasses::Table::HEADER           # "pu-table-header"
ComponentClasses::Table::HEADER_CELL      # "pu-table-header-cell"
ComponentClasses::Table::BODY_ROW         # "pu-table-body-row"
ComponentClasses::Table::BODY_ROW_SELECTED # "pu-table-body-row-selected"
ComponentClasses::Table::BODY_CELL        # "pu-table-body-cell"
ComponentClasses::Table::CHECKBOX         # "pu-checkbox"

Card Classes

ComponentClasses::Card::BASE        # "pu-card"
ComponentClasses::Card::BODY        # "pu-card-body"
ComponentClasses::Card::HEADER      # "pu-panel-header"
ComponentClasses::Card::TITLE       # "pu-panel-title"
ComponentClasses::Card::DESCRIPTION # "pu-panel-description"

Using Tokens in Templates

ERB Templates

<%# Text colors %>
<h1 class="text-[var(--pu-text)]">Title</h1>
<p class="text-[var(--pu-text-muted)]">Description</p>

<%# Surfaces %>
<div class="bg-[var(--pu-surface)] border border-[var(--pu-border)] rounded-[var(--pu-radius-lg)]">
  Content
</div>

<%# With shadows %>
<div class="bg-[var(--pu-card-bg)]" style="box-shadow: var(--pu-shadow-md)">
  Card content
</div>

<%# Form fields %>
<%= form.label :name, class: "pu-label" %>
<%= form.text_field :name, class: "pu-input" %>
<span class="pu-error">Error message</span>

<%# Buttons %>
<%= form.submit "Save", class: "w-full pu-btn pu-btn-md pu-btn-primary" %>

Phlex Components

class MyComponent < Plutonium::UI::Component::Base
  def view_template
    div(class: "bg-[var(--pu-surface)] border border-[var(--pu-border)] rounded-[var(--pu-radius-lg)]",
        style: "box-shadow: var(--pu-shadow-md)") {
      h2(class: "text-lg font-semibold text-[var(--pu-text)]") { "Title" }
      p(class: "text-[var(--pu-text-muted)]") { "Description" }
    }
  end
end

Link Styling Patterns

Plutonium uses consistent link styling patterns:

<%# Primary links %>
<%= link_to "Link", path, class: "font-medium text-secondary-600 dark:text-secondary-400 hover:underline transition-colors" %>

<%# Muted links %>
<%= link_to "Link", path, class: "text-[var(--pu-text-muted)] hover:text-primary-600 transition-colors" %>

Dark Mode

All tokens automatically switch values when the .dark class is present on <html>:

<!-- Light mode -->
<html>
  <body class="bg-[var(--pu-body)]">...</body>
</html>

<!-- Dark mode -->
<html class="dark">
  <body class="bg-[var(--pu-body)]">...</body>
</html>

No additional classes needed - tokens handle the switch automatically.

Customizing Tokens

Override tokens in your application CSS:

/* app/assets/stylesheets/application.tailwind.css */
@import "gem:plutonium/src/css/plutonium.css";
@import "tailwindcss";

:root {
  /* Override light mode tokens */
  --pu-surface: #fafafa;
  --pu-border: #d1d5db;
}

.dark {
  /* Override dark mode tokens */
  --pu-surface: #111827;
  --pu-border: #374151;
}

Migration from Hardcoded Classes

When updating views to use the design token system:

Related Skills

• plutonium-assets - TailwindCSS configuration and asset setup
• plutonium-forms - Form component customization
• plutonium-views - View and layout customization