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

package/skills/cds-builder/references/guides/sass-variables.md

@@ -0,0 +1,238 @@
+---
+sourceHash: 5d3ad246b66c58c6ecd39eb645d52dd6a026eaf2
+---
+
+# 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](theme.md). 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](treeshaking.md)).
+
+> 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 |
+| `$standard-easing` | `cubic-bezier(0.4, 0, 0.2, 1)` | Base animation curve |
+| `$decelerated-easing` | `cubic-bezier(0, 0, 0.2, 1)` | Enter curve |
+| `$accelerated-easing` | `cubic-bezier(0.4, 0, 1, 1)` | Leave curve |
+| `$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](display-and-platform.md)).
+> 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.

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

@@ -0,0 +1,81 @@
+# 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](treeshaking.md) 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](tailwindcss.md) 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](../tokens/themes.md).
+
+Custom themes, runtime theme switching and disabling theming are covered in
+the [Theming](theme.md) guide.
+
+## Icons
+
+The built-in `cds` iconpack is active by default. Other packs are available
+too (`carbon`, `lucide`, `phosphor`, `remix`):
+
+```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](migration-cds3-to-cds4.md).

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

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