Writing User Macros Compatible with Dark Theme

Confluence supports dark theme across the product, and user macros created using User Macro for Confluence Cloud app are designed to inherit this behavior automatically.
That means in most cases, your user macro will already look correct in both Light and Dark modes without any extra work.

Atlassian recommends using Design Tokens (tokenized CSS variables) instead of hardcoded visual values, because tokens automatically adapt when the active theme changes.

Good news: Default user macro styles are already theme-aware

If your macro uses:

• standard HTML elements

• inherited fonts

• default text color

• default backgrounds

• AUI components

then the app will automatically apply the correct colors.

Here’s an example which requires no additional dark-theme adaptation:

When dark theme problems usually appear

Issues start only when use macro authors introduce:

• custom background colors

• custom text colors

• borders

• shadows, etc.

Example of problematic code:

<div style="background: #ffffff; color: #222; border: 1px solid #ccc;">
    Custom panel content
</div>

Important limitation for static content macros

While Atlassian Design Tokens are the recommended way to make custom styling theme-aware, please note that static content macros do not always support the full Atlassian Design System variable set.

Because static macros are rendered inside Confluence page content rather than inside a full Atlassian application runtime (iframe), availability of certain --ds-* CSS variables may vary depending on:

• Confluence version

• rendering context

• surrounding DOM inheritance

In practice, this means:

• some commonly used surface, text, border, and spacing tokens usually work well

• but some newer or more context-specific tokens may not resolve as expected

Recommended approach: Use Atlassian CSS variable-Based design tokens

Atlassian provides a full set of design tokens exposed as CSS custom properties (var(--ds-...)).

These tokens are specifically created to:

• automatically switch between light/dark values

• stay visually consistent with native Confluence UI

• support accessibility contrast requirements

• remain future-proof as Atlassian updates themes

You can browse the full token library here:

• Forge Design Tokens & Theming Guide

• All Atlassian Design Tokens

Commonly used tokens

Use case: Dark theme safe custom panel

❌ Not Recommended

<div style="
    background: #f4f5f7;
    color: #172b4d;
    border: 1px solid #dfe1e6;
    padding: 12px;
">
    $body
</div>

✅ Recommended

<div style="
    background: var(--ds-surface-raised);
    color: var(--ds-text);
    border: 1px solid var(--ds-border);
    padding: var(--ds-space-200);
    border-radius:4px;
">
    $body
</div>