From 3c486358c47d22c2667f80f85d13b2680238bb6e 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?= Date: Wed, 7 Jul 2021 11:41:39 +0300 Subject: [PATCH 1/6] docs(woly/button-icon): add specification --- src/woly/atoms/button-icon/specification.mdx | 49 ++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 src/woly/atoms/button-icon/specification.mdx diff --git a/src/woly/atoms/button-icon/specification.mdx b/src/woly/atoms/button-icon/specification.mdx new file mode 100644 index 00000000..8fb97ffd --- /dev/null +++ b/src/woly/atoms/button-icon/specification.mdx @@ -0,0 +1,49 @@ +## Overview + +`ButtonIcon` is an interactive element that contains an icon and no (visible) accompanying text. An icon expresses what action will occur when the user interacts with it. + +**Recommended to use** + +- to trigger an action on an item, for example, to delete, to change, or add an element within a group; often comes with another 2 or 3 adjacent `ButtonIcon`. + +**Not recommended using** + +- to trigger actions that could influence the user’s flow, like submitting a form (use `Button` instead); +- to navigate a user to another page or an external web resource (use a link instead); + +## Appearance + +### Icon + +Since the `ButtonIcon` has no label and therefore compact, it is commonly used in an interface where extra space matters. Its icon should be easily recognizable. You may pair `ButtonIcon` with a component `Tooltip` containing a hint about the `ButtonIcon` underlying action. + +Recommendations for a hint text: + +- make it short (2-3 words); +- use “action” verbs first ( “save”, “send”, etc.); + +## Placement + +### Grouping + +If `ButtonIcon`s share related actions, they’re good to be in a group. For example, in a list of items (users, products, blog posts), each item can have a group of `ButtonIcon`s with actions like `delete`, `edit`, `move`. In most cases, all buttons within a group should have the same priority, weight and size. But it does not limit you to make one particular button with the main action as `primary` and with weight `fill` then make other buttons as `secondary` and weight `outline`. + +### Inside other components + +`ButtonIcon` can be used as a part of a more complex component, like a hide/show toggle in the `InputPassword` component. Here, `ButtonIcon` should have the same `priority` and `weight` as its parent for consistency. + +## 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 it has focus. + +## Accessibility + +It’s recommended to provide `ButtonIcon` with an aria-label to describe the action to people using assistive technologies, such as screen readers. From 7042b1584406ffca2e5f1ef9e374abb44ad85724 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?= Date: Wed, 7 Jul 2021 11:56:09 +0300 Subject: [PATCH 2/6] =?UTF-8?q?docs(woly/button-icon):=20specification=20?= =?UTF-8?q?=E2=80=93=20changes=20in=20'Overview'=20and=20'Behaviors'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/woly/atoms/button-icon/specification.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/woly/atoms/button-icon/specification.mdx b/src/woly/atoms/button-icon/specification.mdx index 8fb97ffd..24597317 100644 --- a/src/woly/atoms/button-icon/specification.mdx +++ b/src/woly/atoms/button-icon/specification.mdx @@ -5,6 +5,7 @@ **Recommended to use** - to trigger an action on an item, for example, to delete, to change, or add an element within a group; often comes with another 2 or 3 adjacent `ButtonIcon`. +- to switch between two actions. One of the actions is always active, one is inactive ( e.g., "Like" icon-button). **Not recommended using** @@ -42,7 +43,7 @@ Users can trigger a button by clicking anywhere within the button container. _Keyboard_ -Users can trigger a button by pressing `Enter` while it has focus. +Users can trigger a button by pressing `Enter` or `Space`, while it has focus. ## Accessibility From c71f27a2ae36923bb0b3df3e506b96d0c461b56d 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?= Date: Wed, 7 Jul 2021 12:17:48 +0300 Subject: [PATCH 3/6] =?UTF-8?q?docs(woly/button-icon):=20specification=20?= =?UTF-8?q?=E2=80=93=20changes=20in=20'Overview',=20'Placement'=20and=20'B?= =?UTF-8?q?ehaviors'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/woly/atoms/button-icon/specification.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/woly/atoms/button-icon/specification.mdx b/src/woly/atoms/button-icon/specification.mdx index 24597317..f2346e4f 100644 --- a/src/woly/atoms/button-icon/specification.mdx +++ b/src/woly/atoms/button-icon/specification.mdx @@ -5,7 +5,7 @@ **Recommended to use** - to trigger an action on an item, for example, to delete, to change, or add an element within a group; often comes with another 2 or 3 adjacent `ButtonIcon`. -- to switch between two actions. One of the actions is always active, one is inactive ( e.g., "Like" icon-button). +- to switch between two actions. One of the actions is always active, one is inactive ( e.g., "Like" icon-button, 'Hamburger' menu button). Offten comes with transtion animation betweet active and inactive states. **Not recommended using** @@ -27,11 +27,11 @@ Recommendations for a hint text: ### Grouping -If `ButtonIcon`s share related actions, they’re good to be in a group. For example, in a list of items (users, products, blog posts), each item can have a group of `ButtonIcon`s with actions like `delete`, `edit`, `move`. In most cases, all buttons within a group should have the same priority, weight and size. But it does not limit you to make one particular button with the main action as `primary` and with weight `fill` then make other buttons as `secondary` and weight `outline`. +If `ButtonIcon`s share related actions, they’re good to be in a group. For example, in a list of items (users, products, blog posts), each item can have a group of `ButtonIcon`s with actions like `delete`, `edit`, `move`. Or app toolbars, containing a groups of button-icons with most offten used actions. In most cases, all buttons within a group should have the same priority, weight and size. But it does not limit you to make one particular button with the main action as `primary` and with weight `fill` then make other buttons as `secondary` and weight `outline`. ### Inside other components -`ButtonIcon` can be used as a part of a more complex component, like a hide/show toggle in the `InputPassword` component. Here, `ButtonIcon` should have the same `priority` and `weight` as its parent for consistency. +`ButtonIcon` can be used as a part of a more complex component, like a hide/show toggle in the `InputPassword` or remove button in `Chip`. Here, `ButtonIcon` should have the same `priority` as its parent for consistency. ## Behaviors @@ -43,7 +43,7 @@ Users can trigger a button by clicking anywhere within the button container. _Keyboard_ -Users can trigger a button by pressing `Enter` or `Space`, while it has focus. +Users can trigger a button by pressing `Enter` or `Space`, while it has focus. If the `ButtonIcon` is located in the toolbar for quick access, you should provide a keyboard shortcut for even easier access. ## Accessibility From 32d7ec7381c9032ef2e94b6191a747ddd6b760b4 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?= Date: Wed, 7 Jul 2021 12:20:09 +0300 Subject: [PATCH 4/6] =?UTF-8?q?docs(woly/button-icon):=20specification=20?= =?UTF-8?q?=E2=80=93=20typo=20in=20'Overview'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/woly/atoms/button-icon/specification.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/woly/atoms/button-icon/specification.mdx b/src/woly/atoms/button-icon/specification.mdx index f2346e4f..df6506cb 100644 --- a/src/woly/atoms/button-icon/specification.mdx +++ b/src/woly/atoms/button-icon/specification.mdx @@ -5,7 +5,7 @@ **Recommended to use** - to trigger an action on an item, for example, to delete, to change, or add an element within a group; often comes with another 2 or 3 adjacent `ButtonIcon`. -- to switch between two actions. One of the actions is always active, one is inactive ( e.g., "Like" icon-button, 'Hamburger' menu button). Offten comes with transtion animation betweet active and inactive states. +- to switch between two actions. One of the actions is always active, another is inactive ( e.g., "Like" icon-button, 'Hamburger' menu button). Often comes with transition animation between these two states. **Not recommended using** From 9e64276f54f854a8c0cb5ccbea507e34bdd2bdab 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?= Date: Thu, 8 Jul 2021 23:00:18 +0300 Subject: [PATCH 5/6] refactor: corrections --- src/woly/atoms/button-icon/specification.mdx | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/woly/atoms/button-icon/specification.mdx b/src/woly/atoms/button-icon/specification.mdx index df6506cb..7acd5c36 100644 --- a/src/woly/atoms/button-icon/specification.mdx +++ b/src/woly/atoms/button-icon/specification.mdx @@ -16,12 +16,9 @@ ### Icon -Since the `ButtonIcon` has no label and therefore compact, it is commonly used in an interface where extra space matters. Its icon should be easily recognizable. You may pair `ButtonIcon` with a component `Tooltip` containing a hint about the `ButtonIcon` underlying action. +Since the `ButtonIcon` has no label and therefore compact, it is commonly used in an interface where extra space matters. Icon button has no text that tells the user the purpose of the button, thats why its important that icon should be easily recognizable. You may pair `ButtonIcon` with a component `Tooltip` containing a hint about the `ButtonIcon` underlying action. -Recommendations for a hint text: - -- make it short (2-3 words); -- use “action” verbs first ( “save”, “send”, etc.); +### Weight and priority ## Placement @@ -35,6 +32,8 @@ If `ButtonIcon`s share related actions, they’re good to be in a group. For exa ## Behaviors +### States + ### Interactions _Mouse_ @@ -43,7 +42,7 @@ Users can trigger a button by clicking anywhere within the button container. _Keyboard_ -Users can trigger a button by pressing `Enter` or `Space`, while it has focus. If the `ButtonIcon` is located in the toolbar for quick access, you should provide a keyboard shortcut for even easier access. +Users can trigger a button by pressing `Enter` or `Space`, while it has focus and is not disabled. If the `ButtonIcon` is located in the toolbar, you should provide a keyboard shortcut for easier access. ## Accessibility From 07f202a11384a47c61b2e4a123174d1825881be0 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?= Date: Thu, 15 Jul 2021 12:57:46 +0300 Subject: [PATCH 6/6] refactor: update some sections --- src/woly/atoms/button-icon/specification.mdx | 24 +++++++++++++++----- 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/src/woly/atoms/button-icon/specification.mdx b/src/woly/atoms/button-icon/specification.mdx index 7acd5c36..fc044b80 100644 --- a/src/woly/atoms/button-icon/specification.mdx +++ b/src/woly/atoms/button-icon/specification.mdx @@ -4,36 +4,48 @@ **Recommended to use** -- to trigger an action on an item, for example, to delete, to change, or add an element within a group; often comes with another 2 or 3 adjacent `ButtonIcon`. -- to switch between two actions. One of the actions is always active, another is inactive ( e.g., "Like" icon-button, 'Hamburger' menu button). Often comes with transition animation between these two states. +- to trigger an action that takes effect immediately without additional input. These buttons are either grouped and placed in a distinguishable interface frame or container and their actions affect globally (e.g. toolbars, toolbox), or placed right next to an object on which the action is performed (e.g. list item, which we can remove, edit, make favorite, etc.). +- to switch between two actions. One of the actions is always active, another is inactive ( e.g., "favorite", "hamburger"). Icons of such buttons have a different appearance for their states (e.g., different shape, fill color, transition animation) **Not recommended using** -- to trigger actions that could influence the user’s flow, like submitting a form (use `Button` instead); +- to trigger actions that could influence the user’s flow, like submitting a form, because `ButtonIcon` can't have a primary action in the current user scenario (use `Button` instead); - to navigate a user to another page or an external web resource (use a link instead); ## Appearance ### Icon -Since the `ButtonIcon` has no label and therefore compact, it is commonly used in an interface where extra space matters. Icon button has no text that tells the user the purpose of the button, thats why its important that icon should be easily recognizable. You may pair `ButtonIcon` with a component `Tooltip` containing a hint about the `ButtonIcon` underlying action. +`ButtonIcon` has no label, that would clarify its meaning in that particular context, and all responsibility for this task is placed on the icon. Some icons are fairly fast to recognize at a glance, icons for home, print, and the magnifying glass for search are such instances. Outside of these examples, most icons continue to be ambiguous to users due to their association with different meanings across various interfaces. That's why it's important to make icon easily recognizable and have a meaning that corresponds to the action performed by the `ButtonIcon`. To help overcome the ambiguity that almost all icons face, you may pair `ButtonIcon` with a component `Tooltip` containing a hint about the `ButtonIcon` underlying action. ### Weight and priority +Styles are primarily used to differentiate more important actions from less important ones. Create a hierarchy of actions that will guide the user where there are multitudes of choices. You can do it by changing the button's priority and weight. Usually, you can have a single prominent button (that style is often called "primary"), and several medium "secondary" and low emphasis "tertiary" actions ('default' priority). + ## Placement +Put buttons where users expect to find them. Buttons should be located in places where users can easily find them or expect to see them. Don’t make users hunt for buttons. If users can’t find a button, they won’t know that it exists. + ### Grouping -If `ButtonIcon`s share related actions, they’re good to be in a group. For example, in a list of items (users, products, blog posts), each item can have a group of `ButtonIcon`s with actions like `delete`, `edit`, `move`. Or app toolbars, containing a groups of button-icons with most offten used actions. In most cases, all buttons within a group should have the same priority, weight and size. But it does not limit you to make one particular button with the main action as `primary` and with weight `fill` then make other buttons as `secondary` and weight `outline`. +If `ButtonIcon`s share related actions, they’re good to be in a group and should be placed either globally (toolbar, toolbox, etc) or next to an object on which the action is performed. In most cases, all buttons within a group should have the same priority, weight, and size. But it does not limit you to make one particular button with the main action as `primary` and others as `secondary`. ### Inside other components -`ButtonIcon` can be used as a part of a more complex component, like a hide/show toggle in the `InputPassword` or remove button in `Chip`. Here, `ButtonIcon` should have the same `priority` as its parent for consistency. +`ButtonIcon` can be used as a part of a more complex component, like a hide/show toggle in the `InputPassword` or remove button in `Chip`. It's recommended to place `ButtonIcon` on the right side after component's content and match its `priority` with its parent for consistency. ## Behaviors ### States +`ButtonIcon` has a common set of states for an interactive element: + +- **normal** — communicates that component is interactive and enabled. +- **focus** — communicates that the user has highlighted an element, using a keyboard or other input method. +- **hover** — communicates when a user has placed a cursor above an interactive element. +- **active** — or pressed state communicates that the user had tapped on the button. +- **disabled** — communicates that component is currently noninteractive but can be enabled in the future. + ### Interactions _Mouse_