@octopusdeploy/design-system-tokens/skills/design-system-tokens/SKILL.md

The design systems tokens. This package contains the raw tokens in their original format, and compiled to an appropriate format for consumption by the design system components.

---
name: skills/design-system-tokens
description: >
  Use when writing styling within or alongside @octopusdeploy/design-system-components. Any
  spacing, colour, typography, border, or shadow value must come from
  @octopusdeploy/design-system-tokens rather than arbitrary values. Triggers on imports from
  @octopusdeploy/design-system-tokens, or when custom CSS-in-JS (Emotion), inline styles, or
  style props are written in any codebase that uses design system components.

metadata:
  sources: []
---

# Design System Tokens

## Overview

`@octopusdeploy/design-system-tokens` provides the single source of truth for all visual values
used by the Octopus design system. This applies whether you are adding new components to the
design system itself or building bespoke components alongside it — styling must use these tokens
to stay visually consistent. **Never use hardcoded values for colour, spacing, typography, or
border radius** — always use a token instead.

Most styling should come from design system components which already apply the correct tokens
internally. Tokens are for the cases where custom styling is genuinely unavoidable.

## Token hierarchy

**Global tokens** — raw primitives (`colorScales`, `space`, `borderRadius`, `fontSize`,
`fontWeight`, `borderWidth`, etc.). Most of these are fine to use in feature and component code
and are preferable over arbitrary values. The one exception is `colorScales` — see Colour below.

**Theme tokens** — compiled from global tokens, theme-aware (light/dark). Exported as
`themeTokens`. Use these for colour and shadows.

## Spacing — always use `space`

Never write arbitrary pixel or rem values for margin, padding, gap, width, or height when a
spacing token exists. The `space` scale covers: `0, 1, 2, 4, 6, 8, 12, 16, 24, 32, 40, 48, 56,
64, 72, 80` (all in px).

```tsx
import { space } from "@octopusdeploy/design-system-tokens";

// ✅ Use space tokens
css({ padding: space[16], gap: space[8] })

// ❌ Don't use arbitrary values
css({ padding: "16px", gap: "8px" })
```

## Colour — use `themeTokens.color` for theme-aware styling

`themeTokens.color` provides colour mappings that work correctly across light and dark modes.

```tsx
import { themeTokens } from "@octopusdeploy/design-system-tokens";

// ✅ Theme-aware
css({ color: themeTokens.color.text.primary })
css({ backgroundColor: themeTokens.color.background.primary })
css({ borderColor: themeTokens.color.border.default })
```

### Generic vs component-specific theme tokens

`themeTokens.color` contains two kinds of tokens:

**Generic tokens** — broadly applicable, fine to use anywhere in feature code:
- `themeTokens.color.text.*`
- `themeTokens.color.background.*`
- `themeTokens.color.border.*`

**Component-specific semantic tokens** — tied to a specific design system component
(`themeTokens.color.button.*`, `themeTokens.color.badge.*`, `themeTokens.color.callout.*`,
`themeTokens.color.avatar.*`, etc.). These are **only for use inside design system components
themselves**. Do not use them to build custom components or style feature code. If you find
yourself reaching for a component-specific token, use the design system component instead.

```tsx
// ❌ Don't use component-specific tokens in feature code
css({ color: themeTokens.color.button.text.primary })  // use <Button> instead
css({ backgroundColor: themeTokens.color.badge.background.info })  // use <Badge> instead

// ✅ Generic tokens are fine in feature code
css({ color: themeTokens.color.text.secondary })
css({ borderColor: themeTokens.color.border.subtle })
```

### `colorScales` 

Avoid the usage of `colorScales` as these are raw hex values with no theme awareness — they do not adapt to light/dark mode.
Do not use them in feature code or custom components. The direct use of a colorScale, even when provided as part of a design
should be questioned/challenged.

```tsx
// ❌ Avoid — not theme-aware
css({ color: colorScales.navy[800] })

```

### Colour without a design spec

Do not invent colour usages. If a design does not specify which token to use for a particular
element, do not guess — ask or leave a comment flagging the decision. Colour token choices have
accessibility and theming implications that require design input.

## Typography — use `text` composite tokens

The `text` export provides composite typography tokens that set font size, weight, line height,
and family together. Prefer these over assembling typography from individual global tokens.

```tsx
import { text } from "@octopusdeploy/design-system-tokens";

// ✅ Spread into a css block
css({ ...text.body.regular.medium })

// ✅ Use the font shorthand property
css({ font: text.heading.large })
css({ font: text.body.regular.medium })

// ❌ Don't assemble from raw globals
import { fontSize, fontWeight } from "@octopusdeploy/design-system-tokens";
css({ fontSize: fontSize.medium, fontWeight: fontWeight[400] })
```

Available categories: `heading`, `body.regular`, `body.bold`, `code.regular`, `code.bold`.
Sizes: `2xLarge`, `xLarge`, `large`, `medium`, `small`, `xSmall` (not all sizes exist in every
category).

## Border radius and border width

Use `borderRadius` and `borderWidth` globals — these are straightforward to use anywhere.

```tsx
import { borderRadius, borderWidth } from "@octopusdeploy/design-system-tokens";

css({ borderRadius: borderRadius.medium, borderWidth: borderWidth[1] })
```

## Code generation checklist

After writing any styling code, verify:
- [ ] No hardcoded values for colour, spacing, typography, or border radius
- [ ] No `position` property in CSS styles
- [ ] Colour uses `themeTokens.color.*` (not raw hex or `colorScales`)
- [ ] Spacing uses `space[n]` (not `"16px"` etc.)
- [ ] Typography uses `text.*` composite tokens (not `fontSize`/`fontWeight` individually)

## Summary

| Need | Import | Notes |
|---|---|---|
| Spacing | `space` | Always — no arbitrary values |
| Generic colour | `themeTokens.color.text/background/border.*` | Fine in feature code |
| Component colour | `themeTokens.color.button/badge/callout/...` | Design system only |
| Shadows | `themeTokens.shadow` | Fine in feature code |
| Typography (composite) | `text` | Prefer over raw globals |
| Border radius | `borderRadius` | Fine anywhere |
| Border width | `borderWidth` | Fine anywhere |
| Raw colour scales | `colorScales` | Avoid — only when design specifies theme-invariant |