From 3e49884b5aa08fbc1c6b0ae3cf71874ec87d204a Mon Sep 17 00:00:00 2001 From: Rene Pot Date: Mon, 4 Mar 2024 16:23:50 +0100 Subject: [PATCH] docs: improved ui docs --- docs/docs/components/button.md | 51 +++++++++++- docs/docs/components/calendar.md | 136 ++++++++++++++++++++++--------- docs/docs/components/card.md | 4 + 3 files changed, 153 insertions(+), 38 deletions(-) diff --git a/docs/docs/components/button.md b/docs/docs/components/button.md index 4f71631b3f..b5e9881a7b 100644 --- a/docs/docs/components/button.md +++ b/docs/docs/components/button.md @@ -11,7 +11,7 @@ import API from '../../../components/button/API.md' Buttons are used to trigger actions. There are different button variants that are used for different types of actions. - + ## Usage @@ -41,6 +41,10 @@ Buttons are used to trigger actions. There are different button variants that ar +```jsx + +``` + - A `basic` button is the default button to use. It suits the majority of use cases. - Don't use a `basic` button for the most important action on the page. Use `primary` instead. @@ -50,6 +54,10 @@ Buttons are used to trigger actions. There are different button variants that ar +```jsx + +``` + - Only use for the most important action on a page, like _Save data_ in a form. - Only use one `primary` button per page, otherwise it's not clear what the main action is. - A page doesn't need to have a `primary` button if there isn't a clear main action. @@ -60,6 +68,10 @@ Buttons are used to trigger actions. There are different button variants that ar +```jsx + +``` + - Use for actions that are used less often. Using `secondary` buttons reduces amount of elements on a page competing for a user's attention. - Use as a passive alternative to `primary` actions, like _Cancel_ as a passive alternative to _Save_. - Don't use if there's only one action on the page. @@ -73,6 +85,13 @@ Buttons are used to trigger actions. There are different button variants that ar +```jsx +
+ + +
+``` + - Only use for primary-type actions that will destroy data. - Don't use if the action will only remove an item from the current context. - Only use a one `destructive` button per page. @@ -109,6 +128,10 @@ Buttons are available in different sizes. Use the size that matches the usage gu Dropdown button +```jsx +Dropdown button +``` + - A dropdown button offers several actions in a small space. Clicking the button opens a menu with several actions. - Use to replace a group of buttons where space is limited. - A dropdown button label should make it clear there are more options inside, like _Actions_. @@ -119,6 +142,10 @@ Buttons are available in different sizes. Use the size that matches the usage gu Split button +```jsx +Split button +``` + - A split button offers a main action and a dropdown of several other actions. Clicking the main button triggers an action. Clicking the split arrow opens a menu with several actions. - Use when there is a main action and several secondary actions, like a main action of _Save_ and secondary actions of _Save and add another_ and _Save and open_. - Use when space is limited. Otherwise, show buttons for all the actions. @@ -133,6 +160,13 @@ Buttons are available in different sizes. Use the size that matches the usage gu +```jsx +
+ + +
+``` + - Represents an on/off state. - Use a toggle button when an option can be turned on or off, and a checkbox ==link== isn't suitable, like in a toolbar. - Toggle buttons can be used with `basic` and `secondary` variants. @@ -147,6 +181,13 @@ Buttons are available in different sizes. Use the size that matches the usage gu +```jsx +
+ + +
+``` + - Buttons can have an optional icon alongside the text label. - Buttons can show only an icon. - Icons with a text label are useful for providing more information about the action. Users scanning an interface might recognize an icon quicker than text. @@ -159,6 +200,10 @@ Buttons are available in different sizes. Use the size that matches the usage gu +```jsx + +``` + - Use a disabled state when the button action can't be triggered. - Show a tooltip ==link== on hover, or help text, that tells the user why the action can't be triggered. - Don't change the button label between disabled and enabled states. @@ -170,6 +215,10 @@ Buttons are available in different sizes. Use the size that matches the usage gu +```jsx + +``` + - Use a loading state after a user triggers that button. - Change the button label to tell the user what's happening. For example, after clicking a _Start job_ button, the loading state label could be _Starting job…_. - If triggering other actions on the page should be prevented, consider showing a blocking loader ==link== instead. diff --git a/docs/docs/components/calendar.md b/docs/docs/components/calendar.md index 52a86da41c..4f01edf93b 100644 --- a/docs/docs/components/calendar.md +++ b/docs/docs/components/calendar.md @@ -18,55 +18,117 @@ Here are some sample calendars built with this UI component. Check [StoryBook](( ## Ethiopic calendar -Ethiopic calendar (with narrow day names, short day names and localised to English) +Ethiopic calendar with narrow day names, short day names and localised to English. You can see all three calendars below with their respective code blocks. + +### Narrow day names -
- - - -
+ + + +```jsx + +``` + +### Short day names + + + +```jsx + +``` + +### English day names + + + + + +```jsx + +``` + ## Nepali calendar Nepali calendar (with Nepali and English characters) -> Nepali is a custom calendar not natively implemented in Temporal and Nepali locale is not natively supported by browsers' Internationalization standard. We are providing a custom implementation for the calendar, as well as the localised values. The only two locales allowed are: `ne-NP` (nepali) and `en-NP` (nepali transliterated in latin characters). +:::note +Nepali is a custom calendar not natively implemented in Temporal and Nepali locale is not natively supported by browsers' Internationalization standard. We are providing a custom implementation for the calendar, as well as the localised values. The only two locales allowed are: `ne-NP` (nepali) and `en-NP` (nepali transliterated in latin characters). +::: + +### Nepali -
- - -
+ +```jsx + +``` + +### Transliterated in latin characters + + + + +```jsx + +``` + ## Gregorian calendar Gregorian calendar localised in English, Arabic (Tunisia), Arabic (Sudan), Arabic (Iraq) and Amharic. diff --git a/docs/docs/components/card.md b/docs/docs/components/card.md index f12545c50f..0086c505d1 100644 --- a/docs/docs/components/card.md +++ b/docs/docs/components/card.md @@ -17,6 +17,10 @@ A card is a container element used to group together and separate blocks of cont ## Usage +```jsx +This is content that's inside a card. +``` + ### When to use - **Group content**. Use a card as a container for related content. When there's different areas of content on a page, a card helps to establish boundaries between them.