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

package/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "cds",
+  "description": "Agent Skills for the Central Design System (CDS 4): build UI, migrate from CDS 3, refactor to CDS",
+  "version": "4.0.0-alpha.6",
+  "author": { "name": "magersoft" }
+}

package/README.md

@@ -0,0 +1,218 @@
+# 🤖 CDS AI Agent Skills
+
+Agent Skills for the **Central Design System (CDS 4)** design system, made for AI
+agents (Claude Code and compatible ones). Skills fire automatically based on what
+you ask — you don't have to name them.
+
+There are three of them, split by task so that a question about migration doesn't
+drag in knowledge about building interfaces:
+
+| Skill | What it covers |
+| --- | --- |
+| [`cds-builder`](#cds-builder) | Build UI, plug in the library, themes and tokens |
+| [`cds-migrate`](#cds-migrate) | Move a project from CDS 3 to CDS 4 |
+| [`cds-refactor`](#cds-refactor) | Review code and convert someone else's markup to CDS |
+
+## 🚀 Installation
+
+```bash
+bun add -D @central-design-system/skills
+npx cds-skills install
+```
+
+The command copies all three skills into `.claude/skills/` of the current project.
+
+```bash
+npx cds-skills install cds-builder      # only the one you need
+npx cds-skills install --dir <path>     # a different skills directory
+npx cds-skills list                     # what is available and what is installed
+```
+
+## 🔄 Updating
+
+```bash
+bun update @central-design-system/skills
+npx cds-skills install
+```
+
+`npx cds-skills list` shows the installed version — the same one lives in
+`GENERATION.md` of every skill (CDS version, git SHA, date and generation stats).
+
+## cds-builder
+
+The main skill. Building an interface, plugging in the library, themes and tokens.
+
+**When it fires**
+
+- building any UI: a form, a page, a table, a card, a modal, a dashboard, a header;
+- plugging CDS into a new or existing project, configuring `createCds`, styles,
+  Tailwind;
+- questions about the contract: "what props does CdsSelect have", "does CdsButton
+  have a variant";
+- themes, brand palette, tokens, bundle size;
+- building from a screenshot or a mockup.
+
+**Example requests:** _"build a sign-in form on CDS with validation"_, _"install
+CDS in my project"_, _"lay out an order list page"_, _"add a custom theme"_,
+_"here is a screenshot, build it on CDS"_.
+
+**What it does.** Reads the project context (CDS version, bundler, TypeScript,
+whether Tailwind is present), picks a component through a decision tree, checks
+every prop against the contract and returns a working SFC. The key rule of the
+skill is never to invent props: an invented prop looks plausible and silently
+does nothing.
+
+**Output format:** complete working code with imports → 2–4 sentences about the
+decisions made (for a trivial request — no explanation at all).
+
+**Contract linter.** The skill ships a mechanical check of the generated
+markup — every `Cds*` tag in the given `.vue` files is checked against the
+API reference (the component exists, every prop and event is real):
+
+```bash
+node .claude/skills/cds-builder/scripts/check-contracts.mjs src/components/MyForm.vue
+```
+
+The agent runs it on the files it created; you can also wire it into CI or
+a pre-commit hook. Exit code 0 — clean, 1 — problems found. `cds-refactor`
+uses the same script to verify code before and after a rewrite.
+
+**Reference files** (loaded on demand):
+
+| File | What's inside | When it loads |
+| --- | --- | --- |
+| `references/component-decision-tree.md` | What every component is for, plus a breakdown of similar pairs | The component isn't named, or the choice is in doubt |
+| `references/components/<name>/api.md` | The full contract: props / events / slots / exposed | Always, before using a component |
+| `references/components/<name>/examples.md` | Usage examples | A working pattern is needed |
+| `references/components/<name>/guidelines.md` | Do / Don't rules | Not present for every component |
+| `references/components/<name>/tokens.md` | Local SCSS variables | Fine-tuning styles |
+| `references/tokens/` | Themes and palette | Working with color and themes |
+| `references/guides/` | Installation, conventions, forms, theming, Tailwind, tree-shaking, responsiveness | Depends on the topic |
+| `references/patterns/` | Playbooks: form, page shell, list table, modal | A whole complex screen |
+
+## cds-migrate
+
+Moving a project from CDS 3 to CDS 4.
+
+**When it fires**
+
+- bumping the CDS version, something broke after the update;
+- `[CDS UPGRADE]` warnings in the console;
+- CDS 3 patterns in the code: `dist/cds.css`, `@central-design-system/icons`,
+  `CdsDropdown`, `CdsRadioButton`, `CdsProgress`, `CdsTabsV2`,
+  `CdsCheckboxGroup`, `CdsContainer` — even if the word "migration" never came up.
+
+**Example requests:** _"migrate the project to CDS 4"_, _"styles fell apart after
+the update"_, _"it can't find dist/cds.css"_, _"what changed in CDS 4"_.
+
+**What it does.** Surveys the project and shows the scope of work before making
+any edits, then goes step by step: package and styles entry point → icons →
+component and prop renames → CSS architecture → composables and exports. It ends
+with a verification checklist and says honestly what is left uncovered.
+
+**Reference file:** `references/migration-full.md` — the full migration guide with
+every Before / After pair.
+
+## cds-refactor
+
+Reviewing existing code and converting someone else's markup to CDS.
+
+**When it fires**
+
+- review: "check this", "what's wrong here", "am I using CdsSelect correctly";
+- conversion: plain HTML/CSS → CDS, hand-rolled Tailwind controls → CDS;
+- cleanup: hardcoded colors instead of tokens, form fields assembled by hand,
+  accessibility problems.
+
+**Example requests:** _"review my component"_, _"convert this markup to CDS"_,
+_"replace my own buttons with CdsButton"_, _"drop the hardcoded colors"_.
+
+**Output modes**
+
+- **Review only** → a breakdown by importance: Critical / Improvements / Optional,
+  with the smallest possible fix for each finding.
+- **Refactor** → rewritten code + a list of changes + suggestions.
+- **Both** → the breakdown first, then the code.
+
+Behavior is preserved either way: handlers, state and conditional rendering are
+carried over as they are. A partially converted working component beats a fully
+converted broken one.
+
+**Reference files:** `references/html-to-cds.md`, `references/tailwind-to-cds.md`
+(mapping tables), `references/review-checklist.md` (the review checklist).
+
+Refactoring does not strip Tailwind out of the project: CDS 4 is integrated with
+Tailwind CSS v4, and laying out with utilities is the recommended approach. Only
+hand-rolled controls get replaced.
+
+This skill does not handle migration from CDS 3 — `cds-migrate` is there for that.
+
+
+## 📂 Package structure
+
+```
+@central-design-system/skills
+├── bin/cds-skills.mjs      # installer
+├── .claude-plugin/plugin.json
+└── skills/
+    ├── cds-builder/
+    │   ├── SKILL.md
+    │   ├── GENERATION.md
+    │   ├── scripts/check-contracts.mjs
+    │   └── references/
+    │       ├── component-decision-tree.md
+    │       ├── components/<name>/{api,examples,guidelines,tokens}.md
+    │       ├── tokens/{themes,colors}.md
+    │       ├── guides/
+    │       └── patterns/
+    ├── cds-migrate/
+    │   ├── SKILL.md
+    │   ├── GENERATION.md
+    │   └── references/migration-full.md
+    └── cds-refactor/
+        ├── SKILL.md
+        ├── GENERATION.md
+        └── references/{html-to-cds,tailwind-to-cds,review-checklist}.md
+```
+
+The heavy component reference lives in `cds-builder` only and is not duplicated;
+`cds-migrate` and `cds-refactor` link to it, and if it isn't installed — to the
+`llms/` directory from the library's npm package.
+
+## 🧩 Agents without skill support
+
+For Cursor, Copilot, Windsurf and others there is a catalog following the
+[llmstxt.org](https://llmstxt.org) convention — it ships both in the library's npm
+package (`node_modules/@central-design-system/components/llms/`) and on the
+documentation site:
+
+| File | What's inside |
+| --- | --- |
+| `llms.txt` | Index: the documentation sets and what every component is for |
+| `llms-full.txt` | Everything at once: guides, tokens, components, migration |
+| `llms-components.txt` | Components only: purpose, examples, API contract |
+| `llms-tokens.txt` | Tokens and themes only |
+| `llms-guides.txt` | Guides only |
+| `llms-migration.txt` | CDS 3 → CDS 4 migration only |
+
+Add a pointer to the file you need in your product's instructions (`AGENTS.md`,
+`.cursorrules`, `.github/copilot-instructions.md`). More on the
+[LLMs.txt](https://cds.b2b-center.ru/en/guide/ai/llms-txt) page.
+
+## 🛠️ Regeneration (for CDS developers)
+
+The contents of the skills are generated in the monorepo:
+
+```bash
+cd packages/components
+bun run generate:meta    # if components changed
+bun run generate:skill
+```
+
+The `cds-builder/`, `cds-migrate/` and `cds-refactor/` directories are
+disposable — do not edit them by hand. Handwritten content lives in
+`packages/components/build/plugins/`:
+
+- `generate-skill/content/<skill>/` — the body of `SKILL.md`, playbooks, mapping
+  tables, the breakdown of similar pairs;
+- `content/guides/` — guides shared with the `llms/` reference.

package/bin/cds-skills.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+/**
+ * Installer of the CDS design system Agent Skills into a consumer project.
+ *
+ * `npx cds-skills install [skill…] [--dir <path>]` copies skills from this
+ * package into `.claude/skills/` of the current project (existing copies are
+ * overwritten). With no arguments, all skills are installed.
+ * `npx cds-skills list` shows what the package ships and what is installed.
+ *
+ * Updating skills = update the package and run install again.
+ */
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const SKILLS_ROOT = resolve(PACKAGE_ROOT, 'skills');
+
+/** Skills = package directories that contain a `SKILL.md` file. */
+const AVAILABLE = readdirSync(SKILLS_ROOT, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && existsSync(resolve(SKILLS_ROOT, entry.name, 'SKILL.md')))
+  .map((entry) => entry.name)
+  .sort();
+
+/** Pre-4.0.0 layout: a single `cds` skill instead of three. */
+const LEGACY_SKILL = 'cds';
+
+const USAGE = `Usage: npx cds-skills <command> [skill…] [--dir <path>]
+
+Commands:
+  install [skill…]   Install skills (all of them when no arguments given)
+  list               Show available and installed skills
+
+Options:
+  --dir <path>       Skills directory (default: .claude/skills)
+  -h, --help         Show this help
+
+Available skills: ${AVAILABLE.join(', ')}`;
+
+const { values, positionals } = parseArgs({
+  options: {
+    dir: { type: 'string', default: '.claude/skills' },
+    help: { type: 'boolean', short: 'h', default: false }
+  },
+  allowPositionals: true
+});
+
+const [command, ...requested] = positionals;
+
+if (values.help || !command) {
+  console.log(USAGE);
+  process.exit(values.help ? 0 : 1);
+}
+
+if (!['install', 'list'].includes(command)) {
+  console.error(`Unknown command: ${command}\n\n${USAGE}`);
+  process.exit(1);
+}
+
+const skillsDir = resolve(process.cwd(), values.dir);
+
+/** Version and SHA from `GENERATION.md` of an installed or packaged skill. */
+function provenance(skillDir) {
+  try {
+    const generation = readFileSync(resolve(skillDir, 'GENERATION.md'), 'utf-8');
+    const version = generation.match(/`@central-design-system\/components`: (.+)/)?.[1];
+    const sha = generation.match(/Git SHA: `(\w{8})/)?.[1];
+    return version ? `CDS ${version}${sha ? `, ${sha}` : ''}` : '';
+  } catch {
+    return '';
+  }
+}
+
+if (command === 'list') {
+  console.log(`Available in the package (${SKILLS_ROOT}):`);
+  for (const skill of AVAILABLE) {
+    console.log(`  ${skill} — ${provenance(resolve(SKILLS_ROOT, skill)) || 'no provenance'}`);
+  }
+
+  console.log(`\nInstalled in ${skillsDir}:`);
+  const installed = AVAILABLE.filter((skill) => existsSync(resolve(skillsDir, skill)));
+
+  if (installed.length === 0) {
+    console.log('  none — install with: npx cds-skills install');
+  } else {
+    for (const skill of installed) {
+      console.log(`  ${skill} — ${provenance(resolve(skillsDir, skill)) || 'no provenance'}`);
+    }
+  }
+
+  if (existsSync(resolve(skillsDir, LEGACY_SKILL))) {
+    console.log(`\n! Found the legacy "${LEGACY_SKILL}" layout — it will be removed on the next install.`);
+  }
+
+  process.exit(0);
+}
+
+const unknown = requested.filter((skill) => !AVAILABLE.includes(skill));
+if (unknown.length > 0) {
+  console.error(`Unknown skills: ${unknown.join(', ')}\nAvailable: ${AVAILABLE.join(', ')}`);
+  process.exit(1);
+}
+
+const toInstall = requested.length > 0 ? requested : AVAILABLE;
+
+for (const skill of toInstall) {
+  const target = resolve(skillsDir, skill);
+
+  rmSync(target, { recursive: true, force: true });
+  cpSync(resolve(SKILLS_ROOT, skill), target, { recursive: true });
+
+  const details = provenance(target);
+  console.log(`✓ ${skill} → ${target}${details ? ` (${details})` : ''}`);
+}
+
+// Before 4.0.0 the package installed a single `cds` skill; left in place, it
+// duplicates the references and competes with `cds-builder` for activation.
+const legacyDir = resolve(skillsDir, LEGACY_SKILL);
+if (existsSync(legacyDir) && !AVAILABLE.includes(LEGACY_SKILL)) {
+  rmSync(legacyDir, { recursive: true, force: true });
+  console.log(`✓ removed the legacy layout at ${legacyDir} — cds-builder replaces it`);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@central-design-system/skills",
+  "version": "4.0.0-alpha.6",
+  "author": "magersoft",
+  "description": "Agent Skills for the Central Design System (CDS 4): component API reference, examples, tokens, and guides for AI agents",
+  "homepage": "https://cds.b2b-center.ru/",
+  "repository": "https://gitlab.b2b-center.ru/cds/central-design-system",
+  "type": "module",
+  "bin": {
+    "cds-skills": "bin/cds-skills.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    ".claude-plugin",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "keywords": [
+    "cds",
+    "design system",
+    "agent skills",
+    "claude",
+    "ai",
+    "vue"
+  ]
+}

package/skills/cds-builder/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
+```