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

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

@@ -0,0 +1,240 @@
+# CdsAvatar — 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 avatar shows a person, a team or a company: a photo, initials or an icon inside a round container. Use it in member lists, comments and profile headers — anywhere the reader needs to recognize "who is this" at a glance.
+
+## Content
+
+The content comes from one of three props: `image` — a photo, `icon` — an icon, `text` — initials. If you pass several of them, `image` wins, then `icon`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAvatar } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center gap-3">
+    <CdsAvatar image="https://i.pravatar.cc/120?img=12" />
+    <CdsAvatar icon="user-avatar" color="brand-secondary" />
+    <CdsAvatar text="ВМ" color="brand-primary" />
+  </div>
+</template>
+```
+
+## Sizes
+
+The `size` prop takes a token from `xs` to `xl` or a number of pixels. The default size is `md`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAvatar } from '@central-design-system/components';
+
+const sizes = CdsAvatar.constants.sizes;
+</script>
+
+<template>
+  <div class="flex items-center justify-center gap-2">
+    <CdsAvatar v-for="size in sizes" :key="size" :size="size" text="ВМ" color="brand-primary" />
+  </div>
+</template>
+```
+
+## Colors
+
+The `color` prop paints the background of an avatar with initials or an icon: a theme token or any CSS color will do.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAvatar } from '@central-design-system/components';
+
+const items = [
+  { color: 'brand-primary', text: 'BP' },
+  { color: 'brand-secondary', text: 'BS' },
+  { color: '#0f9d58', text: 'GR' },
+  { color: '#db4437', text: 'RD' },
+  { color: '#673ab7', text: 'PR' }
+];
+</script>
+
+<template>
+  <div class="flex justify-center gap-2">
+    <CdsAvatar v-for="item in items" :key="item.text" size="md" :color="item.color" :text="item.text" />
+  </div>
+</template>
+```
+
+## Badge
+
+The `badge` prop set to `true` shows a dot in the corner of the avatar. An object is passed through as props of [CdsBadge](../cds-badge/api.md): this is how you change the color of the dot, show a counter (`dot: false` plus `content`) or move the badge away from the edge (`floating`). The `badge` slot replaces the content of the badge with anything you like — an icon, for example.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAvatar, CdsIcon } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center gap-3">
+    <CdsAvatar size="lg" badge image="https://i.pravatar.cc/120?img=12" />
+    <CdsAvatar size="lg" text="АД" color="brand-primary" :badge="{ color: 'status-success-surface' }" />
+    <CdsAvatar size="lg" icon="user-group" color="brand-secondary" :badge="{ dot: false, content: 3 }" />
+    <CdsAvatar size="lg" image="https://i.pravatar.cc/120?img=32" :badge="{ color: 'status-success-surface' }">
+      <template #badge>
+        <CdsIcon icon="check" />
+      </template>
+    </CdsAvatar>
+  </div>
+</template>
+```
+
+## Spacing
+
+The `start` and `end` props add a margin on the side of the neighboring content: `start` — for an avatar at the beginning of a line, `end` — at the end. This way the avatar fits into text without wrappers that carry outer margins.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAvatar } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col gap-2">
+    <div class="flex items-center justify-center">
+      <CdsAvatar start size="sm" text="АД" color="brand-primary" />
+      <span>Анна Дмитриева оставила комментарий</span>
+    </div>
+
+    <div class="flex items-center justify-center">
+      <span>Задачу проверяет</span>
+      <CdsAvatar end size="sm" image="https://i.pravatar.cc/80?img=32" />
+    </div>
+  </div>
+</template>
+```
+
+## Member list
+
+In a list of people the avatar is a fast visual anchor. The `start` prop gives the margin before the text, photos and initials alternate depending on what the user has, and the badge dot shows who is online right now.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAvatar } from '@central-design-system/components';
+
+const members = [
+  { name: 'Анна Дмитриева', role: 'Менеджер проекта', image: 'https://i.pravatar.cc/80?img=47', online: true },
+  { name: 'Павел Соколов', role: 'Аналитик', text: 'ПС', color: 'brand-primary', online: false },
+  { name: 'Мария Ильина', role: 'Дизайнер', image: 'https://i.pravatar.cc/80?img=32', online: true },
+  { name: 'Служба поддержки', role: 'Общий канал', icon: 'user-group', color: 'brand-secondary', online: false }
+];
+</script>
+
+<template>
+  <div class="m-auto flex w-[350px] flex-col gap-3">
+    <div v-for="member in members" :key="member.name" class="flex items-center">
+      <CdsAvatar
+        start
+        :image="member.image"
+        :icon="member.icon"
+        :text="member.text"
+        :color="member.color"
+        :badge="member.online && { color: 'status-success-surface' }"
+      />
+
+      <div class="flex flex-col">
+        <span>{{ member.name }}</span>
+        <span class="text-200 text-content-secondary">{{ member.role }}</span>
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+## Group of members
+
+When there are many members and little space, avatars are stacked with a slight overlap — a border in the background color separates the neighbors from each other. The last avatar with `text="+3"` tells how many people did not fit.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAvatar } from '@central-design-system/components';
+
+const images = [
+  'https://i.pravatar.cc/80?img=12',
+  'https://i.pravatar.cc/80?img=47',
+  'https://i.pravatar.cc/80?img=32',
+  'https://i.pravatar.cc/80?img=56'
+];
+</script>
+
+<template>
+  <div class="flex items-center justify-center gap-3">
+    <div class="avatar-stack flex items-center">
+      <CdsAvatar v-for="image in images" :key="image" :image="image" />
+      <CdsAvatar text="+3" color="brand-secondary" />
+    </div>
+
+    <span class="text-content-secondary">7 участников</span>
+  </div>
+</template>
+
+<style scoped>
+.avatar-stack .cds-avatar {
+  border: 2px solid rgb(var(--cds-color-surface-primary));
+}
+
+.avatar-stack .cds-avatar:not(:first-child) {
+  margin-inline-start: -8px;
+}
+</style>
+```
+
+## Uploading a profile photo
+
+While there is no photo yet, the avatar shows the initials from `text` — the page is not left with an empty circle. As soon as `image` gets a link, the photo replaces the initials; after the photo is removed, the initials come back on their own.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsAvatar, CdsButton } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const image = ref('');
+const loading = ref(false);
+
+const upload = async () => {
+  loading.value = true;
+
+  await new Promise((resolve) => setTimeout(resolve, 1200));
+
+  image.value = 'https://i.pravatar.cc/160?img=47';
+  loading.value = false;
+};
+
+const remove = () => {
+  image.value = '';
+};
+</script>
+
+<template>
+  <div class="flex items-center justify-center gap-3">
+    <CdsAvatar size="xl" :image="image" text="АД" color="brand-primary" />
+
+    <CdsButton v-if="!image" prepend-icon="upload" text="Загрузить фото" :loading="loading" @click="upload" />
+    <CdsButton v-else appearance="tertiary" text="Удалить фото" @click="remove" />
+  </div>
+</template>
+```

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

@@ -0,0 +1,10 @@
+# CdsAvatar — 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 |
+| --- | --- |
+| Initials are one or two letters: the first letters of the first and last name. | Long text does not fit into the round container and gets cut off. |
+| Inside one list keep avatars the same size — the row reads as a whole. | Different sizes read as different importance of the members. |
+| A colored dot shows the status — it is noticeable and does not fight the content. | A text badge covers the avatar; for a caption there is the line next to it. |

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

@@ -0,0 +1,32 @@
+# CdsAvatar — 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.
+
+## _CdsAvatar.variables.scss
+
+```scss
+@use '../../../styles/tools';
+
+// Геометрия
+$avatar-border-radius: 50% !default;
+$avatar-line-height: normal !default;
+$avatar-vertical-align: middle !default;
+
+// Отступы модификаторов start / end
+$avatar-margin-start: var(--cds-spacing-200) !default;
+$avatar-margin-end: var(--cds-spacing-200) !default;
+
+// Длительность перехода размеров
+$avatar-transition-duration: 0.2s !default;
+
+// Размеры
+$avatar-sizes: (
+  'xs': tools.to-rem(24px),
+  'sm': tools.to-rem(32px),
+  'md': tools.to-rem(40px),
+  'lg': tools.to-rem(48px),
+  'xl': tools.to-rem(56px)
+) !default;
+```

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

@@ -0,0 +1,44 @@
+# CdsBadge — 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)
+
+A badge is a small marker in the corner of an element or next to it: a counter of unread messages, a "there is something new" dot, a short label. A badge is not interactive — it draws attention to the element it is attached to instead of acting on its own.
+
+## CdsBadge
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `color` | `string \| undefined` | — | no | Component color |
+| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
+| `dot` | `boolean \| undefined` | — | no | Shrinks the component and hides its content, rendering it as a dot |
+| `dotSize` | `string \| number \| undefined` | — | no | Dot size |
+| `floating` | `boolean \| undefined` | — | no | Moves the component further away from the content — an 8 pixel offset. |
+| `height` | `string \| number \| undefined` | — | no | Component height |
+| `icon` | `IconValue \| undefined` | — | no | Icon shown inside the component. Ignored when the `dot` prop is set. |
+| `inline` | `boolean \| undefined` | — | no | Renders as an inline block instead of using absolute positioning. The location, floating and offset props are ignored. |
+| `label` | `string \| undefined` | `'$cds.badge'` | no | Aria-label for the component. Falls back to the default value when not set. |
+| `location` | `Anchor \| null \| undefined` | `'top end'` | no | Position of the element relative to its container, for example "top left", "center", "bottom right". |
+| `max` | `string \| number \| undefined` | — | no | Sets the maximum allowed value when content holds a number. If the number exceeds the maximum, a "+" suffix is added. |
+| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
+| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
+| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
+| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
+| `modelValue` | `boolean \| undefined` | `true` | no | Controls whether the component is shown or hidden. |
+| `offsetX` | `string \| number \| undefined` | — | no | Offset along the X axis |
+| `offsetY` | `string \| number \| undefined` | — | no | Offset along the Y axis |
+| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
+| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| null \| undefined` | `'fade-transition'` | no | Transition animation |
+| `width` | `string \| number \| undefined` | — | no | Component width |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `badge` | `any` | Slot for the content placed inside the badge. |
+| `default` | `any` | Default slot |

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

@@ -0,0 +1,332 @@
+# CdsBadge — 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.
+
+A badge is a small marker in the corner of an element or next to it: a counter of unread messages, a "there is something new" dot, a short label. A badge is not interactive — it draws attention to the element it is attached to instead of acting on its own.
+
+## Content
+
+The `content` prop sets what the badge shows — most often a counter of events. By default the badge sits in the top right corner of the element from the slot.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge, CdsFunctionalButton } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsBadge content="10">
+      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
+    </CdsBadge>
+  </div>
+</template>
+```
+
+## Content
+
+The `max` prop caps the counter: anything above it collapses into "99+". Without `max` the value is printed in full.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge, CdsFunctionalButton } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center gap-4">
+    <CdsBadge content="150">
+      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
+    </CdsBadge>
+    <CdsBadge content="150" :max="99">
+      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
+    </CdsBadge>
+  </div>
+</template>
+```
+
+## Content
+
+Besides a number, `content` accepts a short text — a "new section" mark in a menu, for example. Here the badge is placed into the line by the `inline` prop — more on it in the positioning section.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge, CdsCard, CdsList, CdsListItem } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsCard class="m-auto w-[200px]">
+    <CdsList>
+      <CdsListItem value="0">
+        <template #title>Главная</template>
+      </CdsListItem>
+      <CdsListItem value="1">
+        <template #title>Входящие</template>
+        <template #append>
+          <CdsBadge content="new" inline />
+        </template>
+      </CdsListItem>
+      <CdsListItem value="2">
+        <template #title>Исходящие</template>
+      </CdsListItem>
+    </CdsList>
+  </CdsCard>
+</template>
+```
+
+## Content
+
+The `icon` prop shows an icon instead of text.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsBadge icon="check" inline />
+  </div>
+</template>
+```
+
+## Dot
+
+The `dot` prop shrinks the badge to a dot and hides its content — only the "there is something new" signal is left. The diameter is changed via `dot-size`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge, CdsFunctionalButton } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsBadge dot>
+      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
+    </CdsBadge>
+  </div>
+</template>
+```
+
+## Colors
+
+The `color` prop accepts any color alias of the design system, `text-color` changes the color of the content. By default the badge is red — the color of indication.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge } from '@central-design-system/components';
+
+const colors = CdsBadge.constants.colors;
+</script>
+
+<template>
+  <div class="flex flex-wrap justify-center gap-2">
+    <CdsBadge v-for="color in colors" :key="color" :color="color" :content="color" inline />
+  </div>
+</template>
+```
+
+## Positioning
+
+By default the badge is positioned absolutely relative to the element from the slot. The `location` prop picks the corner.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge, CdsButton } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center gap-4">
+    <CdsBadge content="1" location="top end">
+      <CdsButton appearance="tertiary" icon="notification" aria-label="Уведомления" />
+    </CdsBadge>
+    <CdsBadge content="2" location="bottom end">
+      <CdsButton appearance="tertiary" icon="notification" aria-label="Уведомления" />
+    </CdsBadge>
+    <CdsBadge content="3" location="top start">
+      <CdsButton appearance="tertiary" icon="notification" aria-label="Уведомления" />
+    </CdsBadge>
+    <CdsBadge content="4" location="bottom start">
+      <CdsButton appearance="tertiary" icon="notification" aria-label="Уведомления" />
+    </CdsBadge>
+  </div>
+</template>
+```
+
+## Positioning
+
+The `floating` prop moves the badge 8 pixels away from the content, so it overlaps the element less. For fine-tuning there are `offset-x` and `offset-y`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge, CdsButton } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsBadge content="3" floating>
+      <CdsButton icon="notification" aria-label="Уведомления" />
+    </CdsBadge>
+  </div>
+</template>
+```
+
+## Visibility
+
+The `model-value` prop shows and hides the badge. The change of state is animated, and the animation is configured through `transition`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge, CdsButton } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const visible = ref(false);
+const toggle = () => {
+  visible.value = !visible.value;
+};
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-4">
+    <CdsBadge content="5" :model-value="visible" :inline="false">
+      <CdsButton appearance="secondary" @click="toggle"> {{ visible ? 'Скрыть' : 'Показать' }} бейдж </CdsButton>
+    </CdsBadge>
+  </div>
+</template>
+```
+
+## Slots
+
+Слот `badge` полностью замещает содержимое из `content` и `icon`.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge, CdsFunctionalButton } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsBadge>
+      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
+
+      <template #badge> Alert </template>
+    </CdsBadge>
+  </div>
+</template>
+```
+
+## Notification center
+
+A counter on the notifications icon: `max` keeps the badge compact for any number of events, and `model-value` hides it once nothing is unread — an empty "0" does not hang on the icon.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge, CdsButton, CdsFunctionalButton } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const unread = ref(3);
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-4">
+    <CdsBadge :content="unread" :model-value="unread > 0" :max="99">
+      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
+    </CdsBadge>
+
+    <div class="flex flex-wrap justify-center gap-2">
+      <CdsButton appearance="secondary" text="Новое уведомление" @click="unread++" />
+      <CdsButton appearance="secondary" text="+100" @click="unread += 100" />
+      <CdsButton appearance="tertiary" text="Прочитать все" :disabled="unread === 0" @click="unread = 0" />
+    </div>
+  </div>
+</template>
+```
+
+## Menu with updates
+
+Counters in menu items hint where to look. A badge with `inline` goes into the `append` slot of a list item, and once the section is opened `model-value` removes it. Open "Входящие" — the counter disappears.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge, CdsCard, CdsList, CdsListItem } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const sections = ref([
+  { title: 'Входящие', unread: 12 },
+  { title: 'Задачи', unread: 3 },
+  { title: 'Архив', unread: 0 }
+]);
+</script>
+
+<template>
+  <CdsCard class="m-auto w-[240px]">
+    <CdsList>
+      <CdsListItem v-for="section in sections" :key="section.title" :value="section.title" @click="section.unread = 0">
+        <template #title>{{ section.title }}</template>
+        <template #append>
+          <CdsBadge :content="section.unread" :model-value="section.unread > 0" inline />
+        </template>
+      </CdsListItem>
+    </CdsList>
+  </CdsCard>
+</template>
+```
+
+## Contacts online
+
+A dot indicator shows the state without words: `color="green"` — the contact is online, `neutral` — not. `inline` puts the dot into the list row, and the `label` prop announces the state to screen readers.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsBadge, CdsCard, CdsList, CdsListItem } from '@central-design-system/components';
+
+const contacts = [
+  { name: 'Анна Савельева', online: true },
+  { name: 'Пётр Максимов', online: true },
+  { name: 'Мария Ким', online: false }
+];
+</script>
+
+<template>
+  <CdsCard class="m-auto w-[240px]">
+    <CdsList>
+      <CdsListItem v-for="contact in contacts" :key="contact.name" :value="contact.name">
+        <template #prepend>
+          <CdsBadge
+            dot
+            inline
+            :color="contact.online ? 'green' : 'neutral'"
+            :label="contact.online ? 'В сети' : 'Не в сети'"
+          />
+        </template>
+        <template #title>{{ contact.name }}</template>
+      </CdsListItem>
+    </CdsList>
+  </CdsCard>
+</template>
+```

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

@@ -0,0 +1,10 @@
+# CdsBadge — 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 max prop collapses large numbers, so the badge stays compact. | Точное «1528» не помогает принять решение и растягивает бейдж. |
+| A badge appears only where an update waits for the user to react. | A badge on every icon turns the signal into noise — nothing gets attention. |
+| The badge text is one short word. | A long phrase turns the indicator into a label and breaks the layout. |