Skip to content
dbx tools

@dbx-tools/ui-branding

Portable dbx tools brand assets and React/browser bindings for a validated BrandContext from @dbx-tools/shared-core.

Key features:

  • Theme-aware dbx tools icon and logo assets as SVG package exports and data URLs.
  • BrandProvider, BrandIcon, and BrandLogo React bindings.
  • Framework-agnostic CSS variable and document metadata helpers.
  • No duplicated hand-maintained artwork: package assets are generated from the root branding source files.

Why Use This Over Native AppKit

Section titled “Why Use This Over Native AppKit”

Use AppKit’s own theming when its default palette and tokens are enough. Use this package when one portable BrandContext must drive dbx-tools UI, AppKit semantic tokens, logos, favicons, document metadata, and non-DOM surfaces such as email or chart configuration.

React

Section titled “React”
import { BrandIcon, BrandLogo, BrandProvider } from "@dbx-tools/ui-branding/react";


<BrandProvider applyToDocument>
  <BrandIcon width={32} height={32} />
  <BrandLogo width={240} />
</BrandProvider>;

Pass parsed YAML/JSON data through context to use another brand. Missing fields receive the dbx tools defaults defined by the shared Zod schema.

Browser Helpers

Section titled “Browser Helpers”
import { applyBrandContext } from "@dbx-tools/ui-branding/browser";
import { brand } from "@dbx-tools/shared-core";


applyBrandContext(brand.parseBrandContext(input));

Import @dbx-tools/ui-branding/styles.css once to expose the default CSS custom properties. applyBrandContext() updates those properties and can set the page title and favicon.

Theming the UI (the [data-brand] token bridge)

Section titled “Theming the UI (the [data-brand] token bridge)”

The dbx-tools UI components style off AppKit’s shadcn semantic tokens (--primary, --ring, --sidebar-primary, --font-sans, …), not the --brand-color-* variables directly. brand-bridge.css connects the two: it remaps those AppKit tokens onto the brand variables, scoped to :root[data-brand].

It is imported (inert) through @dbx-tools/ui-appkit/styles.css — the shared UI base every feature UI package depends on — so every dbx-tools UI component carries the bridge automatically. It stays inert until a brand is applied: applyBrandContext() (and therefore <BrandProvider applyToDocument>) sets the data-brand attribute, which is what activates the remap. With no data-brand, default AppKit renders untouched.

// Theme the whole app: sets brand vars + data-brand + title/favicon.
<BrandProvider applyToDocument>
  <App />
</BrandProvider>

The bridge is identity-only (primary/accent/ring/sidebar-primary + fonts). It intentionally does not remap neutrals (--background/--foreground/--muted/ --border) because a BrandContext carries a single light palette — remapping neutrals would disable dark mode. Add new semantic tokens to re-skin in brand-bridge.css.

Assets

Section titled “Assets”
import { dbxToolsAssetDataUrls } from "@dbx-tools/ui-branding/assets";

Static SVG files are also exported from @dbx-tools/ui-branding/assets/icon-light.svg, icon-dark.svg, logo-light.svg, and logo-dark.svg.

Modules

Section titled “Modules”
  • ./react - provider, hook, and theme-aware icon/logo components.
  • ./browser - CSS token, metadata, and built-in asset resolution helpers.
  • ./assets - generated SVG strings and data URLs.
  • ./assets/*.svg - static package asset files.
  • ./styles.css - default brand CSS custom properties.
  • ./brand-bridge.css - :root[data-brand]-scoped remap of AppKit semantic tokens onto the brand variables. Imported via ui-appkit/styles.css; inert until applyBrandContext() sets data-brand.