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

package/skills/cds-refactor/GENERATION.md

@@ -0,0 +1,44 @@
+# Генерация скиллов CDS
+
+- Версия `@central-design-system/components`: 4.0.0-alpha.6
+- Скиллы в пакете: cds-builder, cds-migrate, cds-refactor
+
+## Статистика
+
+- Семейств компонентов: 79
+- Контрактов meta.json: 125
+- Извлечено примеров: 710
+- Пропущено историй (неожиданная форма):
+  - нет
+
+## Полнота документации
+
+Счётчики ниже — долг документации, а не ошибка генерации: справочники
+собираются из того, что заполнено, и растут по мере переработки страниц
+компонентов.
+
+- Описание («что это и когда брать»): 77 из 79
+- Подсказка «Смотрите также»: 77 из 79
+- Рекомендации Do/Don't: 60 из 79 (пар правил: 169)
+- Props/events/slots/exposed без описания: 0
+- Без описания: CdsApp, CdsDefaultsProvider
+- Без рекомендаций: CdsApp, CdsButtonGroup, CdsCheckboxButton, CdsCounter, CdsDefaultsProvider, CdsDescription, CdsField, CdsInput, CdsLabel, CdsLoader, CdsMain, CdsMessages, CdsNotificationAlert, CdsPage, CdsRadio, CdsSelectionControl, CdsSelectionControlGroup, CdsSurface, CdsToastQueue
+- Без примеров: CdsApp, CdsDefaultsProvider, CdsRadio
+
+## Перевод (en)
+
+Генераторы читают английские страницы (`docs/en/`) и `@en` из JSDoc; там, где
+перевода ещё нет, подставляется русский текст — это долг перевода.
+
+- Страниц компонентов переведено: 77 из 79
+- Страниц: 107 — ok 101, outdated 0, drift 0, missing 6
+- Props/events/slots/exposed без `@en`: 0
+- Подписи DoDont/AnatomyDemo без `-en`/`labelEn`: 9
+
+## Регенерация
+
+```bash
+cd packages/components
+bun run generate:meta   # если менялись компоненты
+bun run generate:skill
+```

package/skills/cds-refactor/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: cds-refactor
+description: >-
+  Reviewing code and converting it to the CDS 4 design system
+  (`@central-design-system/components`, Central Design System, B2B-Center):
+  checking existing CDS code for mistakes and deprecated props, converting
+  plain HTML/CSS and Tailwind markup to CDS components, replacing hardcoded
+  colors with tokens, fixing form composition and accessibility. Use this
+  skill when asked to look at, assess, clean up or rewrite markup — «отревьюй
+  мой компонент», «что здесь не так», «правильно ли я использую CdsSelect»,
+  «переведи это на CDS», «перепиши на дизайн-систему», «замени свои кнопки на
+  CdsButton», «убери хардкод цветов» — even if the words "review" or
+  "refactoring" were never said. RU triggers: «проверь код на CDS», «сделай
+  code review вёрстки», «перепиши эту вёрстку на CDS», «замени div на
+  компоненты CDS», «почисти компонент», «правильно ли собрана форма».
+  EN triggers: «review my CDS component», «convert this HTML to CDS»,
+  «refactor to design system», «is this correct CDS usage». Do not use it for
+  migrating from CDS 3 to CDS 4 — that is what the `cds-migrate` skill is for.
+metadata:
+  author: cds-team
+  version: "4.0.0-alpha.6"
+  source: https://gitlab.b2b-center.ru/cds/central-design-system
+---
+
+# CDS Refactor & Review
+
+You review and improve markup built with the CDS 4 design system (version
+4.0.0-alpha.6). Depending on the request, the result is an analysis, rewritten
+code, or both. Read the code and the project context in full before producing
+any output.
+
+---
+
+## Step 1 — Determine the intent and the source
+
+Before answering, establish:
+
+- **Source type** — existing CDS code, plain HTML/CSS, Tailwind markup,
+  mixed.
+- **What is expected of you:**
+  - **review only** — "check", "what's wrong", "is this correct" → an
+    analysis with targeted fixes, no full rewrite;
+  - **refactoring** — "rewrite", "convert to CDS", "clean up" → rewritten
+    code;
+  - **both** — "look at it and fix it" → analysis first, then code.
+
+State your reading in the first line of the answer: "Reading this as existing
+CDS 4 code, mode — review".
+
+No code yet — ask for the code. Do not review a description of code.
+
+If the code contains CDS 3 patterns (`dist/cds.css`, `CdsDropdown`,
+`CdsTabsV2`, `@central-design-system/icons`) — this is not refactoring but
+migration: say so and hand the task over to the `cds-migrate` skill.
+
+---
+
+## Step 2 — Analyze the code along the axes
+
+Walk every axis regardless of the output mode: for a review these are
+findings, for refactoring — a checklist of edits. The detailed list of checks
+is `references/review-checklist.md`.
+
+**API existence.** Does every prop, event and slot used exist in the
+component's contract? An invented prop does not throw — it is silently
+ignored, and that is the most common cause of "why doesn't it work". The
+contracts live in the `cds-builder` skill
+(`../cds-builder/references/components/<slug>/api.md`); if it is not
+installed —
+`node_modules/@central-design-system/components/llms/llms-components.txt`.
+When `cds-builder` is installed next to this skill, check this axis
+mechanically — both the incoming code and your rewritten result:
+
+```bash
+node ../cds-builder/scripts/check-contracts.mjs <file.vue>
+```
+
+**Component choice.** Was something hand-built that the library already has:
+a dropdown assembled from `CdsSurface` and `CdsList` instead of `CdsSelect`,
+a table made of `div`s instead of `CdsTable`, a custom field from `CdsField`
++ `CdsInput` instead of `CdsTextInput`.
+
+**Tokens instead of raw values.** Are there `#fff`, `16px`, `rgb(...)` in the
+styles; is color set via the `color` / `bgColor` / `appearance` props.
+Hardcoding breaks theming and the dark theme.
+
+**Form composition.** Are the label, field, hint and error linked — through a
+ready-made control or `CdsField`. A standalone `<label>` next to `CdsInput`
+does not link them for a screen reader.
+
+**Accessibility.** `aria-label` on icon buttons, `alt` on images, heading
+hierarchy, state conveyed by more than color, keyboard accessibility.
+
+**Responsiveness.** Is behavior defined for at least two sizes; are there
+fixed widths that break mobile.
+
+**Structure.** Extra nesting, margins on every sibling instead of the
+container's `gap`, a repeated block that begs to become a component.
+
+**Deprecated.** Props marked deprecated in the contract, and `[CDS UPGRADE]`
+warnings.
+
+---
+
+## Step 3a — Output in review mode
+
+Split the findings by significance:
+
+**Critical** — broken or excludes users:
+
+- a prop, event or slot the component does not have;
+- a field without a linked label;
+- an icon button without `aria-label`;
+- an interactive element not reachable from the keyboard.
+
+**Improvements** — works, but incorrectly:
+
+- hardcoded colors and sizes instead of tokens;
+- hand-building what exists ready-made;
+- no responsive behavior;
+- deprecated props.
+
+**Optional** — taste and future work: extract a repeated block into a
+component, flatten nesting, complete the types.
+
+For every critical finding and significant improvement, show the minimal
+edit:
+
+```
+**Icon button without an accessible name** (Critical)
+The delete button has no text; a screen reader will announce it as "button".
+
+<!-- Before -->
+<CdsButton icon="delete" @click="remove" />
+<!-- After -->
+<CdsButton icon="delete" aria-label="Delete" @click="remove" />
+```
+
+Skip empty sections. Scale the volume to the size of the code: a 20-line
+component needs a short analysis, not an exhaustive one.
+
+---
+
+## Step 3b — Output in refactoring mode
+
+Mapping tables:
+
+- plain HTML and CSS → `references/html-to-cds.md`;
+- Tailwind markup → `references/tailwind-to-cds.md`.
+
+### Preserving behavior is non-negotiable
+
+- Event handlers, state and conditional rendering are carried over **as is**.
+- Existing `aria-*` attributes are kept; missing ones are added.
+- Tag semantics are preserved: a `<nav>` does not turn into a nameless
+  container.
+- A working partially converted component beats a fully converted broken one.
+  Not sure about a replacement — leave it as it was and say so.
+- Do not change logic "while you're at it". A markup refactor is not the
+  place to fix business rules.
+
+### Output format
+
+1. **Rewritten code** — in full, with imports, no stubs.
+2. **What changed** — a list, only the non-obvious:
+   ```
+   - <button class="btn-primary"> → CdsButton appearance="primary"
+   - background: #f5f5f5 → token --cds-color-surface-secondary
+   - Custom field from label + input → CdsTextInput (links label and error)
+   - Submit handler and validation left unchanged
+   ```
+3. **Suggestions** (if any) — what is worth doing beyond this edit.
+
+---
+
+## When to ask, when to act
+
+Act right away if the code and the intent are clear. Ask if:
+
+- there is no code;
+- the component is large and the scope is unclear ("rewrite everything or
+  just the form?");
+- the behavior is ambiguous and can be read two ways;
+- there is external state or styles you cannot see, and they change the
+  output.
+
+When acting without asking — state your assumptions in the first line.

package/skills/cds-refactor/references/html-to-cds.md

@@ -0,0 +1,80 @@
+# Plain HTML and CSS → CDS 4
+
+The mappings below are a starting point, not a find-and-replace. Before
+substituting a component, open its `api.md`: take the prop set from there.
+
+## Elements
+
+| HTML | CDS |
+| --- | --- |
+| `<button>` | `CdsButton` |
+| `<a>` inside text | `CdsLink` |
+| `<a>` styled as a button | `CdsButton` with `to` / `href` |
+| `<input type="text">` with a label | `CdsTextInput` |
+| `<input type="password">` | `CdsTextInput` with `type="password"` |
+| `<textarea>` | `CdsTextArea` |
+| `<select>` | `CdsSelect` |
+| `<input type="checkbox">` | `CdsCheckbox` |
+| `<input type="radio">` in a group | `CdsRadioGroup` |
+| `<input type="file">` | `CdsFileInput` |
+| `<input type="date">` | `CdsDateInput` |
+| `<img>` | `CdsImage` (keep the `alt`) |
+| `<table>` | `CdsTable` (`columns` + `data`) |
+| `<ul>` / `<ol>` of uniform items | `CdsList` |
+| Block with a border, a heading and actions | `CdsCard` |
+| Styled container without card semantics | `CdsSurface` |
+| Custom modal `<div>` with an overlay | `CdsModal` |
+| Tooltip via `title` | `CdsTooltip` |
+| Counter badge | `CdsBadge` |
+| Status label | `CdsStatus` or `CdsTag` |
+
+Leave markup with no visual role (`<div class="wrapper">`) as a plain
+element — do not replace it with `CdsSurface` just for the sake of "a CDS
+component".
+
+## Styles
+
+| CSS | CDS way |
+| --- | --- |
+| `color: #333` | `color` prop or `rgb(var(--cds-color-text-primary))` |
+| `background: #f5f5f5` | `bgColor` prop or a `--cds-color-surface-*` token |
+| `border: 1px solid #e0e0e0` | `--cds-color-border-*` token |
+| `padding: 16px` | `p-4` utility (Tailwind) or a spacing token |
+| `border-radius: 8px` | `rounded-200` or a radius token |
+| `font-size: 14px` | the component's `size` prop or a typography utility |
+| `display: flex; gap: 16px` | `flex gap-4` |
+| `width: 100%` on a button | `block` prop on `CdsButton` |
+
+Exact token names — in `../cds-builder/references/tokens/themes.md`
+(or in `node_modules/@central-design-system/components/llms/llms-tokens.txt`
+if the `cds-builder` skill is not installed).
+
+## Forms
+
+The most common finding is a hand-assembled field:
+
+```html
+<!-- Before -->
+<label for="email">Email</label>
+<input id="email" type="email" v-model="email" />
+<span class="error">{{ error }}</span>
+
+<!-- After -->
+<CdsTextInput v-model="email" label="Email" type="email" :rules="rules.email" />
+```
+
+`CdsTextInput` links the label, the field and the error message itself — done
+by hand this takes `for`/`id` and `aria-describedby`, which people usually
+forget.
+
+If a ready-made control truly does not exist, a field is assembled from the
+atoms `CdsField` / `CdsLabel` / `CdsDescription` / `CdsMessages` /
+`CdsInput` — but first make sure it truly does not exist.
+
+## What to carry over unchanged
+
+- Handlers (`@click`, `@submit`), state, conditional rendering.
+- Existing `aria-*` and `role` attributes.
+- Semantic tags: `<nav>`, `<main>`, `<section>` stay where they are.
+- Animations and complex selectors that cannot be expressed with props —
+  leave them in CSS and say so.

package/skills/cds-refactor/references/review-checklist.md

@@ -0,0 +1,73 @@
+# CDS 4 code review checklist
+
+The checks are grouped by the axes from step 2 of the skill. For a review
+this is a list of findings, for refactoring — a list of edits. Do not show
+empty sections in the answer.
+
+## API existence
+
+- [ ] Every prop in the code exists in the component's `api.md`.
+- [ ] Every `@event` exists in the contract (a common mistake — `@change`
+      where the component emits `@update:modelValue`).
+- [ ] Every `#slot` exists in the contract.
+- [ ] Props marked deprecated are replaced.
+- [ ] No `[CDS UPGRADE]` warnings in the dev-mode console.
+
+An invented prop does not raise an error — Vue silently puts it into the
+attributes. This is a critical finding, not a nitpick.
+
+## Component choice
+
+- [ ] Nothing is hand-built that exists ready-made (dropdown, table, modal,
+      input field).
+- [ ] The narrowest suitable component is used, not a generic surface with
+      hand-rolled markup.
+- [ ] Atoms (`CdsField`, `CdsInput`, `CdsSurface`) are used only where a
+      ready-made component truly does not exist.
+
+## Tokens
+
+- [ ] No hardcoded colors in the styles (`#fff`, `rgb(...)`, `hsl(...)`).
+- [ ] No fixed sizes where a `size` prop exists.
+- [ ] Color is set via the `color` / `bgColor` / `appearance` props.
+- [ ] Custom CSS is written on `--cds-*` tokens.
+- [ ] The dark theme is not broken by hardcoding.
+
+## Forms
+
+- [ ] The label is linked to the field — through a ready-made control or
+      `CdsField`, not a standalone `<label>` next to it.
+- [ ] Errors are shown by the component's mechanism, not duplicated by hand.
+- [ ] Validation rules live on the fields, aggregation — on `CdsForm`.
+- [ ] The submit button is not disabled on "form is invalid": the user must
+      be able to click and see the errors.
+- [ ] During a request the button is in `loading`, resubmitting is
+      impossible.
+
+## Accessibility
+
+- [ ] Icon buttons have an `aria-label`.
+- [ ] Images have a meaningful `alt` (or `alt=""` for decorative ones).
+- [ ] Headings follow their levels without gaps.
+- [ ] State is conveyed by more than color.
+- [ ] Interactive elements are keyboard-accessible; focus is not removed via
+      `outline: none` without a replacement.
+- [ ] The click handler sits on a button or a link, not on a `div`.
+
+## Responsiveness
+
+- [ ] Behavior is defined for at least two screen sizes.
+- [ ] No fixed widths that break mobile.
+- [ ] Long tables and text do not overflow the screen.
+
+## Structure
+
+- [ ] No nesting without a semantic reason.
+- [ ] Spacing between siblings is set with `gap`, not each sibling's margin.
+- [ ] A block repeated three times or more is extracted into a component.
+- [ ] Imports are grouped: Vue, CDS, local.
+
+## Types
+
+- [ ] The component's props are typed.
+- [ ] No `any` where the type is known from the CDS contract.

package/skills/cds-refactor/references/tailwind-to-cds.md

@@ -0,0 +1,65 @@
+# Tailwind markup → CDS 4
+
+**Tailwind does not get removed from the project.** CDS 4 is officially
+integrated with Tailwind CSS v4, and utility-based layout is the recommended
+way to build markup. The refactoring task here is different: replace
+**hand-made controls** assembled from `div`s and utilities with ready-made
+CDS components.
+
+## What to replace
+
+| Hand-made with Tailwind | CDS component |
+| --- | --- |
+| `<button class="px-4 py-2 bg-blue-600 rounded text-white">` | `CdsButton` |
+| `<div class="border rounded-lg p-4 shadow">` with a heading and actions | `CdsCard` |
+| `<input class="border rounded px-3 py-2">` with a standalone `<label>` | `CdsTextInput` |
+| Dropdown built on `absolute` + `hidden` | `CdsSelect` / `CdsMenu` |
+| Modal built on `fixed inset-0 bg-black/50` | `CdsModal` |
+| Table made of `grid` rows | `CdsTable` |
+| `<span class="px-2 py-1 rounded-full text-xs bg-green-100">` | `CdsTag` or `CdsStatus` |
+| Spinner made of `animate-spin border-t-transparent` | `CdsProgressCircle` |
+| Gray placeholder rectangles on `animate-pulse` | `CdsSkeletonLoader` |
+
+The tell of a hand-made control: a set of utilities reproduces behavior that
+has states (hover, focus, disabled, loading). CDS already has these things
+built and keyboard-accessible.
+
+## What to keep
+
+Layout, spacing and typography utilities stay:
+
+```html
+<div class="flex flex-col gap-4 md:flex-row md:items-center">
+  <CdsTextInput v-model="query" label="Search" />
+  <CdsButton text="Find" />
+</div>
+```
+
+## Colors: from the Tailwind palette to CDS tokens
+
+This is the main replacement in the styles. Classes like `bg-gray-100`,
+`text-gray-500`, `border-gray-200` know nothing about CDS themes and do not
+switch in the dark theme.
+
+| Before | After |
+| --- | --- |
+| `bg-white`, `bg-gray-50` | `bg-surface-primary`, `bg-surface-secondary` |
+| `text-gray-900`, `text-gray-500` | `text-primary`, `text-secondary` |
+| `border-gray-200` | `--cds-color-border-*` token |
+| `bg-blue-600` on a button | `appearance="primary"` on `CdsButton` |
+| `rounded-lg` | `rounded-200` (CDS radius token) |
+| `p-4`, `gap-2`, `mt-2` | keep as is — CDS uses the standard Tailwind spacing scale |
+
+Exact names of the available utilities and tokens — in the guide
+`../cds-builder/references/guides/tailwindcss.md` and in
+`../cds-builder/references/tokens/themes.md`. Do not guess a token name by
+analogy: if the one you need does not exist, say so and keep the current
+value.
+
+## Order of work
+
+1. Find the hand-made controls and replace them with CDS components.
+2. Replace Tailwind palette classes with CDS classes and tokens.
+3. Keep the layout utilities; align the spacing scale with the CDS scale.
+4. Check that the states (hover, focus, disabled) are no longer described by
+   hand — the component provides them.