Tokens

Tokens are CSS variables named --cs-*. Clawscale's styles read them, so one override restyles every component that uses the token.

Usage#

CSS#

@clawscale/react/styles.css declares every token of the default theme, for both color schemes. A theme stylesheet in @clawscale/react/themes/ sets its own values. Read them with var().

.queue-panel {
  background: var(--cs-color-surface);
  border: 1px solid var(--cs-color-border);
  border-radius: var(--cs-radius-lg);
  padding: var(--cs-space-4);
}

Elements styled with tokens follow the theme and the color scheme. Press Shift + T or Shift + D to switch them and watch this panel.

const runs = [
  { pipeline: "orders-daily", region: "us-east-1", status: "Succeeded", failed: false },
  { pipeline: "events-hourly", region: "eu-west-1", status: "Failed", failed: true },
  { pipeline: "billing-sync", region: "ap-south-1", status: "Succeeded", failed: false },
];

const panel = {
  background: "var(--cs-color-surface)",
  border: "1px solid var(--cs-color-border)",
  borderRadius: "var(--cs-radius-lg)",
  boxShadow: "var(--cs-shadow-1)",
  padding: "var(--cs-space-1) 0",
  width: 340,
};

const row = { display: "flex", gap: "var(--cs-space-3)", padding: "var(--cs-space-2) var(--cs-space-4)" };

export default function TokensCustomElement() {
  return (
    <div style={panel}>
      {runs.map((run) => (
        <div key={run.pipeline} style={row}>
          <span style={{ flex: 1, fontWeight: "var(--cs-font-weight-medium)" }}>{run.pipeline}</span>
          <span style={{ color: "var(--cs-color-text-muted)" }}>{run.region}</span>
          <span style={{ color: run.failed ? "var(--cs-color-danger-text)" : "var(--cs-color-success-text)" }}>
            {run.status}
          </span>
        </div>
      ))}
    </div>
  );
}

JavaScript#

Install @clawscale/tokens to read the values in code, for example for a canvas chart.

npm install @clawscale/tokens

import { dark, light, shared, themes } from "@clawscale/tokens";

light.color.surface; // "#FFFFFF"
dark.color.surface; // "#16171B"
shared.radius.md; // "6px"
themes.default.dark.color.surface; // the same value as dark.color.surface

light, dark and shared are the default theme. themes holds every theme, each with shared, light, dark and sequential. light and dark hold color, shadow and chart. shared holds the groups that do not change with the color scheme. chartPalettes and sequentialBlue hold chart colors. themeVariables(theme, colorScheme) and sharedVariables(theme) return the values keyed by variable name, such as "--cs-radius-md".

Without Clawscale styles#

@clawscale/tokens/tokens.css declares the default theme's variables alone, outside any cascade layer. The dark values apply under [data-cs-color-scheme="dark"]. A theme other than the default ships @clawscale/tokens/themes/<name>.css, which applies under [data-cs-theme="<name>"]. Use them on pages that do not load @clawscale/react/styles.css. @clawscale/tokens/tokens.json holds the same values for other tools.

@import "@clawscale/tokens/tokens.css";

Override a token#

Set the variable in your own CSS. Unlayered CSS beats both Clawscale layers, so you never need !important.

:root {
  --cs-radius-md: 4px;
  --cs-color-primary-text-light: #0b6b5c;
  --cs-color-primary-text-dark: #4fd1b8;
}

Color, shadow and chart tokens have a light and a dark value, such as --cs-color-primary-text-light and --cs-color-primary-text-dark. Set both, and each color scheme picks its own. Theming covers brand colors and scoped overrides.

The tables below list the default theme.

Reference#

Color#

Surfaces, borders, text, controls and intents. Colors shows them as swatches.

Shadow#

0 to 4 are elevation levels. control sits under buttons and inputs.

Chart#

Slots 1 to 8 are the categorical palette, in fixed order. grid and axis draw chart chrome. The status colors are the same in every theme and color scheme.

The sequential ramp shows magnitude, such as heatmap cells. The lightest step means near zero. It is the same in both color schemes.

Font#

Font stacks. @clawscale/react/fonts.css loads the first family of each.

Font size#

The type scale. Body text uses md.

Font weight#

Line height#

Radius#

Space#

A 4px grid. Use it for padding, margins and gaps.

Corner#

The CSS corner-shape of rounded corners: round, or bevel to cut them where the browser supports it.

Label#

How short labels look: buttons, tabs, column headers and section titles. Text that shows data never takes these.

Control height#

The heights of Blueprint's small, medium and large buttons and inputs. Use them to size your own controls to match.

Duration#

Ease#