Add Button design guidelines (#621)

packages/web-ui/src/components/Button/Button.guidelines.mdx

@@ -0,0 +1,272 @@
+import { Meta, Canvas } from '@storybook/blocks';
+
+import * as Stories from './Button.stories';
+
+import { BackToTop } from '../../storybook-components/BackToTop';
+import { Heading } from '../Heading';
+
+<Meta title="Web UI / Design Guidelines / Button" />
+<BackToTop />
+
+<Heading variant="h1">Button Design Guidelines</Heading>
+
+The Button component is highly flexible, and features various style variants,
+colorSchemes, and other configurations to adapt to a wide range of design use
+cases and compositions.
+
+- [Accessibility](#accessibility)
+- [Variants](#variants)
+- [Colour Schemes](#colour-schemes)
+- [Inverted](#inverted)
+- [Size](#size)
+- [State](#state)
+- [Icons](#icons)
+- [Autolayout config (Figma only)](#autolayout-config-figma-only)
+- [Best Practices](#best-practices)
+- [Customisation and overrides](#customisation-and-overrides)
+
+## Accessibility
+
+- **If it does something it's a button, if it goes somewhere it's a link.**
+- If you need help deciding which component works best for your content, please refer to the [global usage guidelines](https://wiki.uw.systems/posts/buttons-links-and-icon-buttons-guidelines-fs09gshh).
+- All buttons, except solid cyan, meet WCAG AA colour contrast standards on a white background.
+- Text within a button is also crucial for [accessibility and usability](https://wiki.uw.systems/posts/buttons-links-and-icon-buttons-guidelines-fs09gshh).
+
+## Variants
+
+Buttons, like many other components, come in pre-designed variants. For more
+information on style variant concepts, refer to the [naming convention doc](https://wiki.uw.systems/posts/naming-conventions-and-stack-mirroring-z1olqysr#hco7u-variants).
+
+The Button component offers a set of variants to address a wide variety of use
+cases. Each variant provides control over its appearance, including elements
+like borders, background colour, and foreground colours.
+
+The choice of Button variant depends on several factors:
+
+- Where does the button appear in the user flow?
+- The importance of the action within that context
+- How does the button interact with other elements on the screen?
+
+### Solid
+
+Solid Buttons are ideal for primary actions in screens or compositions that
+require high visual emphasis. Their appearance creates a strong presence,
+making them perfect for highlighting the main action especially when combined
+with other Button variants to create a clear visual hierarchy within a
+composition.
+
+Solid buttons are ideal for submitting data in forms, such as
+submitting an application or finalising a purchase.
+
+<Canvas of={Stories.SolidVariantDesignExample} sourceState="none" />
+
+### Outline
+
+Outline Buttons offer a moderate level of emphasis, making them suitable for
+secondary or non-critical actions like "Cancel" or "Edit." To enhance the
+meaning and purpose of the action further, these buttons can be combined with
+any colorScheme from our design system.
+
+<Canvas of={Stories.OutlineVariantDesignExample} sourceState="none" />
+
+### Ghost
+
+Ghost buttons are a subtle button variant designed to have a low visual presence compared to other Button variants.
+
+Ghost buttons start out with a transparent look, only becoming fully visible when a user interacts with them.
+Typical use cases of the ghost variant are:
+
+- Suitable for actions that are less important than the primary one on a screen:
+- Ghost buttons excel at complementing solid and outlined Buttons by providing additional actions without overwhelming users.
+- Their simple design makes them ideal as building blocks for other UI components that require user interaction, such as Input, Tiles, Calendar, etc.
+
+To enhance the meaning and purpose of the action further, these buttons can be combined with any colorScheme from our design system.
+
+<Canvas of={Stories.GhostVariantDesignExample} sourceState="none" />
+
+## Colour Schemes
+
+The `colorScheme` prop determines the colours applied to the Button component.
+These colour schemes are visually defined within the design system, and not all
+Button variants support every available colour scheme as they are tailored to
+specific use cases.
+
+Choosing a colour scheme that aligns with the intended meaning of the user
+action (e.g. success, warning) can enhance the user experience. If no
+colour scheme is specified, the default scheme is cyan.
+
+The choice of colour scheme and button variant depends on several factors:
+
+- The context in which the button is used.
+- How critical is the action triggered by the button.
+- The importance of the action within that context.
+- The relationship between the Button and other elements in the composition.
+
+To learn more about the colour schemes please refer to the
+[naming conventions document](https://wiki.uw.systems/posts/naming-conventions-and-stack-mirroring-z1olqysr#hz3pw-color-schemes).
+
+### Cyan
+
+**By default, cyan is used for primary actions to signify their importance.**
+
+However, it's important to remember that different visual weight and hierarchy
+in a composition can be achieved using button variants. Depending on
+the hierarchy of the action within the context of your design, you may want to
+consider using a different button variant to either emphasise or de-emphasise
+the importance of an action.
+
+<Canvas of={Stories.CyanColorSchemeDesignExample} sourceState="none" />
+
+### Red
+
+**Red is the most suitable button colour scheme for destructive actions.**
+
+These actions can result in data loss, are irreversible, or have significant
+negative consequences for the user. The red colour serves as a strong visual
+warning, prompting users to carefully consider such actions due to their
+potential impact.
+
+**The importance and potential consequences of a destructive action can be
+further emphasised, or reduced, depending on the impact and context of your
+design.**
+
+This can be achieved by using different button variants in relation to other
+actions. For instance, a solid red button might be used for a highly
+destructive action, while a red ghost Button, or a red outline Button could be
+used for a less impactful one.
+
+<Canvas of={Stories.RedColorSchemeDesignExample} sourceState="none" />
+
+### Green
+
+**Green is a great choice when you want to signal positive or affirmative actions.**
+
+Green effectively draws attention to actions that confirm or approve something
+in your design. However, consider using different button variants depending on
+the context. These variants can emphasise or reduce the importance of the
+positive action and help highlight the most crucial action for the user.
+
+<Canvas of={Stories.GreenColorSchemeDesignExample} sourceState="none" />
+
+### Gold
+
+**Gold buttons are often used for actions that require user attention or careful
+consideration. They serve as a visual cue for users to proceed with caution.**
+
+However, gold buttons don't convey the same level of urgency or potential
+consequences as red buttons. Since their primary function is to complement
+other UI elements, they typically don't have a solid variant like other button
+types used for primary actions. You could also see them in the context of a
+form.
+
+<Canvas of={Stories.GoldColorSchemeDesignExample} sourceState="none" />
+
+### Grey
+
+**Grey buttons excel at providing subtle calls to action when you want the button
+to blend in with the background and not compete for attention with other design
+elements.**
+
+This approach is particularly useful in colour-heavy designs or when
+you want to emphasise other elements or actions in your design. For example,
+grey buttons can be used for secondary actions or as building blocks within
+other UI components.
+
+<Canvas of={Stories.GreyColorSchemeDesignExample} sourceState="none" />
+
+## Inverted
+
+The inverted property is a boolean value. Setting it to true triggers an
+inversion of the original colorScheme of the Button. In essence, if the
+original colour scheme was optimised for a light background, the inverted
+property will adjust the button's colours to function effectively on a darker
+background.
+
+To learn more about inverted colour schemes in components please refer to the
+[naming conventions document](https://wiki.uw.systems/posts/naming-conventions-and-stack-mirroring-z1olqysr#hz3pw-color-schemes).
+
+<Canvas of={Stories.InvertedColour} sourceState="none" />
+
+## Size
+
+The size prop helps you create a clear hierarchy and guide users towards the
+most important actions in your design layout. All button variants and colour
+schemes can be used with various sizes, giving you maximum flexibility.
+
+<Canvas of={Stories.Sizes} sourceState="none" />
+
+### Small
+
+Small buttons are perfect for subtle interactions, allowing you to offer
+additional functionality without overwhelming users with prominent calls to
+action.
+
+### Medium
+
+Medium buttons are best for emphasising crucial actions. They
+effectively grab user attention, making them ideal for situations where a
+specific action is the core function of a page or a large section. As the
+default size, medium buttons strike a perfect balance between prominence,
+usability, and provide a comfortable target area for touch interactions.
+
+## State
+
+Buttons have different states to provide visual feedback to users and indicate interaction possibilities.
+
+- In Figma, properties represent different states of a component (e.g., hover, focus).
+- In code, interactive components have built-in states that can be styled (e.g., active, disabled).
+
+| State    | Description                                                                                                                                                                                                                                                               |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Default  | This is the button's resting state when the user isn't interacting with it.                                                                                                                                                                                               |
+| Hover    | When the user hovers their mouse cursor over the button, it enters the hover state.                                                                                                                                                                                       |
+| Active   | The active state is triggered when the user activates the button. When using a mouse, "activation" typically starts when the user presses down the primary mouse button. This state visually indicates that the button is being pressed and an action is about to happen. |
+| Focus    | This state applies when the user navigates to the button using the keyboard's Tab key, and it becomes the currently focused element.                                                                                                                                      |
+| Disabled | This state is used when a button action is unavailable or not applicable in the current context. Disabled buttons do not respond to hover or click states, but are still focusable via the keyboard.                                                                      |
+
+## Icons
+
+Icons can sometimes serve as visual shortcuts, supporting the button text and
+helping users to identify the button's function and the anticipated result of
+clicking it.
+
+Each icon prop (iconLeft and iconRight) offers customization options for the
+button's appearance. It is important to note that due to design limitations,
+you can only choose to have an icon positioned either to the left or right of
+the button text, not both.
+
+**If you have to use a button with only an icon, please use the Icon Button component.**
+
+<Canvas of={Stories.WithIcons} sourceState="none" />
+
+## Autolayout config (Figma only)
+
+Buttons in Figma have built-in auto-layout capabilities that allow you to
+easily adjust their size to fit your design needs.
+
+**Hug Content** - By default, buttons use the "Hug Content" layout, where the
+button width automatically adapts to the width of its text content.
+
+**Full-Width Buttons** - You can create full-width buttons, typically
+recommended for large sizes. To achieve this:
+
+- Select the button frame.
+- In the Properties panel (right-hand side), locate the "Layout" section.
+- Under "Sizing," change the option from "Hug Content" to "Fill Container".
+- Ensure the button is placed within a container frame set to either "Fixed" or "Hug Content" layout/container.
+
+## Best Practices
+
+- For clarity, use clear and concise Button text that accurately reflects the action it triggers.
+- Provide visual hierarchy; use button sizes, colours, and variants according to importance and meaning.
+- Avoid overwhelming users with too many buttons, this can lead to confusion and decision fatigue.
+
+## Customisation and overrides
+
+The buttons offer a diverse range of sizes, variants, and colour schemes,
+catering to a multitude of design scenarios. **It's important to remember that
+these options address core functionalities, and may not encompass every unique
+design need or context.** Since the button designs dictate properties like
+colour usage, **local overrides are generally discouraged**. If you encounter
+design limitations or believe a new button variant or size is necessary, please
+don't hesitate to share your feedback with the Design Systems team.