From 966881a7da447f034c1a050a3603885339695abe Mon Sep 17 00:00:00 2001 From: leksaBoiko <168754213+leksaBoiko@users.noreply.github.com> Date: Tue, 23 Jul 2024 13:40:14 +0300 Subject: [PATCH] docs(pie-docs): DSW-2220 add overview page and assets (#1605) * docs(pie-docs): DSW-2220 add overview page and assets * fix(pie-docs): DSW-2220 correct a typo * docs(pie-docs): DSW-2220 change alt text * Update changeset file Co-authored-by: Ashley Watson-Nolan * Update list item Co-authored-by: Xander Marjoram * Apply suggestions from code review Co-authored-by: Xander Marjoram --------- Co-authored-by: Ashley Watson-Nolan Co-authored-by: Xander Marjoram --- .changeset/afraid-chairs-develop.md | 5 + .../img/components/checkbox/anatomy.svg | 14 + .../checkbox/checkbox-LTR-agreement.svg | 20 ++ .../checkbox/checkbox-RTL-agreement.svg | 20 ++ .../components/checkbox/checkbox-active.svg | 4 + .../checkbox/checkbox-checked-LTR.svg | 7 + .../checkbox/checkbox-checked-RTL.svg | 7 + .../components/checkbox/checkbox-default.svg | 4 + .../components/checkbox/checkbox-disabled.svg | 4 + .../components/checkbox/checkbox-error.svg | 14 + .../components/checkbox/checkbox-focused.svg | 7 + .../components/checkbox/checkbox-hovered.svg | 4 + .../checkbox/checkbox-interaction.svg | 5 + .../checkbox/checkbox-label-interaction.svg | 5 + .../checkbox/checkbox-partially-selected.svg | 12 + .../components/checkbox/checkbox-selected.svg | 5 + .../checkbox/checkbox-unselected.svg | 4 + .../checkbox/checkbox-with-assistive-text.svg | 14 + .../img/components/checkbox/checkbox.svg | 3 + .../img/components/checkbox/overflow.svg | 4 + .../img/components/checkbox/overview.svg | 35 +-- .../src/components/checkbox/checkbox.json | 2 +- .../src/components/checkbox/checkbox.md | 26 +- .../components/checkbox/overview/overview.md | 297 ++++++++++++++++++ 24 files changed, 475 insertions(+), 47 deletions(-) create mode 100644 .changeset/afraid-chairs-develop.md create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/anatomy.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-LTR-agreement.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-RTL-agreement.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-active.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-checked-LTR.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-checked-RTL.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-default.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-disabled.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-error.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-focused.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-hovered.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-interaction.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-label-interaction.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-partially-selected.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-selected.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-unselected.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox-with-assistive-text.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/checkbox.svg create mode 100644 apps/pie-docs/src/assets/img/components/checkbox/overflow.svg create mode 100644 apps/pie-docs/src/components/checkbox/overview/overview.md diff --git a/.changeset/afraid-chairs-develop.md b/.changeset/afraid-chairs-develop.md new file mode 100644 index 0000000000..ece675ea4c --- /dev/null +++ b/.changeset/afraid-chairs-develop.md @@ -0,0 +1,5 @@ +--- +"pie-docs": minor +--- + +[Added] - Checkbox overview page diff --git a/apps/pie-docs/src/assets/img/components/checkbox/anatomy.svg b/apps/pie-docs/src/assets/img/components/checkbox/anatomy.svg new file mode 100644 index 0000000000..a7e8465811 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/anatomy.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-LTR-agreement.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-LTR-agreement.svg new file mode 100644 index 0000000000..3029d273c7 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-LTR-agreement.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-RTL-agreement.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-RTL-agreement.svg new file mode 100644 index 0000000000..0b63ca1d33 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-RTL-agreement.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-active.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-active.svg new file mode 100644 index 0000000000..f187a7dc60 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-active.svg @@ -0,0 +1,4 @@ + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-checked-LTR.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-checked-LTR.svg new file mode 100644 index 0000000000..86f3a48b25 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-checked-LTR.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-checked-RTL.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-checked-RTL.svg new file mode 100644 index 0000000000..46afa2f22f --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-checked-RTL.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-default.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-default.svg new file mode 100644 index 0000000000..0f73c70a9a --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-default.svg @@ -0,0 +1,4 @@ + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-disabled.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-disabled.svg new file mode 100644 index 0000000000..d2affe85cb --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-disabled.svg @@ -0,0 +1,4 @@ + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-error.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-error.svg new file mode 100644 index 0000000000..6577115950 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-error.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-focused.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-focused.svg new file mode 100644 index 0000000000..3626196af6 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-focused.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-hovered.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-hovered.svg new file mode 100644 index 0000000000..36a6cc8fe2 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-hovered.svg @@ -0,0 +1,4 @@ + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-interaction.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-interaction.svg new file mode 100644 index 0000000000..81b5d42d5f --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-interaction.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-label-interaction.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-label-interaction.svg new file mode 100644 index 0000000000..b75e9520f4 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-label-interaction.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-partially-selected.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-partially-selected.svg new file mode 100644 index 0000000000..5a474b04c4 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-partially-selected.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-selected.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-selected.svg new file mode 100644 index 0000000000..8911df9e23 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-selected.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-unselected.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-unselected.svg new file mode 100644 index 0000000000..1ea0d12a3d --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-unselected.svg @@ -0,0 +1,4 @@ + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox-with-assistive-text.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-with-assistive-text.svg new file mode 100644 index 0000000000..739dfc33b5 --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox-with-assistive-text.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/checkbox.svg b/apps/pie-docs/src/assets/img/components/checkbox/checkbox.svg new file mode 100644 index 0000000000..c1edbb0bbf --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/checkbox.svg @@ -0,0 +1,3 @@ + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/overflow.svg b/apps/pie-docs/src/assets/img/components/checkbox/overflow.svg new file mode 100644 index 0000000000..e5427eb3be --- /dev/null +++ b/apps/pie-docs/src/assets/img/components/checkbox/overflow.svg @@ -0,0 +1,4 @@ + + + + diff --git a/apps/pie-docs/src/assets/img/components/checkbox/overview.svg b/apps/pie-docs/src/assets/img/components/checkbox/overview.svg index aba2738d27..436c93fe7d 100644 --- a/apps/pie-docs/src/assets/img/components/checkbox/overview.svg +++ b/apps/pie-docs/src/assets/img/components/checkbox/overview.svg @@ -1,32 +1,23 @@ - - - + + + - - - + + + - - - - - - - - - - - - - - + + + + + - + - + diff --git a/apps/pie-docs/src/components/checkbox/checkbox.json b/apps/pie-docs/src/components/checkbox/checkbox.json index 056307cab4..b93d371021 100644 --- a/apps/pie-docs/src/components/checkbox/checkbox.json +++ b/apps/pie-docs/src/components/checkbox/checkbox.json @@ -1,5 +1,5 @@ { "title": "Checkbox", "navKey": "Checkbox", - "description": "A checkbox is an interactive element that allows users to select or deselect options from a list of choices." + "description": "A checkbox is an interactive element that allows users to select or deselect an option." } diff --git a/apps/pie-docs/src/components/checkbox/checkbox.md b/apps/pie-docs/src/components/checkbox/checkbox.md index a838e9f41b..88fea999f6 100644 --- a/apps/pie-docs/src/components/checkbox/checkbox.md +++ b/apps/pie-docs/src/components/checkbox/checkbox.md @@ -2,30 +2,8 @@ eleventyNavigation: key: 'Checkbox' parent: Components + url: /components/checkbox/ order: 12 +permalink: false --- -## Overview - -Checkboxes provide a binary selection mechanism where users can either check the box to indicate they want a particular option or leave it unchecked to indicate they do not want that option. - -They are commonly used in forms, settings panels, and various other interfaces where users need to make multiple selections or provide input from a predefined set of options. - - -{% contentPageImage { - src:"../../assets/img/components/checkbox/overview.svg", - alt: "A group of checkboxes vertically stacked together." -} %} - ---- - -## Resources - -{% notification { - type: "warning", - message: "We’re currently working on updating our Checkbox documentation, please see the resources below." -} %} - -{% resourceTable { - componentName: 'Checkbox' -} %} diff --git a/apps/pie-docs/src/components/checkbox/overview/overview.md b/apps/pie-docs/src/components/checkbox/overview/overview.md new file mode 100644 index 0000000000..638152addd --- /dev/null +++ b/apps/pie-docs/src/components/checkbox/overview/overview.md @@ -0,0 +1,297 @@ +--- +eleventyNavigation: + key: Overview + parent: 'Checkbox' + order: 1 +shouldShowContents: true +permalink: components/checkbox/ +--- + +## Overview + +Checkboxes provide a binary selection mechanism where users can either check the box to indicate they want a particular option or leave it unchecked to indicate they do not want that option. + +They are commonly used in forms, settings panels, and various other interfaces where users need to make a single selection. + +{% contentPageImage { + src:"../../../assets/img/components/checkbox/overview.svg", + alt: "Checkbox labeled 'I have read and accepted the terms and conditions' is checked." +} %} + +--- + +## Dos and Don’ts + +{% usage { + do: { + type: usageTypes.text, + items: [ + "Make sure labels are concise and that they clearly describe what checking the box means." + ] + }, + dont: { + type: usageTypes.text, + items: [ + "If multiple checkboxes are needed, use a checkbox group." + ] + } +} %} + +--- + +## Anatomy + +{% contentPageImage { + src:"../../../assets/img/components/checkbox/anatomy.svg", + alt: "Anatomy of a checkbox component.", + width: "84px" +} %} + +{% list { + type: listTypes.ordered, + items: [ + "**Checkbox input:** A checkbox input indicates the appropriate state. By default it is unselected.", + "**Label (Optional):** Describes the information you want to select or unselect.", + "**Assistive text (Optional):** The [assistive text](/components/assistive-text/) provides additional instructional information / error / success messaging." + ] +} %} + +--- + +## Variations + +### Default + +{% contentPageImage { + src:"../../../assets/img/components/checkbox/checkbox-default.svg", + alt: "Checkbox component in a default state.", + width: "70px" +} %} + +--- + +## Modifiers + +### Label + +A label should always be present unless being utilised as a nested component and an alternative label is present. + +{% contentLayout %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-default.svg", + width: "70px", + alt: "A blank checkbox followed by the label text." + } %} + {% endcontentItem %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox.svg", + width: "24px", + alt: "A blank checkbox component." + } %} + {% endcontentItem %} +{% endcontentLayout %} + +### Assistive text + +Assistive text is used where needed to provide additional information or error / success messaging. The assistive text is always used for an error state to provide the user with the information required to complete the form element. + +{% contentPageImage { + src:"../../../assets/img/components/checkbox/checkbox-with-assistive-text.svg", + alt: "A blank checkbox followed by assistive text in red below it.", + width: "112px" +} %} + +--- + +## Content + +All content should use sentence case. + +### Label + +- Always use clear and concise labels for checkboxes. +- Labels appear to the right of checkbox input (when the text direction is left-to-right). + +--- + +## Overflow + +### Multiple words overflow + +When the label exceeds the available width, the label will wrap onto a new line. + +{% contentPageImage { + src:"../../../assets/img/components/checkbox/overflow.svg", + alt: "A blank checkbox followed by the label that exceeds the available width and wraps onto a new line.", + width: "281px" +} %} + +--- + +## Behaviours + +### States + +The checkbox input allows for a series of three states: unselected, selected, and partially selected. The default state for a checkbox is unselected. + +Use the partially selected state when the checkbox contains a sublist of selections, some of which are selected, and some unselected. + +{% contentLayout %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-unselected.svg", + width: "112px", + alt: "Checkbox component in a selected state." + } %} + {% endcontentItem %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-selected.svg", + width: "94px", + alt: "Checkbox component in an unselected state." + } %} + {% endcontentItem %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-partially-selected.svg", + width: "154px", + alt: "Checkbox component in a partially selected state." + } %} + {% endcontentItem %} +{% endcontentLayout %} + +--- + +## Interactions + +Users can trigger the checkbox directly or by clicking the checkbox label. Having all regions interactive creates a more accessible click target. + +{% contentLayout %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-interaction.svg", + width: "70px", + alt: "An illustration represents that users can trigger the checkbox directly." + } %} + {% endcontentItem %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-label-interaction.svg", + width: "70px", + alt: "An illustration represents that users can trigger the checkbox by clicking the checkbox label. " + } %} + {% endcontentItem %} +{% endcontentLayout %} + +--- + +## Interactive states + +Outlines the atomic level interactive elements for the component. + +{% contentLayout %} + {% contentItem %} +

Default

+ {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-default.svg", + width: "70px", + alt: "Checkbox component in a default state." + } %} + {% endcontentItem %} + {% contentItem %} +

Hover

+ {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-hovered.svg", + width: "70px", + alt: "Checkbox component when hovered over." + } %} + {% endcontentItem %} + {% contentItem %} +

Active

+ {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-active.svg", + width: "70px", + alt: "Checkbox component in an active state." + } %} + {% endcontentItem %} + {% contentItem %} +

Focus

+ {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-focused.svg", + width: "70px", + alt: "Checkbox component when it has focus." + } %} + {% endcontentItem %} + {% contentItem %} +

Disabled

+ {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-disabled.svg", + width: "70px", + alt: "Checkbox component in a disabled state." + } %} + {% endcontentItem %} + {% contentItem %} +

Error

+ {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-error.svg", + width: "112px", + alt: "Checkbox state example showing an error." + } %} + {% endcontentItem %} +{% endcontentLayout %} + +--- + +## Examples + +### LTR examples + +Here are some examples of the component in a left-to-right context: + +{% contentLayout %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-LTR-agreement.svg", + width: "375px", + alt: "Checkbox labeled 'I have read and accepted the terms and conditions' in a left-to-right context." + } %} + {% endcontentItem %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-checked-LTR.svg", + width: "360px", + alt: "Selected checkbox followed by the label text in a left-to-right context." + } %} + {% endcontentItem %} +{% endcontentLayout %} + +### RTL examples + +Here are some examples of the component in a right-to-left context: + +{% contentLayout %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-RTL-agreement.svg", + width: "271px", + alt: "Checkbox labeled 'I have read and accepted the terms and conditions' in a right-to-left context." + } %} + {% endcontentItem %} + {% contentItem %} + {% contentPageImage { + src: "../../../assets/img/components/checkbox/checkbox-checked-RTL.svg", + width: "360px", + alt: "Selected checkbox followed by the label text in a right-to-left context." + } %} + {% endcontentItem %} +{% endcontentLayout %} + +--- + +## Resources + +{% resourceTable { + componentName: 'Checkbox' +} %}