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

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

@@ -0,0 +1,652 @@
+# CdsCard — 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 card gathers related content — a title, text, an image, actions — into one bordered block. Use it when an object (a product, a plan, a document) should read as a whole: a card can act as a link and as a selectable item in a group.
+
+## Content
+
+There are three ways to fill a card: the `title`, `subtitle` and `text` props for typical cases; the slots of the same name when you need your own markup instead of a string; the `CdsCardItem`, `CdsCardTitle`, `CdsCardSubtitle` and `CdsCardText` components when you need full control over the structure. The `divider` prop adds a divider between the header and the text.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import {
+  CdsCard,
+  CdsCardDivider,
+  CdsCardItem,
+  CdsCardSubtitle,
+  CdsCardText,
+  CdsCardTitle,
+  CdsIcon
+} from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="cds-row">
+    <div class="cds-col">
+      <CdsCard
+        title="Заголовок карточки"
+        subtitle="Подзаголовок карточки"
+        text="Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore voluptatibus! Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum unde voluptatem!"
+        append-icon="add"
+        divider
+      />
+      <div class="flex justify-center my-2">Использование Props</div>
+    </div>
+
+    <div class="cds-col">
+      <CdsCard divider>
+        <template #title>Заголовок карточки</template>
+        <template #subtitle>Подзаголовок карточки</template>
+        <template #text>
+          Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore
+          voluptatibus! Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum unde
+          voluptatem!
+        </template>
+        <template #append>
+          <CdsIcon icon="add" />
+        </template>
+      </CdsCard>
+      <div class="flex justify-center my-2">Использование Slots</div>
+    </div>
+
+    <div class="cds-col">
+      <CdsCard>
+        <CdsCardItem>
+          <CdsCardTitle>Заголовок карточки</CdsCardTitle>
+          <CdsCardSubtitle>Подзаголовок карточки</CdsCardSubtitle>
+          <template #append>
+            <CdsIcon icon="add" />
+          </template>
+        </CdsCardItem>
+
+        <CdsCardDivider />
+
+        <CdsCardText>
+          Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore
+          voluptatibus! Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum unde
+          voluptatem!
+        </CdsCardText>
+      </CdsCard>
+      <div class="flex justify-center my-2">Использование Компонентов</div>
+    </div>
+  </div>
+</template>
+```
+
+## Header
+
+The `prepend-icon` and `append-icon` props put an icon at the edges of the header, `prepend-avatar` and `append-avatar` put an avatar by image URL. By default the prepend and append areas are pinned to the top of the header; `item-align="center"` centers them against the title and the subtitle (on `CdsCardItem` this prop is called `align`).
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsCard } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-wrap justify-center gap-4">
+    <CdsCard
+      width="320"
+      prepend-avatar="/images/temp/thumbnail.jpg"
+      title="Анна Смирнова"
+      subtitle="Менеджер проекта"
+      append-icon="overflow-menu-vertical"
+      item-align="center"
+    />
+
+    <CdsCard
+      width="320"
+      prepend-icon="doc"
+      title="Договор поставки"
+      subtitle="Обновлён вчера"
+      append-icon="download"
+      item-align="center"
+    />
+  </div>
+</template>
+```
+
+## Appearance
+
+A clickable card — one with a link, a click handler, inside a group or with the `link` prop — highlights its border on hover by itself, you do not need to turn anything on. `borderless` removes the border — for cards on a surface or inside other containers.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsCard } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-wrap justify-center gap-4">
+    <CdsCard width="240" title="Обычная" text="Рамка по умолчанию отделяет карточку от фона." />
+    <CdsCard width="240" link title="Кликабельная" text="Наведите курсор — рамка подсветится." />
+    <CdsCard width="240" borderless title="Borderless" text="Без рамки — для карточек на подложке." />
+  </div>
+</template>
+```
+
+## Link
+
+Pass `href` (or `to` with a vue-router route) and the card is rendered as an `a` tag and becomes clickable as a whole, keeping its appearance.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsCard } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsCard
+    class="m-auto"
+    title="CDS Sandbox"
+    subtitle="Перейти на песочницу CDS"
+    href="https://magersoft.github.io/cds-sandbox"
+    target="_blank"
+    append-icon="external"
+    width="300"
+  />
+</template>
+```
+
+## Images
+
+An image at the top is a [CdsImage](../cds-image/api.md) component placed first inside the card. You can overlay content on top of it by putting the header into the image slot.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import {
+  CdsButton,
+  CdsCard,
+  CdsCardActions,
+  CdsCardDivider,
+  CdsCardItem,
+  CdsCardSubtitle,
+  CdsCardText,
+  CdsCardTitle,
+  CdsImage
+} from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-wrap justify-center gap-6">
+    <CdsCard width="400">
+      <CdsImage src="/images/temp/girl.webp" cover class="items-end" />
+
+      <CdsCardItem>
+        <CdsCardTitle>Заголовок карточки</CdsCardTitle>
+        <CdsCardSubtitle>Подзаголовок карточки</CdsCardSubtitle>
+      </CdsCardItem>
+
+      <CdsCardDivider />
+
+      <CdsCardText>
+        Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore voluptatibus!
+        Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum unde voluptatem!
+      </CdsCardText>
+
+      <CdsCardActions class="justify-end">
+        <CdsButton>Действие</CdsButton>
+      </CdsCardActions>
+    </CdsCard>
+
+    <CdsCard width="400">
+      <CdsImage src="/images/temp/dark-city.webp" cover class="items-end">
+        <CdsCardItem>
+          <CdsCardTitle class="text-content-on-dark">Заголовок карточки</CdsCardTitle>
+          <CdsCardSubtitle class="text-content-on-dark opacity-80">Подзаголовок карточки</CdsCardSubtitle>
+        </CdsCardItem>
+      </CdsImage>
+
+      <CdsCardText>
+        Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore voluptatibus!
+        Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum unde voluptatem!
+      </CdsCardText>
+
+      <CdsCardActions class="justify-end">
+        <CdsButton>Действие</CdsButton>
+      </CdsCardActions>
+    </CdsCard>
+  </div>
+</template>
+```
+
+## Images
+
+The `image` prop stretches the image as the background of the whole card. Take care of the contrast: set the text color through `color` and pick a dark image or a gradient.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsCard, CdsCardActions } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsCard
+    class="m-auto"
+    title="Заголовок"
+    subtitle="Подзаголовок карточки"
+    color="content-on-dark"
+    text="Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore voluptatibus! Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum unde voluptatem!"
+    image="/images/temp/dark-city.webp"
+    width="400"
+  >
+    <CdsCardActions class="justify-end">
+      <CdsButton appearance="inverse">Действие</CdsButton>
+    </CdsCardActions>
+  </CdsCard>
+</template>
+```
+
+## Group with selection
+
+Wrap the cards in `CdsCardGroup` and give each of them a `value` — the group turns into a selection control with `v-model`, and the selected card gets a highlighted border. `required` forbids clearing the selection.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsCard, CdsCardGroup } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const selected = ref(1);
+const items = [1, 2, 3];
+</script>
+
+<template>
+  <CdsCardGroup v-model="selected" required class="flex-wrap justify-center gap-4">
+    <CdsCard
+      v-for="item in items"
+      :key="item"
+      title="Заголовок карточки"
+      subtitle="Подзаголовок карточки"
+      text="Используется в качестве элемента, где вся область карточки — это интерактивное состояние."
+      :append-icon="selected === item ? 'check-fill' : undefined"
+      :value="item"
+      width="250"
+    />
+  </CdsCardGroup>
+</template>
+```
+
+## Group with selection
+
+The `multiple` prop enables multiple selection — `v-model` then holds an array of values.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsCard, CdsCardGroup } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const selected = ref([2]);
+const items = [1, 2, 3];
+</script>
+
+<template>
+  <CdsCardGroup v-model="selected" multiple class="flex-wrap justify-center gap-4">
+    <CdsCard
+      v-for="item in items"
+      :key="item"
+      title="Заголовок карточки"
+      subtitle="Подзаголовок карточки"
+      text="Используется в качестве элемента, где вся область карточки — это интерактивное состояние."
+      :append-icon="selected.includes(item) ? 'check-fill' : undefined"
+      :value="item"
+      width="250"
+    />
+  </CdsCardGroup>
+</template>
+```
+
+## Choosing a plan
+
+A group of cards replaces radio buttons when every option needs room for a price and a description. The `check-fill` icon in `append-icon` repeats the selection in the header, and the button below stays disabled until an option is picked.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsCard, CdsCardGroup } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const selected = ref<string>();
+
+const plans = [
+  { id: 'start', title: 'Старт', price: 'Бесплатно', description: '5 проектов и базовая аналитика.' },
+  { id: 'team', title: 'Команда', price: '990 ₽ / мес', description: 'Совместная работа и роли доступа.' },
+  {
+    id: 'business',
+    title: 'Бизнес',
+    price: '2 900 ₽ / мес',
+    description: 'Без ограничений и с приоритетной поддержкой.'
+  }
+];
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-4">
+    <CdsCardGroup v-model="selected" class="flex-wrap justify-center gap-4">
+      <CdsCard
+        v-for="plan in plans"
+        :key="plan.id"
+        :value="plan.id"
+        :title="plan.title"
+        :subtitle="plan.price"
+        :text="plan.description"
+        :append-icon="selected === plan.id ? 'check-fill' : undefined"
+        width="240"
+      />
+    </CdsCardGroup>
+
+    <CdsButton :disabled="!selected" text="Продолжить" />
+  </div>
+</template>
+```
+
+## Product cards
+
+A storefront is assembled from ready-made blocks: [CdsImage](../cds-image/api.md) with the photo, a rating made of icons in `CdsCardText`, [CdsTag](../cds-tag/api.md) tags with the specs and a pair of actions in `CdsCardActions` — the main "add to cart" button and a secondary icon button for favorites that toggles the bookmark and tints it with a utility class. The `loading` and `disabled` props show the loading bar and protect the card from repeated clicks while the request runs — press «В корзину».
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import {
+  CdsButton,
+  CdsCard,
+  CdsCardActions,
+  CdsCardDivider,
+  CdsCardItem,
+  CdsCardSubtitle,
+  CdsCardText,
+  CdsCardTitle,
+  CdsIcon,
+  CdsImage,
+  CdsTag
+} from '@central-design-system/components';
+import { ref } from 'vue';
+
+const loadingId = ref<string | null>(null);
+
+const products = [
+  {
+    id: 'headphones',
+    title: 'Наушники Aura ANC',
+    category: 'Аудио',
+    image: 'https://images.unsplash.com/photo-1505740420928-5e560c06d30e?auto=format&fit=crop&w=600&q=80',
+    rating: 4.8,
+    stars: 5,
+    reviews: 214,
+    price: '12 990 ₽',
+    description: 'Беспроводные наушники с активным шумоподавлением и зарядом на 30 часов.',
+    tags: [
+      {
+        name: 'Хит',
+        color: 'green'
+      },
+      {
+        name: 'Доставка завтра',
+        color: 'purple'
+      }
+    ]
+  },
+  {
+    id: 'watch',
+    title: 'Часы Meridian 40',
+    category: 'Аксессуары',
+    image: 'https://images.unsplash.com/photo-1523275335684-37898b6baf30?auto=format&fit=crop&w=600&q=80',
+    rating: 4.6,
+    stars: 5,
+    reviews: 98,
+    price: '24 490 ₽',
+    description: 'Классический корпус 40 мм, сапфировое стекло и ремешок из натуральной кожи.',
+    tags: [
+      {
+        name: 'Новинка',
+        color: 'cyan'
+      }
+    ]
+  },
+  {
+    id: 'sneakers',
+    title: 'Кроссовки Vertex Run',
+    category: 'Обувь',
+    image: 'https://images.unsplash.com/photo-1542291026-7eec264c27ff?auto=format&fit=crop&w=600&q=80',
+    rating: 4.9,
+    stars: 5,
+    reviews: 531,
+    price: '8 790 ₽',
+    description: 'Лёгкая беговая пара с амортизирующей подошвой для ежедневных тренировок.',
+    tags: [
+      {
+        name: '−20%',
+        color: 'green'
+      },
+      {
+        name: 'Остался 42 размер',
+        color: 'red'
+      }
+    ]
+  }
+];
+
+const addToCart = (id: string) => {
+  loadingId.value = id;
+
+  setTimeout(() => (loadingId.value = null), 2000);
+};
+
+const favorites = ref<string[]>([]);
+
+const toggleFavorite = (id: string) => {
+  favorites.value = favorites.value.includes(id)
+    ? favorites.value.filter((item) => item !== id)
+    : [...favorites.value, id];
+};
+</script>
+
+<template>
+  <div class="flex flex-wrap justify-center gap-4">
+    <CdsCard
+      v-for="product in products"
+      :key="product.id"
+      width="280"
+      :loading="loadingId === product.id"
+      :disabled="loadingId === product.id"
+    >
+      <CdsImage :src="product.image" height="200" cover />
+
+      <CdsCardItem>
+        <CdsCardTitle>{{ product.title }}</CdsCardTitle>
+        <CdsCardSubtitle>{{ product.category }}</CdsCardSubtitle>
+      </CdsCardItem>
+
+      <CdsCardText>
+        <div class="flex items-center gap-1">
+          <CdsIcon
+            v-for="star in product.stars"
+            :key="star"
+            :icon="star <= Math.floor(product.rating) ? 'star-fill' : 'star'"
+            size="sm"
+            class="text-other-lemon-content"
+          />
+          <span class="text-sm text-content-secondary">{{ product.rating }} ({{ product.reviews }})</span>
+        </div>
+
+        <div class="my-2 text-lg font-bold">{{ product.price }}</div>
+
+        <div>{{ product.description }}</div>
+      </CdsCardText>
+
+      <CdsCardDivider />
+
+      <div class="flex flex-wrap gap-1 px-4 pt-2">
+        <CdsTag v-for="tag in product.tags" :key="tag.name" :text="tag.name" :color="tag.color" size="sm" />
+      </div>
+
+      <CdsCardActions class="gap-2">
+        <CdsButton class="flex-1" text="В корзину" @click="addToCart(product.id)" />
+        <CdsButton
+          appearance="tertiary"
+          :icon="favorites.includes(product.id) ? 'bookmark-fill' : 'bookmark'"
+          :class="{ 'text-other-pink-content': favorites.includes(product.id) }"
+          :aria-label="favorites.includes(product.id) ? 'Убрать из избранного' : 'Добавить в избранное'"
+          @click="toggleFavorite(product.id)"
+        />
+      </CdsCardActions>
+    </CdsCard>
+  </div>
+</template>
+```
+
+## Expandable details
+
+Hide secondary content behind an expander: a block with `v-if` is wrapped in `CdsTransitionExpand` for a smooth animation. Anything can trigger the expansion — a chevron icon or a button in the actions bar.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import {
+  CdsButton,
+  CdsCard,
+  CdsCardActions,
+  CdsCardDivider,
+  CdsCardItem,
+  CdsCardSubtitle,
+  CdsCardText,
+  CdsCardTitle,
+  CdsFunctionalButton,
+  CdsTransitionExpand
+} from '@central-design-system/components';
+import { ref } from 'vue';
+
+const expanded = ref(false);
+const showFull = ref(false);
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-4">
+    <CdsCard width="400">
+      <CdsCardItem>
+        <CdsCardTitle>Расширяемая карточка</CdsCardTitle>
+        <CdsCardSubtitle>Просто нажмите на иконку стрелочки</CdsCardSubtitle>
+      </CdsCardItem>
+
+      <CdsCardActions class="justify-between">
+        <CdsButton appearance="tertiary">Действие</CdsButton>
+        <CdsFunctionalButton :icon="expanded ? 'chevron-up' : 'chevron-down'" @click="expanded = !expanded" />
+      </CdsCardActions>
+
+      <CdsTransitionExpand>
+        <div v-if="expanded">
+          <CdsCardDivider />
+          <CdsCardText>
+            Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore
+            voluptatibus! Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum
+            unde voluptatem!
+          </CdsCardText>
+        </div>
+      </CdsTransitionExpand>
+    </CdsCard>
+
+    <CdsCard width="400">
+      <CdsCardItem>
+        <CdsCardTitle>Расширяемая карточка</CdsCardTitle>
+        <CdsCardSubtitle>Просто нажмите на кнопку</CdsCardSubtitle>
+      </CdsCardItem>
+
+      <CdsTransitionExpand>
+        <div v-if="showFull">
+          <CdsCardText>
+            Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore
+            voluptatibus! Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum
+            unde voluptatem!
+          </CdsCardText>
+        </div>
+      </CdsTransitionExpand>
+
+      <CdsCardDivider />
+
+      <CdsCardActions class="justify-between">
+        <CdsButton appearance="tertiary" @click="showFull = !showFull">
+          {{ showFull ? 'Скрыть' : 'Показать' }}
+        </CdsButton>
+      </CdsCardActions>
+    </CdsCard>
+  </div>
+</template>
+```
+
+## Gallery
+
+Cards nest into each other: the outer one is an album with a header and a counter, the inner ones are photo tiles in a mosaic built on a CSS grid with a fixed row height; `col-span` / `row-span` make individual shots larger. The `absolute` mode of [CdsImage](../cds-image/api.md) stretches the photo across the whole tile, `borderless` removes the borders, and a gradient darkens the last tile under the counter of the remaining photos.
+
+**Example (SFC):**
+
+```vue
+<script setup lang="ts">
+import {
+  CdsCard,
+  CdsCardItem,
+  CdsCardSubtitle,
+  CdsCardTitle,
+  CdsFunctionalButton,
+  CdsImage
+} from '@central-design-system/components';
+
+const photos = [
+  { src: '/images/temp/ny.webp', span: 'col-span-2 row-span-2' },
+  { src: '/images/temp/space.webp', span: 'col-span-2' },
+  { src: '/images/temp/cat.webp', span: '' },
+  { src: '/images/temp/dark-city.webp', span: '' },
+  { src: '/images/temp/girl.webp', span: '' },
+  { src: '/images/temp/city.webp', span: 'col-span-2' },
+  { src: '/images/temp/airbnb.webp', span: '', rest: 18 }
+];
+</script>
+
+<template>
+  <CdsCard width="800" class="m-auto">
+    <CdsCardItem align="center">
+      <CdsCardTitle>Путешествия</CdsCardTitle>
+      <CdsCardSubtitle>25 фото · обновлён вчера</CdsCardSubtitle>
+      <template #append>
+        <div class="flex gap-1">
+          <CdsFunctionalButton icon="upload" aria-label="Загрузить фото" />
+          <CdsFunctionalButton icon="overflow-menu-vertical" aria-label="Действия с альбомом" />
+        </div>
+      </template>
+    </CdsCardItem>
+
+    <div class="grid grid-cols-4 auto-rows-[160px] gap-2 px-4 pb-4">
+      <CdsCard
+        v-for="photo in photos"
+        :key="photo.src"
+        link
+        borderless
+        :class="['flex items-center justify-center', photo.span]"
+      >
+        <CdsImage
+          :src="photo.src"
+          absolute
+          cover
+          :gradient="photo.rest ? 'to bottom, rgba(0,0,0,.55), rgba(0,0,0,.55)' : undefined"
+        />
+        <span v-if="photo.rest" class="text-2xl font-bold text-content-on-dark">+{{ photo.rest }} фото</span>
+      </CdsCard>
+    </div>
+  </CdsCard>
+</template>
+```

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

@@ -0,0 +1,10 @@
+# CdsCard — 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 |
+| --- | --- |
+| A clickable card means one action: its whole area leads to the same result. | Buttons inside a clickable card compete with the click on the card itself. |
+| The actions bar holds one main action as primary; the rest are less prominent. | Several primary buttons in one card compete for attention. |
+| The subtitle adds a new fact to the title — a place, a date, a price. | A subtitle that repeats the title in other words tells the reader nothing. |