import { Meta } from '@storybook/addon-docs/blocks';

import {
    ActionChip,
    BorderChip,
    ColorChip,
    MotionDemo,
    RadiusChip,
    ShadowChip,
    SizingBar,
    SpacingGap,
    TypeSample,
} from './components/TokenPreviews';

<Meta title="Design tokens/Overview" summary="How to use the Design System's design tokens." />

# Design tokens

Design tokens are named values — colors, spacing, radii, typography — shared by every Design
System component. Each token resolves to a CSS variable (eg. `var(--12345)`), and the actual value
depends on the active theme and color scheme, so UI built on tokens adapts automatically.

Prefer **semantic tokens** — tokens named after a role, like `color.text.primary` or
`action.variant.primary.bgColor` — over raw values or palette entries. Code that describes the
role it plays stays correct when the underlying values change.

Use the [Token Explorer](/docs/design-tokens-token-explorer--docs) to search all tokens by name,
id, or value (make sure you have the correct theme selected).

## Semantic vocabulary

Semantic tokens are grouped by the role they play in the UI. This section lists the groups you
will reach for most often — what each one is for and which roles it contains. Component-scoped
groups (`badge.*`, `input.*`, `avatar.*`, …) are not listed here; find them in the
[Token Explorer](/docs/design-tokens-token-explorer--docs).

### Text colors

`color.text.*` colors copy. `primary`, `secondary`, and `tertiary` step down in emphasis.

| Token                    | Use for                                            |                                              |
| ------------------------ | -------------------------------------------------- | -------------------------------------------- |
| `color.text.primary`     | Headings and body copy — the default               | <ColorChip token="color.text.primary" />     |
| `color.text.secondary`   | Supporting copy: subtitles, descriptions           | <ColorChip token="color.text.secondary" />   |
| `color.text.tertiary`    | De-emphasized copy: captions, metadata, timestamps | <ColorChip token="color.text.tertiary" />    |
| `color.text.placeholder` | Placeholder text inside form fields                | <ColorChip token="color.text.placeholder" /> |
| `color.text.inverted`    | Text on dark or strongly colored surfaces          | <ColorChip token="color.text.inverted" />    |
| `color.text.disabled`    | Text in disabled controls                          | <ColorChip token="color.text.disabled" />    |

The colored text tokens below are **legacy — don't use them in new code**. Instead of coloring
text, communicate intent through surface and border colors (`color.background.*`,
`color.border.*`).

| Token                   | Legacy use                        |                                             |
| ----------------------- | --------------------------------- | ------------------------------------------- |
| `color.text.accentDark` | Accent-colored copy               | <ColorChip token="color.text.accentDark" /> |
| `color.text.positive`   | Success messages, positive values | <ColorChip token="color.text.positive" />   |
| `color.text.info`       | Informational messages            | <ColorChip token="color.text.info" />       |
| `color.text.warning`    | Warnings                          | <ColorChip token="color.text.warning" />    |
| `color.text.critical`   | Errors and destructive actions    | <ColorChip token="color.text.critical" />   |

For icons use the matching `color.icon.*` tokens: the same roles (`primary` … `disabled`, minus
`placeholder`) tuned for iconography.

### Background colors

`color.background.*` fills surfaces. Neutral roles (`primary` → `tertiary`) step up in contrast,
and each status color comes as a `…Light` / `…Dark` pair: light backgrounds take dark text, dark
backgrounds take `color.text.inverted`.

| Token                                        | Use for                                                |                                                                  |
| -------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------- |
| `color.background.primary`                   | Default surface: pages, cards, dialogs                 | <ColorChip token="color.background.primary" />                   |
| `color.background.secondary`                 | One step of contrast: section backgrounds, wells       | <ColorChip token="color.background.secondary" />                 |
| `color.background.tertiary`                  | Two steps of contrast: emphasized neutral areas        | <ColorChip token="color.background.tertiary" />                  |
| `color.background.overlay`                   | Scrim behind dialogs and drawers (semi-transparent)    | <ColorChip token="color.background.overlay" />                   |
| `color.background.disabled`                  | Fill of disabled controls                              | <ColorChip token="color.background.disabled" />                  |
| `color.background.brand`                     | Brand surfaces and marketing moments                   | <ColorChip token="color.background.brand" />                     |
| `color.background.brandB2b`                  | Brand surfaces in Preply Business contexts             | <ColorChip token="color.background.brandB2b" />                  |
| `color.background.accentLight`               | Subtle accent highlight                                | <ColorChip token="color.background.accentLight" />               |
| `color.background.accentDark`                | Strong accent surface — pair with inverted text        | <ColorChip token="color.background.accentDark" />                |
| `color.background.positiveLight`             | Subtle success surface                                 | <ColorChip token="color.background.positiveLight" />             |
| `color.background.positiveDark`              | Strong success surface — pair with inverted text       | <ColorChip token="color.background.positiveDark" />              |
| `color.background.infoLight`                 | Subtle informational surface                           | <ColorChip token="color.background.infoLight" />                 |
| `color.background.infoDark`                  | Strong informational surface — pair with inverted text | <ColorChip token="color.background.infoDark" />                  |
| `color.background.warningLight`              | Subtle warning surface                                 | <ColorChip token="color.background.warningLight" />              |
| `color.background.warningDark`               | Strong warning surface — pair with inverted text       | <ColorChip token="color.background.warningDark" />               |
| `color.background.criticalLight`             | Subtle error surface                                   | <ColorChip token="color.background.criticalLight" />             |
| `color.background.criticalDark`              | Strong error surface — pair with inverted text         | <ColorChip token="color.background.criticalDark" />              |
| `color.background.statusOnline`              | Presence indicator: online                             | <ColorChip token="color.background.statusOnline" />              |
| `color.background.statusOffline`             | Presence indicator: offline                            | <ColorChip token="color.background.statusOffline" />             |
| `color.background.primaryInverted`           | Default dark surface: inverted sections, tooltips      | <ColorChip token="color.background.primaryInverted" />           |
| `color.background.secondaryInverted`         | One step of contrast on dark surfaces                  | <ColorChip token="color.background.secondaryInverted" />         |
| `color.background.tertiaryInverted`          | Two steps of contrast on dark surfaces                 | <ColorChip token="color.background.tertiaryInverted" />          |
| `color.background.ai.surface.linearGradient` | Gradient fill for AI-feature surfaces                  | <ColorChip token="color.background.ai.surface.linearGradient" /> |

### Border colors

`color.border.*` draws strokes and dividers. It also carries interaction states that apply across
components: `hover`, `focus`, and validation colors for form fields.

| Token                                    | Use for                                               |                                                               |
| ---------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------- |
| `color.border.primary`                   | Default border: inputs, cards, dividers               | <BorderChip token="color.border.primary" />                   |
| `color.border.secondary`                 | High-contrast border                                  | <BorderChip token="color.border.secondary" />                 |
| `color.border.secondary-opacity`         | High-contrast border at low opacity — subtle anywhere | <BorderChip token="color.border.secondary-opacity" />         |
| `color.border.tertiary`                  | Softest divider                                       | <BorderChip token="color.border.tertiary" />                  |
| `color.border.disabled`                  | Borders of disabled controls                          | <BorderChip token="color.border.disabled" />                  |
| `color.border.brand`                     | Brand-colored emphasis                                | <BorderChip token="color.border.brand" />                     |
| `color.border.critical`                  | Invalid fields, error states                          | <BorderChip token="color.border.critical" />                  |
| `color.border.focus`                     | Focus rings for keyboard navigation                   | <BorderChip token="color.border.focus" />                     |
| `color.border.hover`                     | Hovered inputs and controls                           | <BorderChip token="color.border.hover" />                     |
| `color.border.positive`                  | Valid fields, success states                          | <BorderChip token="color.border.positive" />                  |
| `color.border.ai.button.linearGradient`  | Gradient border for AI buttons                        | <BorderChip token="color.border.ai.button.linearGradient" />  |
| `color.border.ai.surface.linearGradient` | Gradient border for AI surfaces                       | <BorderChip token="color.border.ai.surface.linearGradient" /> |

### Action

`action.*` styles interactive elements — buttons, links, and anything clickable. The group has
four parts:

- **`action.variant.<variant>.*`** — colors per visual variant: `color`, `bgColor`, and
  `borderColor` at rest, plus the same set under `.hover.*`, `.active.*`, and `.disabled.*`
  (and `.selected.*` where the variant supports a toggled state).
- **`action.base.*`** — chrome shared by all variants: `borderRadius`, `borderWidth`, `gap`,
  the focus ring (`focus.outlineColor` / `outlineWidth` / `outlineOffset`), and neutral
  `hover.bgColor` / `active.bgColor` washes.
- **`action.size.<large|medium|small>.*`** — `height`, paddings, and typography per size.
- **`action.link.*`** — colors for standalone links.

Each variant family rendered on a real Button:

| Token family                 | Use for                                         |                                    |
| ---------------------------- | ----------------------------------------------- | ---------------------------------- |
| `action.variant.primary.*`   | The main call to action                         | <ActionChip variant="primary" />   |
| `action.variant.secondary.*` | Secondary actions                               | <ActionChip variant="secondary" /> |
| `action.variant.tertiary.*`  | Lower-emphasis actions                          | <ActionChip variant="tertiary" />  |
| `action.variant.ghost.*`     | Minimal actions; supports a `.selected.*` state | <ActionChip variant="ghost" />     |
| `action.variant.critical.*`  | Destructive actions                             | <ActionChip variant="critical" />  |
| `action.variant.inverted.*`  | Actions on dark surfaces                        | <ActionChip variant="inverted" />  |
| `action.variant.onColor.*`   | Actions on brand or colored surfaces            | <ActionChip variant="onColor" />   |
| `action.variant.ai.*`        | AI features                                     | <ActionChip variant="ai" />        |

### Spacing and sizing

`spacing.*` sets distances **between** elements — paddings, gaps, margins. `sizing.*` sets
element **dimensions** — widths and heights. Both are pixel scales where the token name is the
value: `spacing.16` is `16px`.

#### Spacing

| Token         | Value   |                                    |
| ------------- | ------- | ---------------------------------- |
| `spacing.0`   | `0px`   | <SpacingGap token="spacing.0" />   |
| `spacing.1`   | `1px`   | <SpacingGap token="spacing.1" />   |
| `spacing.2`   | `2px`   | <SpacingGap token="spacing.2" />   |
| `spacing.4`   | `4px`   | <SpacingGap token="spacing.4" />   |
| `spacing.6`   | `6px`   | <SpacingGap token="spacing.6" />   |
| `spacing.8`   | `8px`   | <SpacingGap token="spacing.8" />   |
| `spacing.12`  | `12px`  | <SpacingGap token="spacing.12" />  |
| `spacing.16`  | `16px`  | <SpacingGap token="spacing.16" />  |
| `spacing.20`  | `20px`  | <SpacingGap token="spacing.20" />  |
| `spacing.24`  | `24px`  | <SpacingGap token="spacing.24" />  |
| `spacing.32`  | `32px`  | <SpacingGap token="spacing.32" />  |
| `spacing.48`  | `48px`  | <SpacingGap token="spacing.48" />  |
| `spacing.64`  | `64px`  | <SpacingGap token="spacing.64" />  |
| `spacing.96`  | `96px`  | <SpacingGap token="spacing.96" />  |
| `spacing.160` | `160px` | <SpacingGap token="spacing.160" /> |

#### Sizing

| Token        | Value   |                                  |
| ------------ | ------- | -------------------------------- |
| `sizing.0`   | `0px`   | <SizingBar token="sizing.0" />   |
| `sizing.1`   | `1px`   | <SizingBar token="sizing.1" />   |
| `sizing.2`   | `2px`   | <SizingBar token="sizing.2" />   |
| `sizing.4`   | `4px`   | <SizingBar token="sizing.4" />   |
| `sizing.8`   | `8px`   | <SizingBar token="sizing.8" />   |
| `sizing.12`  | `12px`  | <SizingBar token="sizing.12" />  |
| `sizing.16`  | `16px`  | <SizingBar token="sizing.16" />  |
| `sizing.20`  | `20px`  | <SizingBar token="sizing.20" />  |
| `sizing.24`  | `24px`  | <SizingBar token="sizing.24" />  |
| `sizing.32`  | `32px`  | <SizingBar token="sizing.32" />  |
| `sizing.40`  | `40px`  | <SizingBar token="sizing.40" />  |
| `sizing.48`  | `48px`  | <SizingBar token="sizing.48" />  |
| `sizing.64`  | `64px`  | <SizingBar token="sizing.64" />  |
| `sizing.96`  | `96px`  | <SizingBar token="sizing.96" />  |
| `sizing.160` | `160px` | <SizingBar token="sizing.160" /> |

### Radius

`radius.*` rounds corners. Like the spacing scale, the token name is the pixel value — `radius.300`
is large enough to make any element pill-shaped.

| Token        | Value   |                                   |
| ------------ | ------- | --------------------------------- |
| `radius.0`   | `0px`   | <RadiusChip token="radius.0" />   |
| `radius.2`   | `2px`   | <RadiusChip token="radius.2" />   |
| `radius.4`   | `4px`   | <RadiusChip token="radius.4" />   |
| `radius.8`   | `8px`   | <RadiusChip token="radius.8" />   |
| `radius.16`  | `16px`  | <RadiusChip token="radius.16" />  |
| `radius.300` | `300px` | <RadiusChip token="radius.300" /> |

### Typography

Body text uses `text.fontFamily`; headings use `text.heading.fontFamily`. Each variant below is a
family of sub-tokens: `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, and `fontStyle`
(eg. `text.variant.default-regular.fontSize`). Standalone weights live under `text.weight.*`
(`base`, `normal`, `medium`, `bold`).

Body variants (`text.variant.*`) pair a size with a weight; most also have an `…-italic`
counterpart:

| Token family                      | Use for                              |                                                                                              |
| --------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------- |
| `text.variant.caption-regular.*`  | Smallest copy: captions, helper text | <TypeSample token="text.variant.caption-regular">Language learning made simple</TypeSample>  |
| `text.variant.caption-semibold.*` | Emphasized captions                  | <TypeSample token="text.variant.caption-semibold">Language learning made simple</TypeSample> |
| `text.variant.small-regular.*`    | Secondary copy, dense UI             | <TypeSample token="text.variant.small-regular">Language learning made simple</TypeSample>    |
| `text.variant.small-semibold.*`   | Emphasized secondary copy            | <TypeSample token="text.variant.small-semibold">Language learning made simple</TypeSample>   |
| `text.variant.default-regular.*`  | Body copy — the default              | <TypeSample token="text.variant.default-regular">Language learning made simple</TypeSample>  |
| `text.variant.default-semibold.*` | Emphasized body copy                 | <TypeSample token="text.variant.default-semibold">Language learning made simple</TypeSample> |
| `text.variant.large-regular.*`    | Lead paragraphs, prominent copy      | <TypeSample token="text.variant.large-regular">Language learning made simple</TypeSample>    |
| `text.variant.large-semibold.*`   | Emphasized prominent copy            | <TypeSample token="text.variant.large-semibold">Language learning made simple</TypeSample>   |

Heading variants (`heading.variant.*`), from page titles up to marketing heroes:

| Token family                   | Use for                |                                                                    |
| ------------------------------ | ---------------------- | ------------------------------------------------------------------ |
| `heading.variant.small.*`      | Card and widget titles | <TypeSample token="heading.variant.small">Preply</TypeSample>      |
| `heading.variant.medium.*`     | Section titles         | <TypeSample token="heading.variant.medium">Preply</TypeSample>     |
| `heading.variant.large.*`      | Page titles            | <TypeSample token="heading.variant.large">Preply</TypeSample>      |
| `heading.variant.extraLarge.*` | Prominent page titles  | <TypeSample token="heading.variant.extraLarge">Preply</TypeSample> |
| `heading.variant.huge.*`       | Landing-page headlines | <TypeSample token="heading.variant.huge">Preply</TypeSample>       |
| `heading.variant.massive.*`    | Marketing heroes       | <TypeSample token="heading.variant.massive">Preply</TypeSample>    |

### Elevation

`dropShadow.*` has three levels of elevation. On web use the `.shorthand` token as a `box-shadow`
value; the individual parts (`shadowColor`, `shadowOffsetX/Y`, `shadowBlurRadius`,
`shadowOpacity`, `elevation`) exist for React Native.

| Token                    | Use for                                 |                                               |
| ------------------------ | --------------------------------------- | --------------------------------------------- |
| `dropShadow.1.shorthand` | Low elevation: cards, hovering elements | <ShadowChip token="dropShadow.1.shorthand" /> |
| `dropShadow.2.shorthand` | Medium elevation: dropdowns, popovers   | <ShadowChip token="dropShadow.2.shorthand" /> |
| `dropShadow.3.shorthand` | High elevation: dialogs, drawers        | <ShadowChip token="dropShadow.3.shorthand" /> |

### Motion

`motion.components.interaction` is the standard easing for interactive feedback — a complete
`<duration> <easing-function>` shorthand, ready to drop into a `transition`:

```css
.MyComponent {
    transition: transform $motion-components-interaction;
}
```

<MotionDemo />

## Referencing tokens in code

Most of the time you don't reference tokens directly: component props such as `color`, `padding`,
and `variant` already accept token-backed values. Reach for raw tokens only in custom CSS.

### SCSS

Import the generated tokens file; it declares one `$variable` per token:

```css
@use '@preply/ds-web-core/dist/generated/tokens' as *;

.MyComponent {
    color: $action-variant-primary-color;
    background-color: $action-variant-primary-bgColor;
    border-radius: $action-base-borderRadius;
}
```

### Less

Import the generated tokens file; it declares one `@variable` per token:

```css
@import '@preply/ds-web-core/dist/generated/tokens.less';

.MyComponent {
    color: @action-variant-primary-color;
    background-color: @action-variant-primary-bgColor;
    border-radius: @action-base-borderRadius;
}
```

### CSS-in-JS

The [getTokenVar](/docs/utilities-gettokenvar--docs) utility returns a token's CSS variable:

```tsx
import styled from 'styled-components';
import { action } from '@preply/ds-core';
import { getTokenVar as t } from '@preply/ds-web-core';

export const MyComponent = styled.div`
    color: ${t(action.variant.primary.color)};
    background-color: ${t(action.variant.primary.bgColor)};
    border-radius: ${t(action.base.borderRadius)};
`;
```

## Don't

- **Don't hardcode raw values** (`#232323`, `12px`) that a token covers — they won't adapt to
  themes or color schemes.
- **Don't use palette tokens for UI roles** — pick the semantic token that describes the role
  (`color.text.tertiary`), not the palette entry that currently matches it.
- **Don't use legacy `@preply/ui` variables** (`@border-radius-m`, `@responsive-mobile-normal`) in
  new code.
