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

package/skills/cds-builder/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: cds-builder
+description: >-
+  Building product UI on Vue 3 with the CDS 4 design system
+  (`@central-design-system/components`, Central Design System, B2B-Center):
+  components, screen and form markup, library setup in a project, themes and
+  tokens. Use this skill whenever the user asks to build or lay out any UI
+  with CDS — a form, page, table, card, modal, dashboard, header; to add CDS
+  to a new or existing project, configure `createCds`, styles, or Tailwind;
+  to learn a component's contract ("what props does CdsSelect have", "does
+  CdsButton have variant"); to configure a theme, palette, or tokens; to
+  build a UI from a screenshot or mockup. RU triggers: «сделай
+  форму на CDS», «свёрстай страницу на дизайн-системе», «установи CDS»,
+  «какие пропсы у Cds…», «как использовать Cds…», «токены CDS», «тема
+  b2b/promo», «своя тема CDS», «tailwind в CDS», «уменьши бандл CDS»,
+  «вот скриншот, сделай это на CDS». EN triggers: «build UI with central
+  design system», «add CDS to my app», «CDS component props», «CDS
+  tokens/themes», «custom CDS theme», «tailwindcss with CDS», «CDS
+  tree-shaking». Trigger on any request about building UI with CDS, no
+  matter how casually it is phrased.
+metadata:
+  author: cds-team
+  version: "4.0.0-alpha.6"
+  source: https://gitlab.b2b-center.ru/cds/central-design-system
+---
+
+# CDS Builder
+
+You build product UI on Vue 3 with the CDS 4 design system
+(version 4.0.0-alpha.6). The goal is working code that fits into the project and
+uses the ready-made components — not generic markup. Read the project context
+first, then build.
+
+All references live in `references/` and are generated from the design
+system's sources. The skill works offline.
+
+---
+
+## Step 1 — Read the project context
+
+Open `package.json` and check:
+
+- whether `@central-design-system/components` is present and which version (CDS 4 is `4.0.0` and up);
+- framework and bundler: Vite, Nuxt, plain Vue 3;
+- TypeScript or JavaScript;
+- whether `tailwindcss` is present (affects how you write markup, see step 5);
+- package manager — by the lock file (`bun.lock`, `pnpm-lock.yaml`, `yarn.lock`,
+  `package-lock.json`). In the CDS monorepo — `bun` only.
+
+If the library is not in the project — run "Setup" first, then build.
+
+If `tailwindcss` is not in the project — **stop and ask the user** whether to
+add Tailwind, before writing the first line of markup: with it you get
+utility classes built on CDS tokens, and every example in the references is
+written that way. Setup is described in `references/guides/tailwindcss.md`.
+If they agree — set up Tailwind per the guide first, then build. If they
+decline — write markup without utilities (step 5) and do not offer it again
+in this session.
+
+If the user refers to existing project components, look at them: your code
+must match the project's established conventions for naming, file structure,
+and import style.
+
+---
+
+## Setup
+
+```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');
+```
+
+Usage: `<CdsButton appearance="primary">Click me</CdsButton>`.
+
+This is the **full** registration: the namespace import `components` and the
+`styles` aggregate keep the entire library in the bundle. It is convenient
+where the set of components is not known in advance (admin panels,
+sandboxes, documentation).
+
+For product applications register components selectively —
+`createCds({ components: { CdsButton } })` plus the base layer
+`@central-design-system/components/styles/common.css`. Details are in the
+"Tree-shaking" guide.
+
+Common problems:
+
+- **Components without styles** — `@central-design-system/components/styles` is not imported.
+- **Component not found** — not passed to `createCds({ components })` with selective registration.
+- **`dist/cds.css` does not resolve** — this is a CDS 3 path; in CDS 4 the entry
+  point is `@central-design-system/components/styles`. This looks like a
+  migration — tell the user; the full migration guide is in the `cds-migrate`
+  skill.
+
+---
+
+## Step 2 — Choose a component
+
+If the component is not named explicitly or you are not sure which one fits —
+**read `references/component-decision-tree.md` before writing code**. It covers
+the purpose of all 79 components and the head-to-head cases
+(`CdsSelect` vs `CdsCombobox` vs `CdsAutocomplete`, `CdsModal` vs `CdsMenu`,
+`CdsTable` vs `CdsList`, and others).
+
+Rules:
+
+- **Take the narrowest component that fits.** If `CdsSelect` exists — do not
+  build a dropdown out of `CdsSurface` and `CdsList`.
+- **Do not invent a component that does not exist.** If the task is not
+  covered, assemble it from existing atoms and tell the user.
+
+What exists at all:
+
+- **Atoms** — CdsCounter, CdsDescription, CdsDivider, CdsField, CdsFunctionalButton, CdsHighlight, CdsInput, CdsLabel, CdsMessages, CdsResponsive, CdsSelectionControl, CdsSelectionControlGroup, CdsSlideGroup, CdsSlideView, CdsSurface
+- **Content** — CdsAvatar, CdsButton, CdsButtonGroup, CdsButtonToggle, CdsCard, CdsCarousel, CdsExpandablePanel, CdsIcon, CdsImage, CdsList, CdsMenu, CdsModal, CdsOverlay, CdsTable, CdsTag, CdsTagGroup, CdsTooltip, CdsTree, CdsVirtualScroll
+- **Controls** — CdsAutocomplete, CdsCheckbox, CdsCheckboxButton, CdsCombobox, CdsDateInput, CdsDatePicker, CdsFileInput, CdsFileUpload, CdsForm, CdsOtpInput, CdsRadio, CdsRadioGroup, CdsSelect, CdsTextArea, CdsTextInput, CdsTimePicker, CdsToggle, CdsUploader
+- **Feedback** — CdsBadge, CdsEmptyState, CdsLoader, CdsNotification, CdsNotificationAlert, CdsProgressBar, CdsProgressCircle, CdsSkeletonLoader, CdsStages, CdsStatus, CdsToast, CdsToastQueue
+- **Layouts** — CdsDrawer, CdsFooter, CdsGrid, CdsHeader, CdsLayout, CdsMain, CdsPage, CdsToolbar
+- **Navigation** — CdsBreadcrumbs, CdsLink, CdsPagination, CdsSteps, CdsTabs
+- **Other** — CdsApp, CdsDefaultsProvider
+
+---
+
+## Step 3 — Check the contract
+
+The reference path is derived from the name: `CdsTextInput` →
+`references/components/cds-text-input/api.md` (kebab-case).
+
+| File | What is inside |
+| --- | --- |
+| `api.md` | The full contract: props / events / slots / exposed with types and defaults. Always present. |
+| `examples.md` | Ready-made usage examples. |
+| `guidelines.md` | Do / Don't rules for this component. Not every component has one. |
+| `tokens.md` | The component's local SCSS variables. |
+
+**Do not make up props, events, or slots.** If something is not in `api.md` —
+it does not exist in the component. This is the skill's main rule: an
+invented prop looks plausible and silently does nothing.
+
+After the markup is written, verify it mechanically — the skill ships a
+contract linter:
+
+```bash
+node <skill-dir>/scripts/check-contracts.mjs src/components/MyForm.vue
+```
+
+It checks every `Cds*` tag in the given `.vue` files (or directories)
+against the reference: the component exists, every prop and event is in its
+contract. Run it on the files you created or changed before returning the
+answer; fix everything it reports — each finding is API that would be
+silently ignored at runtime.
+
+---
+
+## Step 4 — Tokens instead of raw values
+
+Three levels: **L1** — palette primitives, **L2** — theme color tokens
+(`--cds-color-*`), **L3** — the component's local SCSS variables.
+
+- Set color with the `color` / `bgColor` / `appearance` props, not CSS.
+- Hardcoded values like `#fff`, `16px`, `rgb(0 0 0)` in styles are forbidden —
+  they break theming and the dark theme.
+- If you need custom CSS — tokens only: `rgb(var(--cds-color-surface-primary))`.
+
+Token values: `references/tokens/themes.md` (themes and `--cds-color-*`),
+`references/tokens/colors.md` (level 1 palette).
+
+---
+
+## Step 5 — Markup and spacing
+
+Check whether Tailwind is installed (step 1):
+
+- **Tailwind is present** — use utilities for layout, spacing, and typography.
+  Beyond the standard ones, classes built on CDS tokens are available for
+  color, radius, and type (`bg-surface-primary`, `text-brand-primary`,
+  `rounded-200`), synchronized with the active theme. Examples in
+  `examples.md` are written exactly this way.
+- **Spacing is written with the standard Tailwind numeric scale** (`gap-2`,
+  `p-4`, `mt-2`) — the CDS spacing tokens are aligned with it, so there is no
+  separate spacing scale to learn. Do not use `gap-200`/`p-400`-style spacing
+  classes.
+- **Tailwind is absent** (the user declined the setup in step 1) — do not
+  use utility classes. Style with component props and CSS on the `--cds-*`
+  tokens.
+
+Set spacing between siblings with the container's `gap`, not with a margin on
+each element. Do not multiply nesting: three wrappers with no semantics are a
+reason to simplify.
+
+Default spacing rhythm — keep it compact, do not oversize gaps:
+
+- between form controls and between buttons in one row — `gap-2`;
+- between meaningful blocks (a field group and the actions row, cards on a
+  page) — `gap-3` / `gap-4`;
+- controls are visually dense on their own (label, field, and messages are
+  already spaced inside), so `gap-4` between fields makes a form fall apart.
+
+---
+
+## Step 6 — Forms
+
+For typical fields take the ready-made controls (`CdsTextInput`, `CdsSelect`,
+`CdsCheckbox`, `CdsDateInput`) — they already wire together the label, hint,
+error, and the field itself.
+
+The atoms `CdsField` / `CdsLabel` / `CdsDescription` / `CdsMessages` /
+`CdsInput` are needed only when no ready-made control exists. Building a
+plain text field out of them means manually reimplementing `CdsTextInput`.
+
+`CdsForm` assembles fields into a form and provides validation; rules go
+through `useRules` / `useValidation`.
+
+The actions row of a form: buttons aligned to the right, primary action last
+in reading order, `gap-2` between buttons. On mobile the buttons stack
+(`flex-col-reverse` keeps the primary one on top) and return to a row from
+`sm:` already — there is enough width for two buttons, and stretched
+full-width buttons on a tablet look broken.
+
+Complex forms (server errors, steps, dynamic fields) —
+`references/patterns/forms.md`.
+
+---
+
+## Step 7 — Responsiveness
+
+Lay out for at least mobile and desktop sizes unless "desktop only" is said
+explicitly. Breakpoints are available both in script (`useDisplay`) and in
+SCSS (the `cds-breakpoint-*` mixins) — the values are shared. Details in the
+"Display & Platform" guide.
+
+---
+
+## Step 8 — Accessibility
+
+CDS components cover most of accessibility themselves. What you must do:
+
+- `aria-label` on icon buttons (`<CdsButton icon="delete" aria-label="Delete" />`);
+- meaningful `alt` on images (`alt=""` — if the image is decorative);
+- link the label and the field — through a ready-made control or `CdsField`,
+  not "by eye";
+- heading hierarchy without skipped levels;
+- color must not be the only indicator of a state — duplicate it with text or
+  an icon.
+
+---
+
+## Step 9 — When to read the references
+
+Read **before answering**:
+
+- custom theme, brand palette, runtime theme switching, disabling theming —
+  `references/guides/theme.md`;
+- bundle size, selective registration, extra styles in the build —
+  `references/guides/treeshaking.md`;
+- Tailwind installation and configuration — `references/guides/tailwindcss.md`;
+- responsiveness, breakpoints, platform detection — `references/guides/display-and-platform.md`;
+- a whole complex screen (a form, a page skeleton, a table with a list,
+  a confirmation modal) — `references/patterns/`.
+
+| Guide | When to read |
+| --- | --- |
+| [Setup and themes](references/guides/setup.md) | Installing the package, wiring up styles, choosing a theme. |
+| [CDS 4 conventions](references/guides/conventions.md) | Uniform props, tokens instead of raw CSS, default values. |
+| [Forms with CDS 4](references/guides/forms.md) | Building forms: ready-made controls and atomic field composition. |
+| [CDS 3 → CDS 4 migration (digest)](references/guides/migration-cds3-to-cds4.md) | Porting existing code from CDS 3: breaking changes and renames. |
+| [Tailwind CSS v4 + CDS 4](references/guides/tailwindcss.md) | Installing and configuring Tailwind CSS v4 in a CDS project, utilities on CDS tokens. |
+| [Theming](references/guides/theme.md) | Custom themes, runtime theme switching (`useTheme`), token groups, disabling theming. |
+| [Tree-shaking](references/guides/treeshaking.md) | Per-component registration and the base style layer instead of the `styles` aggregate. |
+| [SASS variables](references/guides/sass-variables.md) | Overriding SASS variables at build time: `@use … with`, reset, typography, grid and breakpoints, settings file. |
+| [Icons](references/guides/icons.md) | Icon packs, wiring via UnoCSS, alias mappings, the legacy CDS 3 icon set. |
+| [Display & Platform](references/guides/display-and-platform.md) | Responsiveness: breakpoints, `useDisplay`, SCSS mixins, platform detection. |
+| [Global configuration](references/guides/global-configuration.md) | Default prop values: `defaults` in `createCds`, contextual defaults, `class`/`style`, aliases, `CdsDefaultsProvider`, `useDefaults`, `blueprint`. |
+| [Internationalization (i18n)](references/guides/internationalization.md) | Localizing component texts: the `locale` option in `createCds`, `$cds.*` keys, `useLocale`, `provideLocale`, date locales, RTL, custom adapters (vue-i18n). |
+| [Date Utils](references/guides/date-utils.md) | Working with dates without third-party libraries: `formatDate`/`extractDate` and masks (`DD.MM.YYYY`), arithmetic (`addToDate`), comparison, ranges, calendar math. |
+
+---
+
+## Output format
+
+1. **Complete working code** — with imports, without `TODO` stubs or
+   "...rest of the component".
+2. **`<script setup lang="ts">`** — if the project uses TypeScript; otherwise
+   omit `lang`.
+3. **Grouped imports** — Vue first, then CDS, then local ones.
+4. **Responsiveness** — at least mobile and desktop sizes for the layout.
+5. **2–4 sentences after the code** — which decisions were made and why
+   (component choice, form composition, responsiveness). Skip the explanation
+   for a trivial request.
+
+---
+
+## When to ask, when to act
+
+Build right away if the request is clear. Ask if:
+
+- the data shape is unknown and the whole structure depends on it ("make a
+  table" — which columns?);
+- there is a significant design fork that matters to the user (number of
+  columns, layout direction, set of actions);
+- the user refers to files or components you have not seen.
+
+In a borderline case state your assumptions in one line at the top and build:
+concrete code is easier for the user to react to than a question.