Кнопка-иконка

Кнопка-иконка выполняет одно действие и вместо текста показывает одну иконку. Для скринридеров её называет label.

Стабильный

Figma

Обзор

Использование

API

Доступность

<tk-icon-button label="Search"><tk-icon name="search"></tk-icon></tk-icon-button>
<tk-icon-button label="Settings"><tk-icon name="settings"></tk-icon></tk-icon-button>
<tk-icon-button label="More actions"><tk-icon name="more-horizontal"></tk-icon></tk-icon-button>

Анатомия

Часть	Что это
`tk-icon-button`	сам элемент; одна остановка Tab; квадрат фиксированного размера
слот по умолчанию	одна иконка, обязательна; скрыта от скринридеров
слот `pressed`	иконка для состояния `pressed`, например залитая пара, по желанию
part `button`	нативный `<button>` внутри; `label` становится его доступным именем

Варианты

<tk-icon-button label="Edit"><tk-icon name="edit"></tk-icon></tk-icon-button>
<tk-icon-button variant="secondary" label="Edit"><tk-icon name="edit"></tk-icon></tk-icon-button>
<tk-icon-button variant="outline" label="Edit"><tk-icon name="edit"></tk-icon></tk-icon-button>
<tk-icon-button variant="primary" label="Edit"><tk-icon name="edit"></tk-icon></tk-icon-button>

ghost (по умолчанию): голая иконка без подложки. Для панелей инструментов, шапок и строк. В отличие от ghost-Button, иконка и подсветка при наведении нейтральные, а не акцентные.
secondary: залитый квадрат, когда действию нужен вес заметного контрола.
outline: квадрат с рамкой, когда нужна видимая граница на пёстром фоне или в соединённой Button group. Рамка у неё светлая, поэтому на утопленной поверхности, например в нейтральном Banner или Section message, используйте ghost или secondary.
primary: главное быстрое действие панели. Не больше одной залитой кнопки-иконки на панель.

Опасное действие

tone="danger" отмечает действие, которое что-то удаляет. Выглядит всегда одинаково, какой бы variant вы ни задали: красный квадрат с красной иконкой.

<tk-icon-button tone="danger" label="Delete file"><tk-icon name="trash"></tk-icon></tk-icon-button>

У иконки нет слов, которые человек прочтёт перед нажатием, поэтому опасная кнопка-иконка должна открывать подтверждение, например Dialog, где названо, что будет удалено. Никогда не удаляйте с первого нажатия.

Форма

shape="round" делает кнопку круглой. Работает с любым вариантом, тоном и размером. Соединённая группа кнопок или Split button задаёт углы сама.

<tk-icon-button shape="round" label="Add"><tk-icon name="plus"></tk-icon></tk-icon-button>
<tk-icon-button variant="secondary" shape="round" label="Share"><tk-icon name="share"></tk-icon></tk-icon-button>

Размеры

<tk-icon-button size="small" label="Close"><tk-icon name="close"></tk-icon></tk-icon-button>
<tk-icon-button label="Close"><tk-icon name="close"></tk-icon></tk-icon-button>
<tk-icon-button size="large" label="Close"><tk-icon name="close"></tk-icon></tk-icon-button>

`size`	Квадрат	Иконка	Скругление (`rect`)
`small`	24×24px	`icon-size-16`	`radius-8`
`medium` (по умолчанию)	32×32px	`icon-size-16`	`radius-8`
`large`	36×36px	`icon-size-16`	`radius-8`

Стороны квадратов равны высотам Button, поэтому смешанные ряды выравниваются. small ровно 24px, это минимальный размер цели нажатия: не уменьшайте её, не давайте отрицательных отступов и не перекрывайте ничем. Иконка всегда 16px, её размер задаёт кнопка.

Состояния

<tk-icon-button disabled label="Edit"><tk-icon name="edit"></tk-icon></tk-icon-button>
<tk-icon-button loading label="Download report"><tk-icon name="download"></tk-icon></tk-icon-button>

Наведение, нажатие и фокус работают без атрибутов. При фокусе с клавиатуры у любой кнопки-иконки появляется рамка.

disabled: на кнопку нельзя перейти и нельзя нажать, а опасная кнопка становится серой. Лучше оставить кнопку активной.
loading: вместо иконки крутится индикатор, квадрат не меняется, повторные нажатия не срабатывают. Кнопка остаётся в фокусе, сохраняет label и сообщает скринридеру, что занята. Если задан ещё и disabled, кнопка будет отключена.
pressed: включённое состояние переключателя, см. ниже.

Переключатель

Для действий «вкл/выкл», например закладка, избранное, без звука, закрепить, задайте pressed. Положите залитую пару иконки в слот pressed, и кнопка будет их менять.

<tk-icon-button label="Bookmark" pressed>
  <tk-icon name="bookmark"></tk-icon>
  <tk-icon slot="pressed" name="bookmark-filled"></tk-icon>
</tk-icon-button>

pressed ставит aria-pressed. Кнопка без этого атрибута не объявляется переключателем.
Подпись называет действие, а не состояние: «Выключить звук», а не «Звук выключен». Скринридер сам добавит «нажата», а подпись, которая меняется, читается наоборот.
pressed управляете вы. Кнопка сама его не переключает и событий изменения не шлёт. Слушайте click и меняйте его либо оберните кнопку в Toggle button: он сделает это за вас.
Все варианты, кроме primary, во включённом состоянии подсвечиваются. Без иконки в слоте pressed состояние показывает только подсветка.
Не сочетайте pressed с tone="danger".

Оберните кнопку-иконку в Tooltip типа label, чтобы зрячие пользователи видели её название при наведении и фокусе. Не задавайте подсказке text: она покажет label кнопки, и они никогда не разойдутся.

<tk-tooltip type="label">
  <tk-icon-button label="Copy link"><tk-icon name="link"></tk-icon></tk-icon-button>
</tk-tooltip>

Делайте так для любой неочевидной иконки. Кнопка-иконка с одним label тоже доступна.

Когда использовать

Для действия, иконку которого знают все: закрыть, поиск, настройки, ещё, избранное. Проверьте это на пользователях, а не только на команде.
Там, где мало места: панели инструментов, шапки, строки таблиц, углы карточек.
В остальных случаях берите Button с текстом. Текст понимают быстрее, чем иконку.
Чтобы открыть меню, используйте Menu с кнопкой-иконкой в роли триггера.

Текст

label обязателен. Это доступное имя кнопки; если его нет, кнопка предупреждает в консоли.

Называйте действие: «Найти», «Переименовать», «Скопировать ссылку». Не иконку («Карандаш») и не состояние («Звук выключен»).
Правила те же, что у подписей Button: глагол, заглавная буква только в начале, без точки в конце.
Одна подпись на иконку во всём продукте. Одна и та же иконка не должна в одном месте значить «Закрепить», а в другом «Сохранить».
В опасной подписи назовите, что удаляется: «Удалить файл».
Не называйте кнопку через title. С клавиатуры и на сенсорном экране его не видно.

Подробнее в Action labels.

Можно / нельзя

✅ Можно	❌ Нельзя
Только иконка для известных значков и тесных панелей	Менять кнопку с текстом на иконку, когда место есть
`small` в полный размер 24×24px	Уменьшать, обрезать или перекрывать `small`
Не больше одной залитой кнопки-иконки на панель	Две залитые кнопки-иконки на одной панели
`ghost` или `secondary` на утопленной поверхности	`outline` там же: рамка пропадает
Называть действие: `label="Rename"`	Называть иконку («Карандаш») или состояние («Звук выключен»)
Подтверждение перед опасным действием	Удалять с первого нажатия
Залитая пара иконки в слоте `pressed`	Менять подпись, когда меняется `pressed`

Button: та же кнопка с видимой подписью.
Toggle button: оборачивает кнопку-иконку и сам переключает pressed.
Tooltip: показывает подпись при наведении и фокусе.
Menu: берёт кнопку-иконку как триггер.
Spinner: индикатор, который показывает loading.
Icon: что кладут в слоты.

API

Атрибуты

Атрибут	Тип	По умолчанию	Что делает
`label`	string	обязателен	доступное имя; называет действие
`variant`	`primary` \| `secondary` \| `outline` \| `ghost`	`ghost`	насколько кнопка заметна
`tone`	`neutral` \| `danger`	`neutral`	`danger` для удаления; один вид при любом `variant`
`size`	`small` \| `medium` \| `large`	`medium`	квадрат 24 / 32 / 36px
`shape`	`rect` \| `round`	`rect`	скруглённые углы или круг
`disabled`	boolean	`false`	не в фокусе, не нажимается, не попадает в форму
`loading`	boolean	`false`	индикатор, тот же размер, повторные нажатия не срабатывают, `aria-busy`
`pressed`	boolean	не задан	включённый переключатель и `aria-pressed`; ставите вы
`type`	`button` \| `submit` \| `reset`	`button`	`submit` отправляет форму

Слоты

Слот	Содержимое
по умолчанию	один `tk-icon`, обязателен
`pressed`	один `tk-icon` для включённого состояния, по желанию

События

Своих событий нет. Слушайте click; disabled и loading его блокируют.

CSS

::part(button): нативный <button>.
--tk-button-radius: задаёт углы и важнее, чем shape. Нужен компонентам, которые соединяют кнопки, например Button group.

Токены

Вариант / тон	Покой	Наведение	Нажатие	Отключена
primary	`fill/accent` + `icon/accent/on-fill`	`fill/accent/hover`	`fill/accent/active`	`surface/disabled` + `text/disabled`
secondary	`surface/subtle` + `text/default`	`state/hover`	`state/press`	`surface/disabled` + `text/disabled`
outline	`border/subtle` + `text/default`	`state/hover`	`state/press`	`border/disabled` + `text/disabled`
ghost	`icon/default`	`state/hover`	`state/press`	`text/disabled`
`tone="danger"`	`surface/error` + `icon/error`	`state/error/hover`	`state/error/press`	`surface/disabled` + `text/disabled`

Токены state/* — полупрозрачные слои поверх цвета кнопки в покое. Нажатая кнопка берёт state/on (под курсором state/on-hover) и иконку icon/default, а у outline ещё и border/selected. Рамка фокуса у всех кнопок border/accent/focus. Значения по темам: Color.

Доступность

Встроено:

Нативный <button>: до него доходит Tab, его нажимают Space и Enter, его видят формы.
label становится доступным именем; иконки в слотах скрыты от скринридеров.
pressed ставит aria-pressed, и он остаётся при disabled и loading.
loading ставит aria-busy и сохраняет имя.
Рамка фокуса для клавиатуры, которая никогда не прячется.
Любой размер не меньше 24×24px.

На вашей стороне:

Убедитесь, что иконку понимают; если сомневаетесь, берите Button с текстом.
Подпись называет действие и не меняется вместе с pressed.
Перед опасным действием открывайте подтверждение.
Неочевидные иконки оборачивайте в Tooltip типа label.

Клавиша	Действие
`Tab`	переводит фокус на кнопку
`Space` / `Enter`	нажимает её; с `type="submit"` отправляет форму

Пределы контраста

Рамка outline: 1.33:1 в светлой теме и 2.00:1 в тёмной, ниже минимума 3:1; в контрастной 4.22:1. Без текста и заливки только рамка показывает, что это кнопка. На утопленной поверхности в светлой теме её не видно.
Нажатый переключатель: в светлой и тёмной теме включённый выглядит так же, как наведённый; в контрастной они различаются. Скринридер всегда сообщает состояние, а глазу его показывает иконка из слота pressed.

Анатомия

Варианты

Опасное действие

Форма

Размеры

Состояния

Переключатель

Подсказка

Когда использовать

Текст

Можно / нельзя

Связанные

API

Атрибуты

Слоты

События

CSS

Токены

Доступность

Пределы контраста