From f883fca3bc7ecad17057bf96bcb984043dcd7ca2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=A8=D0=B0=D1=80=D0=B0=D0=B5=D0=B2=20=D0=90=D0=B9=D0=BD?=
 =?UTF-8?q?=D1=83=D1=80=20=D0=A0=D0=B0=D0=B8=D0=BB=D1=8C=D0=B5=D0=B2=D0=B8?=
 =?UTF-8?q?=D1=87?= <mr.sharaevainur@yandex.ru>
Date: Tue, 29 Jun 2021 17:16:18 +0300
Subject: [PATCH] wip: rewrite in english, change structure

---
 src/woly/atoms/button-icon/specification.mdx | 45 +++++++++++++-------
 1 file changed, 29 insertions(+), 16 deletions(-)

diff --git a/src/woly/atoms/button-icon/specification.mdx b/src/woly/atoms/button-icon/specification.mdx
index cbcf0f19..ffd05450 100644
--- a/src/woly/atoms/button-icon/specification.mdx
+++ b/src/woly/atoms/button-icon/specification.mdx
@@ -1,27 +1,40 @@
-`Кнопка-иконка` — это компонент, который представляет собой кнопку с svg-иконкой.
+Use the `ButtonIcon` to perform an action. An icon is present to signify what the button does.
 
-Кнопки-иконки используют, чтобы:
+## Overview
 
-- применить действие к объекту, к примеру, удалить, изменить, добавить новый элемент
-- показать новую информацию, например, открыть модальное окно с информацией
+`ButtonIcon` are clickable interactive elements that contain an icon and no (visible) accompanying text.
 
-Чаще всего они нужны для того, чтобы сохранить пространство, но ценою узнаваемости, поскольку из-за отсутствия текстового описания трудно понять их действие. Поэтому очень важно использовать такие иконки для кнопки, чтобы по ним и по окружающему контексту было максимально понятно о действии кнопки.
+Typically, the `ButtonIcon` is used to save space. Since the `ButtonIcon` has no text that tells the user its purpose, it is important to pick easily recognizable icons, that, accounting for the surrounding context, will tell for sure about the button's action.
 
-### Поведение
+**When to use**
 
-Компонент имеет стандартное поведение для интерактивных элементов, такие как:
-– изменение оформления для индикации состояний, таких как `default`, `hover`, `active`, `focus`, `disabled`
-– запускает действие через манипуляции мышки / клавиатуры, если не находится в состоянии `disabled`
+- to do an action on an item, for example, to delete, to change, or add a new element within a group;
+- to display new information, for example, show a popover with фdescription
 
-### Иконка
+**When to not use**
 
-Иконка должна ясно отражать действие этой кнопки, то есть не иметь разные интерпретации. Если в силу каких-нибудь ограничений этого не избежать, то нужно дополнить кнопку-иконку компонентом "Тултип", где будет описание о действии кнопки:
+- to trigger actions, which influence the user's flow, like submitting form, (use `Button` instead)
+- to navigate a user to another page or an external web resource (use a link instead)
 
-- Не более 2-3 слов.
-- В начале описания используйте глаголы, например, "Сохранить" или "Отправить"
+## Appearance
 
-Иконка должна иметь консистентный дизайн, и также быть читабельной и четкой при любых размерах.
+### Icon
 
-### Оформление
+As it was said in _Overview_, a button's icon should be easly recognizable and unambiguous. You may consided pairing `ButtonIcon` with a component `Tooltip` to describe the buttons’s underlying action.
 
-Для комфортной интеракции с компонентом она должна быть как минимум 42 пикселя по ширине и по высоте, и как минимум 10 px от другой кнопки-иконки. Эти правила больше касается мобильных пользователей, чьи устройства имеют touch экраны.
+Recomendations for a description:
+
+- make it short (3-5 words).
+- use "action" verbs at the beggining ( "save", "send", etc.)
+
+## Behaviors
+
+### Interactions
+
+_Mouse_
+Users can trigger a button by clicking anywhere within the button container.
+
+_Keyboard_
+Users can trigger a button by pressing `Enter` while the button has focus.
+
+## Placement