@central-design-system/skills 4.0.0-alpha.6

package/skills/cds-builder/references/guides/theme.md

@@ -0,0 +1,343 @@
+---
+sourceHash: 41872192eda1479740145bb7f4bcb9dbb28f0462
+---
+
+# 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, …
+```
+
+Colors are written into the variables as **RGB channels** rather than finished
+colors — that's what makes opacity control possible:
+
+```css
+/* generated by CDS */
+:root {
+  --cds-color-brand-primary: 0,90,178;
+  --cds-color-surface-primary: 255,255,255;
+  --cds-spacing-400: 1rem;
+  --cds-border-radius-200: 0.25rem;
+}
+
+/* usage */
+.my-block {
+  background: rgb(var(--cds-color-surface-primary));
+  border: var(--cds-border-100) solid rgb(var(--cds-color-brand-primary) / 0.4);
+  padding: var(--cds-spacing-400);
+}
+```
+
+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`.
+
+```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': '#2C8926',
+    '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](./tailwindcss.md).
+
+### CSS / SCSS
+
+```scss
+.my-card {
+  background: rgb(var(--cds-color-surface-elevated));
+  color: rgb(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';
+```

package/skills/cds-builder/references/guides/treeshaking.md

@@ -0,0 +1,237 @@
+---
+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.

package/skills/cds-builder/references/patterns/dialogs.md

@@ -0,0 +1,89 @@
+# Pattern: confirming an action in a modal
+
+A modal interrupts the user's work, so it is justified only where you cannot
+proceed without an answer: an irreversible action, a form, data loss. To report
+the result of an action that already happened, a modal is not needed — that is
+`CdsToast`.
+
+## Confirming an irreversible action
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsModal } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const open = ref(false);
+const deleting = ref(false);
+
+const confirm = async (): Promise<void> => {
+  deleting.value = true;
+
+  try {
+    await api.removeDraft(draftId);
+    open.value = false;
+  } finally {
+    deleting.value = false;
+  }
+};
+</script>
+
+<template>
+  <CdsButton appearance="tertiary" text="Delete draft" @click="open = true" />
+
+  <CdsModal v-model="open" persistent max-width="480">
+    <div class="flex flex-col gap-4 p-6">
+      <h2>Delete the draft?</h2>
+      <p>The draft and all unsaved changes will be deleted. This action cannot be undone.</p>
+
+      <div class="flex justify-end gap-3">
+        <CdsButton appearance="tertiary" text="Cancel" :disabled="deleting" @click="open = false" />
+        <CdsButton text="Delete" :loading="deleting" @click="confirm" />
+      </div>
+    </div>
+  </CdsModal>
+</template>
+```
+
+Key points:
+
+- `persistent` — clicking outside the modal and `Esc` do not close it. Set it
+  only for irreversible actions and forms with entered data; for an ordinary
+  modal it is annoying.
+- The modal closes **after** a successful server response, not immediately on
+  click: otherwise the user will never learn about an error.
+- `:loading` on the confirm button guards against a repeated click, `:disabled`
+  on "Cancel" — against closing while the request is in flight.
+
+## Opening via an activator
+
+If a button exists only to open the modal, you can skip the state entirely —
+`CdsModal` provides an `activator` slot:
+
+```vue
+<CdsModal max-width="480">
+  <template #activator="{ props }">
+    <CdsButton v-bind="props" text="Open" />
+  </template>
+
+  <template #default="{ isActive }">
+    <div class="p-6">
+      <CdsButton text="Close" @click="isActive.value = false" />
+    </div>
+  </template>
+</CdsModal>
+```
+
+## Copy
+
+The title and the buttons name **the action and its outcome**, not "Yes" /
+"OK": a "Yes" button gives the user no idea what will happen. A destructive
+action is named directly — "Delete draft", not "Continue".
+
+## What not to do
+
+- Do not open a modal on top of a modal. If a second step is needed, put the
+  steps inside a single modal.
+- Do not put a long form into a modal when it can live on a page.
+- Do not use `CdsDrawer` as a "modal on the side": it is app-level side
+  navigation.
+- Do not report success with a modal — that is what `CdsToast` is for.