# @mezzanine-ui/system

> Design system foundation for Mezzanine UI — provides color palette, typography, spacing, radius, motion, and z-index tokens as CSS custom properties and SCSS mixins.

## Purpose

`@mezzanine-ui/system` is the lowest-level package in the Mezzanine UI stack. It defines all design tokens and exposes them in two ways:

1. **SCSS mixins** — consumed by `@mezzanine-ui/core` to generate component styles
2. **TypeScript constants and types** — consumed by `@mezzanine-ui/react` for runtime token references

Application code rarely imports this package directly; instead, tokens flow through `@mezzanine-ui/core` and `@mezzanine-ui/react`.

## Token Categories

| Category     | What it covers                                              |
| ------------ | ----------------------------------------------------------- |
| `palette`    | Primitive colors + semantic color roles (light/dark mode)   |
| `typography` | Font family, font size, font weight, line height, letter spacing |
| `spacing`    | Semantic spacing scale (primitive + semantic)               |
| `radius`     | Border radius scale                                         |
| `motion`     | Animation duration and easing curves                        |
| `effect`     | Shadow/elevation tokens                                     |
| `z-index`    | Layer ordering constants                                    |

## CSS Custom Properties

All tokens are emitted as CSS custom properties (e.g. `--mzn-color-primary`, `--mzn-spacing-md`). The `common-variables` and `colors` mixins in `_system.scss` emit these onto a selector of your choice (typically `:root`).

## Theme Setup

Apply the SCSS mixins in your global stylesheet:

```scss
@use '@mezzanine-ui/system' as mzn-system;

:root {
  @include mzn-system.common-variables('default');
  @include mzn-system.colors('light');
}

[data-theme='dark'] {
  @include mzn-system.colors('dark');
}

[data-density='compact'] {
  @include mzn-system.common-variables('compact');
}
```

The two public mixins are:
- `common-variables($mode, $options)` — emits spacing, typography, radius, motion, z-index, and effect tokens. `$mode` is `'default'` or `'compact'`.
- `colors($mode, $semantic, $primitives)` — emits palette color tokens. `$mode` is `'light'` or `'dark'`.

## TypeScript Exports

```ts
import { Color, Size, Severity, Orientation } from '@mezzanine-ui/system';
import { toCssVar } from '@mezzanine-ui/system/css';
```

- `Size` — `'small' | 'medium' | 'large'`
- `Severity` — `'success' | 'warning' | 'error' | 'info'`
- `Orientation` — `'horizontal' | 'vertical'`
- `toCssVar(token)` — converts a token name to its `var(--mzn-...)` CSS variable string

## Further Reference

- Complete token values (hex colors, spacing scales, typography variants): `packages/system/DESIGN_TOKENS.md`

## Consumed By

- `@mezzanine-ui/core` — imports SCSS mixins to generate all component stylesheets
- `@mezzanine-ui/react` — imports TypeScript types and runtime token helpers

## GitHub

https://github.com/Mezzanine-UI/mezzanine/tree/main/packages/system