Table of Contents

Cratis token reference

The --cratis-* CSS variable layer is the Cratis-scoped tint surface every Cratis wrapper reads from. Each token resolves the PrimeReact v11 design token first (@primeuix/themes, e.g. --p-content-border-color), falling back to the legacy v10 theme variable (e.g. --surface-border) via tokens.css. Loading any PrimeReact theme — v10 or v11 — therefore gives every Cratis surface the right color without any further work, and the same build keeps working across a PrimeReact 10 → 11 upgrade.

This indirection is deliberate: it is the single seam that insulates your code (and your consumers' --cratis-* overrides) from PrimeReact's token system changing underneath you.

You override --cratis-* tokens when you want just Cratis-scoped surfaces (validation error text, FormElement addon, breadcrumb borders, …) tinted independently of PrimeReact widgets. To repaint PrimeReact widgets themselves, override the PrimeReact variables directly — see the custom palette setup.

Loading the tokens

The token layer ships at two import paths:

import '@cratis/components/styles';

The recommended one — ships the Tailwind utility classes used inside the package plus the --cratis-* token declarations as a single stylesheet.

import '@cratis/components/tokens';

Just the token declarations, with no Tailwind utilities. Use this if you bring your own utility CSS solution (or use Tailwind with custom classnames that don't match what the package ships).

Token catalogue

Each token resolves the PrimeReact v11 design token first, then the v10 legacy variable (e.g. --cratis-surface-border → var(--p-content-border-color, var(--surface-border))). v11 is not a 1:1 rename of v10 — where v11's vocabulary has no direct equivalent for a v10 concept (surface-ground, surface-section, surface-overlay, the composite focus-ring), the closest durable v11 semantic token is used (see the inline notes in tokens.css). Set the --cratis-* token to override regardless of which PrimeReact version is loaded.

Surfaces

Token Cratis surfaces tinted by it
--cratis-surface-0 Reserved for any Cratis-scoped surface that maps to PrimeReact's --surface-0.
--cratis-surface-100 FormElement addon background.
--cratis-surface-ground PivotViewer canvas and panel backgrounds.
--cratis-surface-section PivotViewer panel section backgrounds.
--cratis-surface-card Backgrounds of the ObjectContentEditor snapshot card and similar panels; PivotViewer card gradients.
--cratis-surface-overlay Overlay backgrounds inside Cratis wrappers.
--cratis-surface-hover Hover state on row alternation inside ObjectContentEditor.
--cratis-surface-border FormElement addon border, ObjectNavigationalBar bottom border, SchemaEditor bottom border, table/paginator borders inside DataTableForQuery / DataTableForObservableQuery.

Text

Token Cratis surfaces tinted by it
--cratis-text-color Default body text inside Cratis wrappers.
--cratis-text-color-secondary ObjectContentEditor label column, ObjectNavigationalBar breadcrumbs, SchemaEditor secondary labels.

Brand

Token Cratis surfaces tinted by it
--cratis-primary-color ObjectContentEditor navigation links into nested objects/arrays, default brand accent.
--cratis-primary-color-text Foreground used on top of --cratis-primary-color backgrounds (e.g. CommandStepper step number color).
--cratis-primary-300 PivotViewer loading spinner ring.
--cratis-primary-400 PivotViewer loading spinner ring.
--cratis-primary-500 PivotViewer loading spinner ring and card gradient.
--cratis-primary-600 PivotViewer loading spinner ring.

Selection / highlight

Token Cratis surfaces tinted by it
--cratis-highlight-bg Background of timestamp/highlight chips inside ObjectContentEditor.
--cratis-highlight-text-color Text on top of --cratis-highlight-bg.

Semantic accents

Token Cratis surfaces tinted by it
--cratis-green-500 CommandStepper visited-step indicator.
--cratis-orange-500 Reserved for warning accents.
--cratis-red-500 Inline validation error text (replaces PrimeReact's .p-error styling), CommandStepper error-step indicator, error border tint inside ObjectContentEditor.

Geometry

Token Cratis surfaces tinted by it
--cratis-border-radius Border radius on FormElement addon and any Cratis surface that mirrors PrimeReact's --border-radius.

Effects

Token Cratis surfaces tinted by it
--cratis-focus-ring Focus-ring box-shadow on interactive PivotViewer elements.
--cratis-maskbg PivotViewer modal mask background.

Overriding tokens

Apply on :root for an app-wide override:

:root {
    --cratis-red-500: #f97316;
    --cratis-border-radius: 12px;
}

…or on an ancestor scope for a region-specific look:

.brand-region {
    --cratis-surface-border: theme('colors.violet.500');
    --cratis-text-color-secondary: theme('colors.violet.300');
}

<div className="brand-region">
    <ObjectNavigationalBar navigationPath={path} onNavigate={…} />
</div>

Cratis tokens cascade like any other CSS variable, so any selector that increases specificity over :root wins.

With TailwindCSS

Tailwind's @layer base is the idiomatic spot — declare tokens once and let Tailwind handle cascade and dark mode:

@import "tailwindcss";
@import "@cratis/components/tokens";

@layer base {
    :root {
        --cratis-surface-border: theme('colors.slate.700');
        --cratis-text-color:     theme('colors.slate.50');
        --cratis-red-500:        theme('colors.red.500');
    }

    .dark {
        --cratis-surface-border: theme('colors.slate.600');
        --cratis-text-color:     theme('colors.slate.100');
    }
}

Relationship to PrimeReact variables

The Cratis token layer is additive on top of PrimeReact's theme system, not a replacement for it. The cascade in tokens.css resolves the v11 token first, then the v10 legacy variable:

:root {
    /* v11 (@primeuix/themes) first, v10 legacy fallback */
    --cratis-surface-card: var(--p-content-background, var(--surface-card));
    --cratis-text-color:   var(--p-text-color, var(--text-color));
    /* … */
}

That means:

  • Repaint PrimeReact itself — on v11 customize the preset (definePreset / --p-* tokens), on v10 override the legacy --surface-* / --text-color variables — and both PrimeReact widgets and Cratis surfaces follow.
  • Override --cratis-surface-card (Cratis) → only Cratis surfaces follow; PrimeReact widgets keep their existing color, on either version.

Use the PrimeReact token when you want a whole-UI repaint. Use the Cratis token when you want a Cratis-specific accent that differs from PrimeReact widgets.

See also