Theming

Two-tier theming architecture. Tier 1 (Branded) swaps accent and surfaces. Tier 2 (Bespoke) is a full personality shift. Use the theme switcher in the sidebar to see both tiers applied live.

Architecture

BASE TOKENS tokens/base.css Raw values. Never used directly in components.
SEMANTIC TOKENS tokens/semantic.css Role-based aliases. This is what themes override.
COMPONENT TOKENS tokens/components.css Component-scoped. Reference semantic tokens.

Tier 1: Branded

Client dashboards, whitelabel products, internal tools with client branding. The result still feels like an aiaiai product, but with the client's color identity.

WHAT CHANGES
  • Accent color (orange to client brand)
  • Surface tint direction (warm/cool)
  • Border colors (follow surface tint)
  • Text colors (follow tint direction)
  • Overlay tint
WHAT STAYS
  • Typography (Instrument Sans + Berkeley Mono)
  • Spacing scale (8px grid)
  • Motion language (snappy, functional)
  • Radius scale (sharp, precise)
  • Elevation model (borders over shadows)
  • Component sizing
<20 TOKENS TO OVERRIDE
EXAMPLE: VERDANT FINANCE

A fintech client that uses teal instead of orange. Cooler surface tint. Switch to "Branded (Tier 1)" in the sidebar to see this live.

[data-theme="branded-example"] {
  /* Accent: teal instead of orange */
  --color-accent: #0d9488;
  --color-accent-hover: #0f766e;
  --color-accent-subtle: #f0fdfa;

  /* Surface: cooler tint direction */
  --color-surface: #f8faf9;
  --color-surface-secondary: #f0f4f2;
  --color-surface-tertiary: #e4ebe7;

  /* Borders: slightly cooler */
  --color-border: #d4ddd8;
  --color-border-strong: #a8b8b0;

  /* Text: still warm, slightly cooled */
  --color-text: #1a2c25;
  --color-text-secondary: #4a6358;
  --color-text-muted: #7a9488;

  /* Total: 14 tokens */
}

Tier 2: Bespoke

Client-facing consumer products where aiaiai builds something that does not look like aiaiai. Full personality shift.

WHAT CHANGES
  • Full color palette
  • Typography pairing (different fonts)
  • Surface materials (texture vs. flat)
  • Motion personality (snappy vs. bouncy)
  • Elevation style (shadows vs. borders)
  • Radius language (sharp vs. rounded)
  • Component sizing and feel
WHAT STAYS
  • Spacing scale (8px grid, non-negotiable)
  • Grid structure and breakpoints
  • Accessibility minimums (contrast, touch targets)
  • Token naming convention
  • Semantic color roles
40-80 TOKENS TO OVERRIDE
EXAMPLE: SPROUT (CHILDREN'S APP)

A fictional children's learning app. Purple accent, rounded corners, bouncy motion, shadow-based elevation. Switch to "Bespoke (Tier 2)" in the sidebar to see this live.

[data-theme="bespoke-example"] {
  /* Full color palette override */
  --color-accent: #7c3aed;
  --color-surface: #fffdf7;
  --color-text: #2d2006;

  /* Different fonts entirely */
  --font-sans: "Nunito", "Quicksand", sans-serif;
  --font-mono: "Space Mono", ui-monospace, monospace;

  /* Larger type for children */
  --type-body-size: var(--raw-font-size-18);

  /* Shadows instead of borders */
  --elevation-border: none;
  --elevation-raised: 0 2px 8px rgba(60,40,10,0.1), ...;

  /* Rounded, friendly radius */
  --radius-sm: 8px;
  --radius-md: 12px;
  --radius-lg: 16px;

  /* Bouncy easing */
  --easing-default: cubic-bezier(0.34, 1.56, 0.64, 1);

  /* Total: ~54 tokens */
}

Creating a Theme

1

Choose your tier

Tier 1 if the product should still feel like aiaiai with different colors. Tier 2 if it should be a completely different product.

2

Create a theme file

Copy the appropriate example file and override the tokens.

tokens/themes/my-client.css
3

Scope with data-theme attribute

All overrides go inside a [data-theme="my-client"] selector.

<html data-theme="my-client">
  <!-- Everything inside uses the theme -->
</html>
4

Import in your project

Import the base tokens, then your theme file.

@import 'aiaiai-design-system/tokens/semantic.css';
@import 'aiaiai-design-system/tokens/components.css';
@import 'aiaiai-design-system/tokens/themes/my-client.css';

LIVE DEMO

Use the theme switcher in the sidebar to toggle between the three themes. Every page on this site updates live — foundations, components, and this page itself. The theme switcher demonstrates that the token architecture works as designed: swap the theme, and every component adapts without any code changes.