Get Started

Custom Variables

Adding your own CSS variables and design tokens to OxyMade.

Learn how to extend OxyMade with your own custom CSS variables and design tokens.

Overview

While OxyMade provides a comprehensive set of variables, you may need to add custom variables for:

  • Brand-specific colors
  • Project-specific spacing
  • Custom effects
  • Component-specific tokens

Adding Custom Variables

Via Custom CSS

The simplest approach is adding variables in your CSS:

:root {
  /* Custom brand colors */
  --brand-gradient-start: #6366f1;
  --brand-gradient-end: #8b5cf6;
  --brand-gradient: linear-gradient(135deg, var(--brand-gradient-start), var(--brand-gradient-end));

  /* Custom spacing */
  --container-padding: var(--s6);
  --card-padding: var(--s5);

  /* Custom effects */
  --glow-primary: 0 0 20px rgba(var(--primary-rgb-vals), 0.3);
}

Usage

.hero {
  background: var(--brand-gradient);
}

.card {
  padding: var(--card-padding);
  box-shadow: var(--glow-primary);
}

Semantic Custom Variables

Create semantic aliases for better maintainability:

:root {
  /* Surface variables */
  --surface-page: var(--bg-neutral);
  --surface-card: var(--surface-neutral);
  --surface-overlay: rgba(var(--base-black-rgb-vals), 0.5);

  /* Text variables */
  --text-body: var(--text-neutral);
  --text-heading: var(--heading-neutral);
  --text-link: var(--primary);
  --text-link-hover: var(--hover-primary);

  /* Border variables */
  --border-default: var(--border-neutral);
  --border-focus: var(--primary);

  /* Component spacing */
  --button-padding-x: var(--s4);
  --button-padding-y: var(--s2);
  --input-padding: var(--s3);
  --card-gap: var(--s6);
}

Component Tokens

Create tokens for specific components:

Button Tokens

:root {
  --btn-font-size: var(--text-sm);
  --btn-font-weight: var(--font-medium);
  --btn-padding-x: var(--s4);
  --btn-padding-y: var(--s2);
  --btn-radius: var(--radius-md);

  --btn-primary-bg: var(--primary);
  --btn-primary-text: var(--base-white);
  --btn-primary-hover: var(--hover-primary);

  --btn-secondary-bg: transparent;
  --btn-secondary-text: var(--primary);
  --btn-secondary-border: var(--border-primary);
}

.btn-primary {
  background: var(--btn-primary-bg);
  color: var(--btn-primary-text);
  padding: var(--btn-padding-y) var(--btn-padding-x);
  border-radius: var(--btn-radius);
  font-size: var(--btn-font-size);
  font-weight: var(--btn-font-weight);
}

.btn-primary:hover {
  background: var(--btn-primary-hover);
}

Card Tokens

:root {
  --card-bg: var(--surface-neutral);
  --card-border: var(--border-neutral);
  --card-radius: var(--radius-lg);
  --card-padding: var(--s6);
  --card-shadow: var(--shadow-md);
  --card-hover-shadow: var(--shadow-lg);
}

.card {
  background: var(--card-bg);
  border: 1px solid var(--card-border);
  border-radius: var(--card-radius);
  padding: var(--card-padding);
  box-shadow: var(--card-shadow);
}

.card:hover {
  box-shadow: var(--card-hover-shadow);
}

Dark Mode Variables

Create dark mode overrides:

:root {
  --surface-page: #ffffff;
  --surface-card: #f8fafc;
  --text-body: #334155;
  --text-heading: #0f172a;
}

@media (prefers-color-scheme: dark) {
  :root {
    --surface-page: #0f172a;
    --surface-card: #1e293b;
    --text-body: #94a3b8;
    --text-heading: #f8fafc;
  }
}

/* Or with class toggle */
.dark {
  --surface-page: #0f172a;
  --surface-card: #1e293b;
  --text-body: #94a3b8;
  --text-heading: #f8fafc;
}

Responsive Variables

Create responsive variable values:

:root {
  --hero-padding: var(--ss-lg);
  --grid-columns: 1;
  --sidebar-width: 100%;
}

@media (min-width: 768px) {
  :root {
    --hero-padding: var(--ss-xl);
    --grid-columns: 2;
    --sidebar-width: 280px;
  }
}

@media (min-width: 1024px) {
  :root {
    --hero-padding: var(--ss-xxl);
    --grid-columns: 3;
    --sidebar-width: 320px;
  }
}

.hero {
  padding: var(--hero-padding) 0;
}

.grid {
  grid-template-columns: repeat(var(--grid-columns), 1fr);
}

.sidebar {
  width: var(--sidebar-width);
}

Animation Variables

Create animation tokens:

:root {
  /* Durations */
  --duration-fast: 150ms;
  --duration-normal: 250ms;
  --duration-slow: 400ms;

  /* Easings */
  --ease-in: cubic-bezier(0.4, 0, 1, 1);
  --ease-out: cubic-bezier(0, 0, 0.2, 1);
  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
  --ease-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);

  /* Common transitions */
  --transition-colors: color var(--duration-fast) var(--ease-in-out),
                       background-color var(--duration-fast) var(--ease-in-out),
                       border-color var(--duration-fast) var(--ease-in-out);
  --transition-transform: transform var(--duration-normal) var(--ease-out);
  --transition-opacity: opacity var(--duration-normal) var(--ease-in-out);
}

.button {
  transition: var(--transition-colors), var(--transition-transform);
}

.button:hover {
  transform: translateY(-2px);
}

.modal {
  transition: var(--transition-opacity), var(--transition-transform);
}

Best Practices

Naming Convention

Use a consistent naming pattern:

/* Component-property pattern */
--[component]-[property]: value;

/* Examples */
--card-padding: var(--s6);
--card-radius: var(--radius-lg);
--card-shadow: var(--shadow-md);

/* State variations */
--button-bg: var(--primary);
--button-bg-hover: var(--hover-primary);
--button-bg-active: var(--active-primary);
--button-bg-disabled: var(--muted-neutral);

Reference OxyMade Variables

Build on OxyMade’s system:

/* Good - references existing scale */
--component-spacing: var(--s6);

/* Avoid - arbitrary value */
--component-spacing: 23px;

Document Your Variables

Add comments for clarity:

:root {
  /* ===== Brand Colors ===== */
  --brand-primary: #your-color;  /* Main brand color */
  --brand-secondary: #your-color; /* Supporting brand color */

  /* ===== Component Tokens ===== */
  /* Card component styling */
  --card-padding: var(--s6);
  --card-radius: var(--radius-lg);
}

Keep Variables Organized

Group related variables:

:root {
  /* Colors */
  --custom-color-1: ...;
  --custom-color-2: ...;

  /* Spacing */
  --custom-spacing-1: ...;
  --custom-spacing-2: ...;

  /* Components */
  --card-...: ...;
  --button-...: ...;
}

Using in Oxygen

After defining custom variables, use them in Oxygen:

  1. Add variables to your site’s custom CSS
  2. In Oxygen, reference with {var-custom-variable-name}
  3. Note: Custom variables won’t appear in Oxygen’s variable picker unless synced

Syncing Custom Variables

To add custom variables to Oxygen’s picker:

  1. Define in OxyMade’s custom variables section (if available)
  2. Or manually add to Oxygen’s global settings
  3. Re-sync to propagate changes