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

package/skills/cds-builder/references/components/cds-highlight/examples.md

@@ -0,0 +1,313 @@
+# CdsHighlight — usage examples
+
+> Extracted from Storybook stories (`docs/*.stories.ts`) by `bun run generate:skill`. Do not edit manually.
+> The full component contract is in [api.md](api.md). `v-bind="args"` in templates refers to the props from the **Args** block of the corresponding example.
+
+Highlighting explains why a row made it into the results: the component finds the matches with the query (`query`) or with ready ranges (`matches`) in the text and wraps them into `mark`. Take it for search results, autocomplete suggestions and filtered lists.
+
+## Search query
+
+The `text` prop takes the source string, `query` takes what the user was looking for. The query can be a string or an array of terms: all of them get highlighted.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsHighlight } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-2">
+    <CdsHighlight
+      class="text-900 text-content-primary"
+      text="Шаблоны: договор поставки, договор аренды и договор подряда"
+      query="договор"
+    />
+
+    <CdsHighlight
+      class="text-900 text-content-primary"
+      text="Шаблоны: договор поставки, договор аренды и договор подряда"
+      :query="['поставки', 'подряда']"
+    />
+  </div>
+</template>
+```
+
+## All occurrences
+
+By default the first occurrence of every term is highlighted. The `match-all` prop highlights all of them — in a long text this shows the full picture.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsHighlight } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-2">
+    <CdsHighlight
+      class="text-900 text-content-primary"
+      text="Шаблоны: договор поставки, договор аренды и договор подряда"
+      query="договор"
+    />
+
+    <CdsHighlight
+      class="text-900 text-content-primary"
+      text="Шаблоны: договор поставки, договор аренды и договор подряда"
+      query="договор"
+      match-all
+    />
+  </div>
+</template>
+```
+
+## Case
+
+The `ignore-case` prop looks for matches regardless of the case. You need it almost always when the query is typed by the user.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsHighlight } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-2">
+    <CdsHighlight class="text-900 text-content-primary" text="ИНН, Инн и инн — одно и то же" query="инн" match-all />
+
+    <CdsHighlight
+      class="text-900 text-content-primary"
+      text="ИНН, Инн и инн — одно и то же"
+      query="инн"
+      match-all
+      ignore-case
+    />
+  </div>
+</template>
+```
+
+## Ready ranges
+
+When the matches are found by the server rather than by the browser, pass them into `matches` — an array of `[start, end]` pairs by the indexes of the source string. The ranges take precedence over `query`, and overlapping ones are merged automatically.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsHighlight } from '@central-design-system/components';
+
+// Диапазоны [start, end] в исходной строке: «канцелярских товаров» и «офиса»
+const matches = [
+  [28, 48],
+  [67, 72]
+] as const;
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsHighlight
+      class="text-900 text-content-primary"
+      text="Заявка на участие в закупке канцелярских товаров для регионального офиса"
+      :matches="matches"
+    />
+  </div>
+</template>
+```
+
+## Color and density
+
+The `color` prop sets the color of the highlighting — the background is tinted with it too, so a single value is enough. `opacity` changes the density of the background.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsHighlight } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-2">
+    <CdsHighlight class="text-900 text-content-primary" text="Подсветка цветом по умолчанию" query="по умолчанию" />
+
+    <CdsHighlight
+      class="text-900 text-content-primary"
+      text="Подсветка цветом бренда"
+      query="цветом бренда"
+      color="brand-primary"
+    />
+
+    <CdsHighlight
+      class="text-900 text-content-primary"
+      text="Более плотный фон подсветки"
+      query="плотный фон"
+      color="green"
+      opacity="28%"
+    />
+  </div>
+</template>
+```
+
+## Markup
+
+The `tag` prop sets the tag of the wrapper (`span` by default), `mark-class` adds your own class to every match.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsHighlight } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-2">
+    <CdsHighlight
+      class="text-900 text-content-primary"
+      tag="p"
+      text="Подсветка внутри абзаца: тег задаётся пропом tag"
+      query="внутри абзаца"
+    />
+
+    <CdsHighlight
+      class="text-900 text-content-primary"
+      text="Совпадению можно добавить свой класс"
+      query="свой класс"
+      mark-class="font-bold"
+    />
+  </div>
+</template>
+```
+
+## Searching through a list
+
+The same query filters the list and highlights the matches in the found rows. `match-all` and `ignore-case` keep the highlighting and the filter consistent: once a row made it into the results, the match inside it is visible.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsHighlight, CdsTextInput } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const query = ref('дог');
+
+const documents = [
+  'Договор поставки канцелярии',
+  'Договор аренды помещения',
+  'Акт сверки взаиморасчётов',
+  'Счёт на оплату № 1024'
+];
+
+const found = computed(() => {
+  const needle = query.value.trim().toLowerCase();
+
+  return needle ? documents.filter((document) => document.toLowerCase().includes(needle)) : documents;
+});
+</script>
+
+<template>
+  <div class="flex w-[350px] flex-col gap-2 m-auto">
+    <CdsTextInput v-model="query" placeholder="Поиск по документам" prepend-inner-icon="search" clearable />
+
+    <ul class="m-0 flex list-none flex-col gap-1 p-0">
+      <li v-for="document in found" :key="document">
+        <CdsHighlight
+          class="text-900 text-content-primary"
+          :text="document"
+          :query="query.trim()"
+          match-all
+          ignore-case
+        />
+      </li>
+
+      <li v-if="found.length === 0" class="text-900 text-content-secondary">Ничего не найдено</li>
+    </ul>
+  </div>
+</template>
+```
+
+## A query of several words
+
+Split the typed phrase into words and pass them as an array into `query` — the component highlights every word separately, even if they stand far apart in the text.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsHighlight, CdsTextInput } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const query = ref('бумага а4');
+
+const description =
+  'Закупка бумаги: бумага А4 плотностью 80 г/м², бумага А3 и картон. Поставка на склад в Москве до конца месяца.';
+
+const terms = computed(() => query.value.trim().split(/\s+/).filter(Boolean));
+</script>
+
+<template>
+  <div class="flex w-[350px] flex-col gap-2 m-auto">
+    <CdsTextInput v-model="query" label="Запрос" placeholder="Например: бумага а4" clearable />
+
+    <CdsHighlight
+      class="text-900 text-content-primary"
+      tag="p"
+      :text="description"
+      :query="terms"
+      match-all
+      ignore-case
+    />
+  </div>
+</template>
+```
+
+## Matches from the server
+
+The full-text search on the backend already knows which fragments count as matches: it accounts for morphology, synonyms and typos. Give those ranges to `matches` — the client will not search anything again.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsHighlight } from '@central-design-system/components';
+import { ref } from 'vue';
+
+interface SearchResult {
+  id: number;
+  title: string;
+  matches: [number, number][];
+}
+
+const loading = ref(false);
+const results = ref<SearchResult[]>([]);
+
+// Ответ поиска: сервер сам решил, какие фрагменты считать совпадениями
+const response: SearchResult[] = [
+  { id: 1, title: 'Заявка на поставку бумаги А4 для офиса', matches: [[19, 28]] },
+  { id: 2, title: 'Договор поставки бумаги и картона', matches: [[17, 23]] }
+];
+
+const search = () => {
+  loading.value = true;
+  results.value = [];
+
+  setTimeout(() => {
+    results.value = response;
+    loading.value = false;
+  }, 1200);
+};
+</script>
+
+<template>
+  <div class="flex w-[350px] flex-col gap-2 m-auto">
+    <CdsButton text="Найти «бумага А4»" :loading="loading" @click="search" />
+
+    <ul class="m-0 flex list-none flex-col gap-1 p-0">
+      <li v-for="result in results" :key="result.id">
+        <CdsHighlight class="text-900 text-content-primary" :text="result.title" :matches="result.matches" />
+      </li>
+    </ul>
+  </div>
+</template>
+```

package/skills/cds-builder/references/components/cds-highlight/guidelines.md

@@ -0,0 +1,10 @@
+# CdsHighlight — guidelines
+
+> Extracted from `docs/demos/Guidelines.vue` by `bun run generate:skill`. Do not edit manually.
+> The full component contract is in [api.md](api.md).
+
+| ✅ Do | ❌ Don't |
+| --- | --- |
+| Only what the user searched for is highlighted — it is clear why the row made it into the results. | The whole row is highlighted: the highlighting stops highlighting anything. |
+| In a long text turn on match-all: the user sees every match at once. | Only the first occurrence is highlighted — it looks like there are no matches further on. |
+| For a query typed by the user turn on ignore-case — they do not double-check the case. | Без ignore-case запрос «инн» не находит «ИНН», и совпадение теряется. |

package/skills/cds-builder/references/components/cds-highlight/tokens.md

@@ -0,0 +1,18 @@
+# CdsHighlight — tokens (level 3)
+
+> Copy of the component's `styles/*.variables.scss`, taken by `bun run generate:skill`. Do not edit manually.
+> `--cds-*` are global level-2 tokens whose values come from the active theme: see [themes.md](../../tokens/themes.md).
+> Variables marked `!default` can be overridden at build time via SCSS.
+
+## _CdsHighlight.variables.scss
+
+```scss
+$highlight-opacity: 8% !default;
+$highlight-background: color-mix(
+  in srgb,
+  currentcolor var(--cds-highlight-opacity, $highlight-opacity),
+  transparent
+) !default;
+$highlight-border-radius: var(--cds-border-radius-100) !default;
+$highlight-color: inherit !default;
+```

package/skills/cds-builder/references/components/cds-icon/api.md

@@ -0,0 +1,33 @@
+# CdsIcon — API
+
+> Generated from meta.json by `bun run generate:skill`. Do not edit manually.
+> Examples: [examples.md](examples.md) · Guidelines: [guidelines.md](guidelines.md) · Tokens: [tokens.md](tokens.md)
+
+An icon is a short visual mark next to the text: the status of a record, the type of a file, the direction of a transition. The component takes an icon by name from a connected pack and subordinates its size, color and spacing to the design system tokens.
+
+## CdsIcon
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
+| `bgColor` | `string \| undefined` | — | no | Background color of the component |
+| `color` | `string \| undefined` | — | no | Component color |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `end` | `boolean \| undefined` | — | no | Adds spacing to the left of the icon — for an icon after the text |
+| `icon` | `IconValue \| undefined` | — | no | Name of the icon or the icon component to render |
+| `name` | `string \| undefined` | — | no | String name of an icon from a registered pack (an alias for icon) |
+| `opacity` | `string \| number \| undefined` | — | no | Opacity of the icon — a number between 0 and 1 |
+| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
+| `start` | `boolean \| undefined` | — | no | Adds spacing to the right of the icon — for an icon before the text |
+| `tag` | `string \| JSXComponent<any> \| undefined` | `'i'` | no | Custom HTML tag or component to render |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `any` | Name of the icon as text — an alternative to the `icon` prop |

package/skills/cds-builder/references/components/cds-icon/examples.md

@@ -0,0 +1,272 @@
+# CdsIcon — usage examples
+
+> Extracted from Storybook stories (`docs/*.stories.ts`) by `bun run generate:skill`. Do not edit manually.
+> The full component contract is in [api.md](api.md). `v-bind="args"` in templates refers to the props from the **Args** block of the corresponding example.
+
+An icon is a short visual mark next to the text: the status of a record, the type of a file, the direction of a transition. The component takes an icon by name from a connected pack and subordinates its size, color and spacing to the design system tokens.
+
+## Icon
+
+The `icon` prop takes the name of an icon from the default pack — `add` or `search`, for example. The `name` prop does the same and reads more naturally when the icon is set by a string. Besides a name, `icon` also accepts an icon component and an array of SVG paths, so you can pass your own graphics into it.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsIcon } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center justify-center gap-4">
+    <CdsIcon icon="add" />
+    <CdsIcon icon="search" />
+    <CdsIcon icon="settings" />
+    <CdsIcon name="star-fill" />
+  </div>
+</template>
+```
+
+## Sizes
+
+The `size` prop takes one of the scale values — from `xs` to `xl` — or a number in pixels when the icon works as an illustration. The default is `md`, level with the body text.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsIcon } from '@central-design-system/components';
+
+const sizes = CdsIcon.constants.sizes;
+</script>
+
+<template>
+  <div class="flex flex-wrap items-end justify-center gap-5">
+    <div v-for="size in sizes" :key="size" class="flex flex-col items-center gap-1">
+      <CdsIcon icon="star-fill" :size="size" />
+      <span class="text-50 text-content-secondary">{{ size }}</span>
+    </div>
+
+    <div class="flex flex-col items-center gap-1">
+      <CdsIcon icon="star-fill" :size="40" />
+      <span class="text-50 text-content-secondary">40</span>
+    </div>
+  </div>
+</template>
+```
+
+## Color
+
+Without `color` the icon inherits the text color of its parent — this is the default behavior and the right one in most cases. The `color` prop takes a palette token (`content-secondary`, `brand-primary`), a status color alias (`green`, `red`, `lemon`) or a `hex/rgb` value. The `opacity` prop mutes the icon without changing its color.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsIcon } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="text-brand-primary-content flex flex-wrap items-center justify-center gap-4">
+    <CdsIcon icon="star-fill" size="lg" />
+    <CdsIcon icon="star-fill" size="lg" color="content-secondary" />
+    <CdsIcon icon="check-fill" size="lg" color="green" />
+    <CdsIcon icon="error-fill" size="lg" color="red" />
+    <CdsIcon icon="star" size="lg" color="#9e45f9" />
+    <CdsIcon icon="star-fill" size="lg" color="brand-primary" />
+    <CdsIcon icon="star-fill" size="lg" color="brand-primary" :opacity="0.4" />
+  </div>
+</template>
+```
+
+## Spacing from the text
+
+The `start` and `end` props add spacing on the side of the text: `start` for an icon before the label, `end` for one after it. This saves you from picking margins by hand.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsIcon } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center justify-center gap-6">
+    <span>
+      <CdsIcon icon="download" start />
+      Скачать отчёт
+    </span>
+
+    <span>
+      Открыть в новой вкладке
+      <CdsIcon icon="external" end />
+    </span>
+  </div>
+</template>
+```
+
+## Reacting to a click
+
+If you attach a `@click` handler to an icon, it gets `role="button"`, joins the Tab order and changes the cursor; `disabled` removes it from the order and stops it from accepting clicks. This is handy for small toggles inside your own components — for a full-fledged action [CdsFunctionalButton](../cds-functional-button/api.md) fits better.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsIcon } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const count = ref(0);
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center justify-center gap-4">
+    <CdsIcon icon="refresh" size="lg" @click="count++" />
+    <CdsIcon icon="refresh" size="lg" color="content-disable" disabled @click="count++" />
+
+    <span class="text-100 text-content-secondary">Обновлений: {{ count }}</span>
+  </div>
+</template>
+```
+
+## Slot
+
+The name of the icon can be passed as text into the default slot — the result is the same as with `icon`. Useful when the name comes from an expression in the template.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsIcon } from '@central-design-system/components';
+
+const icon = 'notification';
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center justify-center gap-4">
+    <CdsIcon size="lg">star-fill</CdsIcon>
+    <CdsIcon size="lg">{{ icon }}</CdsIcon>
+  </div>
+</template>
+```
+
+## Statuses in a list
+
+An icon to the left of a label sets the status by color and shape, while the text names it in words. The colors come from the status aliases, `size="sm"` fits the icon to small text, and `start` adds the spacing before the label.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsIcon } from '@central-design-system/components';
+
+const orders = [
+  { id: 1, title: 'Счёт № 5512', status: 'Оплачен', icon: 'check-fill', color: 'green' },
+  { id: 2, title: 'Счёт № 5513', status: 'Ожидает оплаты', icon: 'clock', color: 'content-secondary' },
+  { id: 3, title: 'Счёт № 5514', status: 'Просрочен', icon: 'error-fill', color: 'red' },
+  { id: 4, title: 'Счёт № 5515', status: 'Требует проверки', icon: 'alert-fill', color: 'lemon' }
+];
+</script>
+
+<template>
+  <div class="m-auto flex w-[320px] flex-col gap-2">
+    <div v-for="order in orders" :key="order.id" class="flex items-center justify-between gap-3">
+      <span>{{ order.title }}</span>
+
+      <span class="text-200 text-content-secondary">
+        <CdsIcon :icon="order.icon" :color="order.color" size="sm" start />
+        {{ order.status }}
+      </span>
+    </div>
+  </div>
+</template>
+```
+
+## List of attachments
+
+The icon shows the type of a file and keeps the eye on the left edge of the list. The `lg` size makes it more noticeable than the label, and the `content-secondary` color keeps it from competing with the file name. The action next to it is already a button: `CdsFunctionalButton` with an `aria-label`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsFunctionalButton, CdsIcon } from '@central-design-system/components';
+
+const files = [
+  { name: 'Договор поставки № 42.pdf', size: '340 КБ', icon: 'doc' },
+  { name: 'Спецификация.xlsx', size: '82 КБ', icon: 'data-cards' },
+  { name: 'Приложения.zip', size: '4,1 МБ', icon: 'archive' }
+];
+</script>
+
+<template>
+  <div class="m-auto flex w-[320px] flex-col gap-3">
+    <div v-for="file in files" :key="file.name" class="flex items-center gap-2">
+      <CdsIcon :icon="file.icon" size="lg" color="content-secondary" />
+
+      <div class="flex min-w-0 flex-col">
+        <span class="truncate">{{ file.name }}</span>
+        <span class="text-100 text-content-secondary">{{ file.size }}</span>
+      </div>
+
+      <CdsFunctionalButton class="ml-auto" icon="download" :aria-label="`Скачать ${file.name}`" />
+    </div>
+  </div>
+</template>
+```
+
+## Progress of an operation
+
+The icon reflects the state of a process: the request is ready, is being sent, has been sent. Only `icon` and `color` change — the component repaints in place and the status line does not jump.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsIcon } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const state = ref<'idle' | 'sending' | 'done'>('idle');
+
+const status = computed(() => {
+  if (state.value === 'sending') return { icon: 'sandglass', color: 'content-secondary', text: 'Отправляем заявку…' };
+  if (state.value === 'done') return { icon: 'check-fill', color: 'green', text: 'Заявка отправлена' };
+
+  return { icon: 'doc', color: 'content-secondary', text: 'Заявка готова к отправке' };
+});
+
+function send() {
+  state.value = 'sending';
+  setTimeout(() => (state.value = 'done'), 1500);
+}
+</script>
+
+<template>
+  <div class="m-auto flex w-[300px] flex-col items-center gap-3">
+    <span class="text-content-secondary">
+      <CdsIcon :icon="status.icon" :color="status.color" start />
+      {{ status.text }}
+    </span>
+
+    <CdsButton text="Отправить" :loading="state === 'sending'" :disabled="state === 'done'" @click="send" />
+  </div>
+</template>
+```
+
+## A note inside text
+
+Inside a paragraph the icon aligns to the middle of the line, so you can put it right into the text. The `sm` size and `start` keep it from breaking the line.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsIcon } from '@central-design-system/components';
+</script>
+
+<template>
+  <p class="text-200 m-auto w-[360px] text-content-secondary">
+    <CdsIcon icon="info" size="sm" start />
+    Заявку можно отредактировать, пока она не отправлена. После отправки изменения согласовываются с заказчиком.
+  </p>
+</template>
+```

package/skills/cds-builder/references/components/cds-icon/guidelines.md

@@ -0,0 +1,10 @@
+# CdsIcon — guidelines
+
+> Extracted from `docs/demos/Guidelines.vue` by `bun run generate:skill`. Do not edit manually.
+> The full component contract is in [api.md](api.md).
+
+| ✅ Do | ❌ Don't |
+| --- | --- |
+| The icon stands next to a label and speeds up reading the line. | Without a label the icon has to be decoded: does a check mark mean «paid» or «verified»? |
+| The color comes from the palette — the icon follows the theme and stays readable. | An arbitrary color falls out of the theme: on a dark background such an icon gets lost. |
+| A clickable icon is a button: it has a name, hover states and keyboard focus. | A handler on an icon gives you a pointer cursor, but no name for a screen reader and no visible hover response. |