# Central Design System (CDS 4) — guides

> Version: 4.0.0-alpha.13
> Setup, conventions, forms, theming, Tailwind CSS, tree-shaking, and responsiveness.
> Generated automatically (`bun run generate:meta` → `bun run generate:llms`). Do not edit manually.

---

# Setup and themes

## Installation

```bash
npm install @central-design-system/components
```

## Wiring it into the app

```ts
import { createApp } from 'vue';
import '@central-design-system/components/styles';
import { createCds, components, directives } from '@central-design-system/components';
import App from './App.vue';

const cds = createCds({ components, directives });
createApp(App).use(cds).mount('#app');
```

After that every component is available globally: `<CdsButton appearance="primary">Click me</CdsButton>`.

This is the full registration — it pulls in the entire library. For production
apps register components individually, see the Tree-shaking guide.

## Style entry points

| Import | What it provides |
| --- | --- |
| `@central-design-system/components/styles` | Aggregate: CSS of every component (~556 KB). Quick start, tree-shaking disabled |
| `@central-design-system/components/styles/common.css` | Base layer (~9 KB): layers, reset, fonts, typography, grid |
| `@central-design-system/components/styles/core` | Only layers, fonts and reset — no typography |
| `@central-design-system/components/styles/utilities` | Utility classes |
| `@central-design-system/components/styles/tailwind` | Tailwind CSS integration layer |
| `@central-design-system/components/styles/legacy` | Legacy utilities for migrating from CDS 3 |

With per-component registration you only include the base layer
`styles/common.css` — each component ships its own CSS alongside the
component itself.

Tailwind CSS v4 integration (installation, layers, utilities built on CDS
tokens) is covered in the Tailwind CSS + CDS guide.

## Themes

The theme is set at initialization via `createCds`:

```ts
const cds = createCds({
  components,
  directives,
  theme: { defaultTheme: 'b2bLight' }
});
```

Built-in themes: `cdsLight` (default), `cdsDark`, `b2bLight`, `b2bDark`,
`promoLight`, `promoDark`. The values of every color token in each theme
are listed in ../tokens/themes.md.

Custom themes, runtime theme switching and disabling theming are covered in
the Theming guide.

## Icons

The Phosphor iconpack is active by default and needs no setup: its CSS ships
with the package. Other packs are available too (`cds`, `lucide`,
`materialSymbols`, `remix`, `tabler`):

```ts
import { createCds, iconsets } from '@central-design-system/components';

createCds({
  icons: {
    defaultSet: 'remix',
    sets: { remix: iconsets.remix.icons },
    aliases: iconsets.remix.aliases
  }
});
```

The `@central-design-system/icons` package (CDS 3) is deprecated, see the
migration guide.

---

# CDS 4 conventions

The golden rule: **the source of truth is the component's `api.md`**
(`references/components/<name>/api.md`). Do not invent props, events or
slots — if they are not in api.md, they do not exist on the component.

## Shared props

The props below come from shared composable factories and behave identically
in every component that has them:

| Prop | Semantics |
| --- | --- |
| `size` | Size: `xs` / `sm` / `md` / `lg` / `xl` or a number |
| `appearance` | Appearance (visual variant); the set of values is component-specific — check the type in api.md |
| `color` / `bgColor` | Content / background color as a **theme token**, not a CSS value |
| `disabled` | Disabled state |
| `loading` | Loading state |
| `width` / `height` | Dimensions (number → px, or a CSS value as a string) |

## Tokens, not raw values

- Set colors via the `color` prop / theme tokens (`--cds-color-*`), never
  arbitrary CSS (`#fff`, `red`). Theme tokens are listed in ../tokens/themes.md.
- Spacing, radii and other values in custom SCSS go through the global
  `--cds-*` variables, never hardcoded.

## Atomic Design

Complex UI is composed from atoms. Example — a form: the ready-made
`CdsTextInput` "molecule" is internally built as `CdsField` + `CdsLabel` +
`CdsDescription` + `CdsMessages` + `CdsInput`, and the same atoms are
available for building your own fields. See the Forms guide
for details.

## Defaults

Prop defaults can be set centrally:

- globally — via the `defaults` option in `createCds({ defaults: { CdsButton: { size: 'lg' } } })`;
- for a subtree — with the `CdsDefaultsProvider` component
  (api).

## Deprecated APIs

Props/components marked `_(deprecated)_` in api.md still work but will be
removed. In the dev console they emit a warning prefixed `[CDS UPGRADE]`.
When migrating legacy code, see the migration guide.

---

# Forms with CDS 4

## Ready-made controls

For typical forms use the ready-made "molecules" (each has its own `api.md`
and `examples.md` in `references/components/`):

| Control | Purpose |
| --- | --- |
| CdsTextInput | Text field with label / description / messages |
| CdsSelect | Dropdown (single / multiple) |
| CdsAutocomplete | Selection with search over the list |
| CdsCombobox | Selection that also accepts free-form input |
| CdsCheckbox | Checkbox |
| CdsRadioGroup | Radio button group |
| CdsToggle | Toggle |
| CdsDatePicker / CdsTimePicker | Date / time |

## CdsForm: aggregation and validation

`CdsForm` groups fields, aggregates their validation (`v-model` — form
validity) and exposes `validate` / `reset` / `resetValidation` methods via
slot props and the exposed API. Validation rules are set on the fields with
the `rules` prop (an array of functions `value → true | 'error text'`).

A verified example (from Storybook):

```html
<CdsForm v-model="valid" @submit.prevent>
  <template #default="{ reset }">
    <CdsTextInput v-model="name" :rules="rules.name" label="Name" placeholder="Enter name" />
    <CdsTextInput v-model="email" :rules="rules.email" label="Email" placeholder="Enter Email" />
    <CdsButton appearance="secondary" @click="reset">Clear</CdsButton>
    <CdsButton type="submit">Submit</CdsButton>
  </template>
</CdsForm>
```

```ts
const valid = ref(false);
const name = ref('');
const email = ref('');

const rules = {
  name: [
    (value: string) => !!value || 'Must not be empty',
    (value: string) => value.length <= 10 || 'No more than 10 characters'
  ],
  email: [
    (value: string) => !!value || 'Must not be empty',
    (value: string) => /.+@.+\..+/.test(value) || 'Invalid format'
  ]
};
```

Useful modes (full list in api.md):

- `first-fail` — validation stops at the first invalid field;
- `disabled` / `readonly` on the form propagate to every nested field.

CdsForm also works with external validators (vuelidate, vee-validate) — see
examples.md.

## Building your own field from atoms

When no ready-made molecule fits, assemble the field from atoms:

| Atom | Role |
| --- | --- |
| CdsField | Field wrapper: wires up label/control/messages, states |
| CdsLabel | Field label |
| CdsDescription | Supporting description |
| CdsMessages | Error messages / hints |
| CdsInput | Bare input control |

Before assembling, open the `api.md` of every atom — take the set of props
and slots only from there.

---

# CDS 3 → CDS 4 migration (digest)

This is a short digest. **The full version with Before/After for every
change is `MIGRATION.md` at the root of the
`@central-design-system/components` npm package.**

## Severity legend

| Marker | Meaning |
| --- | --- |
| ⚠️ **BREAKING** | Breaks existing code — action required |
| 🔁 **RENAMED** | Rename — mechanical search & replace |
| 🟠 **DEPRECATED** | Works in 4.x, will be removed in 5.x |
| ✨ **NEW** | New capability, nothing breaks |

## Quick checklist

- [ ] Replace the CSS import: `@central-design-system/components/dist/cds.css` →
      `@central-design-system/components/styles` (⚠️ breaking).
- [ ] If you use `@central-design-system/icons` — the package is 🟠 deprecated;
      switch to iconpacks via `createCds({ icons })` (see setup.md).
- [ ] Go through the component rename index below.
- [ ] Run the build and check the dev console: `[CDS UPGRADE]` warnings
      point at deprecated props.

## Key breaking changes

- ⚠️ **CSS import path** — `dist/cds.css` is no longer a public entry point;
  import `@central-design-system/components/styles` instead.
- ⚠️ **Legacy reset is off by default** — the global reset from CDS 3 is now
  opt-in: `@use '@central-design-system/components/styles' with ($legacy-reset: true);`.
- ⚠️ **CSS architecture on ITCSS + CSS Layers** — the cascade is driven by
  native `@layer`; global overrides of CDS styles without `!important` may
  now resolve differently.

## Component rename and removal index

| CDS 3 | CDS 4 |
| --- | --- |
| `CdsDropdown` | 🔁 `CdsSelect` (the native `<select>` from CDS 3 — via the `native-select` prop) |
| `CdsRadioButton` | 🔁 `CdsRadioGroup` |
| `CdsProgress` | 🔁 `CdsProgressBar` |
| `CdsTabsV2` | 🔁 `CdsTabs` |
| `CdsCheckboxGroup` | ⚠️ removed (use `CdsCheckbox` on its own) |
| `CdsContainer` | ⚠️ removed |
| `CdsBadge` | 🔁 props: `count`→`content`, `limited`→`:max`; ⚠️ `invertColor` removed |

After renaming, double-check the `api.md` of the new component in
`../components/` — prop contracts may have changed.

---

---
sourceHash: fd1b145c7543a70dd8d9773e38d2341cf367cb5b
---

# Tailwind CSS v4 + CDS 4

For Vite projects, install Tailwind CSS v4 by following the official Tailwind
guide: [Installing Tailwind CSS with Vite](https://tailwindcss.com/docs/installation/using-vite).

Below is the recommended way to integrate CDS 4 with Tailwind CSS v4.

- The Vite plugin goes into `vite.config.ts`
- Tailwind's CSS layer goes into `main.ts`

## 1. Install Tailwind CSS

```bash
npm install -D tailwindcss @tailwindcss/vite
```

## 2. Add the Vite plugin

Add `@tailwindcss/vite` to `vite.config.ts`:

```ts
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [tailwindcss()]
});
```

## 3. Create a `tailwind.css` file

For example, `src/tailwind.css`:

```css
@import "@central-design-system/components/styles/tailwind";
@import "tailwindcss/theme" layer(cds-utilities.tailwind);
@import "tailwindcss/utilities" layer(cds-utilities.tailwind);
```

This wires CDS tokens into Tailwind. You don't need `preflight` separately —
the base reset styles already come from `@central-design-system/components/styles`.

## 4. Import the styles in your app entry point

```ts
import { createApp } from 'vue';

import '@central-design-system/components/styles';
import './tailwind.css';

import { createCds, components, directives } from '@central-design-system/components';

import App from './App.vue';

const cds = createCds({
  components,
  directives
});

createApp(App).use(cds).mount('#app');
```

## 5. Use Tailwind utilities and CDS tokens together

```html
<template>
  <div class="flex flex-col gap-3 rounded-200 bg-surface-primary p-4 text-content-primary">
    <h1 class="text-900 font-bold text-brand-primary">Hello CDS + Tailwind</h1>
    <CdsButton>Click me</CdsButton>
  </div>
</template>
```

Once this is set up, you get both at the same time:

- standard Tailwind utilities: `flex`, `font-bold`, `gap-3`, `p-4`
- utility classes built from CDS tokens: `bg-surface-primary`, `text-content-primary`, `rounded-200`
- typography on the CDS scale: `font-sans` (the design system font), sizes
  `text-50`…`text-1100`, line heights `leading-50`…`leading-1100`, weights
  `font-regular` / `font-bold`, tracking `tracking-500`. Size and line height are
  separate utilities: `text-*` never touches `line-height`

Write spacing with the standard Tailwind numeric scale (`gap-2`, `p-4`,
`mt-2`): the CDS spacing scale matches it, so there is no need for
`gap-200`/`p-400`-style spacing classes. Token-based classes remain for
color, radius, and typography.

The CDS configuration stays in sync with the active CDS theme automatically, so
color utility classes switch along with the theme.

---

---
sourceHash: 099fbd8735b578ab40ec1e171e04b7c65a1f70b9
---

# Theming

The design system lets you switch themes or configure your own theme
programmatically, including at runtime.

## How it works

A theme in CDS 4 is a set of **semantic tokens** that are turned into CSS
variables when the application starts:

```
ThemeDefinition (TS)  →  --cds-color-* / --cds-* (CSS variables)  →  component styles
                                     ↓
                          @theme (Tailwind CSS v4)  →  bg-surface-primary, rounded-200, …
```

The variables hold **finished colors**, exactly as they are written in the
theme. The built-in themes write colors in `oklch()`. Opacity on top of a token
is set with `color-mix()`:

```css
/* generated by CDS */
:root {
  --cds-color-brand-primary: oklch(57.4% 0.16 254.98);
  --cds-color-surface-primary: oklch(100% 0 0);
  --cds-spacing-400: 1rem;
  --cds-border-radius-200: 0.25rem;
}

/* usage */
.my-block {
  background: var(--cds-color-surface-primary);
  border: var(--cds-border-100) solid color-mix(in srgb, var(--cds-color-brand-primary) 40%, transparent);
  padding: var(--cds-spacing-400);
}
```

> In CDS 3 and early CDS 4 builds the variables held RGB channels and a color
> was read as `rgb(var(--cds-color-x))`. That no longer works — see the
> migration guide.

Theme styles are injected into `<style id="cds-theme-stylesheet">` and are
recalculated reactively when the theme changes.

## Enabling a theme

CDS 4 ships eight ready-made themes:

| Theme         | Description                             |
| ------------- |-----------------------------------------|
| `cdsLight`    | light theme, used by default            |
| `cdsDark`     | dark theme                              |
| `b2bLight`    | light theme for B2B-Center applications |
| `b2bDark`     | dark theme for B2B-Center applications  |
| `lumaLight`   | light Luma theme                        |
| `lumaDark`    | dark Luma theme                         |
| `promoLight`  | light promo theme                       |
| `promoDark`   | dark promo theme                        |

> `cdsLight` is used by default — you don't need to enable it.

To switch to another theme, pass its name in the `createCds` options:

```ts
import { createApp } from 'vue';
import '@central-design-system/components/styles';
import { createCds, components, directives } from '@central-design-system/components';

import App from './App.vue';

const cds = createCds({
  components,
  directives,
  theme: {
    defaultTheme: 'b2bLight'
  }
});

createApp(App).use(cds);
```

## Theming options

```ts
createCds({
  theme: {
    defaultTheme: 'cdsLight',
    prefix: 'cds',
    themes: {},
    variations: false,
    utilities: true,
    legacyClasses: false,
    scoped: false,
    scope: undefined,
    stylesheetId: 'cds-theme-stylesheet',
    cspNonce: undefined
  }
});
```

| Option          | Type                                                        | Default                 | Purpose                                                                    |
| --------------- | ---------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------- |
| `defaultTheme`  | `ThemeName \| string`                                       | `'cdsLight'`            | Theme active at startup                                                     |
| `prefix`        | `string`                                                    | `'cds'`                 | Prefix of the generated CSS variables (`--cds-color-*`)                     |
| `themes`        | `Record<string, ThemeDefinition>`                           | built-in themes         | Your own themes; merged with the built-in ones                              |
| `variations`    | `false \| { colors: string[]; lighten: number; darken: number }` | `false`             | Auto-generation of lighter/darker color variations                          |
| `utilities`     | `boolean`                                                   | `true`                  | Generation of background/text utility classes from theme tokens             |
| `legacyClasses` | `boolean`                                                   | `false`                 | CDS 3 legacy classes (`cds-bg-*`, `cds-text-*`, `cds-border-*`)             |
| `scoped`        | `boolean`                                                   | `false`                 | Don't write the variables into `:root`                                      |
| `scope`         | `string`                                                    | —                       | Limit theme selectors to a subtree (`:where(<scope>)`)                      |
| `stylesheetId`  | `string`                                                    | `'cds-theme-stylesheet'`| `id` of the `<style>` tag holding the theme                                 |
| `cspNonce`      | `string`                                                    | —                       | `nonce` for Content Security Policy                                         |

## Creating your own theme

A custom theme is a `ThemeDefinition` object with the fields `dark`, `colors` and
`variables`. You only need to specify the **overrides**: missing tokens are
inherited from `cdsLight` / `cdsDark`.

A color can be written as hex, `rgb()` or `oklch()` — the value lands in the CSS
variable exactly as written. CDS computes the contrasting `on-*` text and the
variations for any of these formats.

```ts
import { createApp } from 'vue';
import { createCds, components, directives } from '@central-design-system/components';

import type { ThemeDefinition } from '@central-design-system/components';

import App from './App.vue';

const myCustomGreenTheme: ThemeDefinition = {
  dark: false,
  colors: {
    // Main brand colors of the new theme
    'brand-primary': 'oklch(55.5% 0.1605 142.24)',
    'brand-primary-hover': '#3C9C2C',
    'brand-primary-active': '#50A946',
    'brand-primary-border': '#2C8926',
    'brand-primary-content': '#005005',
    'brand-secondary': '#DCF5D0',
    'brand-secondary-hover': '#A5DD98',
    'brand-secondary-active': '#97D283',
    'brand-secondary-border': '#BCE8AB',
    // Surfaces
    'page-primary': '#F2F8F0',
    'surface-secondary': '#E8F3E4'
  },
  // Variables: typography, spacing, radii, shadows
  variables: {
    'font-family': 'Roboto, sans-serif',
    'border-radius-200': '0.625rem'
  }
};

const cds = createCds({
  components,
  directives,
  theme: {
    defaultTheme: 'myCustomGreenTheme',
    themes: {
      myCustomGreenTheme
    }
  }
});

createApp(App).use(cds);
```

Every registered theme also gets a `.cds-theme--<name>` class — use it to enable
the theme on an arbitrary part of the markup.

### Token groups

`colors` — semantic colors:

- `brand-*` — brand (`primary`, `secondary` and their `hover` / `active` / `border` / `content`)
- `surface-*`, `page-*`, `fill-*` — surfaces and fills
- `content-*` — text, icons, links
- `line-*` — borders, dividers, focus and selection
- `status-{success,warning,progress,info,danger,indication}-*` — statuses
- `other-*` — additional accent palettes

`variables` — dimensions: `spacing-*`, `font-size-*`, `font-line-height-*`,
`font-weight-*`, `border-*`, `border-radius-*`, `shadow-{x,y,blur}-*`,
`font-family`, `base-unit`.

For the full token list of a specific theme, see the package sources:
`@central-design-system/components/src/themes/cdsLight.ts`.

## Switching the theme

You can change the theme at runtime through the `useTheme` composable:

```vue
<script setup lang="ts">
import { useTheme } from '@central-design-system/components';

const theme = useTheme();

function toggleTheme(): void {
  theme.global.name.value = theme.global.current.value.dark ? 'cdsLight' : 'cdsDark';
}
</script>

<template>
  <cds-button @click="toggleTheme">Toggle theme</cds-button>
</template>
```

You can also change the theme of a single component by passing it the `theme`
prop. Keep in mind that the theme applies not only to the component itself but to
everything nested inside it:

```vue
<template>
  <cds-notification theme="b2bLight">
    <!-- the button will use the b2bLight theme -->
    <cds-button>Button</cds-button>
  </cds-notification>
</template>
```

The `theme` prop is supported by container components and most visual components:
`CdsApp`, `CdsLayout`, `CdsPage`, `CdsSurface`, `CdsCard`, `CdsDrawer`,
`CdsModal`, `CdsOverlay`, `CdsButton`, `CdsField`, `CdsTable` and others.

## Using theme tokens in your own code

### Tailwind CSS v4

Theme tokens are mapped into Tailwind's `@theme`, so utilities switch along with
the theme automatically:

```html
<div class="bg-surface-primary text-content-primary p-4 rounded-200">…</div>
```

Setup is described in Tailwind CSS v4 + CDS 4.

### CSS / SCSS

```scss
.my-card {
  background: var(--cds-color-surface-elevated);
  color: var(--cds-color-content-primary);
  padding: var(--cds-spacing-500);
  border-radius: var(--cds-border-radius-300);
}
```

When you override CDS component styles, put them into the `cds-overrides` layer —
that way they are guaranteed to win over the library's styles:

```scss
@layer cds-overrides {
  .cds-button {
    border-radius: var(--cds-border-radius-300);
  }
}
```

### CDS 3 legacy classes

The CDS 3 utility classes (`cds-bg-*`, `cds-text-*`, `cds-border-*`) are **off by
default** in CDS 4. To bring them back for the duration of a migration:

```ts
import '@central-design-system/components/styles/legacy';

const cds = createCds({
  theme: { legacyClasses: true }
});
```

## Disabling theming

Pass `false` to the `theme` option. This prevents the generation of CSS variables
and theme classes and disables runtime theme switching — the `<style>` tag is not
created at all.

```ts
import { createCds } from '@central-design-system/components';

const cds = createCds({
  theme: false
});
```

With theming disabled, `theme.isDisabled === true` and `themeClasses` returns
`undefined`.

## Theme instance interface

`useTheme()` returns a `ThemeInstance` — access to the current theme and its
settings.

```ts
interface ThemeInstance {
  /** Whether theming is enabled (`false` with `theme: false`) */
  readonly isDisabled: boolean;

  /**
   * Raw object of the installed themes
   * Themes can be added and modified
   */
  readonly themes: Ref<Record<string, InternalThemeDefinition>>;

  /**
   * Name of the current theme
   * Inherited from the parent component
   */
  readonly name: Readonly<Ref<string>>;

  /**
   * Processed object of the current theme
   * Includes the automatically generated colors
   */
  readonly current: DeepReadonly<Ref<InternalThemeDefinition>>;
  readonly computedThemes: DeepReadonly<Ref<Record<string, InternalThemeDefinition>>>;

  /** Class of the current theme — `cds-theme--<name>` */
  readonly themeClasses: Readonly<ComputedRef<string | undefined>>;

  /** Generated CSS of the current theme */
  readonly styles: Readonly<ComputedRef<string>>;

  readonly global: {
    /** Name of the current global theme in the application (writable) */
    readonly name: Ref<string>;

    /**
     * Processed object of the current global theme in the application
     * Also available from `theme.computedThemes.value[theme.global.name.value]`
     */
    readonly current: DeepReadonly<Ref<InternalThemeDefinition>>;
  };
}
```

The theme instance is also available on the object returned by `createCds()` —
handy outside of a component context:

```ts
const cds = createCds({ theme: { defaultTheme: 'cdsLight' } });

cds.theme.global.name.value = 'cdsDark';
```

---

---
sourceHash: 78639cefdd923c2927f1176d8866bf1131ed5cd2
---

# Motion

CDS 4 has a single motion scale: seven durations, a set of easing curves and two loops. It is the same for every theme (`cds`, `b2b`, `promo`, `luma`). You can use it four ways: ready-made Vue transitions, a Sass module, CSS variables and the `motion` JS object.

> Take steps from the scale instead of literals like `0.2s ease-in-out`. Your animations then run at the same pace as CDS components, and changing a value in the scale reaches every place at once.

## Duration scale

Press «Запустить» (Run): the markers travel the same distance, each in the time of its step.

| Name        | Value | Used for                                               |
| ----------- | ----- | ------------------------------------------------------ |
| `instant`   | 50ms  | press                                                  |
| `very-fast` | 100ms | entering hover, popover and checkmark disappearing     |
| `fast`      | 200ms | leaving hover, color and selection changes, appearance |
| `normal`    | 300ms | resizing a large block, modal and drawer appearance    |
| `slow`      | 400ms | expanding a large element                              |
| `very-slow` | 500ms | backdrop dimming                                       |
| `spring`    | 300ms | the time a spring takes to settle                      |

Loops sit outside the scale: the scale answers a user action, while a loop runs on its own. A pulse lasts 2s, a ripple 1.5s.

## Easing curves

The same duration on different curves: `enter` rushes in and brakes, `exit` accelerates and leaves, `standard` starts softly and stops softly. Switch the duration to compare the curves over a short and a long run.

| Name       | Value                               | Used for                                 |
| ---------- | ----------------------------------- | ---------------------------------------- |
| `standard` | `cubic-bezier(0.2, 0, 0, 1)`        | default: in-place changes and movement   |
| `enter`    | `cubic-bezier(0.05, 0.7, 0.1, 1)`   | appearance                               |
| `exit`     | `cubic-bezier(0.3, 0, 1, 1)`        | leaving only                             |
| `spring`   | `linear(…)`, M3 fast-spatial spring | a small object appearing with a bounce   |
| `loop`     | `cubic-bezier(0.37, 0, 0.63, 1)`    | the pulse loop                           |
| `ripple`   | `cubic-bezier(0, 0, 0.2, 1)`        | the ripple loop                          |
| `linear`   | `linear`                            | timer: the tick step equals the duration |

The `spring` bounce belongs to scale and position only. Use the spring on `transform`, not on `opacity` or `background-color`: color and opacity never bounce.

## What to choose

| Case                                   | Duration        | Curve             |
| -------------------------------------- | --------------- | ----------------- |
| press                                  | `instant`       | `standard`        |
| entering hover                         | `very-fast`     | `standard`        |
| leaving hover, selection change, color | `fast`          | `standard`        |
| popover, dropdown, toast appearing     | `fast`          | `enter`           |
| popover, checkmark leaving             | `very-fast`     | `exit`            |
| resizing a large block                 | `normal`        | `standard`        |
| modal, drawer: appear / leave          | `normal`/`fast` | `enter` / `exit`  |
| pulse / ripple                         | 2s / 1.5s       | `loop` / `ripple` |

## Ready-made transitions

Transitions are wrapper components over Vue `<Transition>` and `<TransitionGroup>`: put an element with `v-if` or `v-show` inside, no classes or styles needed. Pick a transition and hide or show the card:

| Transition                 | What it animates                                                       | Time and curve                                                                          | When to use                                                                                      |
| -------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `CdsTransitionFade`        | opacity                                                                | `fast` `enter` / `very-fast` `exit`                                                     | in-place appear and leave: hints, captions                                                       |
| `CdsTransitionSlideY`      | 8px vertical shift and opacity                                         | `fast` `enter` / `very-fast` `exit`                                                     | small blocks, dropdown content                                                                   |
| `CdsTransitionSlideX`      | 15px horizontal shift and opacity                                      | `fast` `enter` / `very-fast` `exit`                                                     | horizontal content changes                                                                       |
| `CdsTransitionSlideRight`  | full-width shift to the right; the leaving block leaves the flow       | `normal` `standard`                                                                     | paging forward: calendar, carousel                                                               |
| `CdsTransitionSlideLeft`   | full-width shift to the left; the leaving block leaves the flow        | `normal` `standard`                                                                     | paging back                                                                                      |
| `CdsTransitionJumpRight`   | 15px shift to the right and opacity; the leaving block leaves the flow | `normal` `standard`                                                                     | a value that "moves" forward: counters, captions                                                 |
| `CdsTransitionJumpLeft`    | 15px shift to the left and opacity; the leaving block leaves the flow  | `normal` `standard`                                                                     | the same in the other direction                                                                  |
| `CdsTransitionScale`       | scale from zero and opacity; leaving is a fade only                    | `fast` `enter` / `very-fast` `exit`                                                     | pop-up menus, tags                                                                               |
| `CdsTransitionExpand`      | height (JS): vertical expand and collapse                              | `fast` `standard`                                                                       | expandable panels, accordion                                                                     |
| `CdsTransitionExpandX`     | width (JS): the same horizontally                                      | `fast` `standard`                                                                       | side panels, collapsible columns                                                                 |
| `CdsTransitionPresence`    | fade, then collapse of height, spacing and border                      | leave `very-fast` `exit` + `fast` `standard`; appear `fast` `standard` + `fast` `enter` | a block leaves the flow and neighbors must move smoothly; this is how a `CdsTree` branch expands |
| `CdsTransitionModalBottom` | slides in from the bottom of the screen                                | `normal` `enter` / `fast` `exit`                                                        | a panel or window coming from the bottom                                                         |
| `CdsTransitionModalTop`    | slides in from the top of the screen                                   | `normal` `enter` / `fast` `exit`                                                        | a panel or window coming from the top                                                            |
| `CdsModalTransition`       | the modal unfolds from a source element (`target` prop)                | `normal` `enter` / `fast` `exit`; content `normal`×2 / `fast`×2 on `standard`           | a modal that "flies out" of a button or card                                                     |

Props depend on the kind of transition:

- **CSS transitions** (`Fade`, `Slide*`, `Jump*`, `Scale`, `Modal*`): `mode`, `group` (a list via `TransitionGroup`), `disabled` (no animation), `hideOnLeave` (hides the leaving element with `display: none`), `leaveAbsolute` (takes the element out of the flow while it leaves) and `origin` (the point scale starts from).
- **JS transitions** (`Expand`, `ExpandX`): `mode`, `disabled`, `group`, `hideOnLeave`.
- **`CdsTransitionPresence`**: `appear`, `group`, `disabled` — see below.
- **`CdsModalTransition`**: a single `target` prop — the element or `[x, y]` coordinates the modal unfolds from.

You can play with every prop in Storybook, in the «Песочница: переходы» (Transitions playground) story.

What the transitions share:

- A leaving element taken out of the flow (`SlideRight`, `SlideLeft`, `Jump*` and any CSS transition with `leaveAbsolute`) does not take clicks: a click will not land on something that is already leaving.
- Under `prefers-reduced-motion`, shifts and scale are replaced with a fade. `Expand` and `ExpandX` change size instantly under reduced motion. JS transitions (`Expand`, `ExpandX`, `CdsModalTransition`) read the mode at mount, and `disabled` follows it by default.

### `CdsTransitionPresence`: a block leaving the flow

When a notification, alert or list row leaves the page, a fade alone is not enough: a gap stays behind and the neighbors jump into it. Collapsing the height at the same time as the fade shows squashed text. `CdsTransitionPresence` does it in two phases — add and remove a few invoices:

1. **Leave.** A `very-fast` fade on the `exit` curve, then a `fast` collapse on `standard`. Vertical spacing and the border collapse together with the height, so no gap remains.
2. **Enter** runs in reverse: a `fast` expand on `standard`, then a `fast` fade-in on `enter`.
3. Under `prefers-reduced-motion` only the fade stays; the space closes and opens instantly.

This is how `CdsTree` branches expand and `CdsNotification` leaves. Set the spacing between list blocks with `margin`, not with `gap` on the container: `margin` collapses together with the block, while `gap` disappears with a jump at the end of the leave.

| Prop       | What it does                                                 |
| ---------- | ------------------------------------------------------------ |
| `appear`   | play the transition on the initial render                    |
| `group`    | use `TransitionGroup` — for a list of elements               |
| `disabled` | disable the animation: elements appear and disappear at once |

Other `Transition` and `TransitionGroup` attributes (for example, `tag` on a list) are passed through. `@after-leave` fires after both phases — a handy point to emit a close event:

```vue
<CdsTransitionPresence @after-leave="emit('closed')">
  <div v-if="visible" class="alert">Saved</div>
</CdsTransitionPresence>
```

Hook listeners (`@enter`, `@after-leave` and others) receive only the element.

## Pulse and ripple

A pulse signals "happening now": the dot breathes with opacity. A ripple signals "something new": a ring under the dot grows twice its size and fades. Both loops are turned on where needed and do not run under `prefers-reduced-motion`. A ready-made example of a signaling loop is `CdsStatus` with the `indicator` and `pulse` props: the status dot breathes while the process is going. The pulse is endless, so under [WCAG 2.2.2](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html) turn it on only while the signal is relevant.

In SCSS the same loops come from mixins, which declare their keyframes themselves:

```scss
@use '@central-design-system/components/styles/motion';

.status-dot {
  @include motion.pulse;
}

.status-dot__ring {
  @include motion.ripple;
}
```

## Reduced motion

Under `prefers-reduced-motion: reduce`, shifts, scale and springs turn off. Opacity and color stay: state feedback does not disappear, and a color change does not cause vestibular discomfort.

Loops fall into two classes:

- **Decorative or signaling** — pulse, ripple and the `CdsSkeletonLoader` shimmer. Turns off: the status reads without animation, and endless blinking is exactly what such a user asks to get rid of.
- **Progress indicator** — `CdsLoader`, indeterminate `CdsProgressBar`. Keeps running: a frozen spinner reads as a hang. [WCAG 2.2.2](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html) treats such motion as essential.

Write your own progress indicator without `spatial`. DS components follow the same policy: the skeleton shimmer is off under reduced motion, while `CdsLoader` and the indeterminate `CdsProgressBar` keep running.

To check the behavior without changing system settings, use Chrome DevTools: menu ⋮ → More tools → Rendering → Emulate CSS media feature `prefers-reduced-motion` → `reduce`. The demos on this page switch right away.

> If you enable the legacy reset (`$legacy-reset: true`), it does not impose the reduced-motion policy: the CDS 3 markup compatibility reset does not mute animations.

## Reference

The values in the Sass module, the CSS variables and `motion` match — a test checks it.

### Sass module

The module is a separate entry and pulls in nothing else, so it fits any SCSS in your project. The functions return plain values, not `var()`: you can do math with them in Sass (add up delays, sum phases).

```scss
@use '@central-design-system/components/styles/motion';
```

| Call                                                            | Returns                                                          |
| --------------------------------------------------------------- | ---------------------------------------------------------------- |
| `motion.duration(<name>)`                                       | the step duration, for example `200ms`                           |
| `motion.easing(<name>)`                                         | the curve, for example `cubic-bezier(0.2, 0, 0, 1)`              |
| `motion.transition(<properties>, <duration>, <curve>, <delay>)` | a `transition` list: every property with one step                |
| `motion.interactive-transition(<properties>, <state>)`          | the `interactive` step for the `rest`, `hover` or `active` state |

A name that is not in the scale is a compile error listing the valid names. The property list of `transition` is required: the module never writes `transition: all`.

**State change.** `transition` takes space-separated properties, a duration and a curve (`standard` by default). Several calls join with commas:

```scss
.tooltip {
  transition: motion.transition(opacity transform, fast, enter);

  &.is-leaving {
    transition: motion.transition(opacity, very-fast, exit);
  }
}

.handle {
  transition:
    motion.transition(left, fast),
    motion.transition(right, fast, $delay: very-fast);
}
```

**Hover and press.** `@include motion.interactive(<properties>)` spreads the steps over the states: leaving hover 200ms, entering 100ms, press 50ms. The browser takes the `transition` of the state the element moves into, so the steps live on the states. If the hover is on an ancestor and the transition on a descendant, take the step by hand:

```scss
.chip {
  @include motion.interactive(background-color border-color color);
}

.card:hover .arrow {
  transition: motion.interactive-transition(transform, hover);
}
```

**Scale and position.** Put everything that moves or scales into `spatial`: under reduced motion it turns off, while color and opacity stay. If the DS itself sets a shift that would otherwise remain, pair it with `reduced` — rules for reduced-motion users only:

```scss
.badge {
  @include motion.spatial {
    animation: pop motion.duration(spring) motion.easing(spring);
  }
}

.drawer-content {
  transform: translateX(-16px);

  @include motion.reduced {
    transform: none;
  }
}
```

### CSS variables

The same values sit on `:root` — for plain CSS, inline styles and Tailwind. The names follow the scale: `--cds-motion-duration-<name>`, `--cds-motion-easing-<name>`, `--cds-motion-loop-<name>` (names from the tables above). Switching the theme does not change them.

```css
.toast {
  transition: opacity var(--cds-motion-duration-fast) var(--cds-motion-easing-enter);
}
```

### The `motion` JS object

When a script drives the motion — a timer, the Web Animations API, a delay calculation — take the scale from `motion`. Durations and loops are numbers in milliseconds, curves are CSS strings.

```ts
import { motion } from '@central-design-system/components';

motion.durations.fast; // 200
motion.easings.enter; // 'cubic-bezier(0.05, 0.7, 0.1, 1)'
motion.loops.pulse; // 2000

el.animate([{ opacity: 0 }, { opacity: 1 }], {
  duration: motion.durations.fast,
  easing: motion.easings.enter
});
```

---

---
sourceHash: b1ba0f5864509842881b42ebf6cfb46aadcba96f
---

# Tree-shaking

CDS 4 is published as an ESM bundle with its module structure preserved: every
component is a separate chunk with its own CSS next to it. That lets the bundler
(Vite, webpack, Rollup) drop everything your application doesn't use.

For this to work, follow two rules:

1. **Register only the components you actually need in `createCds`.**
2. **Include the base styles selectively** rather than the whole `styles.css`.

Below is how to do that and how much it saves.

## How it works

- The ESM bundle is built with `chunkSplitPlugin({ strategy: 'unbundle' })` — the
  library's module structure is preserved and components are not glued into a
  single file.
- `package.json` declares `sideEffects`, so the bundler knows the library's JS
  modules are pure and safe to remove.
- During the build, each component's chunk gets an import of its own CSS
  appended. That's why `import { CdsButton }` pulls in exactly `CdsButton.css`,
  not the styles of the entire library.

No special build or plugin is required — ordinary named imports are enough.

## Selective component registration

Pass only the components you use to `createCds`:

```ts
import { createApp } from 'vue';

import '@central-design-system/components/styles/common.css';
import { createCds, CdsButton, CdsCard, CdsIcon } from '@central-design-system/components';

import App from './App.vue';

const cds = createCds({
  components: { CdsButton, CdsCard, CdsIcon }
});

createApp(App).use(cds).mount('#app');
```

Components registered this way are available in templates globally — just as with
full registration:

```html
<template>
  <CdsCard>
    <CdsButton>Click me</CdsButton>
  </CdsCard>
</template>
```

> **Important:** `createCds` does not register components on its own. The set is
> always defined by the caller. That's deliberate: if the factory referenced the
> full component list, the bundler could not remove a single one of them.

### Alternative: a local import in an SFC

If you need a component in one or two places, global registration is optional —
import it right inside the component:

```html
<script setup lang="ts">
import { CdsButton } from '@central-design-system/components';
</script>

<template>
  <CdsButton>Click me</CdsButton>
</template>
```

You still need `createCds` in the entry point — it supplies themes, locales,
icons and breakpoints through `provide`. But you don't have to pass `components`
to it at all.

## Full registration

When the set of components is not known in advance (internal admin panels,
sandboxes, documentation), it's easier to register everything:

```ts
import { createCds, components, directives } from '@central-design-system/components';

const cds = createCds({ components, directives });
```

Such a call disables component tree-shaking: the `components` namespace import
keeps the whole library in the bundle.

## Styles

Component styles are included automatically along with the components themselves.
The only thing you have to include manually is the **base layer** — reset, fonts,
CSS layer order and global element styles:

```ts
import '@central-design-system/components/styles/common.css';
```

The base layer is mandatory: it's where the `@layer` order is declared, and the
correct cascade of component styles depends on it.

Take `common.css`, not `core.css`: `core.css` has no typography, so headings
(`h1`–`h6`) keep browser sizes instead of the CDS scale.

Available options:

| Import | Size | What's inside |
| --- | --- | --- |
| `styles/common.css` | ~9 KB | The recommended base: `core` + typography + grid utilities |
| `styles/core.css` | ~2 KB | Layers, fonts and reset only — **no typography** |
| `styles/tailwind.css` | ~12 KB | CDS tokens for Tailwind CSS v4 |
| `styles/legacy.css` | ~253 KB | Compatibility with legacy CDS 3 markup |

> **Don't use `@central-design-system/components/styles` in a tree-shaking
> scenario.** It's a ~556 KB aggregate containing the CSS of every component in
> the library. It's convenient for a quick start, but it completely defeats
> selective registration.

Color tokens (`--cds-color-*` and the rest) are not in the CSS files — they are
generated and injected into the document by `createCds` at runtime, based on the
active theme. There is nothing extra to include.

## Directives

Directives (`ClickOutside`, `Intersect`, `Touch`) are named exports and are
registered just as selectively:

```ts
import { createCds, ClickOutside } from '@central-design-system/components';

const cds = createCds({
  components: { /* ... */ },
  directives: { ClickOutside }
});
```

The library's own components don't need you to register directives — the ones
that use `ClickOutside`, `Intersect` and `Touch` internally (`CdsOverlay` and
everything built on it: `CdsSelect`, `CdsMenu`, `CdsTooltip`, `CdsSlideView`,
input fields) import them themselves and register them locally. Pass `directives`
to `createCds` only for your own markup — `v-click-outside`, `v-intersect`,
`v-touch` in the application's templates.

> **In `4.0.0-alpha.0`:** local registration inside components didn't work, and
> the `CdsSelect` / `CdsMenu` menus wouldn't close on an outside click unless
> `directives` was passed to `createCds`. If you can't upgrade, add
> `directives: { ClickOutside, Touch }` to the registration.

## How much it saves

Measurements on Vite 5 (production, minified, styles in a separate file, Vue
included in the bundle, the base `common.css` not counted):

| Scenario | JS | JS (gzip) | CSS | CSS (gzip) |
| --- | --- | --- | --- | --- |
| Full registration (`components`, `directives`) | 625 KB | 203 KB | 208 KB | 24.6 KB |
| `createCds` + 3 components | 196 KB | 62.6 KB | 27.6 KB | 4.1 KB |
| `createCds` + 1 component | 162 KB | 51.4 KB | 12.6 KB | 1.9 KB |
| 1 component without `createCds` | 63 KB | 23.4 KB | 12.6 KB | 1.9 KB |

The numbers depend on which components exactly you include: composite components
(`CdsTable`, `CdsAutocomplete`, `CdsDatePicker`) pull in more dependencies than
atoms do.

### What isn't tree-shaken

About 99 KB is the core that `createCds` always includes: themes, locales, icons,
breakpoints (`useDisplay`), `goTo` and the `defaults` system. That volume doesn't
depend on the number of components — it is exactly the difference between the
"1 component without `createCds`" (63 KB) and "`createCds` + 1 component"
(162 KB) rows.

If CDS is used in a couple of places and you don't need the global subsystems,
you can skip `createCds` entirely. But then there are no themes, no locales and
no defaults, so that mode only suits pinpoint embeds.

## How to verify the result

```bash
npx vite-bundle-visualizer
```

What to look for:

- the bundle should contain no chunks of components missing from your `createCds`;
- if an "extra" component shows up, it is most likely imported transitively
  (`CdsSelect` pulls in `CdsMenu` and `CdsList`, for instance) — that's normal;
- if the whole library ended up in the bundle, look for `components` or
  `import * as` among your imports.

## Common mistakes

**A namespace import instead of a named one.** Any `import * as` from the library
keeps all of it:

```ts
// ❌ pulls in every component
import * as cdsComponents from '@central-design-system/components';

// ✅
import { CdsButton } from '@central-design-system/components';
```

**Importing icon packs through `iconsets`.** The `iconsets` object references all
packs at once, so it is not tree-shaken: the bundle gets the JS of every pack
(including `cds` — 46 KB) and, since UnoCSS scans them itself, the CSS of all five
packs (≈370 KB instead of ≈70 KB). Import the pack through its subpath:

```ts
// ❌ pulls in every pack
import { iconsets } from '@central-design-system/components';
const aliases = iconsets.remix.aliases;

// ✅ remix only
import { remix } from '@central-design-system/components/iconsets/remix';
const aliases = remix.aliases;
```

**Including the style aggregate.** `@central-design-system/components/styles`
contains the CSS of every component — use `styles/common.css`.

**Your own barrel re-export.** A `src/ui/index.ts` file that re-exports dozens of
CDS components kills tree-shaking if you import everything from it. Import
components directly from the library.

**A bundler without ESM support.** The CJS bundle (`dist/cjs`) and the IIFE build
are not tree-shakable by design. Make sure your bundler resolves the `import`
export condition — Vite, webpack 5 and Rollup do it by default.

---

---
sourceHash: aeca413bbfa5978094c5de9aaab7d6d75bda0c1e
---

# SASS variables

CDS 4 styles are written in SASS/SCSS, and part of the internal setup — the base
reset, global typography, font, grid and breakpoints — is extracted into SASS
variables flagged with `!default`. You can override them when building your
application through the standard
[module configuration](https://sass-lang.com/documentation/at-rules/use/#configuration)
mechanism: `@use '…' with (…)`.

> SASS variables are the **compile-time** configuration layer. Colors, spacing
> and the rest of the component design tokens live in CSS variables (`--cds-*`)
> and are configured by themes at runtime — see Theming. Start
> with the theme; drop down to SASS variables when you need to change the base
> layer itself: reset, typography, grid.

## Setup

Vite compiles SCSS out of the box — you only need the preprocessor itself:

```bash
npm install -D sass-embedded
```

The classic `sass` works too, but `sass-embedded` is noticeably faster. To speed
up large builds, opt into the modern compiler API:

```ts
// vite.config.ts
export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: { api: 'modern-compiler' }
    }
  }
});
```

## Plugging in with a configuration

Normally the base styles are plugged in as ready-made CSS —
`import '@central-design-system/components/styles'`. To override SASS variables,
replace that import with your own SCSS file: in SCSS the
`@central-design-system/components/styles` entry point resolves to the **sources**
of the base layer (the `sass` export condition in `package.json`), and your
configuration is applied at compile time.

```diff
// main.ts
import { createApp } from 'vue';

- import '@central-design-system/components/styles';
+ import './styles/main.scss';
```

```scss
// src/styles/main.scss
@use '@central-design-system/components/styles' with (
  $reset: false,
  $body-font-family: ('Inter', sans-serif)
);
```

The component styles themselves need nothing extra: they are precompiled and ship
with the components' JS chunks — both with selective and with full registration
(see Tree-shaking).

> Wrap a value containing commas — `$body-font-family` with several fonts, for
> instance — in parentheses, otherwise SASS reads it as several arguments.

## A settings file

Module configuration is applied once, on the first load. If you need the values
not only in the entry point but also in your application's component styles,
extract them into a separate settings file and use that everywhere:

```scss
// src/styles/settings.scss
@forward '@central-design-system/components/styles/settings' with (
  $body-font-family: ('Inter', sans-serif),
  $grid-gutter: 24px
);
```

```scss
// src/styles/main.scss
@use './settings'; // configures the CDS variables
@use '@central-design-system/components/styles'; // the base is built with them
```

```html
<!-- Component.vue -->
<style lang="scss">
@use '@/styles/settings' as s;

.card {
  gap: s.$grid-gutter;
  font-family: s.$body-font-family;
}
</style>
```

Every `<style>` block is compiled separately, so "configure it in `main.scss` and
read it straight from the package" won't work — a direct
`@use '@central-design-system/components/styles/settings'` in a component would
return the default values. A shared settings file guarantees identical values at
every compilation point.

The `styles/settings` entry contains variables only and emits not a single byte
of CSS — it's safe to include in any number of files.

## Global variables

| Variable | Default | What it does |
| --- | --- | --- |
| `$reset` | `true` | Emit the base layer's CSS reset |
| `$legacy-reset` | `false` | Reset for compatibility with CDS 3 markup |
| `$enable-typography` | `true` | Global typography (`h1`–`h6`, `.h1`–`.h6` and so on) |
| `$body-font-family` | `var(--cds-font-family), 'PT Root UI VF', …` | `body` font |
| `$font-size-root` | `var(--cds-base-unit)` (16px) | Root font size |
| `$line-height-root` | `1.5` | Root line height |
| `$border-color-root` | `transparent` | Default border color |
| `$border-style-root` | `solid` | Default border style |
| `$border-radius-root` | `var(--cds-border-radius-200)` | Base corner radius |
| `$size-scale` | `4px` | Step of the size scale |
| `$sizes` | `('xs', 'sm', 'md', 'lg', 'xl')` | Size names |
| `$rounded` | map | Radius scale (`sm`, `md`, `lg`, `xl`, `pill`, `circle`, …) |

## Grid and breakpoints

| Variable | Default | What it does |
| --- | --- | --- |
| `$prefix` | `'cds'` | Prefix of the grid CSS classes |
| `$flex-grid-columns` | `16` | Number of flex grid columns (`12` is supported too) |
| `$grid-gutter` | `32px` | Grid gutter |
| `$grid-gutter-condensed` | `1px` | Gutter of the condensed grid |
| `$grid-breakpoints` | map | Breakpoints: width, columns and spacing for `xs`–`xl` |

The grid variables belong to the same settings module, while the breakpoint and
grid mixins live in a separate `styles/breakpoints` entry — which emits no CSS
either:

```scss
@use '@/styles/settings' as s;
@use '@central-design-system/components/styles/breakpoints' as bp;

.sidebar {
  gap: s.$grid-gutter;

  @include bp.cds-breakpoint-up('md') {
    width: 320px;
  }
}
```

> SASS breakpoints affect your styles and the grid mixins. The runtime
> breakpoints of `useDisplay` are configured separately, through the `display`
> option of `createCds` (see Display & Platform).
> The two sets match by default; when you change one, don't forget the other.

## Component variables and vite-plugin

Without the plugin, `@use … with` configures the base layer only: component CSS
is precompiled. The `@central-design-system/vite-plugin` plugin lifts that
limitation — it recompiles the styles of every component you use with your
settings file:

```ts
// vite.config.ts
import cds from '@central-design-system/vite-plugin';

export default defineConfig({
  plugins: [
    vue(),
    cds({ styles: { configFile: 'src/styles/settings.scss' } })
  ]
});
```

The settings file is the same, but you have to forward
`styles/component-settings` — the aggregate that includes both global and
component variables:

```scss
// src/styles/settings.scss
@forward '@central-design-system/components/styles/component-settings' with (
  $border-radius-root: 0,          // global
  $button-border-radius: 9999px    // component-level
);
```

With the plugin you don't need to change the
`@central-design-system/components/styles` import in `main.ts` — it starts
meaning "the configured base layer" on its own, and component styles are rebuilt
on the fly. The plugin can also auto-import components from templates
(`autoImport: true` by default), which makes registration in
`createCds({ components })` optional.

## What SASS can't configure

- **Component-local variables** (`$button-border-radius` and friends from
  `styles/_CdsX.variables.scss`). Unavailable without the plugin: component CSS
  is published precompiled, so its local variables are frozen at the moment the
  library was built. With `@central-design-system/vite-plugin` they are
  configured through `styles/component-settings` — the plugin recompiles the
  published SCSS sources of the components with your settings file (see above).
- **Turning off individual utility classes.** Instead of a toggle map, pick an
  entry point by content: `styles/core` — layers, fonts and reset only;
  `styles/common` — plus typography and helpers.
- **CSS layers.** `@layer cds-*` is always on: the layer order is declared in the
  base style layer, and ordinary application CSS (outside `@layer`) always beats
  the design system's styles — there is nothing to turn off here.

## Pitfalls

- **Variables only in the settings file.** Any styles or imports of regular style
  files inside `settings.scss` get duplicated into every file that includes it.
  Styles belong in `main.scss`; the settings file holds variables, mixins and
  functions.
- **Configure before the module's first load.** `@use … with` fails with a
  `module was already loaded` error if the settings module has already been
  loaded without a configuration higher up the chain. Include the settings file
  first.
- **Build speed.** With ready-made CSS there is nothing to compile; with a
  configuration the base layer is built together with the application. The volume
  is small, but the difference shows on cold builds — `sass-embedded` and
  `api: 'modern-compiler'` keep it to a minimum.
- **Resolution assumes a bundler.** Bare imports such as
  `@use '@central-design-system/components/styles'` are resolved by Vite and
  webpack (`sass-loader`) through the `sass` export condition. In plain `sass`
  CLI without a bundler you'll have to point the paths at the files inside
  `node_modules` by hand.

---

---
sourceHash: 90f87bac9abbe675fb21d70518488a5442172f5b
---

# Icons

CDS v4 supports many popular icon packs out of the box.

## Usage

By default CDS draws icons with the [Phosphor](https://phosphoricons.com/) pack. There is nothing to set up: the CSS for every icon the components use ships with the package. You do not need UnoCSS or `@iconify-json/ph` for it.

```ts
import { createCds } from '@central-design-system/components';

const cds = createCds();

app.use(cds);
```

After that, use icons in your templates:

```html
<template>
  <CdsIcon icon="add" />
</template>
```

An icon name describes its purpose: `close` closes a container, `remove` removes an item or a value, `warning` and `error` are different statuses. See the full list in the icon gallery.

Icons are stored in CSS as `data:` URIs. If your project sets a Content Security Policy, its `img-src` directive must allow `data:`. Printed icons are always black: the color comes from a mask, which does not print correctly.

CDS 3 names keep working throughout 4.x: the icon resolves to its new name and a `[CDS UPGRADE]` warning appears in the dev console. Old names are removed in 5.0. The replacement table is in the migration guide.

### Replacing a single icon

To replace specific icons, pass only those. The other names stay drawn by the selected pack:

```ts
const cds = createCds({
  icons: {
    aliases: {
      remove: 'class:my-remove-icon',
    }
  },
});
```

## Installing icon packs through UnoCSS

CDS integrates with [UnoCSS Preset Icons](https://unocss.dev/presets/icons), which
supports every icon pack available on [Iconify](https://icon-sets.iconify.design/).

Icons are tree-shaken, so only the icons you actually use end up in the final CSS
bundle. You can register several packs at once and freely mix icons from any of
them in your components.

### Icon packs

For the packs listed below, CDS ships iconsets with alias mappings — aliases for
the icons CDS components use (checkboxes, dropdowns, radio buttons and so on).
Pick one of them as the default pack (`defaultSet`); the alias mappings can be
overridden if needed.
Additional packs — without aliases — can be plugged in alongside and used freely
in your own templates.

| Icon library                                     | Iconify package                  | Iconset import                                               | Set name          |
|--------------------------------------------------|----------------------------------|--------------------------------------------------------------|-------------------|
| [Phosphor Icons](https://phosphoricons.com/)     | not needed for aliases           | `@central-design-system/components/iconsets/phosphor`        | `phosphor`        |
| [Remix Icon](https://remixicon.com/)             | `@iconify-json/ri`               | `@central-design-system/components/iconsets/remix`           | `remix`           |
| [Lucide](https://lucide.dev/)                    | `@iconify-json/lucide`           | `@central-design-system/components/iconsets/lucide`          | `lucide`          |
| [Tabler Icons](https://tabler.io/icons)          | `@iconify-json/tabler`           | `@central-design-system/components/iconsets/tabler`          | `tabler`          |
| [Material Symbols](https://fonts.google.com/icons) | `@iconify-json/material-symbols` | `@central-design-system/components/iconsets/materialSymbols` | `materialSymbols` |

Each module exports an object named after the pack: `icons` (the pack itself, for
`sets`) and `aliases` (the aliases, for `aliases`).

Install the pack you need from the table above:

```bash
npm install @iconify-json/ri
```

> Icons from the table run through UnoCSS, so you have to install and configure
> UnoCSS first. See the [official documentation](https://unocss.dev/integrations/)
> for details.

Here is an example integration in a Vite project.

1. Install UnoCSS as a dev dependency (see the [Vite integration](https://unocss.dev/integrations/vite)):

```bash
npm install -D unocss
```

2. Add the UnoCSS plugin to your Vite config:

```ts
// vite.config.ts
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UnoCSS(),
  ],
})
```

3. Create an **unocss.config.ts** file in the project root:

```ts
// unocss.config.ts
import { presetIcons, defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      processor(props) {
        delete props.color
      },
    }),
  ],
})
```

> Nothing else needs to go into `unocss.config.ts`: CDS iconsets carry the
> `@unocss-include` marker, so UnoCSS scans them on its own — even though they
> live in `node_modules` as `.js` files, which are not part of
> `content.pipeline.include` by default.

4. Pass the icon pack to `createCds()`.
The example uses the **[Remix](https://remixicon.com/)** pack, but you can swap it
for any other pack from the table above:

```ts
import { createCds } from '@central-design-system/components';
import { remix } from '@central-design-system/components/iconsets/remix';

const cds = createCds({
  icons: {
    defaultSet: 'remix',
    aliases: remix.aliases,
    sets: {
      remix: remix.icons,
    }
  },
});

app.use(cds);
```

> Import the pack through the `@central-design-system/components/iconsets/<pack>`
> subpath, not from the shared `iconsets` object. The shared object references all
> packs at once and is not tree-shaken — you would ship the extra JS and CSS of all
> packs.

After that, pick any icon from the pack — for example
[ri:settings-3-line](https://icon-sets.iconify.design/ri/?icon-filter=settings-3-line) —
and use it in templates:

```html
<CdsButton icon="i-ri:settings-3-line" />
```

> UnoCSS uses the `i-` prefix for icons. CDS uses the same prefix and already
> configures its aliases with it — don't change it, or the CDS aliases will stop
> working.

## Your own pack in components

Any Iconify pack works without a CDS map: install `@iconify-json/<pack>` and write the class in your template, for example `icon="i-mdi:home"`.

To make components draw with your pack too, pass your own `aliases` map to `createCds`. Names missing from it are drawn by the default pack. UnoCSS will not find the classes from this map by itself: CDS packs carry `@unocss-include`, your project file does not. Add the map file to `content.pipeline.include` or list the classes in `safelist`, otherwise the icons silently do not render.

```ts
// unocss.config.ts
import { presetIcons, defineConfig } from 'unocss'

export default defineConfig({
  content: {
    pipeline: {
      include: [/\.vue$/, 'src/icons/aliases.ts'],
    },
  },
  presets: [presetIcons()],
})
```

## Pack credits

| Pack             | Author              | License                                                                           |
|------------------|---------------------|-----------------------------------------------------------------------------------|
| Phosphor         | Phosphor Icons      | [MIT](https://github.com/phosphor-icons/core/blob/main/LICENSE)                   |
| Remix Icon       | Remix Design        | [Apache-2.0](https://github.com/cyberalien/RemixIcon/blob/master/License)         |
| Lucide           | Lucide Contributors | [ISC](https://github.com/lucide-icons/lucide/blob/main/LICENSE)                   |
| Tabler Icons     | Paweł Kuna          | [MIT](https://github.com/tabler/tabler-icons/blob/master/LICENSE)                 |
| Material Symbols | Google              | [Apache-2.0](https://github.com/google/material-design-icons/blob/master/LICENSE) |

If you add a pack under a CC-BY license (Solar, for example), your project must credit its author.

## The `cds` pack

The CDS 3 pack of inline SVGs is deprecated and keeps working throughout 4.x. Use it to keep the familiar look while moving from CDS 3:

```ts
const cds = createCds({
  icons: {
    defaultSet: 'cds'
  },
});
```

New names the pack has no drawing for use a Phosphor glyph.

## Legacy icons package from CDS v3

The `@central-design-system/icons` package is deprecated and is removed in 5.0. When it is connected, the `cds` pack draws component icons, and the `Icon*` components from the package stay registered globally:

```bash
npm install @central-design-system/icons
```

```ts
import * as icons from '@central-design-system/icons';

const cds = createCds({
  icons
});

app.use(cds);
```

---

---
sourceHash: 2d02d03da0e4d6f0fcb171775b7b88784a216ac0
---

# Display & Platform

Central Design System exposes reactive information about the **screen**
(breakpoints, viewport size, mobile mode) and the **platform** (browser, OS,
device type) through a single composable — `useDisplay`. Breakpoints are the same
in JavaScript and in styles (the `cds-breakpoint-*` SCSS mixins), so responsive
logic in script and CSS always agrees.

## Breakpoints

| Breakpoint | Width range (px) | Start width | Grid columns |
| --- | --- | --- | --- |
| `xs` | `0 … 671` | `0` | 4 |
| `sm` | `672 … 1055` | `672` | 8 |
| `md` | `1056 … 1311` | `1056` | 16 |
| `lg` | `1312 … 1583` | `1312` | 16 |
| `xl` | `1584 … ∞` | `1584` | 16 |

The values have a single source:

- JS — `defaultDisplayOptions.thresholds` (`src/composables/useDisplay/internal/useDisplay.constants.ts`);
- SCSS — `$grid-breakpoints` (`src/styles/utilities/grid/_config.scss`).

## In JavaScript — `useDisplay`

The `useDisplay` composable returns the reactive state of the screen and the
platform. It works out of the box as long as the application is initialized
through `createCds` (which provides `cds:display`).

```ts
import { useDisplay } from '@central-design-system/components';

const display = useDisplay();

display.width.value; // current viewport width, px
display.name.value; // 'xs' | 'sm' | 'md' | 'lg' | 'xl'
display.mobile.value; // true when width < mobileBreakpoint ('sm' by default)
```

### Available flags

| Flag | Meaning |
| --- | --- |
| `xs` / `sm` / `md` / `lg` / `xl` | exactly one is active — the current breakpoint |
| `smUp` / `mdUp` / `lgUp` / `xlUp` | width ≥ the breakpoint's start width ("and up") |
| `smDown` / `mdDown` / `lgDown` / `xlDown` | the breakpoint and everything below it ("and down") |
| `name` | name of the current breakpoint |
| `mobile` | mobile mode (based on `mobileBreakpoint`) |
| `mobileBreakpoint` | current mobile mode threshold |
| `width` / `height` | viewport size, px |
| `thresholds` | current threshold map |
| `platform` | platform/browser flags (see [Platform](#platform)) |
| `update()` | force a recalculation of size and platform |

For example, `mdUp` is true when `width ≥ 1056`, and `smDown` when `width < 1056`
(that is, it covers the `xs` and `sm` ranges).

### Example in a component

```tsx
import { useDisplay } from '@central-design-system/components';

const { mobile, mdUp } = useDisplay();

defineRender(() => (
  <div class={{ 'is-mobile': mobile.value }}>
    {mdUp.value ? <DesktopLayout /> : <MobileLayout />}
  </div>
));
```

### Mobile mode at the prop level

Components that mix in `defineDisplayProps()` accept the `mobile` and
`mobileBreakpoint` props — use them to override the mobile mode threshold
locally:

```html
<!-- Mobile mode kicks in below 1056px (md) instead of the global 'sm' -->
<CdsSlideGroup mobile-breakpoint="md" />
```

### Overriding the thresholds globally

Thresholds and `mobileBreakpoint` are configured at initialization:

```ts
import { createCds } from '@central-design-system/components';

app.use(createCds({
  display: {
    mobileBreakpoint: 'md',
    thresholds: { xs: 0, sm: 600, md: 960, lg: 1280, xl: 1920 }
  }
}));
```

> If you change the thresholds in JS, keep them in sync in SCSS
> (`$grid-breakpoints`) — otherwise responsiveness in script and styles will
> drift apart.

## In SCSS — the `cds-breakpoint-*` mixins

The mixins come from a public entry point:

```scss
@use '@central-design-system/components/styles/breakpoints' as breakpoint;
```

> In plain Dart Sass (without a bundler), use the pkg scheme and the Node
> importer:
> `@use 'pkg:@central-design-system/components/styles/breakpoints' as breakpoint;`.

### `cds-breakpoint-up($name)` — "and up"

```scss
.card {
  display: none;

  // applies at min-width: 1056px (md and up)
  @include breakpoint.cds-breakpoint-up(md) {
    display: block;
  }
}
```

### `cds-breakpoint-down($name)` — "and down"

```scss
.sidebar {
  // applies at max-width: 1055.98px — that is, on sm and xs
  @include breakpoint.cds-breakpoint-down(sm) {
    display: none;
  }
}
```

`cds-breakpoint-down('<name>')` covers the breakpoint itself **and everything
below it** (the upper bound is the start of the next breakpoint minus `0.02px`).
No media query is generated for the largest breakpoint (`xl`) — "xl and down" is
every width.

### `cds-breakpoint-between($lower, $upper)` — a range

```scss
.banner {
  // min-width: 672px and max-width: 1056px
  @include breakpoint.cds-breakpoint-between(sm, md) {
    padding: 16px;
  }
}
```

Both mixins also accept a number instead of a name: `cds-breakpoint-up(900px)`.

### Other mixins and functions

- `cds-breakpoint($name)` — an alias for `cds-breakpoint-up`.
- `cds-largest-breakpoint` — media query for the largest breakpoint.
- `breakpoint-next($name)` / `breakpoint-prev($name)` — the neighboring breakpoint.
- `is-smallest-breakpoint($name)` — whether `$name` is the smallest one.
- `largest-breakpoint-name()` — name of the largest breakpoint.

## JS ↔ CSS correspondence

The `useDisplay` flags and the mixins' media queries cover identical width
ranges — that's what lets you write consistent responsive logic in script and
styles.

| JS (`useDisplay`) | SCSS mixin | Width range |
| --- | --- | --- |
| `smUp` | `cds-breakpoint-up(sm)` | `≥ 672` |
| `mdUp` | `cds-breakpoint-up(md)` | `≥ 1056` |
| `lgUp` | `cds-breakpoint-up(lg)` | `≥ 1312` |
| `xlUp` | `cds-breakpoint-up(xl)` | `≥ 1584` |
| `smDown` | `cds-breakpoint-down(sm)` | `< 1056` |
| `mdDown` | `cds-breakpoint-down(md)` | `< 1312` |
| `lgDown` | `cds-breakpoint-down(lg)` | `< 1584` |
| `xlDown` | `cds-breakpoint-down(xl)` | every width |

> **Important (migrating from CDS 3).** In CDS 3 the semantics of
> `cds-breakpoint-down` in SCSS differed from JS: `down('sm')` meant "strictly
> below `sm`" (only `xs`), whereas `smDown` in JS means "`sm` and down". In CDS 4
> the CSS is aligned with JS: `down('<name>')` now always means "`<name>` and
> down". If you are porting styles from CDS 3, shift the `down()` argument one
> step down (old `down('md')` ⇒ new `down('sm')`).
> See the Migration Guide.

## Platform

`useDisplay().platform` is a reactive object with device, OS and browser flags.
Detection is based on `navigator.userAgent` and touch support.

```ts
import { useDisplay } from '@central-design-system/components';

const { platform } = useDisplay();

if (platform.value.ios) {
  // special behavior for iOS
}

const isTouchDevice = platform.value.touch;
```

### Fields of the `platform` object

Every field is a `boolean`.

| Field | Meaning |
| --- | --- |
| `android` | an Android device |
| `ios` | an iOS device (iPhone / iPad / iPod) |
| `cordova` | the app runs in Cordova |
| `electron` | the app runs in Electron |
| `chrome` | Chrome browser |
| `edge` | Edge browser |
| `firefox` | Firefox browser |
| `opera` | Opera browser |
| `win` | Windows OS |
| `mac` | macOS |
| `linux` | Linux OS |
| `touch` | the device supports touch |
| `ssr` | the value was computed on the server (SSR) |

### Example: a class on the app root

```tsx
import { useDisplay } from '@central-design-system/components';

const { platform } = useDisplay();

defineRender(() => (
  <div
    class={{
      'platform--ios': platform.value.ios,
      'platform--android': platform.value.android,
      'platform--touch': platform.value.touch
    }}
  >
    <slot />
  </div>
));
```

> **Careful with user-agent sniffing.** Detecting the browser or OS from
> `userAgent` is unreliable (the string can be spoofed, and new browsers may not
> be recognized). Use `platform` for progressive enhancement — say, a fix
> specific to iOS Safari — not as the only gate in front of a feature. For
> feature detection, prefer capability checks (`'ontouchstart' in window` and the
> like).

### SSR

During server-side rendering `userAgent` is unavailable, so `platform.ssr === true`
and the rest of the flags are `false`. After hydration the values can be
recalculated by calling `display.update()` (which recalculates both size and
platform). Initial sizes for SSR are set through the second argument of
`createDisplay(options, ssr)` or the `ssr` option in `createCds`.

---

---
sourceHash: 49864e870f2f989420a5ebf7ffc7eb1a3458124a
---

# Global configuration

CDS 4 lets you set default prop values — globally, for a specific component, or
only inside a given subtree. You describe "what buttons look like in our product"
once and stop repeating the same props in every template.

## Setup

Default values are set through the `defaults` option of `createCds`. The `global`
key affects every component; a key named after a component affects only that one.

```ts
import { createApp } from 'vue';
import '@central-design-system/components/styles';
import { createCds, components, directives } from '@central-design-system/components';

import App from './App.vue';

const cds = createCds({
  components,
  directives,
  defaults: {
    global: {
      size: 'sm'
    },
    CdsButton: {
      appearance: 'secondary'
    },
    CdsTextInput: {
      hideDetails: 'auto'
    }
  }
});

createApp(App).use(cds);
```

**Important.** Props in `defaults` are written in camelCase: `hideDetails`, not
`hide-details`.

A component key is its name from `defineOptions({ name })` — `CdsButton`,
`CdsTextInput`, `CdsCardActions` and so on. Subcomponent names (`CdsCardTitle`,
`CdsListItem`) work exactly like root component names.

### Resolution order

For every prop, CDS takes the first value that applies:

1. the prop explicitly passed in the template;
2. `defaults.<ComponentName>.<prop>` from the nearest defaults context;
3. `defaults.global.<prop>`;
4. the default value declared in the component itself.

An explicitly passed prop always wins — defaults can never override the template.

### Changing defaults at runtime

`createCds` returns an instance whose defaults live in a reactive ref. You can
change them on the fly — every mounted component recalculates:

```ts
const cds = createCds({ components, directives });

// for example, turn on compact mode based on a user setting
cds.defaults.value = {
  ...cds.defaults.value,
  global: { size: 'sm' }
};
```

## Contextual defaults

Defaults can be set for components nested inside another component. For example,
to make every button inside a card secondary by default:

```ts
createCds({
  defaults: {
    CdsCard: {
      CdsButton: { appearance: 'secondary' }
    }
  }
});
```

The rule is simple: a capitalized key is the name of a nested component, a
lowercase key is a prop of the current component. Nesting is not limited to one
level:

```ts
createCds({
  defaults: {
    CdsCard: {
      CdsCardActions: {
        CdsButton: { appearance: 'tertiary', size: 'sm' }
      }
    }
  }
});
```

The library uses the same mechanism internally so that grouping components can
hand their settings down to their children:

- `CdsButtonGroup` sets the `appearance`, `color`, `baseColor`, `size` props on nested `CdsButton`s;
- `CdsTagGroup` sets the `color`, `activeColor`, `disabled`, `filter` props on `CdsTag`;
- `CdsSelectionControlGroup` passes settings to the controls, with the target component name
  set by the `defaultsTarget` prop (`CdsCheckbox`, `CdsRadio` and so on);
- `CdsTabs`, `CdsSteps`, `CdsList`, `CdsBreadcrumbs`, `CdsButtonToggle`,
  `CdsExpandablePanels`, `CdsOtpInput` work the same way.

That's why `<CdsButtonGroup size="sm">` makes every button inside small — you
don't have to set `size` on each of them.

## Global class and style

Besides props, a component's defaults can carry `class` and `style`. It's a
convenient way to apply product-specific rules to every instance of a component
without touching the templates:

```ts
createCds({
  defaults: {
    CdsButton: {
      class: 'my-button'
    }
  }
});
```

Any value Vue accepts works — a string, an object, an array:

```ts
createCds({
  defaults: {
    CdsButton: {
      style: [{ textTransform: 'none' }]
    }
  }
});
```

Unlike ordinary props, `class` and `style` are not overwritten by the template
but **merged** with it. So `<CdsButton class="mt-2">` gets both `my-button` and
`mt-2`.

**Important.** `class` and `style` only work under a specific component's key. In
`global` they are ignored.

## Aliases

An alias is the same component registered under a different name with its own
defaults. Aliases are a handy way to assemble "product" variants of components.

```ts
import { createCds, components, directives, CdsButton } from '@central-design-system/components';

const cds = createCds({
  components,
  directives,
  aliases: {
    CdsButtonPrimary: CdsButton,
    CdsButtonDanger: CdsButton
  },
  defaults: {
    CdsButtonPrimary: {
      appearance: 'primary',
      class: 'my-button--primary'
    },
    CdsButtonDanger: {
      appearance: 'primary',
      color: 'red',
      class: 'my-button--danger'
    }
  }
});
```

Aliases are registered globally, so you can use them in templates right away:

```vue
<template>
  <CdsButtonPrimary>Save</CdsButtonPrimary>
  <CdsButtonDanger class="ml-2">Delete</CdsButtonDanger>
</template>
```

**Important.** An alias does not inherit the base component's defaults. If the
configuration has `defaults.CdsButton`, it will not apply to `<CdsButtonPrimary>`
— defaults are looked up by the alias name. Move shared settings into `global` or
duplicate them under the alias key.

## Defaults for part of the application

To set defaults for a subtree rather than globally, use the
`CdsDefaultsProvider` component. The Controls panel in Storybook is built on it
too: the values from the panel are applied to the example's components as
defaults.

```vue
<script setup lang="ts">
import { CdsButton, CdsDefaultsProvider } from '@central-design-system/components';
</script>

<template>
  <CdsDefaultsProvider :defaults="{ CdsButton: { appearance: 'tertiary', size: 'sm' } }">
    <CdsButton>Small tertiary button</CdsButton>
  </CdsDefaultsProvider>
</template>
```

| Prop       | Type                | Purpose                                                                                      |
| ---------- | ------------------- | -------------------------------------------------------------------------------------------- |
| `defaults` | `DefaultsOptions`   | Defaults for the subtree; merged with the inherited ones by default                            |
| `scoped`   | `boolean`           | Don't mix with the parent defaults — only the ones set here apply                              |
| `reset`    | `number \| string`  | Go N levels up the defaults chain                                                              |
| `root`     | `boolean \| string` | Fall back to the root defaults from `createCds`; with a string — to a named group inside them  |
| `disabled` | `boolean`           | Provide nothing — the subtree gets the parent defaults as they are                             |

The typical use for `scoped` is an "island" inside someone else's environment:
enclosing groups (`CdsButtonGroup`, say) should not impose their settings on your
block.

## Your own components

Your application's own components can take part in the defaults system too. Pass
their props through `useDefaults`:

```vue
<script setup lang="ts">
import { useDefaults } from '@central-design-system/components';

const _props = defineProps<{ foo?: string }>();
const props = useDefaults(_props, 'MyComponent');
</script>

<template>
  <div>I am {{ props.foo }}</div>
</template>
```

`useDefaults` takes two arguments, both optional:

- `props` — the props object returned by `defineProps`;
- `name` — the component name used to look up the key in `defaults`. If omitted,
  the name from `defineOptions({ name })` is used, and failing that, the file name.

Now the component is configurable from the shared configuration:

```ts
createCds({
  defaults: {
    MyComponent: { foo: 'bar' }
  }
});
```

**Important.** In the template, refer to `props.foo`, not `foo`. `useDefaults`
returns a proxy over the props, and destructured `defineProps` variables bypass
it:

```diff
-<div>I am {{ foo }}</div>
+<div>I am {{ props.foo }}</div>
```

### Nested defaults in your own components

To make your component hand defaults down to its children (the way
`CdsButtonGroup` does), just call `useDefaults()` with no arguments — the nested
keys from its `defaults` section go into the child context:

```vue
<script setup lang="ts">
import { useDefaults } from '@central-design-system/components';

useDefaults();
</script>

<template>
  <div class="my-panel">
    <slot />
  </div>
</template>
```

```ts
createCds({
  defaults: {
    MyPanel: {
      CdsButton: { appearance: 'tertiary' }
    }
  }
});
```

If the children's defaults depend on the component's props, use `provideDefaults`
directly:

```vue
<script setup lang="ts">
import { provideDefaults } from '@central-design-system/components';
import { toRef } from 'vue';

const props = defineProps<{ size?: 'sm' | 'md' }>();

provideDefaults({
  CdsButton: {
    size: toRef(() => props.size)
  }
});
</script>

<template>
  <div class="my-toolbar">
    <slot />
  </div>
</template>
```

## Blueprint — a configuration preset

If several applications need the same set of options, extract it into a
`blueprint`: a plain `createCds` options object that the rest of the
configuration is layered on top of.

```ts
import { createCds, components, directives } from '@central-design-system/components';
import type { Blueprint } from '@central-design-system/components';

const productBlueprint: Blueprint = {
  theme: { defaultTheme: 'b2bLight' },
  defaults: {
    CdsButton: { appearance: 'secondary' }
  }
};

const cds = createCds({
  blueprint: productBlueprint,
  components,
  directives,
  // overrides the value from the blueprint
  defaults: {
    CdsButton: { size: 'sm' }
  }
});
```

Options are merged deeply (`mergeDeep`), so in the example above the buttons keep
`appearance: 'secondary'` from the preset and gain `size: 'sm'`.

---

---
sourceHash: 26c790bd53cd55729b9902cf5d1032b5c6457f6b
---

# Internationalization (i18n)

CDS components carry texts of their own: "No data available" in a select, the
table filter labels, the `aria-label` of a close button, the file counter. They
all go through the built-in localization layer, so you can translate them into
another language, override a single string for your product, or switch languages
on the fly — without rewriting components.

The library ships two dictionaries — Russian and English. `ru` is active by
default, so out of the box everything is in Russian.

## Setup

The locale is configured through the `locale` option of `createCds`. Switching to
the built-in English is a one-liner — you don't need to pass any dictionaries:

```ts
import { createApp } from 'vue';
import '@central-design-system/components/styles';
import { createCds, components, directives } from '@central-design-system/components';

import App from './App.vue';

const cds = createCds({
  components,
  directives,
  locale: {
    locale: 'en'
  }
});

createApp(App).use(cds);
```

Languages the library doesn't have are added as a dictionary in `messages`:

```ts
import de from './locales/cds-de';

createCds({
  components,
  directives,
  locale: {
    locale: 'de',
    fallback: 'en',
    messages: { de }
  }
});
```

| Option             | Type                      | Purpose                                                                       |
| ------------------ | ------------------------- | ----------------------------------------------------------------------------- |
| `locale`           | `string`                  | Active language; `ru` (default) and `en` are available out of the box          |
| `fallback`         | `string`                  | Language a string is taken from when the active one lacks it; `ru` by default  |
| `messages`         | `LocaleMessages`          | Dictionaries of extra languages; a same-named built-in dictionary is replaced entirely |
| `decimalSeparator` | `string`                  | Decimal separator; derived from the active locale by default                   |
| `rtl`              | `Record<string, boolean>` | Map of right-to-left languages (see [RTL](#rtl))                               |
| `adapter`          | `LocaleInstance`          | Your own translation engine instead of the built-in one (see [Custom adapter](#custom-adapter)) |

The built-in dictionaries are available to you as well — they live in the
`locales` export. Use them as a base for your own language or to fix a couple of
strings:

```ts
import { locales } from '@central-design-system/components';

locales.ru; // Russian dictionary
locales.en; // English dictionary
```

For the full set of keys, see [Message keys](#message-keys).

## How components get their text

Component strings are keys prefixed with `$cds.` that the library runs through a
translation function. Some of the keys are declared as default prop values, so
you can see them in the API: `text` on `CdsFileUpload` is `$cds.fileUpload.browse`,
`closeLabel` on `CdsNotification` is `$cds.close`, `noDataText` on `CdsSelect` is
`$cds.noDataText`.

That gives you three ways to change a text.

**Switch the whole language** — with the `locale` option:

```ts
createCds({ locale: { locale: 'en' } });
```

**Change wording across the product** — with a dictionary on top of the built-in
one:

```ts
import { createCds, locales } from '@central-design-system/components';

createCds({
  locale: {
    messages: {
      en: { ...locales.en, noDataText: 'Nothing found' }
    }
  }
});
```

**Important.** A language dictionary is replaced entirely, not merged key by key.
Without the `...locales.en` spread, the English locale is left with a single key
and the rest of the strings turn into their own keys (`$cds.close` instead of
"Close"). Spread nested sections separately:
`table: { ...locales.en.table, emptyText: '…' }`.

**Change one label in one place** — with a prop:

```vue
<CdsSelect :items="items" no-data-text="No matching suppliers" />
```

The same prop can be set as the default for every instance of the component — see
global configuration:

```ts
createCds({
  defaults: {
    CdsSelect: { noDataText: 'Nothing found' }
  }
});
```

The translation function also accepts plain text: a string without the `$cds.`
prefix is returned as is, with the parameters substituted. That's how props with
a localizable value work the same way with a key and with a ready-made phrase.

If a key is missing from both the active locale and the `fallback`, the component
shows the key itself, and in dev mode a
`[CDS: useLocale] Translation key … not found` warning appears in the console.

## Switching the language at runtime

`createCds` returns an instance whose locale lives in reactive refs — to switch
languages, just write to `current`:

```ts
const cds = createCds({ components, directives });

// for example, following the user's choice in profile settings
cds.locale.current.value = 'en';
```

Inside components, the `useLocale` composable does the same:

```vue
<script setup lang="ts">
import { CdsButton, CdsButtonToggle, useLocale } from '@central-design-system/components';

const { current } = useLocale();
</script>

<template>
  <CdsButtonToggle v-model="current" appearance="tertiary">
    <CdsButton value="ru" text="Русский" />
    <CdsButton value="en" text="English" />
  </CdsButtonToggle>
</template>
```

Every mounted component recalculates its strings on its own — no page reload
needed.

## A locale for part of the application

A single subtree can get its own language — for example, an English-language
widget inside a Russian interface. Call `provideLocale` in a wrapper component:
it takes the locale from the context, applies the props you passed and provides
the result to the children.

```vue
<script setup lang="ts">
import { provideLocale } from '@central-design-system/components';

const props = defineProps<{ locale?: string; fallback?: string }>();

provideLocale(props);
</script>

<template>
  <div>
    <slot />
  </div>
</template>
```

```vue
<template>
  <LocaleProvider locale="en">
    <CdsSelect :items="items" />
  </LocaleProvider>
</template>
```

Props you don't pass are inherited from the parent locale, so a wrapper with just
a `locale` loses neither the `fallback` nor the dictionaries.

## useLocale

The composable hands you the current locale and its functions — use it in your
own components so their texts live in the same dictionaries as the CDS ones.

```vue
<script setup lang="ts">
import { useLocale } from '@central-design-system/components';

const { t, n } = useLocale();
</script>

<template>
  <p>{{ t('$cds.table.emptyText') }}</p>
  <p>{{ n(1234.56) }}</p>
</template>
```

| Property           | Type                                           | Purpose                                                       |
| ------------------ | ---------------------------------------------- | ------------------------------------------------------------- |
| `t`                | `(key: string, ...params: unknown[]) => string` | Translation of a `$cds.…` key with parameter substitution      |
| `n`                | `(value: number) => string`                    | Number formatting for the active locale                        |
| `current`          | `Ref<string>`                                  | Active language; writing to it switches the language           |
| `fallback`         | `Ref<string>`                                  | Fallback language                                              |
| `messages`         | `Ref<LocaleMessages>`                          | Dictionaries; can be extended at runtime                       |
| `decimalSeparator` | `ShallowRef<string>`                           | Decimal separator of the active locale                         |

Parameters in strings are numbered — `{0}`, `{1}`:

```ts
const { t } = useLocale();

t('$cds.carousel.delimiter', 3, 8); // "Slide 3 of 8"
t('Days left: {0}', 5); // "Days left: 5"
```

Under the hood `n` is `Intl.NumberFormat` with the active locale and the
`fallback`, so group and decimal separators come from the browser. The library
derives `decimalSeparator` from the same locale (`,` for `ru`, `.` for `en`); if
your product uses a different one, set it explicitly in `createCds`.

## Dates

Month and weekday names live in separate date locales, shipped by `ru` and `en`.
Date and time components pick the date locale by the active language, so after
`current.value = 'en'` the calendar switches by itself.

A single component gets its language from the `locale` prop — `CdsDatePicker`,
`CdsDateInput` and `CdsTimePicker` all have it:

```vue
<CdsDatePicker v-model="value" locale="en" :first-day-of-week="0" header />
```

The prop accepts not only a language name but also your own date locale object
(type `TDateLocale`) — that's how you plug in a language the library doesn't
have. The built-in date locales, for reference and reuse, live in the same
`locales` export: `locales.ruDate`, `locales.enDate` and the `locales.dateLocales`
map.

```ts
const de = {
  days: 'Sonntag_Montag_Dienstag_Mittwoch_Donnerstag_Freitag_Samstag'.split('_'),
  daysShort: 'So_Mo_Di_Mi_Do_Fr_Sa'.split('_'),
  months: 'Januar_Februar_März_April_Mai_Juni_Juli_August_September_Oktober_November_Dezember'.split('_'),
  monthsLong: 'Januar_Februar_März_April_Mai_Juni_Juli_August_September_Oktober_November_Dezember'.split('_'),
  monthsShort: 'Jan_Feb_Mär_Apr_Mai_Jun_Jul_Aug_Sep_Okt_Nov_Dez'.split('_'),
  today: 'Heute',
  now: 'Jetzt',
  firstDayOfWeek: 1,
  format24h: true,
  pluralDay: (day = 0) => (day === 1 ? 'Tag' : 'Tage')
};
```

```vue
<CdsDatePicker v-model="value" :locale="de" />
```

## Table

`CdsTable` builds its labels from the `$cds.table.*` keys, but it also accepts a
pinpoint override through the `locale` prop — which replaces only the strings you
pass:

```vue
<CdsTable :columns="columns" :data="data" :locale="{ emptyText: 'No requests yet' }" />
```

## RTL

Right-to-left languages are described by the `rtl` map: the key is the language,
the value is the direction.

```ts
createCds({
  locale: {
    locale: 'ar',
    messages: { ar },
    rtl: { ar: true }
  }
});
```

Components read the direction through `useRtl` and flip whatever depends on the
axis: the side menus and tooltips open to, the pagination arrows, the cell order
in `CdsOtpInput`, the fill of `CdsProgressBar`. Spacing and borders in the styles
are mostly written with logical properties (`margin-inline`, `inset-inline`) and
are mirrored by the browser itself — but the design system does not claim full
RTL support yet, and some places will need polishing on your side.

The library does not set the direction attribute for you — put it on the
application root yourself:

```vue
<script setup lang="ts">
import { useRtl } from '@central-design-system/components';

const { isRtl } = useRtl();
</script>

<template>
  <div :dir="isRtl ? 'rtl' : 'ltr'">
    <slot />
  </div>
</template>
```

`useRtl` gives you `isRtl` and `rtlClasses` — a ready `cds-locale--is-rtl` /
`cds-locale--is-ltr` class for your own styles.

## Custom adapter

If your application already has an i18n library, hand the translations over to
it: the `adapter` option accepts any object implementing the `LocaleInstance`
interface. In that case `messages`, `locale` and `fallback` from `createCds` are
unused — your engine becomes the source of truth, and the CDS strings live in the
application's shared dictionaries under the `$cds` key.

```ts
import type { LocaleInstance, LocaleOptions } from '@central-design-system/components';
import { toRef } from 'vue';
import type { I18n } from 'vue-i18n';

export function createVueI18nAdapter(i18n: I18n<any, any, any, string, false>): LocaleInstance {
  const format = (value: number) => i18n.global.n(value);

  return {
    name: 'vue-i18n',
    current: i18n.global.locale,
    fallback: i18n.global.fallbackLocale as never,
    messages: i18n.global.messages as never,
    decimalSeparator: toRef(() => (format(0.1).includes(',') ? ',' : '.')),
    t: (key, ...params) => i18n.global.t(key, params as never),
    n: format,
    provide: () => createVueI18nAdapter(i18n)
  };
}
```

```ts
import { createI18n } from 'vue-i18n';

const i18n = createI18n({
  legacy: false,
  locale: 'en',
  messages: {
    en: {
      $cds: { noDataText: 'No data available' },
      profile: { title: 'Profile' }
    }
  }
});

const cds = createCds({
  components,
  directives,
  locale: {
    adapter: createVueI18nAdapter(i18n)
  }
});
```

Required members of `LocaleInstance`: `name` (that's how the adapter is
recognized), `current`, `fallback`, `messages`, `decimalSeparator`, `t`, `n` and
`provide` — a factory for a nested locale, used by `provideLocale`. If you don't
need "a locale in a subtree", `provide` can return the same instance, as in the
example above.

## Message keys

The built-in English dictionary is a template for translating into a new
language. Copy it, translate the values and pass it to `messages` under your
language's key; the Russian version is available as `locales.ru`.

```ts
export default {
  badge: 'Badge',
  noDataText: 'No data available',
  selectAll: 'Select all',
  close: 'Close',
  open: 'Open',
  dismiss: 'Dismiss',
  confirmEdit: {
    ok: 'OK',
    cancel: 'Cancel'
  },
  carousel: {
    prev: 'Previous slide',
    next: 'Next slide',
    delimiter: 'Slide {0} of {1}'
  },
  input: {
    clear: 'Clear {0}',
    otp: 'Please enter OTP character',
    prependAction: '{0} prepended action',
    appendAction: '{0} appended action'
  },
  fileInput: {
    counter: '{0} files',
    counterSize: '{0} files ({1} in total)'
  },
  fileUpload: {
    title: 'Drag and drop files here',
    divider: 'or',
    browse: 'Browse files'
  },
  steps: {
    prev: 'Back',
    next: 'Next'
  },
  table: {
    filterTitle: 'Filter menu',
    filterConfirm: 'OK',
    filterReset: 'Reset',
    filterEmptyText: 'No filters',
    filterCheckAll: 'Select all items',
    filterSearchPlaceholder: 'Search in filters',
    emptyText: 'No data',
    selectAll: 'Select current page',
    selectInvert: 'Invert current page',
    selectNone: 'Clear all data',
    selectionAll: 'Select all data',
    sortTitle: 'Sort',
    expand: 'Expand row',
    collapse: 'Collapse row',
    triggerDesc: 'Click to sort descending',
    triggerAsc: 'Click to sort ascending',
    cancelSort: 'Click to cancel sorting',
    showed: 'Showed',
    from: 'from',
    rowOnPage: 'Row on page'
  },
  uploader: {
    uploading: 'Uploading...',
    uploadFile: 'Upload file',
    downloadFile: 'Download file',
    removeFile: 'Remove file',
    uploadError: 'Upload error',
    previewFile: 'Preview file'
  }
};
```

The dictionary may stay incomplete: missing keys are taken from the `fallback` —
that is, from Russian by default.

---

---
sourceHash: 16f5caa5227fd7ac98a4d370070985a7094a8a2b
---

# Date Utils

Central Design System includes a set of functions for working with the native JS
`Date`: mask-based formatting, string parsing, arithmetic, comparison and
calendar math. You don't need a separate date library (dayjs, date-fns) for
everyday tasks. The date and time components use the very same functions —
CdsDateInput, CdsDatePicker,
CdsTimePicker — so format masks are identical in
the utilities and in the components.

The functions accept a `Date`, a timestamp (milliseconds) or a date string,
return a native `Date` and **never mutate** the arguments you pass — the result
is always a new object.

## Setup

The utilities are exported from the package under the `utils` namespace:

```ts
import { utils } from '@central-design-system/components';

const { formatDate, addToDate } = utils;

formatDate(new Date(2026, 7, 18), 'DD.MM.YYYY'); // '18.08.2026'
```

## Formatting — `formatDate`

`formatDate(value, mask, dateLocale?)` turns a date into a string using a mask:

```ts
const { formatDate } = utils;

formatDate(new Date(2026, 7, 18, 14, 30), 'DD.MM.YYYY HH:mm'); // '18.08.2026 14:30'
formatDate(Date.now(), 'D MMM YYYY'); // '18 Авг 2026'
formatDate(new Date(2026, 7, 18), 'dddd'); // 'Вторник'
```

Without a mask, an ISO-like format is used: `YYYY-MM-DDTHH:mm:ss.SSSZ`.
For an invalid value the function returns `undefined`.

Month and weekday names come from the Russian date locale by default. To print
them in another language, pass a date locale as the third argument — the
built-in ones live in the `locales` export:

```ts
import { locales, utils } from '@central-design-system/components';

utils.formatDate(new Date(2026, 7, 18), 'dddd, D MMMM', locales.enDate);
// 'Tuesday, 18 August'
```

Your own language is plugged in as a `TDateLocale` object — the same fields as
`locales.ruDate`. See the Internationalization
guide for more on date locales.

### Format tokens

| Unit | Token | Result |
| --- | --- | --- |
| Year | `YY` / `YYYY` | `26` / `2026` |
| Month | `M` / `MM` | `8` / `08` |
| Month (name) | `MMM` / `MMMM` | `Авг` / `Август` |
| Quarter | `Q` / `Qo` | `3` / `3rd` |
| Day of month | `D` / `Do` / `DD` | `18` / `18th` / `18` |
| Day of year | `DDD` / `DDDD` | `230` / `230` (zero-padded to 3 digits) |
| Day of week | `d` | `2` (0 — Sunday) |
| Day of week (name) | `dd` / `ddd` / `dddd` | `Вт` / `Вт` / `Вторник` |
| Day of week (ISO) | `E` | `2` (1 — Monday, 7 — Sunday) |
| Week of year | `w` / `ww` | `34` / `34` |
| Hour (0–23) | `H` / `HH` | `14` / `14` |
| Hour (1–12) | `h` / `hh` | `2` / `02` |
| Minute | `m` / `mm` | `30` / `30` |
| Second | `s` / `ss` | `5` / `05` |
| Fractions of a second | `S` / `SS` / `SSS` | `1` / `12` / `123` |
| Time zone | `Z` / `ZZ` | `+03:00` / `+0300` |
| Meridiem | `A` / `a` / `aa` | `PM` / `pm` / `p.m.` |
| Unix time | `X` / `x` | seconds / milliseconds |

Ordinal suffixes (`Do`, `Qo`) are English (`1st`, `2nd`…) regardless of the
locale.

Arbitrary text inside a mask is escaped with square brackets:

```ts
formatDate(new Date(2026, 7, 18), '[Сегодня] DD.MM'); // 'Сегодня 18.08'
```

## Parsing — `extractDate` and `splitDate`

`extractDate(str, mask, dateLocale?)` parses a string with a mask and returns a
`Date`:

```ts
const { extractDate } = utils;

extractDate('21.03.1985', 'DD.MM.YYYY'); // Date: 21 March 1985
extractDate('2019-10-29 23:12', 'YYYY-MM-DD HH:mm'); // Date: 29 October 2019, 23:12
```

Month and day names inside the string are recognized through the date locale —
Russian by default, just like in `formatDate`.

A non-existent day overflows following the rules of the native `Date`:
`extractDate('30.02.2024', 'DD.MM.YYYY')` gives 1 March 2024. When you need
strict input validation, format the result back and compare it with the string:

```ts
const strict = (str: string, mask: string) => formatDate(extractDate(str, mask), mask) === str;

strict('18.08.2026', 'DD.MM.YYYY'); // true
strict('30.02.2024', 'DD.MM.YYYY'); // false — overflowed into 01.03.2024
```

If you don't need a `Date`, `splitDate(str, mask, dateLocale?)` splits the string
into its parts — an `IRawDate` object with the fields `year`, `month`, `day`,
`hour`, `minute`, `second`, `millisecond` (anything not found is `null`):

```ts
const { splitDate } = utils;

splitDate('18.08.2026', 'DD.MM.YYYY');
// { year: 2026, month: 8, day: 18, hour: null, … }
```

## Creating and changing

### `buildDate`

`buildDate(modified, utc?)` — the current moment with individual parts replaced.
Handy when you need "now, but at 15:00" or "today, but in 2010":

```ts
const { buildDate } = utils;

buildDate({ year: 2010, day: 5, hour: 15 });
// current month, minutes and seconds; year 2010, day 5, hour 15
```

Supported object fields: `year`, `month` (1–12), `day` (or `date`), `hour`,
`minute`, `second`, `millisecond`.

### `adjustDate`

`adjustDate(date, modified, utc?)` — the same thing, but for an arbitrary date:

```ts
const { adjustDate } = utils;

adjustDate(new Date(2026, 10, 2), { year: 2010, month: 2 });
// Date: 2 February 2010
```

Note that `month` here is 1-based (February is `2`), unlike in the `Date`
constructor.

### `addToDate` / `subtractFromDate`

Add and subtract intervals. The object fields are the same, but they mean "how
much to add" rather than "what to set":

```ts
const { addToDate, subtractFromDate } = utils;

addToDate(new Date(2026, 2, 7), { day: 7, month: 1 }); // Date: 14 April 2026
subtractFromDate(new Date(2026, 2, 7), { hour: 24 }); // Date: 6 March 2026
```

### `startOfDate` / `endOfDate`

The start and the end of a period — year, month, day, hour, minute or second:

```ts
const { startOfDate, endOfDate } = utils;

startOfDate(new Date(2026, 7, 18, 14, 30), 'year'); // Date: 1 January 2026, 00:00:00.000
endOfDate(new Date(2026, 7, 18, 14, 30), 'month'); // Date: 31 August 2026, 23:59:59.999
```

Period unit: `'year'`, `'month'`, `'day'`, `'hour'`, `'minute'`, `'second'`
(the plural form is accepted too).

## Comparison and ranges

### `isSameDate`

Compares dates down to a unit: `'year'` — the year only, `'month'` — month and
year, `'day'` — the calendar day, and so on. Without a unit, the timestamps are
compared in full.

```ts
const { isSameDate } = utils;

isSameDate(new Date(2026, 7, 1), new Date(2026, 7, 30), 'month'); // true
isSameDate(new Date(2026, 7, 1), new Date(2026, 7, 30), 'day'); // false
```

### `getDateDiff`

The difference between two dates in the chosen unit (days by default):

```ts
const { getDateDiff } = utils;

getDateDiff(new Date(2026, 4, 12), new Date(2026, 3, 8)); // 34 (days)
getDateDiff(new Date(2026, 4, 12), new Date(2026, 3, 8), 'months'); // 1
```

### `isBetweenDates` / `getDateBetween`

`isBetweenDates(date, from, to, opts?)` checks whether a date falls inside a
range. The bounds are excluded by default; the `inclusiveFrom` and `inclusiveTo`
options include them, and `onlyDate: true` compares calendar days only, ignoring
the time:

```ts
const { isBetweenDates } = utils;

isBetweenDates(date, from, to); // strict range
isBetweenDates(date, from, to, { inclusiveFrom: true, inclusiveTo: true, onlyDate: true });
```

`getDateBetween(date, min, max)` clamps a date to a range: it returns the date
itself if it is inside, otherwise the nearest bound:

```ts
const { getDateBetween } = utils;

getDateBetween(new Date(2025, 0, 1), new Date(2026, 0, 1), new Date(2026, 11, 31));
// Date: 1 January 2026 — the date is below the minimum, so the min bound came back
```

### `getMinDate` / `getMaxDate`

The smallest and the largest of a set of dates. They return a timestamp (number) —
wrap it in `new Date()` if you need a date object:

```ts
const { getMinDate, getMaxDate } = utils;

const min = getMinDate(new Date(2026, 6, 24), new Date(2026, 5, 20), new Date(2026, 6, 26));
new Date(min); // Date: 20 June 2026

const dates = [/* Date[] */];
const max = getMaxDate(dates[0], ...dates.slice(1));
```

## Calendar

```ts
const { getDayOfWeek, getWeekOfYear, getDayOfYear, daysInMonth } = utils;

getDayOfWeek(new Date(2026, 7, 16)); // 7 — Sunday (ISO: 1 — Monday)
getWeekOfYear(new Date(2026, 0, 4)); // 1 — ISO week number in the year
getDayOfYear(new Date(2026, 1, 4)); // 35 — ordinal day in the year
daysInMonth(new Date(2024, 1, 15)); // 29 — February of a leap year
```

## Other

### `isValidDate`

Checks whether a value parses into a date:

```ts
const { isValidDate } = utils;

isValidDate('2026-08-18'); // true
isValidDate('не дата'); // false
```

The check is syntactic — it does not catch non-existent calendar days
(see `splitDate` above).

### `cloneDate`

A copy of a date. Useful before handing it to third-party code that might mutate
the object (CDS utilities themselves never modify their arguments):

```ts
const { cloneDate } = utils;

const copy = cloneDate(original);
```

### `inferDateFormat`

Detects the shape of a value — handy for returning the result in the same form
the value came in:

```ts
const { inferDateFormat } = utils;

inferDateFormat(new Date()); // 'date'
inferDateFormat(1787059805000); // 'number'
inferDateFormat('18.08.2026'); // 'string'
```