> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CSS variable migration

SuperDoc's CSS variables were restructured into a three-tier token system. This page maps every old name to its new equivalent.

> [!NOTE]
>
> **Old names still work.** New tokens fall back to old names automatically. You don't need to change your code immediately.

## What changed

The old system used flat names (`--sd-comment-bg`, `--sd-track-insert-border`). The new system uses a structured pattern:

```
--sd-{scope}-{component}-{element?}-{state?}-{property}

Old:  --sd-comment-bg
New:  --sd-ui-comments-card-bg
```

The JavaScript config API is unchanged. Only CSS variable names moved.

## Full mapping

### Surfaces

| Old | New |
| - | - |
| `--sd-surface-page` | `--sd-ui-bg` |
| `--sd-surface-canvas` | `--sd-color-gray-50` |
| `--sd-surface-card` | `--sd-ui-bg` |
| `--sd-surface-muted` | `--sd-ui-disabled-bg` |
| `--sd-surface-hover` | `--sd-ui-hover-bg` |
| `--sd-surface-selected` | `--sd-color-blue-100` |

### Text

| Old | New |
| - | - |
| `--sd-text-primary` | `--sd-ui-text` |
| `--sd-text-secondary` | `--sd-color-gray-700` |
| `--sd-text-muted` | `--sd-ui-text-muted` |
| `--sd-text-placeholder` | `--sd-ui-text-disabled` |

### Borders

| Old | New |
| - | - |
| `--sd-border-default` | `--sd-ui-border` |
| `--sd-border-subtle` | `--sd-ui-comments-separator` |
| `--sd-border-focus` | `--sd-ui-action` |

### Actions

| Old | New |
| - | - |
| `--sd-action-primary` | `--sd-ui-action` |
| `--sd-action-primary-hover` | `--sd-ui-action-hover` |

### Typography and radius

| Old | New |
| - | - |
| `--sd-font-family` | `--sd-ui-font-family` |
| `--sd-radius-sm` | `--sd-radius-50` |
| `--sd-radius-md` | `--sd-radius-200` |
| `--sd-radius-lg` | `--sd-radius-300` |

### Comment card

| Old | New |
| - | - |
| `--sd-comment-bg` | `--sd-ui-comments-card-bg` |
| `--sd-comment-bg-hover` | `--sd-ui-comments-card-hover-bg` |
| `--sd-comment-bg-active` | `--sd-ui-comments-card-active-bg` |
| `--sd-comment-bg-resolved` | `--sd-ui-comments-card-resolved-bg` |
| `--sd-comment-border-active` | `--sd-ui-comments-card-active-border` |
| `--sd-comment-radius` | `--sd-ui-comments-card-radius` |
| `--sd-comment-padding` | `--sd-ui-comments-card-padding` |
| `--sd-comment-shadow` | `--sd-ui-comments-card-shadow` |
| `--sd-comment-separator` | `--sd-ui-comments-separator` |
| `--sd-comment-transition` | `--sd-ui-comments-transition` |

### Comment text

| Old | New |
| - | - |
| `--sd-comment-author-color` | `--sd-ui-comments-author-text` |
| `--sd-comment-author-size` | `--sd-ui-comments-author-size` |
| `--sd-comment-author-weight` | `--sd-ui-comments-author-weight` |
| `--sd-comment-time-color` | `--sd-ui-comments-timestamp-text` |
| `--sd-comment-time-size` | `--sd-ui-comments-timestamp-size` |
| `--sd-comment-body-size` | `--sd-ui-comments-body-size` |
| `--sd-comment-tc-insert-color` | `--sd-ui-comments-insert-text` |
| `--sd-comment-tc-delete-color` | `--sd-ui-comments-delete-text` |

### Comment highlights

| Old | New |
| - | - |
| `--sd-comment-highlight-internal` | `--sd-comments-highlight-internal` |
| `--sd-comment-highlight-external` | `--sd-comments-highlight-external` |
| `--sd-comment-internal-bg` | `--sd-ui-comments-internal-bg` |
| `--sd-comment-external-bg` | `--sd-ui-comments-external-bg` |

> [!WARNING]
>
> `--sd-comment-highlight-opacity` and `--sd-comment-highlight-opacity-active` were removed. The new system uses pre-computed RGBA colors (`--sd-comments-highlight-external: #b1124b40`). Override the full value directly.

### Tracked changes

| Old | New |
| - | - |
| `--sd-track-insert-border` | `--sd-tracked-changes-insert-border` |
| `--sd-track-insert-bg` | `--sd-tracked-changes-insert-background` |
| `--sd-track-delete-border` | `--sd-tracked-changes-delete-border` |
| `--sd-track-delete-bg` | `--sd-tracked-changes-delete-background` |
| `--sd-track-format-border` | `--sd-tracked-changes-format-border` |

### Removed

These have no replacement:

| Variable | Why |
| - | - |
| `--sd-comment-highlight-opacity` | Replaced by pre-computed RGBA values |
| `--sd-comment-highlight-opacity-active` | Replaced by pre-computed RGBA values |
| `--sd-comment-max-width` | Managed internally |
| `--sd-comment-min-width` | Managed internally |
| `--sd-comment-group-bg` | Group bubble styling removed |
| `--sd-comment-group-color` | Group bubble styling removed |
| `--sd-comment-group-size` | Group bubble styling removed |
| `--sd-comment-group-expanded-size` | Group bubble styling removed |
| `--sd-font-mono` | No longer exposed |

## How backward compatibility works

New tokens in `variables.css` fall back to old names via `var()`:

```css theme={null}
/* Inside variables.css */
:root {
  --sd-ui-comments-card-bg: var(--sd-comment-bg, #f3f6fd);
  --sd-tracked-changes-insert-border: var(--sd-track-insert-border, #00853d);
}
```

CSS resolves `var()` at computed-value time. If you set `--sd-comment-bg` on any element, the new token picks it up in that scope:

```css theme={null}
.my-overrides {
  --sd-comment-bg: #f0f0f0; /* works: --sd-ui-comments-card-bg resolves to #f0f0f0 */
}
```

Setting the new name directly works too: it overrides the whole fallback expression.

> [!WARNING]
>
> Old-name fallbacks will be removed in the next major version. Migrate to the new names when convenient.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.