# Typography Tokens

Typography tokens use the `--typography-*` naming pattern and map to typography primitives in `specs/ux/foundations/typography.md`.

If a primitive changes in `specs/ux/foundations/typography.md`, update the matching token in this file.

The value column keeps the Figma/UX family label `Google Sans`. In the owned runtime, `--font-family-sans` is `Google Sans` in `src/app/design-system/tokens/tokens.scss`. The font is declared in `src/styles.scss` and served from the local project asset `/fonts/GoogleSans-Variable.ttf`.

## Usage

Use typography tokens for:

- headings
- body text
- paragraph text
- captions
- action labels
- descriptions
- sidebar text

## Token Mapping

| CSS Token                                    | Foundation Mapping                                                                                                  | Value                                                       | Usage                         |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------- |
| `--typography-title-whale`                   | `font.family.base` + `font.size.700` + `font.weight.bold` + `font.lineHeight.700` + `font.letterSpacing.default`    | `700 34px/38px Google Sans`                                | Large display titles          |
| `--typography-title-1-elephant`              | `font.family.base` + `font.size.600` + `font.weight.bold` + `font.lineHeight.600` + `font.letterSpacing.default`    | `700 24px/26px Google Sans`                                | Page titles                   |
| `--typography-title-1-elephant-code`         | `font.family.base` + `font.size.600` + `font.weight.code` + `font.lineHeight.code` + `font.letterSpacing.default`   | `700 24px/30px Google Sans`                                 | SMS-code digits               |
| `--typography-title-2-pig`                   | `font.family.base` + `font.size.500` + `font.weight.650` + `font.lineHeight.500` + `font.letterSpacing.default`     | `650 19px/22px Google Sans`                                | Section titles                |
| `--typography-title-3-bear`                  | `font.family.base` + `font.size.400` + `font.weight.bold` + `font.lineHeight.400` + `font.letterSpacing.default`    | `700 17px/20px Google Sans`                                | Compact section titles        |
| `--typography-title-4-crocodile`             | `font.family.base` + `font.size.300` + `font.weight.bold` + `font.lineHeight.300` + `font.letterSpacing.default`    | `700 15px/18px Google Sans`                                | Small titles                  |
| `--typography-caption-regular-kitten`        | `font.family.base` + `font.size.100` + `font.weight.regular` + `font.lineHeight.100` + `font.letterSpacing.default` | `400 11px/14px Google Sans`                                | Regular captions              |
| `--typography-caption-cat`                   | `font.family.base` + `font.size.100` + `font.weight.medium` + `font.lineHeight.100` + `font.letterSpacing.default`  | `500 11px/14px Google Sans`                                | Accent captions               |
| `--typography-caption-uppercase-chameleon`   | `font.family.base` + `font.size.100` + `font.weight.medium` + `font.lineHeight.100` + `font.letterSpacing.default`  | `500 11px/14px Google Sans; text-transform: uppercase`     | Uppercase captions            |
| `--typography-action-capybara`               | `font.family.base` + `font.size.400` + `font.weight.regular` + `font.lineHeight.400` + `font.letterSpacing.default` | `400 17px/20px Google Sans`                                | Action text                   |
| `--typography-action-accent-minipig`         | `font.family.base` + `font.size.400` + `font.weight.medium` + `font.lineHeight.400` + `font.letterSpacing.default`  | `500 17px/20px Google Sans`                                | Accent action text            |
| `--typography-body-horse`                    | `font.family.base` + `font.size.300` + `font.weight.regular` + `font.lineHeight.400` + `font.letterSpacing.default` | `400 15px/20px Google Sans`                                | Body text                     |
| `--typography-body-accent-buffalo`           | `font.family.base` + `font.size.300` + `font.weight.medium` + `font.lineHeight.400` + `font.letterSpacing.default`  | `500 15px/20px Google Sans`                                | Emphasized body text          |
| `--typography-body-strikethrough-zebra`      | `font.family.base` + `font.size.300` + `font.weight.regular` + `font.lineHeight.400` + `font.letterSpacing.default` | `400 15px/20px Google Sans; text-decoration: line-through` | Removed or outdated body text |
| `--typography-paragraph-deer`                | `font.family.base` + `font.size.300` + `font.weight.regular` + `font.lineHeight.500` + `font.letterSpacing.default` | `400 15px/22px Google Sans`                                | Paragraph text                |
| `--typography-paragraph-accent-elk`          | `font.family.base` + `font.size.300` + `font.weight.medium` + `font.lineHeight.500` + `font.letterSpacing.default`  | `500 15px/22px Google Sans`                                | Emphasized paragraph text     |
| `--typography-paragraph-link-unicorn`        | `font.family.base` + `font.size.300` + `font.weight.regular` + `font.lineHeight.500` + `font.letterSpacing.default` | `400 15px/22px Google Sans; text-decoration: underline`    | Paragraph links               |
| `--typography-description-puma`              | `font.family.base` + `font.size.200` + `font.weight.regular` + `font.lineHeight.200` + `font.letterSpacing.default` | `400 13px/16px Google Sans`                                | Description text              |
| `--typography-description-accent-lion`       | `font.family.base` + `font.size.200` + `font.weight.medium` + `font.lineHeight.200` + `font.letterSpacing.default`  | `500 13px/16px Google Sans`                                | Emphasized description text   |
| `--typography-description-uppercase-hamster` | `font.family.base` + `font.size.200` + `font.weight.regular` + `font.lineHeight.200` + `font.letterSpacing.default` | `400 13px/16px Google Sans; text-transform: uppercase`     | Uppercase description labels  |
| `--typography-sidebar-default`               | `font.family.base` + `font.size.250` + `font.weight.regular` + `font.lineHeight.400` + `font.letterSpacing.sidebar` | `400 14px/20px Google Sans; letter-spacing: -0.3px`        | Sidebar text                  |
| `--typography-sidebar-accent`                | `font.family.base` + `font.size.250` + `font.weight.medium` + `font.lineHeight.400` + `font.letterSpacing.sidebar`  | `500 14px/20px Google Sans; letter-spacing: -0.3px`        | Emphasized sidebar text       |

## Raw Values

Do not use raw typography values or non-CSS token names in component styles.

```css
/* Wrong */
.title {
  font: 700 24px/26px 'Google Sans';
}

.caption {
  font: var(typography.caption.cat);
}

/* Correct */
.title {
  font: var(--typography-title-1-elephant);
}

.caption {
  font: var(--typography-caption-cat);
}
```