---
name: slab/using-tokens-web
description: >
  Apply Slab design tokens in a React web app via CSS custom properties.
  Covers required one-time CSS imports from @companycam/slab-tokens
  (base.css, light_environment.css, dark_environment.css), CSS variable naming
  (--cc_color_*, --cc_size_*), web color categories (brand, utility, background,
  text, button, link, border, depth, label, collab), ccMargin spacing prop on
  Slab components, spacing/border/text size tokens, and depth (shadow) tokens.
  Load when writing custom styled-components, applying color or spacing outside
  a Slab component, or selecting a token value to match a design spec.
type: core
library: slab-web
library_version: '2.0.4'
sources:
  - 'CompanyCam/slab:packages/slab-tokens/src/tokens/colors/color.json'
  - 'CompanyCam/slab:packages/slab-tokens/src/tokens/sizes/size.json'
  - 'CompanyCam/slab:packages/slab-tokens/dist/css/base.css'
  - 'CompanyCam/slab:packages/slab-tokens/dist/css/light_environment.css'
  - 'CompanyCam/slab:packages/slab-web/src/lib/shared/styles.ts'
---

# Slab Web — Design Tokens

## Setup

Add three CSS imports once in your app's root stylesheet or entry file. All `--cc_*` CSS variables are undefined without them — this is an app-level setup, not per-component.

```css
/* app root stylesheet — add once */
@import '@companycam/slab-tokens/css/base.css';
@import '@companycam/slab-tokens/css/light_environment.css';
@import '@companycam/slab-tokens/css/dark_environment.css';
```

## Core Patterns

### Apply color tokens in a styled component

```tsx
import styled from 'styled-components';

const ErrorText = styled.span`
  color: var(--cc_color_utility_destroy);
`;

const Card = styled.div`
  background-color: var(--cc_color_background_2);
  border: var(--cc_size_border_width_s) solid var(--cc_color_border_default);
  border-radius: var(--cc_size_border_radius_l);
  box-shadow: 0 var(--cc_size_depth_2_y) var(--cc_size_depth_2_blur) var(--cc_color_depth_2);
`;
```

### Apply spacing via ccMargin on a Slab component

`ccMargin` accepts space-separated token names following CSS shorthand order (top right bottom left).

```tsx
import { Button } from '@companycam/slab-web';

<Button ccMargin="m">Save</Button>         // 16px all sides
<Button ccMargin="s m">Save</Button>       // 8px vertical, 16px horizontal
<Button ccMargin="xl l m s">Save</Button>  // top right bottom left
```

### Apply spacing tokens in CSS

```css
.feature-section {
  padding: var(--cc_size_spacing_l) var(--cc_size_spacing_m);
  gap: var(--cc_size_spacing_s);
}
```

### Apply text size tokens in a styled component

For typography, prefer the `Text` component. When a custom element needs a size token:

```tsx
import styled from 'styled-components';

const MetaLabel = styled.span`
  font-size: var(--cc_size_text_xs); /* 12px */
  color: var(--cc_color_text_subtle);
`;

const SectionTitle = styled.h2`
  font-size: var(--cc_size_text_xl); /* 24px */
  color: var(--cc_color_text_default);
`;
```

## Token Reference

### Color tokens (`--cc_color_*`)

| Category     | Key tokens                                                                                                                       |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `brand`      | `brand_primary` (#0967D2), `brand_secondary` (#142334), `brand_accent` (#FFD000)                                                 |
| `utility`    | `utility_destroy`, `utility_success`, `utility_caution`, `utility_info`, `utility_assigned`, `utility_add_on`, `utility_upgrade` |
| `background` | `background_1` (page default), `background_2` (sidebars/callouts), `background_3` (chips/avatars), `background_backdrop`         |
| `text`       | `text_default`, `text_subtle`, `text_nonessential`                                                                               |
| `button`     | `button_background_primary/secondary/subtle/destroy/success`, `button_text_primary/secondary/subtle/destroy/success`             |
| `link`       | `link_primary`, `link_secondary`, `link_subtle`                                                                                  |
| `border`     | `border_default`, `border_input_inactive`, `border_input_active`                                                                 |
| `depth`      | `depth_1/2/3` (shadow color); pair with `--cc_size_depth_{n}_blur` and `--cc_size_depth_{n}_y`                                   |
| `label`      | `label_green/blue/purple/navy/yellow/orange/red/light-gray/dark-gray`                                                            |
| `collab`     | `collab_purple/orange/green/blue/red/yellow/navy/plum/magenta/brown/owner`                                                       |

Note: New primitive color scales (`--cc_color_blue_500`, `--cc_color_slate_200`, etc.) exist in base.css but are not used by the Slab web component library. Use the semantic categories above. Only reach for primitives if a design explicitly specifies one.

### Spacing tokens (`--cc_size_spacing_*`)

`xxs` 2px · `xs` 4px · `s` 8px · `m` 16px · `l` 24px · `xl` 32px · `xxl` 48px

### Text size tokens (`--cc_size_text_*`)

`xxs` 10px · `xs` 12px · `s` 14px · `m` 16px · `l` 20px · `xl` 24px · `xxl` 32px · `xxxl` 42px

### Border tokens

- Radius: `--cc_size_border_radius_s/m/l/xl/xxl/pill` (2/4/8/16/24/1000px)
- Width: `--cc_size_border_width_s/m/l/xl` (1/2/4/8px)

### Depth (shadow) tokens

```css
box-shadow: 0 var(--cc_size_depth_2_y) var(--cc_size_depth_2_blur) var(--cc_color_depth_2);
/* depth 1: tooltips · depth 2: cards/popovers · depth 3: modals/floating bars */
```

## Common Mistakes

### HIGH Missing slab-tokens CSS imports — all variables undefined

Wrong:

```css
/* no CSS imports — all --cc_* variables resolve to empty string */
```

Correct:

```css
/* once in app root stylesheet */
@import '@companycam/slab-tokens/css/base.css';
@import '@companycam/slab-tokens/css/light_environment.css';
@import '@companycam/slab-tokens/css/dark_environment.css';
```

Without all three imports every `--cc_*` variable is undefined, components render unstyled, and no error is thrown. These are app-level — add once, not per component.

Source: `CompanyCam/slab:packages/slab-tokens/dist/css/`

### HIGH Constructing CSS variable names with wrong separators or structure

Wrong:

```css
color: var(--cc-color-primary); /* hyphens instead of underscores */
background: var(--cc_color_action_primary); /* "action" category doesn't exist */
border: var(--cc_color_border); /* missing subcategory */
```

Correct:

```css
color: var(--cc_color_button_background_primary);
background: var(--cc_color_background_1);
border-color: var(--cc_color_border_default);
```

All Slab CSS variables use underscores and follow the full `--cc_{type}_{category}_{subcategory}` path. A plausible-but-wrong name resolves to empty silently.

Source: `CompanyCam/slab:packages/slab-tokens/dist/css/base.css`

### HIGH Using hardcoded hex or rgb values instead of CSS variables

Wrong:

```tsx
const ErrorText = styled.span`
  color: #ef4e4e;
`;
```

Correct:

```tsx
const ErrorText = styled.span`
  color: var(--cc_color_utility_destroy);
`;
```

Hardcoded values don't respond to dark mode (light/dark env CSS files swap variable values automatically) and drift when the design system updates.

Source: `CompanyCam/slab:packages/slab-tokens/src/tokens/colors/color.json`

### MEDIUM Passing px values to ccMargin instead of token strings

Wrong:

```tsx
<Button ccMargin="16px 8px">Save</Button>
```

Correct:

```tsx
<Button ccMargin="m s">Save</Button>
```

`ccMargin` passes values through `spacingTokensToCSS()` which maps token names to CSS variable calls. Passing `16px` produces invalid CSS output silently. Valid values: `xxs xs s m l xl xxl`.

Source: `CompanyCam/slab:packages/slab-web/src/lib/shared/styles.ts`

### MEDIUM Using inline style with px instead of ccMargin or CSS variables

Wrong:

```tsx
<Button style={{ margin: '16px' }}>Save</Button>
```

Correct:

```tsx
<Button ccMargin="m">Save</Button>
```

Inline style bypasses the token system entirely and does not adapt to dark mode. Use `ccMargin` on Slab components and CSS variables in custom styled-components.

Source: `CompanyCam/slab:packages/slab-web/src/lib/shared/styles.ts`