From c660e12f9af651b4a5d723077071861935491cca Mon Sep 17 00:00:00 2001
From: "ak.dmitriev" <ak.dmitriev@cdek.ru>
Date: Sat, 3 Oct 2026 00:27:15 +0700
Subject: [PATCH] API.togglebutton

---
 docs/components-api/togglebutton.md           |  10 +
 .../togglebutton/togglebutton.component.ts    |  60 +++---
 .../togglebutton/togglebutton.figma.md        |  95 +++------
 .../togglebutton-disabled.component.ts        |   9 +-
 .../togglebutton-icon-only.component.ts       |  18 +-
 .../examples/togglebutton-icons.component.ts  |  22 +-
 .../examples/togglebutton-sizes.component.ts  |  54 -----
 .../togglebutton/togglebutton.stories.ts      | 195 ++++++------------
 8 files changed, 160 insertions(+), 303 deletions(-)
 delete mode 100644 src/stories/components/togglebutton/examples/togglebutton-sizes.component.ts

diff --git a/docs/components-api/togglebutton.md b/docs/components-api/togglebutton.md
index e1cf7715..9c8d67c8 100644
--- a/docs/components-api/togglebutton.md
+++ b/docs/components-api/togglebutton.md
@@ -2,6 +2,8 @@
 
 # ExtraToggleButton
 
+> ✅ **Реализован**: `ExtraToggleButtonComponent` (`@cdek-it/angular-ui-kit`) соответствует спецификации.
+
 Кнопка с двумя состояниями (вкл/выкл). Текущее состояние — это значение (привязка через модель), читается через событие `change`.
 
 | Свойство         | Описание                                | Типизация             |
@@ -10,6 +12,14 @@
 | `icon`           | класс иконки tabler icon                | `string`              |
 | `iconPosition`   | положение иконки                        | `left \| right`       |
 | `size`           | размер кнопки                           | `small \| base \| large \| xlarge` |
+| `iconOnly`       | режим «только иконка» без текста        | `boolean`              |
+| `allowEmpty`     | разрешает снимать выбор повторным нажатием | `boolean \| undefined` |
+| `fluid`          | растяжение кнопки на всю ширину контейнера | `boolean`           |
+| `ariaLabel`      | метка для программ экранного доступа    | `string \| undefined` |
+| `ariaLabelledBy` | id элемента с меткой для доступности    | `string \| undefined` |
+| `inputId`        | id внутреннего элемента для связки с `<label for>` | `string \| undefined` |
+| `tabindex`       | порядок перехода по Tab                 | `number \| undefined` |
+| `autofocus`      | автофокус при монтировании              | `boolean \| undefined` |
 
 # События
 
diff --git a/src/lib/components/togglebutton/togglebutton.component.ts b/src/lib/components/togglebutton/togglebutton.component.ts
index 3967d28b..3e6b9f12 100644
--- a/src/lib/components/togglebutton/togglebutton.component.ts
+++ b/src/lib/components/togglebutton/togglebutton.component.ts
@@ -1,12 +1,18 @@
-import { ChangeDetectionStrategy, ChangeDetectorRef, Component, Input, Output, EventEmitter, forwardRef } from '@angular/core';
+import { ChangeDetectionStrategy, ChangeDetectorRef, Component, EventEmitter, forwardRef, inject, Input, Output } from '@angular/core';
 import { ControlValueAccessor, FormsModule, NG_VALUE_ACCESSOR } from '@angular/forms';
 import { NgClass } from '@angular/common';
 import { ToggleButton, ToggleButtonChangeEvent } from 'primeng/togglebutton';
 
 export type ExtraToggleButtonSize = 'small' | 'base' | 'large' | 'xlarge';
+export type ExtraToggleButtonIconPosition = 'left' | 'right';
+
+export interface ExtraToggleButtonChangeEvent {
+  checked: boolean;
+  originalEvent: Event;
+}
 
 @Component({
-  selector: 'extra-toggle-button',
+  selector: 'extra-togglebutton',
   standalone: true,
   changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [ToggleButton, NgClass, FormsModule],
@@ -14,17 +20,17 @@ export type ExtraToggleButtonSize = 'small' | 'base' | 'large' | 'xlarge';
     {
       provide: NG_VALUE_ACCESSOR,
       useExisting: forwardRef(() => ExtraToggleButtonComponent),
-      multi: true,
-    },
+      multi: true
+    }
   ],
   template: `
     <p-togglebutton
       [ngClass]="extraClasses"
-      [onLabel]="onLabel"
-      [offLabel]="offLabel"
-      [onIcon]="onIcon"
-      [offIcon]="offIcon"
-      [iconPos]="iconPos"
+      [onLabel]="label"
+      [offLabel]="label"
+      [onIcon]="icon"
+      [offIcon]="icon"
+      [iconPos]="iconPosition"
       [size]="primeSize!"
       [disabled]="disabled"
       [allowEmpty]="allowEmpty"
@@ -37,18 +43,15 @@ export type ExtraToggleButtonSize = 'small' | 'base' | 'large' | 'xlarge';
       [(ngModel)]="modelValue"
       (onChange)="onChangeHandler($event)"
     ></p-togglebutton>
-  `,
+  `
 })
 export class ExtraToggleButtonComponent implements ControlValueAccessor {
-  constructor(private cdr: ChangeDetectorRef) {}
+  private readonly _cdr = inject(ChangeDetectorRef);
 
-  @Input() onLabel = 'Вкл';
-  @Input() offLabel = 'Выкл';
-  @Input() onIcon: string | undefined = undefined;
-  @Input() offIcon: string | undefined = undefined;
-  @Input() iconPos: 'left' | 'right' = 'left';
+  @Input() label = '';
+  @Input() icon = '';
+  @Input() iconPosition: ExtraToggleButtonIconPosition = 'left';
   @Input() size: ExtraToggleButtonSize = 'base';
-  @Input() disabled = false;
   @Input() iconOnly = false;
   @Input() allowEmpty: boolean | undefined = undefined;
   @Input() fluid = false;
@@ -58,11 +61,13 @@ export class ExtraToggleButtonComponent implements ControlValueAccessor {
   @Input() tabindex: number | undefined = undefined;
   @Input() autofocus: boolean | undefined = undefined;
 
-  @Output() onChange = new EventEmitter<ToggleButtonChangeEvent>();
+  @Output() onChange = new EventEmitter<ExtraToggleButtonChangeEvent>();
 
+  /** Управляется только через ControlValueAccessor.setDisabledState, не публичный @Input. */
+  disabled = false;
   modelValue = false;
 
-  private _onChange: (value: any) => void = () => {};
+  private _onChange: (value: boolean) => void = () => {};
   private _onTouched: () => void = () => {};
 
   get primeSize(): 'small' | 'large' | undefined {
@@ -74,21 +79,24 @@ export class ExtraToggleButtonComponent implements ControlValueAccessor {
   get extraClasses(): Record<string, boolean> {
     return {
       'p-togglebutton-xlarge': this.size === 'xlarge',
-      'p-togglebutton-icon-only': this.iconOnly,
+      'p-togglebutton-icon-only': this.iconOnly
     };
   }
 
   onChangeHandler(event: ToggleButtonChangeEvent): void {
-    this._onChange(event.checked);
+    const checked = !!event.checked;
+    this.modelValue = checked;
+    this._onChange(checked);
     this._onTouched();
-    this.onChange.emit(event);
+    this.onChange.emit({ checked, originalEvent: event.originalEvent as Event });
   }
 
-  writeValue(value: any): void {
-    this.modelValue = value;
+  writeValue(value: boolean): void {
+    this.modelValue = !!value;
+    this._cdr.markForCheck();
   }
 
-  registerOnChange(fn: (value: any) => void): void {
+  registerOnChange(fn: (value: boolean) => void): void {
     this._onChange = fn;
   }
 
@@ -98,6 +106,6 @@ export class ExtraToggleButtonComponent implements ControlValueAccessor {
 
   setDisabledState(isDisabled: boolean): void {
     this.disabled = isDisabled;
-    this.cdr.markForCheck();
+    this._cdr.markForCheck();
   }
 }
diff --git a/src/lib/components/togglebutton/togglebutton.figma.md b/src/lib/components/togglebutton/togglebutton.figma.md
index 713a37a5..84ef52f2 100644
--- a/src/lib/components/togglebutton/togglebutton.figma.md
+++ b/src/lib/components/togglebutton/togglebutton.figma.md
@@ -1,8 +1,8 @@
 ---
-component: ToggleButtonComponent
-selector: toggle-button
+component: ExtraToggleButton
+selector: extra-togglebutton
 import:
-  symbol: ToggleButtonComponent
+  symbol: ExtraToggleButtonComponent
   from: '@cdek-it/angular-ui-kit'
 figma:
   fileKey: 'Khh7arsuXss3ncqy1Dz3OZ'
@@ -10,12 +10,14 @@ figma:
   componentKey: '19f1388f80113907cee5bc24117e98c7d18eb16c'
   name: '<ToggleButton>'
 status: stable
-updated: '2026-06-23'
+updated: '2026-10-02'
 ---
 
 ## Overview
 
-`ToggleButtonComponent` — кнопка-переключатель с двумя состояниями (нажата / не нажата). Оборачивает PrimeNG `p-togglebutton` и реализует `ControlValueAccessor`, поэтому интегрируется с `[(ngModel)]` и реактивными формами через `formControl` / `formControlName`. Может менять подпись и иконку для включённого и выключенного состояний.
+`ExtraToggleButton` — кнопка-переключатель с двумя состояниями (нажата / не нажата). Оборачивает PrimeNG `p-togglebutton` и реализует `ControlValueAccessor`, поэтому интегрируется с `[(ngModel)]` и реактивными формами через `formControl` / `formControlName`.
+
+В отличие от PrimeNG-демо с разными подписями на вкл/выкл, в Figma `label`/`icon` — **один** статический текст и одна иконка на обоих состояниях: меняется только цвет/заливка (`checked=true/false`), а не содержимое. Поэтому внутри компонент пробрасывает один и тот же `label`/`icon` одновременно в `onLabel`/`offLabel` и `onIcon`/`offIcon` PrimeNG — отдельных инпутов на разные подписи в публичном API нет.
 
 Компонент соответствует Figma-компоненту `<ToggleButton>` (nodeId `174:1363`). Figma-свойство `checked` маппируется на модель значения, а `state`, `size`, `icon-position` и `icon-only` — на Angular-инпуты (см. раздел Props mapping). Не путать с `ToggleSwitch` (свитч настройки, `role=switch`) и `SelectButton` (группа выбора одного из набора).
 
@@ -23,13 +25,10 @@ updated: '2026-06-23'
 
 | Свойство | Тип | По умолчанию | Описание |
 |----------|-----|--------------|---------|
-| `onLabel` | `string` | `'Вкл'` | Текст во включённом состоянии — соответствует Figma-свойству `checked=true` |
-| `offLabel` | `string` | `'Выкл'` | Текст в выключенном состоянии — соответствует Figma-свойству `checked=false` |
-| `onIcon` | `string \| undefined` | `undefined` | CSS-класс иконки во включённом состоянии; доступные иконки — [icons.md](../../figma-code-connect/icons.md) |
-| `offIcon` | `string \| undefined` | `undefined` | CSS-класс иконки в выключенном состоянии; доступные иконки — [icons.md](../../figma-code-connect/icons.md) |
-| `iconPos` | `'left' \| 'right'` | `'left'` | Позиция иконки — соответствует Figma-свойству `icon-position` |
+| `label` | `string` | `''` | Текст кнопки — один и тот же в обоих состояниях (Figma не меняет текст между `checked=true/false`, только заливку) |
+| `icon` | `string` | `''` | CSS-класс иконки (tabler), один и тот же в обоих состояниях; доступные иконки — [icons.md](../../figma-code-connect/icons.md) |
+| `iconPosition` | `'left' \| 'right'` | `'left'` | Позиция иконки — соответствует Figma-свойству `icon-position` |
 | `size` | `'small' \| 'base' \| 'large' \| 'xlarge'` | `'base'` | Размер кнопки — соответствует Figma-свойству `size` |
-| `disabled` | `boolean` | `false` | Отключённое состояние — соответствует Figma-свойству `state=disabled` |
 | `iconOnly` | `boolean` | `false` | Режим «только иконка» без текста — соответствует Figma-свойству `icon-only` |
 | `allowEmpty` | `boolean \| undefined` | `undefined` | Разрешает снимать выбор повторным нажатием |
 | `fluid` | `boolean` | `false` | Растяжение кнопки на всю ширину контейнера |
@@ -39,7 +38,11 @@ updated: '2026-06-23'
 | `tabindex` | `number \| undefined` | `undefined` | Порядок перехода по Tab |
 | `autofocus` | `boolean \| undefined` | `undefined` | Автофокус при монтировании компонента |
 
-Состояние «нажата» (Figma-свойство `checked`) задаётся не отдельным инпутом, а моделью через `ControlValueAccessor`: используйте `[(ngModel)]`, `formControl` или `formControlName`. Значение `true` / `false` соответствует `checked=true` / `checked=false` в Figma. Состояния `hover` и `focus` из Figma воспроизводятся браузером при наведении и фокусе и не имеют отдельных инпутов.
+`allowEmpty`/`fluid`/`ariaLabel`/`ariaLabelledBy`/`inputId`/`tabindex`/`autofocus`/`iconOnly` — полезные
+пропы сверх базовой спеки (`docs/components-api/togglebutton.md`), добавлены туда же по итогам
+доработки (см. чеклист в корневом `CLAUDE.md`, п.3).
+
+Состояние «нажата» (Figma-свойство `checked`) задаётся не отдельным инпутом, а моделью через `ControlValueAccessor`: используйте `[(ngModel)]`, `formControl` или `formControlName`. Значение `true` / `false` соответствует `checked=true` / `checked=false` в Figma. Отключённое состояние (Figma `state=disabled`) задаётся не инпутом, а через форму — `setDisabledState` из `ControlValueAccessor` (как и `invalid`/`disabled` у остальных `extra-*`-полей, см. чеклист, п.5); отдельного `[disabled]` input на компоненте нет. Состояния `hover` и `focus` из Figma воспроизводятся браузером при наведении и фокусе и не имеют отдельных инпутов. Figma не показывает danger/invalid-вариант для этого компонента — `invalid` в спеке/API не заводился.
 
 ## Variants
 
@@ -48,13 +51,13 @@ updated: '2026-06-23'
 Figma: `<ToggleButton>`, state=default, checked=false, icon-only=false
 
 ```html
-<toggle-button onLabel="Вкл" offLabel="Выкл" [(ngModel)]="isOn"></toggle-button>
+<extra-togglebutton label="Подписка" [(ngModel)]="isOn"></extra-togglebutton>
 ```
 
 В реактивных формах эквивалентно:
 
 ```html
-<toggle-button onLabel="Вкл" offLabel="Выкл" [formControl]="control"></toggle-button>
+<extra-togglebutton label="Подписка" [formControl]="control"></extra-togglebutton>
 ```
 
 ### On (включена)
@@ -62,24 +65,17 @@ Figma: `<ToggleButton>`, state=default, checked=false, icon-only=false
 Figma: `<ToggleButton>`, state=default, checked=true, icon-only=false
 
 ```html
-<toggle-button onLabel="Вкл" offLabel="Выкл" [(ngModel)]="isOn"></toggle-button>
+<extra-togglebutton label="Подписка" [(ngModel)]="isOn"></extra-togglebutton>
 ```
 
-### С иконками (onIcon / offIcon)
+### С иконкой
 
 Figma: `<ToggleButton>`, icon-position=left, checked=true/false
 
 Классы иконок — из справочника [icons.md](../../figma-code-connect/icons.md).
 
 ```html
-<toggle-button
-  onLabel="Включено"
-  offLabel="Выключено"
-  onIcon="ti ti-check"
-  offIcon="ti ti-x"
-  iconPos="left"
-  [(ngModel)]="isOn"
-></toggle-button>
+<extra-togglebutton label="Избранное" icon="ti ti-star" iconPosition="left" [(ngModel)]="isOn"></extra-togglebutton>
 ```
 
 ### Иконка справа (icon-position=right)
@@ -87,14 +83,7 @@ Figma: `<ToggleButton>`, icon-position=left, checked=true/false
 Figma: `<ToggleButton>`, icon-position=right
 
 ```html
-<toggle-button
-  onLabel="Включено"
-  offLabel="Выключено"
-  onIcon="ti ti-check"
-  offIcon="ti ti-x"
-  iconPos="right"
-  [(ngModel)]="isOn"
-></toggle-button>
+<extra-togglebutton label="Избранное" icon="ti ti-star" iconPosition="right" [(ngModel)]="isOn"></extra-togglebutton>
 ```
 
 ### Только иконка (icon-only)
@@ -102,13 +91,7 @@ Figma: `<ToggleButton>`, icon-position=right
 Figma: `<ToggleButton>`, icon-only=true, icon-position=null
 
 ```html
-<toggle-button
-  onIcon="ti ti-star-filled"
-  offIcon="ti ti-star"
-  [iconOnly]="true"
-  ariaLabel="В избранное"
-  [(ngModel)]="isOn"
-></toggle-button>
+<extra-togglebutton icon="ti ti-star" [iconOnly]="true" ariaLabel="В избранное" [(ngModel)]="isOn"></extra-togglebutton>
 ```
 
 ### Размер large
@@ -116,27 +99,17 @@ Figma: `<ToggleButton>`, icon-only=true, icon-position=null
 Figma: `<ToggleButton>`, size=large
 
 ```html
-<toggle-button
-  onLabel="Вкл"
-  offLabel="Выкл"
-  size="large"
-  [(ngModel)]="isOn"
-></toggle-button>
+<extra-togglebutton label="Подписка" size="large" [(ngModel)]="isOn"></extra-togglebutton>
 ```
 
 ### Disabled (отключена)
 
 Figma: `<ToggleButton>`, state=disabled
 
-Отключённое состояние задаётся через `[disabled]="true"` либо через `FormControl` в состоянии `disabled`.
+Отключённое состояние задаётся через `FormControl` в состоянии `disabled`, не через `@Input`:
 
 ```html
-<toggle-button
-  onLabel="Вкл"
-  offLabel="Выкл"
-  [disabled]="true"
-  [(ngModel)]="isOn"
-></toggle-button>
+<extra-togglebutton label="Подписка" [formControl]="disabledControl"></extra-togglebutton>
 ```
 
 ### Fluid (на всю ширину)
@@ -144,23 +117,18 @@ Figma: `<ToggleButton>`, state=disabled
 Figma: `<ToggleButton>`, size=base
 
 ```html
-<toggle-button
-  onLabel="Вкл"
-  offLabel="Выкл"
-  [fluid]="true"
-  [(ngModel)]="isOn"
-></toggle-button>
+<extra-togglebutton label="Подписка" [fluid]="true" [(ngModel)]="isOn"></extra-togglebutton>
 ```
 
 ## Slots
 
-Не используются. Подписи и иконки задаются через `@Input` `onLabel` / `offLabel` / `onIcon` / `offIcon`.
+Не используются. Подпись и иконка задаются через `@Input` `label` / `icon`.
 
 ## Related
 
 - [ExtraButton](../button/button.figma.md) — кнопка-действие без двух состояний
 - [ExtraCheckbox](../checkbox/checkbox.figma.md) — выбор в форме с похожим маппингом состояния через модель
-- [Иконки](../../figma-code-connect/icons.md) — доступные иконки (`onIcon` / `offIcon`)
+- [Иконки](../../figma-code-connect/icons.md) — доступные иконки (`icon`)
 - [Токены](../../figma-code-connect/tokens.md) — цветовые токены состояний
 - [Conventions](../../figma-code-connect/conventions.md) — соглашения маппинга Figma → Angular
 
@@ -169,13 +137,14 @@ Figma: `<ToggleButton>`, size=base
 **Do:**
 - Задавайте состояние через модель (`[(ngModel)]`, `formControl` или `formControlName`) — это Figma-свойство `checked`
 - Для режима `[iconOnly]="true"` всегда задавайте `ariaLabel` для доступности
-- Используйте понятные пары `onLabel` / `offLabel`, отражающие включённое и выключенное состояния
-- Для отключения предпочитайте `FormControl` в состоянии `disabled` либо `[disabled]="true"`
+- Используйте один и тот же `label`, описывающий действие/настройку, а не состояние («Подписка», а не «Вкл»/«Выкл»)
+- Для отключения используйте `FormControl` в состоянии `disabled`
 - Используйте `[fluid]="true"` в мобильных макетах и формах на всю ширину
 
 **Don't:**
 - Не задавайте «нажата» через отдельный атрибут — состояние идёт только через модель
+- Не меняйте текст кнопки в зависимости от состояния (нет отдельных `onLabel`/`offLabel` — это осознанно, см. Overview)
 - Не используйте `ToggleButton` для навигации по разделам — для этого есть `Tabs`
 - Не подменяйте им `ToggleSwitch` (свитч настройки) или `SelectButton` (выбор из набора)
-- Не передавайте `[iconOnly]="true"` без `onIcon` / `offIcon` — кнопка окажется пустой
+- Не передавайте `[iconOnly]="true"` без `icon` — кнопка окажется пустой
 - Не инлайньте CSS-классы иконок вручную — используйте справочник [icons.md](../../figma-code-connect/icons.md)
diff --git a/src/stories/components/togglebutton/examples/togglebutton-disabled.component.ts b/src/stories/components/togglebutton/examples/togglebutton-disabled.component.ts
index afb62c42..5e100ddc 100644
--- a/src/stories/components/togglebutton/examples/togglebutton-disabled.component.ts
+++ b/src/stories/components/togglebutton/examples/togglebutton-disabled.component.ts
@@ -4,11 +4,10 @@ import { StoryObj } from '@storybook/angular';
 import { ExtraToggleButtonComponent } from '../../../../lib/components/togglebutton/togglebutton.component';
 
 const template = `
-<extra-toggle-button
-  onLabel="Вкл"
-  offLabel="Выкл"
+<extra-togglebutton
+  label="Подписка"
   [formControl]="control"
-></extra-toggle-button>
+></extra-togglebutton>
 `;
 const styles = '';
 
@@ -45,7 +44,7 @@ import { ReactiveFormsModule, FormControl } from '@angular/forms';
   standalone: true,
   imports: [ExtraToggleButtonComponent, ReactiveFormsModule],
   template: \`
-    <extra-toggle-button onLabel="Вкл" offLabel="Выкл" [formControl]="control"></extra-toggle-button>
+    <extra-togglebutton label="Подписка" [formControl]="control"></extra-togglebutton>
   \`,
 })
 export class ToggleButtonDisabledComponent {
diff --git a/src/stories/components/togglebutton/examples/togglebutton-icon-only.component.ts b/src/stories/components/togglebutton/examples/togglebutton-icon-only.component.ts
index f5fc1b49..d483d0ca 100644
--- a/src/stories/components/togglebutton/examples/togglebutton-icon-only.component.ts
+++ b/src/stories/components/togglebutton/examples/togglebutton-icon-only.component.ts
@@ -4,12 +4,12 @@ import { StoryObj } from '@storybook/angular';
 import { ExtraToggleButtonComponent } from '../../../../lib/components/togglebutton/togglebutton.component';
 
 const template = `
-<extra-toggle-button
-  onIcon="ti ti-star-filled"
-  offIcon="ti ti-star"
+<extra-togglebutton
+  icon="ti ti-star"
   [iconOnly]="true"
+  ariaLabel="В избранное"
   [formControl]="control"
-></extra-toggle-button>
+></extra-togglebutton>
 `;
 const styles = '';
 
@@ -32,7 +32,7 @@ export const IconOnly: StoryObj = {
     controls: { disable: true },
     docs: {
       description: {
-        story: 'Icon-only вариант: квадратная кнопка без текста. Размер регулируется через `size`.',
+        story: 'Icon-only вариант: квадратная кнопка без текста. Размер регулируется через `size`, для доступности обязателен `ariaLabel`.',
       },
       source: {
         language: 'ts',
@@ -46,12 +46,12 @@ import { ReactiveFormsModule, FormControl } from '@angular/forms';
   standalone: true,
   imports: [ExtraToggleButtonComponent, ReactiveFormsModule],
   template: \`
-    <extra-toggle-button
-      onIcon="ti ti-star-filled"
-      offIcon="ti ti-star"
+    <extra-togglebutton
+      icon="ti ti-star"
       [iconOnly]="true"
+      ariaLabel="В избранное"
       [formControl]="control"
-    ></extra-toggle-button>
+    ></extra-togglebutton>
   \`,
 })
 export class ToggleButtonIconOnlyComponent {
diff --git a/src/stories/components/togglebutton/examples/togglebutton-icons.component.ts b/src/stories/components/togglebutton/examples/togglebutton-icons.component.ts
index 12c10755..268971ca 100644
--- a/src/stories/components/togglebutton/examples/togglebutton-icons.component.ts
+++ b/src/stories/components/togglebutton/examples/togglebutton-icons.component.ts
@@ -4,13 +4,11 @@ import { StoryObj } from '@storybook/angular';
 import { ExtraToggleButtonComponent } from '../../../../lib/components/togglebutton/togglebutton.component';
 
 const template = `
-<extra-toggle-button
-  onLabel="Включено"
-  offLabel="Выключено"
-  onIcon="ti ti-check"
-  offIcon="ti ti-x"
+<extra-togglebutton
+  label="Избранное"
+  icon="ti ti-star"
   [formControl]="control"
-></extra-toggle-button>
+></extra-togglebutton>
 `;
 const styles = '';
 
@@ -33,7 +31,7 @@ export const Icons: StoryObj = {
     controls: { disable: true },
     docs: {
       description: {
-        story: 'Кнопка с иконками через `onIcon`/`offIcon`. Позиция иконки управляется `iconPos`.',
+        story: 'Кнопка с иконкой через `icon` — та же иконка в обоих состояниях. Позиция управляется `iconPosition`.',
       },
       source: {
         language: 'ts',
@@ -47,13 +45,11 @@ import { ReactiveFormsModule, FormControl } from '@angular/forms';
   standalone: true,
   imports: [ExtraToggleButtonComponent, ReactiveFormsModule],
   template: \`
-    <extra-toggle-button
-      onLabel="Включено"
-      offLabel="Выключено"
-      onIcon="ti ti-check"
-      offIcon="ti ti-x"
+    <extra-togglebutton
+      label="Избранное"
+      icon="ti ti-star"
       [formControl]="control"
-    ></extra-toggle-button>
+    ></extra-togglebutton>
   \`,
 })
 export class ToggleButtonIconsComponent {
diff --git a/src/stories/components/togglebutton/examples/togglebutton-sizes.component.ts b/src/stories/components/togglebutton/examples/togglebutton-sizes.component.ts
deleted file mode 100644
index 5f815184..00000000
--- a/src/stories/components/togglebutton/examples/togglebutton-sizes.component.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-import { Component } from '@angular/core';
-import { ReactiveFormsModule, FormControl } from '@angular/forms';
-import { StoryObj } from '@storybook/angular';
-import { ExtraToggleButtonComponent } from '../../../../lib/components/togglebutton/togglebutton.component';
-
-const template = `
-<extra-toggle-button size="xlarge" onLabel="Вкл" offLabel="Выкл" [formControl]="control"></extra-toggle-button>
-`;
-const styles = '';
-
-@Component({
-  selector: 'app-togglebutton-sizes',
-  standalone: true,
-  imports: [ExtraToggleButtonComponent, ReactiveFormsModule],
-  template,
-  styles,
-})
-export class ToggleButtonSizesComponent {
-  control = new FormControl(false);
-}
-
-export const Sizes: StoryObj = {
-  render: () => ({
-    template: `<app-togglebutton-sizes></app-togglebutton-sizes>`,
-  }),
-  parameters: {
-    controls: { disable: true },
-    docs: {
-      description: {
-        story: 'Размер компонента задаётся через проп `size`: `small`, `base`, `large`, `xlarge`.',
-      },
-      source: {
-        language: 'ts',
-        code: `
-import { Component } from '@angular/core';
-import { ExtraToggleButtonComponent } from '@cdek-it/angular-ui-kit';
-import { ReactiveFormsModule, FormControl } from '@angular/forms';
-
-@Component({
-  selector: 'app-togglebutton-sizes',
-  standalone: true,
-  imports: [ExtraToggleButtonComponent, ReactiveFormsModule],
-  template: \`
-    <extra-toggle-button size="xlarge" onLabel="Вкл" offLabel="Выкл" [formControl]="control"></extra-toggle-button>
-  \`,
-})
-export class ToggleButtonSizesComponent {
-  control = new FormControl(false);
-}
-        `,
-      },
-    },
-  },
-};
diff --git a/src/stories/components/togglebutton/togglebutton.stories.ts b/src/stories/components/togglebutton/togglebutton.stories.ts
index 3f3a8f00..fdb23fbf 100644
--- a/src/stories/components/togglebutton/togglebutton.stories.ts
+++ b/src/stories/components/togglebutton/togglebutton.stories.ts
@@ -1,8 +1,11 @@
 import { Meta, StoryObj, moduleMetadata } from '@storybook/angular';
 import { ReactiveFormsModule, FormControl } from '@angular/forms';
 import { ExtraToggleButtonComponent } from '../../../lib/components/togglebutton/togglebutton.component';
+import { ToggleButtonIconsComponent, Icons } from './examples/togglebutton-icons.component';
+import { ToggleButtonIconOnlyComponent, IconOnly } from './examples/togglebutton-icon-only.component';
+import { ToggleButtonDisabledComponent, Disabled } from './examples/togglebutton-disabled.component';
 
-type ToggleButtonArgs = ExtraToggleButtonComponent;
+type ToggleButtonArgs = ExtraToggleButtonComponent & { disabled: boolean };
 
 const meta: Meta<ToggleButtonArgs> = {
   title: 'Components/Form/ToggleButton',
@@ -10,59 +13,51 @@ const meta: Meta<ToggleButtonArgs> = {
   tags: ['autodocs'],
   decorators: [
     moduleMetadata({
-      imports: [ExtraToggleButtonComponent, ReactiveFormsModule],
+      imports: [ExtraToggleButtonComponent, ReactiveFormsModule, ToggleButtonIconsComponent, ToggleButtonIconOnlyComponent, ToggleButtonDisabledComponent],
     }),
   ],
   parameters: {
     designTokens: { prefix: '--p-togglebutton' },
     docs: {
       description: {
-        component: `Кнопка-переключатель для выбора булевого значения. Поддерживает размеры \`small\`, \`base\`, \`large\`, \`xlarge\`, иконки и icon-only вариант.`,
+        component: `Кнопка-переключатель для выбора булевого значения.
+
+Реализовано по спецификации [togglebutton.md](https://github.com/cdek-it/angular-ui-kit/blob/main/docs/components-api/togglebutton.md).
+
+\`\`\`typescript
+import { ExtraToggleButtonComponent } from '@cdek-it/angular-ui-kit';
+\`\`\`
+
+Значение подключается через \`[(ngModel)]\` или \`[formControl]\` (ControlValueAccessor). Отключённое состояние управляется через FormControl, не через проп.`,
       },
     },
   },
   argTypes: {
-    // ── Props ────────────────────────────────────────────────
-    onLabel: {
-      control: 'text',
-      description: 'Текст в активном состоянии',
-      table: {
-        category: 'Props',
-        defaultValue: { summary: "'Вкл'" },
-        type: { summary: 'string' },
-      },
-    },
-    offLabel: {
+    // ── Свойства (docs/components-api/togglebutton.md) ─────────────
+    label: {
       control: 'text',
-      description: 'Текст в неактивном состоянии',
+      description: 'Текст кнопки — один и тот же в обоих состояниях',
       table: {
-        category: 'Props',
-        defaultValue: { summary: "'Выкл'" },
+        category: 'Свойства',
+        defaultValue: { summary: "''" },
         type: { summary: 'string' },
       },
     },
-    onIcon: {
+    icon: {
       control: 'text',
-      description: 'CSS-класс иконки в активном состоянии',
+      description: 'CSS-класс иконки (tabler), один и тот же в обоих состояниях',
       table: {
-        category: 'Props',
+        category: 'Свойства',
+        defaultValue: { summary: "''" },
         type: { summary: 'string' },
       },
     },
-    offIcon: {
-      control: 'text',
-      description: 'CSS-класс иконки в неактивном состоянии',
-      table: {
-        category: 'Props',
-        type: { summary: 'string' },
-      },
-    },
-    iconPos: {
+    iconPosition: {
       control: 'select',
       options: ['left', 'right'],
       description: 'Позиция иконки',
       table: {
-        category: 'Props',
+        category: 'Свойства',
         defaultValue: { summary: "'left'" },
         type: { summary: "'left' | 'right'" },
       },
@@ -72,34 +67,35 @@ const meta: Meta<ToggleButtonArgs> = {
       options: ['small', 'base', 'large', 'xlarge'],
       description: 'Размер кнопки',
       table: {
-        category: 'Props',
+        category: 'Свойства',
         defaultValue: { summary: "'base'" },
         type: { summary: "'small' | 'base' | 'large' | 'xlarge'" },
       },
     },
-    disabled: {
+    iconOnly: {
       control: 'boolean',
-      description: 'Отключает взаимодействие',
+      description: 'Режим «только иконка» без текста',
       table: {
-        category: 'Props',
+        category: 'Свойства',
         defaultValue: { summary: 'false' },
         type: { summary: 'boolean' },
       },
     },
-    iconOnly: {
+    fluid: {
       control: 'boolean',
-      description: 'Скрывает label, делает кнопку квадратной',
+      description: 'Растягивает кнопку на всю ширину контейнера',
       table: {
-        category: 'Props',
+        category: 'Свойства',
         defaultValue: { summary: 'false' },
         type: { summary: 'boolean' },
       },
     },
-    fluid: {
+    // ── Состояния (управляются через FormControl) ───────────────────
+    disabled: {
       control: 'boolean',
-      description: 'Растягивает кнопку на всю ширину контейнера',
+      description: 'Отключённое состояние — управляется через FormControl',
       table: {
-        category: 'Props',
+        category: 'Состояния',
         defaultValue: { summary: 'false' },
         type: { summary: 'boolean' },
       },
@@ -115,127 +111,60 @@ const meta: Meta<ToggleButtonArgs> = {
     primeSize: { table: { disable: true } },
     extraClasses: { table: { disable: true } },
 
-    // ── Events ───────────────────────────────────────────────
+    // ── События ──────────────────────────────────────────────────
     onChange: {
       control: false,
       description: 'Событие изменения значения',
       table: {
-        category: 'Events',
-        type: { summary: 'EventEmitter<ToggleButtonChangeEvent>' },
+        category: 'События',
+        type: { summary: 'EventEmitter<ExtraToggleButtonChangeEvent>' },
       },
     },
   },
   args: {
-    onLabel: 'Вкл',
-    offLabel: 'Выкл',
+    label: 'Подписка',
+    icon: '',
+    iconPosition: 'left',
     size: 'base',
-    disabled: false,
     iconOnly: false,
     fluid: false,
+    disabled: false,
   },
 };
 
 export default meta;
 type Story = StoryObj<ToggleButtonArgs>;
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function buildTemplate(args: any): string {
-  const parts: string[] = [];
-
-  if (!args.iconOnly) {
-    parts.push(`onLabel="${args.onLabel}"`);
-    parts.push(`offLabel="${args.offLabel}"`);
-  }
-  if (args.size && args.size !== 'base') parts.push(`size="${args.size}"`);
-  if (args.onIcon) parts.push(`onIcon="${args.onIcon}"`);
-  if (args.offIcon) parts.push(`offIcon="${args.offIcon}"`);
-  if (args.iconPos && args.iconPos !== 'left') parts.push(`iconPos="${args.iconPos}"`);
-  if (args.disabled) parts.push(`[disabled]="true"`);
-  if (args.iconOnly) parts.push(`[iconOnly]="true"`);
-  if (args.fluid) parts.push(`[fluid]="true"`);
-  parts.push(`[formControl]="control"`);
-
-  return `<extra-toggle-button\n  ${parts.join('\n  ')}\n></extra-toggle-button>`;
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function renderStory(args: any) {
-  return { props: { ...args, control: new FormControl(false) }, template: buildTemplate(args) };
-}
-
-// ── Default ──────────────────────────────────────────────────────────────────
+// ── Default (интерактивная) ────────────────────────────────────────────────
 export const Default: Story = {
   name: 'Default',
-  render: (args) => renderStory(args),
-  parameters: {
-    docs: {
-      description: {
-        story: 'Базовый пример компонента. Используйте Controls для интерактивного изменения пропсов.',
-      },
-    },
-  },
-};
+  render: (args) => {
+    const parts: string[] = [];
 
-// ── Sizes ────────────────────────────────────────────────────────────────────
-export const Sizes: Story = {
-  render: (args) => renderStory(args),
-  args: { size: 'xlarge' },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Размер компонента задаётся через проп `size`: `small`, `base`, `large`, `xlarge`.',
-      },
-    },
-  },
-};
+    if (!args.iconOnly && args.label) parts.push(`label="${args.label}"`);
+    if (args.icon) parts.push(`icon="${args.icon}"`);
+    if (args.iconPosition && args.iconPosition !== 'left') parts.push(`iconPosition="${args.iconPosition}"`);
+    if (args.size && args.size !== 'base') parts.push(`size="${args.size}"`);
+    if (args.iconOnly) parts.push(`[iconOnly]="true"`);
+    if (args.fluid) parts.push(`[fluid]="true"`);
 
-// ── Icons ────────────────────────────────────────────────────────────────────
-export const Icons: Story = {
-  render: (args) => renderStory(args),
-  args: {
-    onLabel: 'Включено',
-    offLabel: 'Выключено',
-    onIcon: 'ti ti-check',
-    offIcon: 'ti ti-x',
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Кнопка с иконками через `onIcon`/`offIcon`. Позиция иконки управляется `iconPos`.',
-      },
-    },
-  },
-};
+    const control = new FormControl({ value: false, disabled: args.disabled });
+    const template = `<extra-togglebutton [formControl]="control"\n  ${parts.join('\n  ')}\n></extra-togglebutton>`;
 
-// ── IconOnly ─────────────────────────────────────────────────────────────────
-export const IconOnly: Story = {
-  render: (args) => renderStory(args),
-  args: {
-    onIcon: 'ti ti-star-filled',
-    offIcon: 'ti ti-star',
-    iconOnly: true,
+    // disabled живёт во FormControl, у компонента нет такого @Input — Storybook ругается в консоль
+    // на попытку присвоить его напрямую
+    const { disabled, ...rest } = args;
+
+    return { props: { ...rest, control }, template };
   },
   parameters: {
     docs: {
       description: {
-        story: 'Icon-only вариант: квадратная кнопка без текста. Размер регулируется через `size`.',
+        story: 'Интерактивная кнопка со всеми свойствами спецификации. Используйте Controls для изменения пропсов; disabled управляется через FormControl.',
       },
     },
   },
 };
 
-// ── Disabled ─────────────────────────────────────────────────────────────────
-export const Disabled: Story = {
-  render: () => ({
-    props: { control: new FormControl({ value: false, disabled: true }) },
-    template: `<extra-toggle-button onLabel="Вкл" offLabel="Выкл" [formControl]="control"></extra-toggle-button>`,
-  }),
-  parameters: {
-    controls: { disable: true },
-    docs: {
-      description: {
-        story: 'Отключённое состояние управляется через `FormControl`: `new FormControl({ value: false, disabled: true })` или `control.disable()`.',
-      },
-    },
-  },
-};
+// ── Комбинаторные истории ──────────────────────────────────────────────────
+export { Icons, IconOnly, Disabled };