Augeo AI Docs
Augeo Design SystemTheming

Partner theming

White-label re-branding via DesignSystemTheme and ThemeProvider.

Partner theming

The public branding API is ThemeProvider: pass a DesignSystemTheme object on the existing theme prop to apply a partner or customer brand. Style through ThemeProvider, useTheme, and component props. Do not name design-system CSS custom properties in consumer source. augds- and augds: utility classes remain allowed.

Branding now goes through brandRamp, not colors.partner

Components read the v2 token layer, and ThemeProvider builds that layer from theme.brandRamp. A theme that sets only colors.partner.* re-themes nothing — and fails silently, because the variables still resolve, just to the shipped base defaults. There is no error and no warning; the product simply renders in the base purple. If your brand is not showing up, this is why.

What re-themes vs. what stays

LayerTheme pathRe-themes?Why
Partner brandbrandRamp + brandRolesYes — this is the branding APIEvery brand-colored fill, foreground, border, and focus ring resolves through the ramp
Surface / foreground / border—NoCalm neutral foundation under any brand; not runtime-themeable, it comes from the stylesheet
Status semantic—NoSuccess/warn/danger must mean the same thing under every brand, so they are deliberately brand-independent
Legacy v1 slotscolors.partner, colors.brand, colors.accent, colors.tag, colors.feedbackNo longer read by Augeo componentsStill on the theme object for useTheme(); not a consumer CSS styling path

Consumer flow

Import the stylesheets once, then pass a partner theme object.

One sheet is enough. styles.css carries the v1 layer, the v2 token layer and the Augeo brand layer together, so the single documented import covers every token a migrated component reads:

import "@kigo-digital/design-system/styles.css";

tokens-v2.css and theme-augeo.css are still published separately for the narrower case: replacing the brand layer while keeping the shared token layer.

Import order is load-bearing on that path. Both sheets declare on :root, :host, so specificity is identical and the last declaration wins — and styles.css now carries Augeo's brand layer inside it. A replacement brand sheet must be imported after styles.css, or Augeo's inlined defaults win silently:

import "@kigo-digital/design-system/styles.css";
import "./my-brand-theme.css";

Watch for a bundler hoisting CSS imports — if the order cannot be guaranteed, scope the brand overrides under a selector with higher specificity than :root, :host rather than relying on source order.

Then derive the brand ramp and hand it to ThemeProvider:

import {
  Button,
  SelectionChip,
  Tag,
  ThemeProvider,
  baseTheme,
  type DesignSystemTheme,
} from "@kigo-digital/design-system";

const johnDeereTheme: DesignSystemTheme = {
  ...baseTheme,
  // Generated by `node scripts/generate-brand-ramp.mjs "#367c2b" john-deere`.
  // The supplied color is preserved byte-identically at the step matching its
  // own lightness — here 700, not the 950 Augeo occupies.
  brandRamp: {
    50: "#eef9ec",
    100: "#def3da",
    200: "#c0e5ba",
    300: "#9bd391",
    400: "#72bb67",
    500: "#52a445",
    600: "#3b8b2e",
    700: "#367c2b",
    800: "#245e1b",
    900: "#214e1a",
    950: "#102f0c",
  },
  // Required whenever the brand color does NOT land on step 950, which is most
  // brands. Omitting this leaves `primary` on Augeo's 950 default, so the product
  // renders in a near-black tinted with the partner hue — technically themed,
  // visually unrecognizable.
  brandRoles: { primary: 700 },
};

export default function Page() {
  return (
    <ThemeProvider theme={johnDeereTheme}>
      <Button>Find a dealer</Button>
      <Tag category="trending">Trending</Tag>
      <SelectionChip selected>Tractors</SelectionChip>
    </ThemeProvider>
  );
}

Resolving a host theme with resolvePartnerTheme

An SDK that takes a theme from its host page forwards it to resolvePartnerTheme and passes the result to ThemeProvider. The SDK does not resolve the theme itself.

import { ThemeProvider, resolvePartnerTheme, type PartnerThemeInput } from "@kigo-digital/design-system";

export function Embed({ hostTheme, children }: { hostTheme?: PartnerThemeInput; children: React.ReactNode }) {
  return <ThemeProvider theme={resolvePartnerTheme(hostTheme)}>{children}</ThemeProvider>;
}
  • The host gives its brand colour as palette.primary or colors.partner.primary. palette.primary wins when the host gives both.
  • A partner primary removes Augeo's brand layer. The resolver derives the partner tokens and a full brandRamp from that primary.
  • Explicit host values win over derived values. That covers each colors.partner.* token, a complete brandRamp, and brandRoles.
  • A host that gives no primary keeps the Augeo brand. Fonts and buttonRadius still apply.
  • No input returns augeoTheme unchanged.

Only a hex primary produces a ramp. Any other CSS colour sets colors.partner.* and leaves brandRamp empty.

palette.onPrimary sets the label on the brand fill. Without it, a hex primary gets white or dark navy, whichever has more contrast. A non-hex primary gets white, so give onPrimary with it.

Consumer contract check

Add this job to a consumer pull-request workflow. paths is required; each non-empty line is one file or directory to scan:

name: Consumer contract

on:
  pull_request:

jobs:
  consumer-contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Kigo-Digital/augeo-design-system/.github/actions/consumer-contract-check@main
        with:
          paths: |
            src
            app

A failure reports each named variable and directs you to ThemeProvider, useTheme, and component props. Branding is configured by passing a DesignSystemTheme to the existing ThemeProvider theme prop, not by naming CSS variables. Use the partner theme example above.

ThemeProvider props

PropTypeDefaultNotes
themeDesignSystemThemerequiredComplete theme object. Partner color is set through this object, not by naming CSS variables.
childrenReact.ReactNoderequiredSubtree the theme applies to.
asReact.ElementType"div"Element the wrapper renders as.
classNamestring—Applied to the wrapper element.
styleReact.CSSProperties—Merged onto the wrapper. Spread last, so it overrides the default display: contents.

The wrapper is invisible to layout by default

The wrapper renders with display: contents, so it does not participate in layout. Drop a ThemeProvider anywhere in the tree without it interrupting a height, flex, or grid chain. CSS variables still inherit to children normally.

If you need the wrapper to be a real layout box, override it through style:

<ThemeProvider theme={partnerTheme} style={{ display: "flex", gap: 12 }}>
  <Button>Find a dealer</Button>
  <Tag category="trending">Trending</Tag>
</ThemeProvider>

Theme override surface

A partner theme overrides two things:

brandRamp    the eleven ramp steps (50…950)
brandRoles   which step each brand role points at, where it differs from the default

Writing the scale rather than the semantic names is what makes this work. The v2 tokens alias downward — background/brand → brand-color/primary → brand-primitive-scale/950 — so overriding the eleven steps re-points every token that resolves through the scale. Overriding only brand-color/primary would leave every other brand role on Augeo's scale.

The default role→step mapping, which brandRoles overrides selectively:

RoleDefault step
primary950
primary-readable950
primary-tint900, deprecated
primary-shade900

The tints take no step. primary-tint-1, -2 and -3 are the fill at 8%, 16% and 30%, so they follow primary. A tint key in brandRoles is deprecated and ignored.

Role assignment is a design decision, not a computation. The generator picks the step that matches your color's lightness; deciding which step should become primary is a judgment call about how the brand should read. A yellow brand wants a yellow button with dark text, not a darkened orange one with white text, and only a person looking at it can decide that.

on-primary is not themeable through the ramp — it aliases pure white, because it is a foreground sitting on a brand fill and should not follow the ramp. There is also no secondary or accent brand role; it was removed for being unthemeable in practice.

Anything else a partner needs to customize, such as a custom typeface, is the consumer's responsibility.

See the complete DesignSystemTheme reference for every available key and its Augeo default.

Reading theme values in your own components

Prefer component props and augds- / augds: utility classes. Reach for useTheme() when CSS cannot (inline SVG fills, canvas, dynamic style props from runtime data). Do not name design-system CSS custom properties in consumer source.

The useTheme() hook returns the current DesignSystemTheme from the nearest ThemeProvider. When no provider is mounted above, it returns baseTheme and never throws, so components stay safe to render in any tree.

"use client";

import { baseTheme, useTheme } from "@kigo-digital/design-system";

export function BrandMark() {
  const theme = useTheme();
  const step = theme.brandRoles?.primary ?? 600;
  const brand = theme.brandRamp?.[step] ?? baseTheme.colors.partner.primary;

  return (
    <svg width={24} height={24} viewBox="0 0 24 24" aria-hidden>
      <circle cx={12} cy={12} r={10} fill={brand} />
    </svg>
  );
}

Mount BrandMark inside <ThemeProvider theme={johnDeereTheme}> and the circle picks up John Deere green. Render it without a provider and the ramp is absent, so it falls back to the base brand from baseTheme.

Reading theme.colors.brand.DEFAULT under a partner provider would return Augeo navy, because colors.brand is Augeo's corporate identity rather than the white-label slot — a mistake worth naming, since it fails quietly and looks correct in the Augeo-default screenshot.