# Foundations

The foundations are the design tokens and CSS utilities that every component is built on. They are exposed as UnoCSS classes via [`@aleph-alpha/ui-library/config`](quick-start.md#config-exports-reference) and documented interactively in Storybook.

!!! tip "Browse live in Storybook"
    Every section below has a matching page under **CSS utility/** in [Storybook](https://dev.aleph-alpha.de/ui-library/?path=/docs/css-utility-background--docs) where each token is rendered with its UnoCSS class name. Click a class name in Storybook to copy it.

---

## Color & Dark Mode

Color is delivered through semantic tokens (no raw hex values in app code). Tokens are grouped by purpose — `surface`, `accent`, `status`, `button`, `input` — and each has a paired `content.on-*` token for accessible foreground contrast.

| Group                                                      | Storybook                                                                                                    |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Background tokens (surface, button, input, accent, status) | [CSS utility / Background](https://dev.aleph-alpha.de/ui-library/?path=/docs/css-utility-background--docs)   |
| Hover layer utilities                                      | [CSS utility / Hover Layer](https://dev.aleph-alpha.de/ui-library/?path=/docs/css-utility-hover-layer--docs) |
| Foreground / text content tokens                           | [CSS utility / Content](https://dev.aleph-alpha.de/ui-library/?path=/docs/css-utility-content--docs)         |
| Border tokens                                              | [CSS utility / Border](https://dev.aleph-alpha.de/ui-library/?path=/docs/css-utility-border--docs)           |

### Hover States

Use the hover treatment that matches the component's base fill:

| Component background                              | Hover classes                                                                                                                   |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| No existing background color                      | `hover:bg-background-surface-muted-subtle`                                                                                      |
| Existing background color inherited by component  | `hover-layer hover-layer-subtle`, `hover-layer hover-layer-default`, or `hover-layer hover-layer-strong`                         |

For existing backgrounds, the component keeps its base fill and the hover layer adds the second fill via `overlay-hover-*`. The design team defines the hover strength per component based on the underlying base color, so check the component's existing `hover-layer-*` strength before changing it.

**Dark mode** is driven by the `html.dark` class. Both `presetShadcn` and `presetUiLibraryThemeFromTokens` default to `darkSelector: 'html.dark'`, so all tokens flip automatically when the class is toggled:

```typescript
document.documentElement.classList.toggle('dark');
```

See [Quick Start → Dark mode](quick-start.md#dark-mode) for the full setup.

---

## Spacing & Grid

Spacing follows the standard UnoCSS / Tailwind scale (`p-1`, `gap-4`, `mx-auto`, etc.) provided by `presetWind4`. Layout primitives are documented in dedicated CSS utility pages:

| Topic                                              | Storybook                                                                                              |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Grid columns, gaps, and template helpers           | [CSS utility / Grid](https://dev.aleph-alpha.de/ui-library/?path=/docs/css-utility-grid--docs)         |
| Flex direction, alignment, and gap utilities       | [CSS utility / Flex](https://dev.aleph-alpha.de/ui-library/?path=/docs/css-utility-flex--docs)         |
| Extended utilities (size, position, z-index, etc.) | [CSS utility / Extended](https://dev.aleph-alpha.de/ui-library/?path=/docs/css-utility-extended--docs) |

---

## Typography

Typography is delivered as a fixed set of utility classes generated from `tokens.json` and registered by `presetUiLibraryThemeFromTokens()`. Use the class — never inline `font-size` / `line-height` — so styles stay consistent and themeable.

| Family      | Classes                                                                                | Storybook                                                                                                  |
| ----------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Headings    | `heading-2xl`, `heading-xl`, `heading-l`, `heading-m`, `heading-s`, `heading-xs`       | [CSS utility / Typography](https://dev.aleph-alpha.de/ui-library/?path=/docs/css-utility-typography--docs) |
| Body        | `body-16-{regular,medium,bold}`, `body-14-{regular,medium,bold}`                       | same page                                                                                                  |
| Labels      | `label-12-*`, `label-14-*`, `label-16-*` (each weight also exposes a `*-normal` alias) | same page                                                                                                  |
| Code / mono | `code-*`                                                                               | same page                                                                                                  |

Example:

```vue
<h2 class="heading-s text-content-on-surface-primary">Section title</h2>
<p class="body-14-regular text-content-on-surface-muted">Supporting copy.</p>
```

---

## Elevation & Surfaces

Surfaces and shadows together encode the elevation hierarchy. Use the surface token that matches the layer, and add a shadow only at floating / modal level.

| Layer                                      | Token                              | Notes                                |
| ------------------------------------------ | ---------------------------------- | ------------------------------------ |
| Base app backdrop                          | `bg-background-surface-primary`    | Sidebar lives on this layer.         |
| Sheet above base                           | `bg-background-surface-secondary`  | Use `shadow-lg`, no border.          |
| Sunken / highlighted inner container       | `bg-background-surface-muted`      | Subtle non-floating differentiation. |
| Floating overlay (popover, dropdown, menu) | `bg-background-surface-floating`   | `border-default` + `shadow-xs`.      |
| Modal / dialog container                   | `bg-background-surface-modal`      | `border-default` + `shadow-lg`.      |
| Modal backdrop / scrim                     | `bg-overlay-surface-modal-overlay` | Used by `<UiDialog>` overlay.        |
| Form inputs                                | `bg-background-input-default`      | Text, textarea, file, OTP.           |

| Topic                                       | Storybook                                                                                                               |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| All surface, overlay, and modal backgrounds | [CSS utility / Background — Surface](https://dev.aleph-alpha.de/ui-library/?path=/docs/css-utility-background--surface) |
| Drop shadows (`shadow-xs` … `shadow-xl`)    | [CSS utility / Shadow](https://dev.aleph-alpha.de/ui-library/?path=/docs/css-utility-shadow--docs)                      |
| Overlay scrims                              | [CSS utility / Overlay](https://dev.aleph-alpha.de/ui-library/?path=/docs/css-utility-overlay--docs)                    |

---

## Iconography

Icons are rendered with `<UiIcon>`, which wraps the [Lucide](https://lucide.dev/icons) icon set. This keeps stroke width, sizing, and accessibility semantics consistent across components.

```vue
<script setup lang="ts">
  import { UiIcon } from '@aleph-alpha/ui-library';
</script>

<template>
  <UiIcon name="circle-help" :size="20" aria-label="Help" />
</template>
```

| Prop          | Description                                                          |
| ------------- | -------------------------------------------------------------------- |
| `name`        | Lucide icon name in kebab-case (e.g. `circle-help`, `chevron-down`). |
| `size`        | Pixel size. Defaults to `24`.                                        |
| `strokeWidth` | Stroke width. Defaults to `2`.                                       |
| `ariaLabel`   | Accessible label. Omit for purely decorative icons.                  |

Resources:

- [`UiIcon` in Storybook](https://dev.aleph-alpha.de/ui-library/?path=/docs/components-uiicon--docs)
- [Lucide icon catalogue](https://lucide.dev/icons)
