Aura Design System Theming Overview

The Aura Design System is built on a flexible and scalable theming architecture using CSS root variables. This approach ensures consistency, maintainability, and easy customization across your application. The theming system is designed to adapt seamlessly to different brand identities.

When you run pnpm dlx @aura-design/cli init, the command automatically sets up your theming infrastructure:

style.json: Defines style tokens and variables
theme.json: Contains base theme configurations
app/globals.css: Main stylesheet where all theme customizations should be made

Theme Structure

Aura’s theming system is structured around CSS root variables and Tailwind's utility-first approach. Here's how it works:

css

@import "tailwindcss";

@custom-variant dark (&:is(.dark *));

:root {
  --background: #fcfcff;
  --foreground: #2c2c3b;
  --aura-loader: var(--primary);
  --radius: 13px;
  --accent-1: #fcfdff;
  --accent-2: #f3f9ff;
  --accent-3: #e8f3ff;
  --accent-4: #d8eaff;
  --accent-5: #c9e0ff;
  --accent-6: #b5d3ff;
  --accent-7: #9abfff;
  --accent-8: #73a3ff;
  --accent-9: #007;
  --accent-10: #042692;
  --accent-11: #2458de;
  --accent-12: #011d8a;
  --accent-a1: #0055ff03;
  --accent-a2: #0080ff0c;
  --accent-a3: #007aff17;
  --accent-a4: #0076ff27;
  --accent-a5: #006dff36;
  --accent-a6: #0168ff4a;
  --accent-a7: #005eff65;
  --accent-a8: #0058ff8c;
  --accent-a9: #000077;
  --accent-a10: #002390fb;
  --accent-a11: #003dd9db;
  --accent-a12: #001c8afe;
  --accent-contrast: #fff;
  --accent-surface: #f0f8ffcc;
  --accent-indicator: #007;
  --accent-track: #007;
  --gray-1: #fcfcff;
  --gray-2: #f9f9fe;
  --gray-3: #efeff8;
  --gray-4: #e7e7f3;
  --gray-5: #dfdfee;
  --gray-6: #d8d8e9;
  --gray-7: #cdcde1;
  --gray-8: #b9b9d2;
  --gray-9: #000;
  --gray-10: #2c2c3b;
  --gray-11: #626276;
  --gray-12: #1f1f2c;
  --gray-a1: #0000ff03;
  --gray-a2: #0000d506;
  --gray-a3: #00009010;
  --gray-a4: #00008018;
  --gray-a5: #00007820;
  --gray-a6: #00007027;
  --gray-a7: #00006632;
  --gray-a8: #00005c46;
  --gray-a9: #000000;
  --gray-a10: #000012d3;
  --gray-a11: #0000219d;
  --gray-a12: #00000fe0;
  --gray-contrast: #FFFFFF;
  --gray-surface: #ffffffcc;
  --gray-indicator: #8b8ba4;
  --gray-track: #8b8ba4;
  --primary: var(--accent-9);
  --primary-foreground: var(--accent-contrast);
  --secundary: var(--accent-8);
  --secundary-foreground: var(--accent-contrast);
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --font-sans: Inter, sans-serif;
  --font-mono: var(--font-geist-mono);
  --spacing: 13px;
  --info: #e8ebfe;
  --info-contrast: #0927ec;
  --success: #e8fef7;
  --success-contrast: #045d3c;
  --danger: #feefe8;
  --danger-contrast: #8e3106;
  --warning: #fefbe8;
  --warning-contrast: #5d5104;
  --radius-sm: calc(var(--spacing) * 0.5);
  --radius-md: calc(var(--spacing) * 1);
  --radius-lg: calc(var(--spacing) * 1.5);
  --radius-xl: calc(var(--spacing) * 2);
  --aura-loader: var(--aura-loader);
  --color-warning-contrast: var(--warning-contrast);
  --color-warning: var(--warning);
  --color-danger-contrast: var(--danger-contrast);
  --color-danger: var(--danger);
  --color-success-contrast: var(--success-contrast);
  --color-success: var(--success);
  --color-info-contrast: var(--info-contrast);
  --color-info: var(--info);
  --secundary-foreground: var(--secundary-foreground);
  --secundary: var(--secundary);
  --primary-foreground: var(--primary-foreground);
  --primary: var(--primary);
  --color-gray-track: var(--gray-track);
  --color-gray-indicator: var(--gray-indicator);
  --color-gray-surface: var(--gray-surface);
  --color-gray-contrast: var(--gray-contrast);
  --color-gray-a12: var(--gray-a12);
  --color-gray-a11: var(--gray-a11);
  --color-gray-a10: var(--gray-a10);
  --color-gray-a9: var(--gray-a9);
  --color-gray-a8: var(--gray-a8);
  --color-gray-a7: var(--gray-a7);
  --color-gray-a6: var(--gray-a6);
  --color-gray-a5: var(--gray-a5);
  --color-gray-a4: var(--gray-a4);
  --color-gray-a3: var(--gray-a3);
  --color-gray-a2: var(--gray-a2);
  --color-gray-a1: var(--gray-a1);
  --color-gray-12: var(--gray-12);
  --color-gray-11: var(--gray-11);
  --color-gray-10: var(--gray-10);
  --color-gray-9: var(--gray-9);
  --color-gray-8: var(--gray-8);
  --color-gray-7: var(--gray-7);
  --color-gray-6: var(--gray-6);
  --color-gray-5: var(--gray-5);
  --color-gray-4: var(--gray-4);
  --color-gray-3: var(--gray-3);
  --color-gray-2: var(--gray-2);
  --color-gray-1: var(--gray-1);
  --color-accent-track: var(--accent-track);
  --color-accent-indicator: var(--accent-indicator);
  --color-accent-surface: var(--accent-surface);
  --color-accent-contrast: var(--accent-contrast);
  --color-accent-a12: var(--accent-a12);
  --color-accent-a11: var(--accent-a11);
  --color-accent-a10: var(--accent-a10);
  --color-accent-a9: var(--accent-a9);
  --color-accent-a8: var(--accent-a8);
  --color-accent-a7: var(--accent-a7);
  --color-accent-a6: var(--accent-a6);
  --color-accent-a5: var(--accent-a5);
  --color-accent-a4: var(--accent-a4);
  --color-accent-a3: var(--accent-a3);
  --color-accent-a2: var(--accent-a2);
  --color-accent-a1: var(--accent-a1);
  --color-accent-12: var(--accent-12);
  --color-accent-11: var(--accent-11);
  --color-accent-10: var(--accent-10);
  --color-accent-9: var(--accent-9);
  --color-accent-8: var(--accent-8);
  --color-accent-7: var(--accent-7);
  --color-accent-6: var(--accent-6);
  --color-accent-5: var(--accent-5);
  --color-accent-4: var(--accent-4);
  --color-accent-3: var(--accent-3);
  --color-accent-2: var(--accent-2);
  --color-accent-1: var(--accent-1);
}

.dark {
  --background: #2c2c3b;
  --foreground: #fcfcff;
  --gray-1: #2c2c3b;
  --gray-2: #313140;
  --gray-3: #3b3b4a;
  --gray-4: #434352;
  --gray-5: #4b4b5a;
  --gray-6: #535362;
  --gray-7: #60606f;
  --gray-8: #747483;
  --gray-9: #fcfcff;
  --gray-10: #d8d8e9;
  --gray-11: #b9b9d2;
  --gray-12: #efeff8;
  --gray-a1: #00000003;
  --gray-a2: #00000006;
  --gray-a3: #00000010;
  --gray-a4: #00000018;
  --gray-a5: #00000020;
  --gray-a6: #00000027;
  --gray-a7: #00000032;
  --gray-a8: #00000046;
  --gray-a9: #ffffff;
  --gray-a10: #ffffffd3;
  --gray-a11: #ffffff9d;
  --gray-a12: #ffffffe0;
  --accent-contrast: #fff;
  --accent-surface: #f0f8ffcc;
  --accent-indicator: #007;
  --accent-track: #007;
}

@layer base {
@import "@aura-design/system/main.css";

@import './styles/accordion.css';
html {
    font-size: 17px;
}
}

@layer components {
  .nprogress {
    pointer-events: none;
    z-index: 99999;
  }
  .nprogress .bar {
    background: var(--aura-loader);
    position: fixed;
    z-index: 99999;
    top: 0;
    left: 0;
    width: 100%;
    height: 4px;
  }
}

Customizing the Theme

To customize the theme, override the default CSS variables in your styles:

css

...
    --font-sans:'Geist', 'Geist Fallback';
    --aura-accents-primary: #0071e3;
    --aura-button-hover: #0076DF;
...

Legacy Tokens

The @aura-design/system/main.css includes legacy token variables that you can override. While there are many variables available, for most use cases, you'll only need to modify a few key ones:

Commonly Modified Variables

css

:root {
    /* Font Configuration */
    --font-sans: 'Your-Font', -apple-system, BlinkMacSystemFont, sans-serif;
    
    /* Button Styling */
    --aura-button-radius: 6.5px;
    --aura-button-hover: #323232;
    
    /* Input Styling */
    --aura-input-radius: 6.5px;
    --aura-input-bg: #f0f0f7;
    --aura-input-placeholder-color: #33333380;
}

Other Available Legacy Tokens

While these additional tokens are available in main.css, they typically don't need modification for most applications:

css

:root {
    --aura: 13px;
    --aura-font-stack: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
    --aura-font-quotes: serif;
    --aura-snow: #fafafa;
    --aura-purple: #e8ebfe;
    --aura-white: #fff;
    --aura-black: #333;
    --aura-orange: #feefe8;
    --aura-orange-rose: #fee8ef;
    --aura-pink: #fee8fc;
    --aura-pink-purple: #f3e8fe;
    --aura-blue: #e8f7fe;
    --aura-teal-green: #e8fef7;
    --aura-green: #e8feea;
    --aura-lemon-green: #f3fee8;
    --aura-yellow: #fefbe8;
    --aura-cold-grey: #e8e7ed;
    --aura-grey: #f6f7f9;
    --aura-bg: var(--aura-white);
    --aura-text-primary: #030303;
    --aura-text-primary-inverse: #fff;
    --aura-accents-3: #dadaeb;
    --aura-accents-2: #e6e6f2;
    --aura-accents-1: #ededf5;
    --aura-accents-0: #fafafa;
    --aura-module: var(--aura-accents-0);
    --aura-accents-primary: var(--aura-black);
    --aura-accents-secondary: #0882ba;
    --aura-accents-success: #045d3c;
    --aura-accents-success-bg: var(--aura-teal-green);
    --aura-accents-info: #0927ec;
    --aura-accents-info-bg: var(--aura-purple);
    --aura-accents-warning: #5d5104;
    --aura-accents-warning-bg: var(--aura-yellow);
    --aura-accents-danger: #8e3106;
    --aura-accents-danger-bg: var(--aura-orange);
    --aura-input-radius: 6.5px;
    --aura-button-radius: 6.5px;
    --aura-input-bg: #f0f0f7;
    --aura-input-placeholder-color: #33333380;
    --aura-radius: 13px;
    --aura-opacity: .5;
    --aura-outline: #0927ec solid 2px;
    --aura-button-hover: #323232;
    --aura-link: var(--aura-text-primary);
    --aura-link-hover: var(--aura-accents-1);
    --aura-selector: #d1fdef;
    --aura-loader: #d1fdef;
    --aura-skeleton-start: #c2cfd6;
    --aura-skeleton-end: #f0f3f5;
}

Override these variables in your globals.css file only when you need to customize specific elements of your application's design.

Menu

Aura Design System Theming Overview

Theme Structure

Customizing the Theme

Legacy Tokens

Other Available Legacy Tokens