#Theming

Two CSS custom properties decide how a character is painted; everything else is a token you can override.

#The variables that draw a character

A character's colours come down to a few CSS custom properties.

The component sets the first few for you, from the engine's getInkVars(color). --aora-bg-base is the one you may need to change.

#Light and dark

The ink is written as a light-dark() pair:

--aora-fg: light-dark(#2a92fe, #0e74e0);

This is why the engine never subscribes to a theme change. The value is written once, and the browser re-resolves it when color-scheme flips. A thousand characters re-theme with no JavaScript, no re-render, and no flash.

Every colour token is a light-dark() pair, and the page picks the half with color-scheme. That is the only dark-mode mechanism: there are no per-theme copies of the tokens. These selectors pin the scheme on any element, so one subtree can differ from the rest of the page:

.dark,
[data-theme='dark'],
.rp-dark {
  color-scheme: dark;
}
.light,
[data-theme='light'] {
  color-scheme: light;
}

Several class names are supported because application shells and documentation frameworks disagree about which to use.

#Eye cut-outs

The default cute face is painted white and does not depend on the background. The eyes of the eyes and line faces are holes: filled with --aora-bg and clipped to the body, so they read as transparent on any surface, and so is the cute face of the black ink. That only holds while --aora-bg-base matches what is actually behind the character.

Override it on any ancestor and the whole subtree follows:

import { CharacterMark } from '@aora-bot/react';

const surfaces = ['#0b1220', '#2b1a3d', '#12281f'];

export default function Demo() {
  return (
    <div className="site-demo">
      {surfaces.map((bg) => (
        <div
          key={bg}
          style={{
            padding: 18,
            borderRadius: 14,
            background: bg,
            ['--aora-bg-base' as string]: bg,
          }}
        >
          <CharacterMark shape="tofu" color="yellow" face="eyes" sizePx={72} />
        </div>
      ))}
    </div>
  );
}

If you need the eyes to be a solid colour rather than a hole, pass eyeColor.

#Cascade layers

The stylesheet puts its rules in three layers, from lowest to highest priority: aora.tokens, aora.base and aora.components.

One consequence is worth knowing. Any rule you write outside a layer beats every rule inside one, regardless of specificity — so overriding a component style never needs !important.

/* Wins, despite being a single class against a single class. */
.aora-badge {
  border-radius: 4px;
}

#Tokens

Click any token to copy its name.

#Palette

The inks are data, not CSS. Each carries three layers, because a 20px picker chip and a large filled silhouette have opposite requirements: the chip needs to be told apart from its neighbours, the body needs to stay legible on both a white and a near-black page.

import { COLOR_SWATCHES, getSwatchHex, getInkColor } from '@aora-bot/react';

export default function Demo() {
  return (
    <table>
      <thead>
        <tr>
          <th>id</th>
          <th>chip</th>
          <th>ink (light)</th>
          <th>ink (dark)</th>
        </tr>
      </thead>
      <tbody>
        {COLOR_SWATCHES.map((s) => (
          <tr key={s.id}>
            <td>
              <code>{s.id}</code>
            </td>
            <td>
              <code>{getSwatchHex(s.id)}</code>
            </td>
            <td>
              <code>{getInkColor(s.id, 'light')}</code>
            </td>
            <td>
              <code>{getInkColor(s.id, 'dark')}</code>
            </td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

black is the one special case: its dark-mode ink is white, so the neutral character is always the one with the most contrast whichever way the page is themed.

#Next

• Custom shapes — register a generator of your own
• Palette — every hue in three layers
• Rendering structure — one SVG, every attribute written by hand