From acc260a5f56af13bc227fab434f4d491c1d866d4 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Tue, 4 Apr 2023 12:22:02 +0200 Subject: [PATCH 1/7] feat(DocsTemplate): add DocsTemplate mdx to storybook --- src/stories/Introduction.mdx | 211 -------------------------------- src/stories/ui/DocsTemplate.mdx | 55 +++++++++ 2 files changed, 55 insertions(+), 211 deletions(-) delete mode 100644 src/stories/Introduction.mdx create mode 100644 src/stories/ui/DocsTemplate.mdx diff --git a/src/stories/Introduction.mdx b/src/stories/Introduction.mdx deleted file mode 100644 index a314fa7f4..000000000 --- a/src/stories/Introduction.mdx +++ /dev/null @@ -1,211 +0,0 @@ -import { Meta } from '@storybook/blocks'; -import Code from './assets/code-brackets.svg'; -import Colors from './assets/colors.svg'; -import Comments from './assets/comments.svg'; -import Direction from './assets/direction.svg'; -import Flow from './assets/flow.svg'; -import Plugin from './assets/plugin.svg'; -import Repo from './assets/repo.svg'; -import StackAlt from './assets/stackalt.svg'; - - - - - -# Welcome to Storybook - -Storybook helps you build UI components in isolation from your app's business logic, data, and context. -That makes it easy to develop hard-to-reach states. Save these UI states as **stories** to revisit during development, testing, or QA. - -Browse example stories now by navigating to them in the sidebar. -View their code in the `stories` directory to learn how they work. -We recommend building UIs with a [**component-driven**](https://componentdriven.org) process starting with atomic components and ending with pages. - -
Configure
- -
- - plugin - - Presets for popular tools - Easy setup for TypeScript, SCSS and more. - - - - Build - - Build configuration - How to customize webpack and Babel - - - - colors - - Styling - How to load and configure CSS libraries - - - - flow - - Data - Providers and mocking for data libraries - - -
- -
Learn
- -
- - repo - - Storybook documentation - Configure, customize, and extend - - - - direction - - In-depth guides - Best practices from leading teams - - - - code - - GitHub project - View the source and add issues - - - - comments - - Discord chat - Chat with maintainers and the community - - -
- -
- TipEdit the Markdown in{' '} - stories/Introduction.stories.mdx -
diff --git a/src/stories/ui/DocsTemplate.mdx b/src/stories/ui/DocsTemplate.mdx new file mode 100644 index 000000000..b8a29aabe --- /dev/null +++ b/src/stories/ui/DocsTemplate.mdx @@ -0,0 +1,55 @@ +import { Meta, Controls, Canvas } from '@storybook/blocks'; + +{/* 👇 Replace by */} + + +# ComponentName + +This is the description of the `ComponentName` component. + +{/* */} + +## Props + +{/* */} + +## Usage guidelines + +These are the general usage guidelines, they can be listed. + +- Usage rule 1 +- Usage rule 2 + +## Variants + +### Variant 1 + +{/* */} + +### Variant 2 + +{/* */} + +## Use cases + +### Use case 1 + +{/* */} + +### Use case 2 + +{/* */} + +## SASS variables + +``` +Include here the SASS variables that can be overrided to customize the component. + +Eg.: + +$dv-primary-text-color +$dv-primary-text-shadow-color +$dv-primary-background-color +$dv-primary-background-color-disabled +$dv-primary-border-color +``` \ No newline at end of file From dd3832c6cf8d4d3446b202add228a02d1308b2fa Mon Sep 17 00:00:00 2001 From: MellyGray Date: Tue, 4 Apr 2023 13:06:31 +0200 Subject: [PATCH 2/7] fix(docs): apply docs template to all existing stories --- src/stories/ui/DocsTemplate.mdx | 18 +++++++--- src/stories/ui/button/Button.mdx | 28 ++++++++++----- src/stories/ui/button/Button.stories.tsx | 8 +++++ .../ui/dropdown-button/DropdownButton.mdx | 31 ++++++++++++++++ .../DropdownButton.stories.tsx | 35 ++++++++++++++++++- 5 files changed, 106 insertions(+), 14 deletions(-) diff --git a/src/stories/ui/DocsTemplate.mdx b/src/stories/ui/DocsTemplate.mdx index b8a29aabe..071d68258 100644 --- a/src/stories/ui/DocsTemplate.mdx +++ b/src/stories/ui/DocsTemplate.mdx @@ -5,7 +5,8 @@ import { Meta, Controls, Canvas } from '@storybook/blocks'; # ComponentName -This is the description of the `ComponentName` component. +This is the description of the `ComponentName` component. This template is only necessary for the elements of the design +system inside the UI folder. {/* */} @@ -15,18 +16,27 @@ This is the description of the `ComponentName` component. ## Usage guidelines -These are the general usage guidelines, they can be listed. +These are the general usage guidelines, they can be listed here. For variant specific usage guidelines you can write them +in the variants section. -- Usage rule 1 -- Usage rule 2 +### Dos +- Do usage rule 1 +- Do usage rule 1 + +### Don'ts + +- Don't usage rule 1 +- Don't usage rule 2 ## Variants ### Variant 1 +Here you can include the specific usage guidelines. {/* */} ### Variant 2 +Here you can include the specific usage guidelines. {/* */} diff --git a/src/stories/ui/button/Button.mdx b/src/stories/ui/button/Button.mdx index ab944db0e..f46b89b41 100644 --- a/src/stories/ui/button/Button.mdx +++ b/src/stories/ui/button/Button.mdx @@ -17,11 +17,19 @@ a dialog box, or initiating a process. -## Usage +## Usage guidelines -### General +### Dos +- Button labels: + - Concise + - Should include a verb + - Always include a noun if there is any room for interpretation about what the verb operates on +- For action buttons on a page, we include an icon and text label. -Button width is set by its content. Avoid changing its width. +### Don'ts + +- Button width is set by its content. Avoid changing its width. +- Do not use a button for a text link or navigation item like breadcrumbs. ## Variants @@ -63,12 +71,6 @@ like a link because the usage is very similar. E.g.: "Read More" or "Learn More" -## Variants - -## Usage examples - -Note that unless specified, examples with multiple buttons have `withSpacing` set to true. - ### Basic (enabled, no icon) @@ -85,6 +87,14 @@ Note that unless specified, examples with multiple buttons have `withSpacing` se +## Use cases + +Note that unless specified, examples with multiple buttons have `withSpacing` set to true. + +### Primary button for Call To Action + + + ### Secondary button to cancel diff --git a/src/stories/ui/button/Button.stories.tsx b/src/stories/ui/button/Button.stories.tsx index fdb2f6e14..9514f201b 100644 --- a/src/stories/ui/button/Button.stories.tsx +++ b/src/stories/ui/button/Button.stories.tsx @@ -81,6 +81,14 @@ export const WithIcon: Story = { render: () => } +export const PrimaryAsCTA: Story = { + render: () => ( + <> + + + ) +} + export const SecondaryAsAltOption: Story = { render: () => ( <> diff --git a/src/stories/ui/dropdown-button/DropdownButton.mdx b/src/stories/ui/dropdown-button/DropdownButton.mdx index 199dc45cb..31d45f744 100644 --- a/src/stories/ui/dropdown-button/DropdownButton.mdx +++ b/src/stories/ui/dropdown-button/DropdownButton.mdx @@ -18,16 +18,47 @@ of options is too large to display at once. +## Usage guidelines +Use dropdowns for a list of related options and try to keep the list short. + +### Dos +- Use the dropdown as a navigation tool to goto a href related to the dropdown title + +### Don'ts + +- Use the dropdown as a select input + ## Variants ### All variants at a glance +### Primary dropdown + +The primary dropdown should be used for the main or most important actions in the user interface. + +Use only one primary dropdown. Any remaining calls to action should be represented as variants with lower emphasis. + + + +### Secondary dropdown + +The secondary dropdown should be used to provide additional options or actions to the user that are not as critical or +urgent as the primary actions. + + + ### With Icon +## Use cases + +### Navigation + + + ## SASS variables ``` diff --git a/src/stories/ui/dropdown-button/DropdownButton.stories.tsx b/src/stories/ui/dropdown-button/DropdownButton.stories.tsx index 154c15343..b809c5be0 100644 --- a/src/stories/ui/dropdown-button/DropdownButton.stories.tsx +++ b/src/stories/ui/dropdown-button/DropdownButton.stories.tsx @@ -43,12 +43,36 @@ export const Variants: Story = { ) } +export const Primary: Story = { + render: () => ( + <> + + Item 1 + Item 2 + Item 3 + + + ) +} + +export const Secondary: Story = { + render: () => ( + <> + + Item 1 + Item 2 + Item 3 + + + ) +} + export const WithIcon: Story = { render: () => ( Item 1 @@ -57,3 +81,12 @@ export const WithIcon: Story = { ) } + +export const Navigation: Story = { + render: () => ( + + Users + Products + + ) +} From 81ca5ac96d049b5db5162ba69dc9e8e4403de387 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Tue, 4 Apr 2023 14:46:58 +0200 Subject: [PATCH 3/7] fix(Navbar): add docs with mdx template --- src/stories/ui/CanvasFixedHeight.tsx | 10 ++++ src/stories/ui/DocsTemplate.mdx | 12 ++--- src/stories/ui/navbar/Navbar.mdx | 38 +++++++++++++++ src/stories/ui/navbar/Navbar.stories.tsx | 61 +++++++++++++++--------- 4 files changed, 93 insertions(+), 28 deletions(-) create mode 100644 src/stories/ui/CanvasFixedHeight.tsx create mode 100644 src/stories/ui/navbar/Navbar.mdx diff --git a/src/stories/ui/CanvasFixedHeight.tsx b/src/stories/ui/CanvasFixedHeight.tsx new file mode 100644 index 000000000..dc32cf84a --- /dev/null +++ b/src/stories/ui/CanvasFixedHeight.tsx @@ -0,0 +1,10 @@ +import { ReactNode } from 'react' + +interface CanvasFixedHeight { + height: number + children: ReactNode +} + +export function CanvasFixedHeight({ height, children }: CanvasFixedHeight) { + return
{children}
+} diff --git a/src/stories/ui/DocsTemplate.mdx b/src/stories/ui/DocsTemplate.mdx index 071d68258..5a422bbb5 100644 --- a/src/stories/ui/DocsTemplate.mdx +++ b/src/stories/ui/DocsTemplate.mdx @@ -1,6 +1,6 @@ import { Meta, Controls, Canvas } from '@storybook/blocks'; -{/* 👇 Replace by */} +{/* 👇 Replace by */} # ComponentName @@ -8,7 +8,7 @@ import { Meta, Controls, Canvas } from '@storybook/blocks'; This is the description of the `ComponentName` component. This template is only necessary for the elements of the design system inside the UI folder. -{/* */} +{/* */} ## Props @@ -33,22 +33,22 @@ in the variants section. ### Variant 1 Here you can include the specific usage guidelines. -{/* */} +{/* */} ### Variant 2 Here you can include the specific usage guidelines. -{/* */} +{/* */} ## Use cases ### Use case 1 -{/* */} +{/* */} ### Use case 2 -{/* */} +{/* */} ## SASS variables diff --git a/src/stories/ui/navbar/Navbar.mdx b/src/stories/ui/navbar/Navbar.mdx new file mode 100644 index 000000000..a54605a30 --- /dev/null +++ b/src/stories/ui/navbar/Navbar.mdx @@ -0,0 +1,38 @@ +import { Meta, Controls, Canvas } from '@storybook/blocks'; +import * as NavbarStories from './Navbar.stories'; + + + +# Navbar + +The navbar component is a user interface element that typically appears at the top of a website or application. Its main +purpose is to provide users with easy access to the main sections and features of the website or application. + + + +## Props + + + +## Usage guidelines + +The text used in the component should be concise and meaningful, and the component should be organized in a logical way +to make it easy for users to find what they are looking for. + +## Variants + +### Default + + + +## Use cases + +### Website Menu + + + +## SASS variables + +``` +$dv-brand-color +``` \ No newline at end of file diff --git a/src/stories/ui/navbar/Navbar.stories.tsx b/src/stories/ui/navbar/Navbar.stories.tsx index 51b499a76..1d2dbef19 100644 --- a/src/stories/ui/navbar/Navbar.stories.tsx +++ b/src/stories/ui/navbar/Navbar.stories.tsx @@ -2,6 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react' import { WithI18next } from '../../WithI18next' import { Navbar } from '../../../sections/ui/navbar/Navbar' import logo from '../../../sections/ui/logo.svg' +import { CanvasFixedHeight } from '../CanvasFixedHeight' const meta: Meta = { title: 'UI/Navbar', @@ -12,28 +13,44 @@ const meta: Meta = { export default meta type Story = StoryObj -export const Example: Story = { +export const Default: Story = { render: () => ( - + + + + ) +} + +export const Menu: Story = { + render: () => ( + + + ) } From 3fdff18e028397bc3393659236d93fc59912f9e2 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Tue, 4 Apr 2023 14:55:46 +0200 Subject: [PATCH 4/7] fix(Dropdown): fix canvas height in docs --- .../DropdownButton.stories.tsx | 57 +++++++++++-------- 1 file changed, 32 insertions(+), 25 deletions(-) diff --git a/src/stories/ui/dropdown-button/DropdownButton.stories.tsx b/src/stories/ui/dropdown-button/DropdownButton.stories.tsx index b809c5be0..8c40b5c19 100644 --- a/src/stories/ui/dropdown-button/DropdownButton.stories.tsx +++ b/src/stories/ui/dropdown-button/DropdownButton.stories.tsx @@ -2,6 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react' import { DropdownButton } from '../../../sections/ui/dropdown-button/DropdownButton' import { DropdownButtonItem } from '../../../sections/ui/dropdown-button/dropdown-button-item/DropdownButtonItem' import { Icon } from '../../../sections/ui/icon.enum' +import { CanvasFixedHeight } from '../CanvasFixedHeight' const meta: Meta = { title: 'UI/Dropdown Button', @@ -13,17 +14,19 @@ type Story = StoryObj export const Default: Story = { render: () => ( - - Item 1 - Item 2 - Item 3 - + + + Item 1 + Item 2 + Item 3 + + ) } export const Variants: Story = { render: () => ( - <> + Item 1 Item 2 @@ -39,54 +42,58 @@ export const Variants: Story = { Item 2 Item 3 - + ) } export const Primary: Story = { render: () => ( - <> + Item 1 Item 2 Item 3 - + ) } export const Secondary: Story = { render: () => ( - <> + Item 1 Item 2 Item 3 - + ) } export const WithIcon: Story = { render: () => ( - - Item 1 - Item 2 - Item 3 - + + + Item 1 + Item 2 + Item 3 + + ) } export const Navigation: Story = { render: () => ( - - Users - Products - + + + Users + Products + + ) } From d0cdd21768ee18e20d07b9893007ed4fcc0111e6 Mon Sep 17 00:00:00 2001 From: MellyGray Date: Mon, 10 Apr 2023 17:17:39 +0200 Subject: [PATCH 5/7] feat: Replace docs template by an automated docs template --- .storybook/{preview.ts => preview.tsx} | 4 ++ src/stories/ui/DocsTemplate.mdx | 65 ------------------------ src/stories/ui/DocumentationTemplate.mdx | 18 +++++++ src/stories/ui/grid/Grid.stories.tsx | 18 +++++-- 4 files changed, 37 insertions(+), 68 deletions(-) rename .storybook/{preview.ts => preview.tsx} (70%) delete mode 100644 src/stories/ui/DocsTemplate.mdx create mode 100644 src/stories/ui/DocumentationTemplate.mdx diff --git a/.storybook/preview.ts b/.storybook/preview.tsx similarity index 70% rename from .storybook/preview.ts rename to .storybook/preview.tsx index 9d75b4b27..61ab250f9 100644 --- a/.storybook/preview.ts +++ b/.storybook/preview.tsx @@ -1,5 +1,6 @@ import type { Preview } from '@storybook/react' import '../src/assets/styles/index.scss' +import DocumentationTemplate from '../src/stories/ui/DocumentationTemplate.mdx' const preview: Preview = { parameters: { @@ -9,6 +10,9 @@ const preview: Preview = { color: /(background|color)$/i, date: /Date$/ } + }, + docs: { + page: DocumentationTemplate } } } diff --git a/src/stories/ui/DocsTemplate.mdx b/src/stories/ui/DocsTemplate.mdx deleted file mode 100644 index 5a422bbb5..000000000 --- a/src/stories/ui/DocsTemplate.mdx +++ /dev/null @@ -1,65 +0,0 @@ -import { Meta, Controls, Canvas } from '@storybook/blocks'; - -{/* 👇 Replace by */} - - -# ComponentName - -This is the description of the `ComponentName` component. This template is only necessary for the elements of the design -system inside the UI folder. - -{/* */} - -## Props - -{/* */} - -## Usage guidelines - -These are the general usage guidelines, they can be listed here. For variant specific usage guidelines you can write them -in the variants section. - -### Dos -- Do usage rule 1 -- Do usage rule 1 - -### Don'ts - -- Don't usage rule 1 -- Don't usage rule 2 - -## Variants - -### Variant 1 -Here you can include the specific usage guidelines. - -{/* */} - -### Variant 2 -Here you can include the specific usage guidelines. - -{/* */} - -## Use cases - -### Use case 1 - -{/* */} - -### Use case 2 - -{/* */} - -## SASS variables - -``` -Include here the SASS variables that can be overrided to customize the component. - -Eg.: - -$dv-primary-text-color -$dv-primary-text-shadow-color -$dv-primary-background-color -$dv-primary-background-color-disabled -$dv-primary-border-color -``` \ No newline at end of file diff --git a/src/stories/ui/DocumentationTemplate.mdx b/src/stories/ui/DocumentationTemplate.mdx new file mode 100644 index 000000000..5af08d021 --- /dev/null +++ b/src/stories/ui/DocumentationTemplate.mdx @@ -0,0 +1,18 @@ +import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks'; + + + + + +<Primary /> + +<Description /> + +## Props + +The component accepts the following inputs (props): +<Controls /> + +## Variants + +<Stories /> diff --git a/src/stories/ui/grid/Grid.stories.tsx b/src/stories/ui/grid/Grid.stories.tsx index a92a8dd72..6c575829f 100644 --- a/src/stories/ui/grid/Grid.stories.tsx +++ b/src/stories/ui/grid/Grid.stories.tsx @@ -4,10 +4,22 @@ import { WithI18next } from '../../WithI18next' import { Col } from '../../../sections/ui/grid/col/Col' import { Row } from '../../../sections/ui/grid/row/Row' +/** + * ## Description + * Grid system for the layout of the page + * It is based on a 12-column system, using Bootstrap's grid system underneath. + * + * ## Usage guidelines + * + * Bootstrap provides a responsive, fluid, 12-column grid system that we use to organize our page layouts. + * + * We use the fixed-width Container component which provides responsive widths based on media queries for the page + * layout, with a series of rows and columns for the content. + * + * The grid layout uses Col component for horizontal groups of columns, inside a Row containing component. Content + * should be placed within columns, and only columns may be immediate children of rows. + */ const meta: Meta<typeof Container> = { - /* Grid system for the layout of the page - * It is based on a 12-column system, using Bootstrap's grid system underneath. - */ tags: ['autodocs'], title: 'UI/Grid', component: Container, From 3e0b8a0db2d4088c50a166cd6c63a46312abcdd9 Mon Sep 17 00:00:00 2001 From: MellyGray <melinaabril@gmail.com> Date: Mon, 10 Apr 2023 17:36:23 +0200 Subject: [PATCH 6/7] fix: replace Nabvar docs by autogenerated docs --- src/stories/ui/DocumentationTemplate.mdx | 4 +-- src/stories/ui/navbar/Navbar.mdx | 38 ------------------------ src/stories/ui/navbar/Navbar.stories.tsx | 27 +++++++++++++++-- 3 files changed, 26 insertions(+), 43 deletions(-) delete mode 100644 src/stories/ui/navbar/Navbar.mdx diff --git a/src/stories/ui/DocumentationTemplate.mdx b/src/stories/ui/DocumentationTemplate.mdx index 5af08d021..54a15bac7 100644 --- a/src/stories/ui/DocumentationTemplate.mdx +++ b/src/stories/ui/DocumentationTemplate.mdx @@ -13,6 +13,4 @@ import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook The component accepts the following inputs (props): <Controls /> -## Variants - -<Stories /> +<Stories title="Variants" /> diff --git a/src/stories/ui/navbar/Navbar.mdx b/src/stories/ui/navbar/Navbar.mdx deleted file mode 100644 index a54605a30..000000000 --- a/src/stories/ui/navbar/Navbar.mdx +++ /dev/null @@ -1,38 +0,0 @@ -import { Meta, Controls, Canvas } from '@storybook/blocks'; -import * as NavbarStories from './Navbar.stories'; - -<Meta of={NavbarStories} /> - -# Navbar - -The navbar component is a user interface element that typically appears at the top of a website or application. Its main -purpose is to provide users with easy access to the main sections and features of the website or application. - -<Canvas of={NavbarStories.Default} /> - -## Props - -<Controls /> - -## Usage guidelines - -The text used in the component should be concise and meaningful, and the component should be organized in a logical way -to make it easy for users to find what they are looking for. - -## Variants - -### Default - -<Canvas of={NavbarStories.Default} /> - -## Use cases - -### Website Menu - -<Canvas of={NavbarStories.Menu} /> - -## SASS variables - -``` -$dv-brand-color -``` \ No newline at end of file diff --git a/src/stories/ui/navbar/Navbar.stories.tsx b/src/stories/ui/navbar/Navbar.stories.tsx index 1d2dbef19..fe08fcc31 100644 --- a/src/stories/ui/navbar/Navbar.stories.tsx +++ b/src/stories/ui/navbar/Navbar.stories.tsx @@ -4,10 +4,30 @@ import { Navbar } from '../../../sections/ui/navbar/Navbar' import logo from '../../../sections/ui/logo.svg' import { CanvasFixedHeight } from '../CanvasFixedHeight' +/** + * ## Description + * The navbar component is a user interface element that typically appears at the top of a website or application. Its main + * purpose is to provide users with easy access to the main sections and features of the website or application. + * + * ## Usage guidelines + * + * The text used in the component should be concise and meaningful, and the component should be organized in a logical way + * to make it easy for users to find what they are looking for. + * + * ## SASS variables + * + * ``` + * + * $dv-brand-color + * + * ``` + * + */ const meta: Meta<typeof Navbar> = { title: 'UI/Navbar', component: Navbar, - decorators: [WithI18next] + decorators: [WithI18next], + tags: ['autodocs'] } export default meta @@ -41,7 +61,10 @@ export const Default: Story = { ) } -export const Menu: Story = { +/** + * This an example use case for a menu using the navbar component + */ +export const UseCaseMenu: Story = { render: () => ( <CanvasFixedHeight height={150}> <Navbar From 9d28dc40019a4cd6fccb9a04615dbb2310b5ce57 Mon Sep 17 00:00:00 2001 From: MellyGray <melinaabril@gmail.com> Date: Mon, 10 Apr 2023 17:54:01 +0200 Subject: [PATCH 7/7] fix: replace Button and dropdown docs by autogenerated docs --- src/stories/ui/button/Button.mdx | 113 ------------------ src/stories/ui/button/Button.stories.tsx | 78 ++++++++++-- .../ui/dropdown-button/DropdownButton.mdx | 76 ------------ .../DropdownButton.stories.tsx | 59 ++++++++- src/stories/ui/navbar/Navbar.stories.tsx | 1 + 5 files changed, 125 insertions(+), 202 deletions(-) delete mode 100644 src/stories/ui/button/Button.mdx delete mode 100644 src/stories/ui/dropdown-button/DropdownButton.mdx diff --git a/src/stories/ui/button/Button.mdx b/src/stories/ui/button/Button.mdx deleted file mode 100644 index 88e1ca13c..000000000 --- a/src/stories/ui/button/Button.mdx +++ /dev/null @@ -1,113 +0,0 @@ -import { Canvas, Meta, Controls } from '@storybook/blocks'; - -import * as ButtonStories from './Button.stories'; - -<Meta of={ButtonStories} /> - -# Button - -A button is a graphical control element that is used to trigger an action or event when the user clicks or taps on it. - -Buttons can be used to perform a wide variety of actions, such as submitting a form, navigating to a new page, opening -a dialog box, or initiating a process. - -<Canvas of={ButtonStories.Default} /> - -## Props - -<Controls /> - -## Usage guidelines - -### Dos -- Button labels: - - Concise - - Should include a verb - - Always include a noun if there is any room for interpretation about what the verb operates on -- For action buttons on a page, we include an icon and text label. - -### Don'ts - -- Button width is set by its content. Avoid changing its width. -- Do not use a button for a text link or navigation item like breadcrumbs. - -## Variants - -### All variants at a glance - -<Canvas of={ButtonStories.Variants} /> - -### Primary button - -The primary button should be used for the main or most important action in the user interface. Its purpose is to -encourage users to take a specific action, such as submitting a form or initiating a new task. - -Use only one primary button. Any remaining calls to action should be represented as variants with lower emphasis. - -<Canvas of={ButtonStories.Primary} /> - -### Secondary button - -The secondary button should be used to provide additional options or actions to the user that are not as critical or -urgent as the primary action. E.g.: "Cancel" or "Skip". - -Do not use the secondary button without being accompanied by a primary button. It should be the negative or alternative -action to the primary. - -<Canvas of={ButtonStories.Secondary} /> - -### Link - -The link button should be used as a secondary or tertiary button, or as a subtle call-to-action. Its purpose is to -draw attention to the button without being overly distracting, while also providing a clear call-to-action. It looks -like a link because the usage is very similar. E.g.: "Read More" or "Learn More". - -<Canvas of={ButtonStories.Link} /> - -### Basic (enabled, no icon) - -<Canvas of={ButtonStories.Variants} /> - -### Disabled - -<Canvas of={ButtonStories.Disabled} /> - -### No spacing - -<Canvas of={ButtonStories.NoSpacing} /> - -### With icon - -<Canvas of={ButtonStories.WithIcon} /> - -## Use cases - -Note that unless specified, examples with multiple buttons have `withSpacing` set to true. - -### Primary button for Call To Action - -<Canvas of={ButtonStories.PrimaryAsCTA} /> - -### Secondary button to cancel - -<Canvas of={ButtonStories.SecondaryAsAltOption} /> - -### Link button to learn more - -<Canvas of={ButtonStories.LinkButtonUsage} /> - -## SASS variables - -``` -$dv-primary-text-color -$dv-primary-text-shadow-color -$dv-primary-background-color -$dv-primary-background-color-disabled -$dv-primary-border-color - -$dv-secondary-text-color -$dv-secondary-text-shadow-color -$dv-secondary-background-color -$dv-secondary-background-color-disabled -$dv-secondary-border-color -``` \ No newline at end of file diff --git a/src/stories/ui/button/Button.stories.tsx b/src/stories/ui/button/Button.stories.tsx index 94ebfd396..631f78cd0 100644 --- a/src/stories/ui/button/Button.stories.tsx +++ b/src/stories/ui/button/Button.stories.tsx @@ -2,9 +2,47 @@ import type { Meta, StoryObj } from '@storybook/react' import { Button } from '../../../sections/ui/button/Button' import { Icon } from '../../../sections/ui/icon.enum' +/** + * ## Description + * A button is a graphical control element that is used to trigger an action or event when the user clicks or taps on it. + * + * Buttons can be used to perform a wide variety of actions, such as submitting a form, navigating to a new page, opening + * a dialog box, or initiating a process. + * + * ## Usage guidelines + * + * ### Dos + * - Button labels: + * - Concise + * - Should include a verb + * - Always include a noun if there is any room for interpretation about what the verb operates on + * - For action buttons on a page, we include an icon and text label. + * + * ### Don'ts + * + * - Button width is set by its content. Avoid changing its width. + * - Do not use a button for a text link or navigation item like breadcrumbs. + * + * ## SASS variables + * + * ``` + * $dv-primary-text-color + * $dv-primary-text-shadow-color + * $dv-primary-background-color + * $dv-primary-background-color-disabled + * $dv-primary-border-color + * + * $dv-secondary-text-color + * $dv-secondary-text-shadow-color + * $dv-secondary-background-color + * $dv-secondary-background-color-disabled + * $dv-secondary-border-color + * ``` + */ const meta: Meta<typeof Button> = { title: 'UI/Button', - component: Button + component: Button, + tags: ['autodocs'] } export default meta @@ -14,19 +52,40 @@ export const Default: Story = { render: () => <Button>Button</Button> } -export const Primary: Story = { +/** + * The primary button should be used for the main or most important action in the user interface. Its purpose is to + * encourage users to take a specific action, such as submitting a form or initiating a new task. + * + * Use only one primary button. Any remaining calls to action should be represented as variants with lower emphasis. + */ +export const PrimaryButton: Story = { render: () => <Button>Primary</Button> } -export const Secondary: Story = { +/** + * The secondary button should be used to provide additional options or actions to the user that are not as critical or + * urgent as the primary action. E.g.: "Cancel" or "Skip". + * + * Do not use the secondary button without being accompanied by a primary button. It should be the negative or alternative + * action to the primary. + */ +export const SecondaryButton: Story = { render: () => <Button variant="secondary">Secondary</Button> } -export const Link: Story = { +/** + * The link button should be used as a secondary or tertiary button, or as a subtle call-to-action. Its purpose is to + * draw attention to the button without being overly distracting, while also providing a clear call-to-action. It looks + * like a link because the usage is very similar. E.g.: "Read More" or "Learn More". + */ +export const LinkButton: Story = { render: () => <Button variant="link">Link</Button> } -export const Variants: Story = { +/** + * Note that unless specified, examples with multiple buttons have `withSpacing` set to true. + */ +export const AllVariantsAtAGlance: Story = { render: () => ( <> <Button withSpacing>Primary</Button> @@ -70,7 +129,8 @@ export const WithIcon: Story = { render: () => <Button icon={Icon.COLLECTION}>Primary</Button> } -export const PrimaryAsCTA: Story = { +export const UseCasePrimaryButtonAsCallToAction: Story = { + name: 'Example use case: Primary button as call-to-action', render: () => ( <> <Button>Publish</Button> @@ -78,7 +138,8 @@ export const PrimaryAsCTA: Story = { ) } -export const SecondaryAsAltOption: Story = { +export const UseCaseSecondaryButtonToCancel: Story = { + name: 'Example use case: Secondary button to cancel', render: () => ( <> <Button withSpacing>Continue</Button> @@ -89,7 +150,8 @@ export const SecondaryAsAltOption: Story = { ) } -export const LinkButtonUsage: Story = { +export const UseCaseLinkButtonToLearnMore: Story = { + name: 'Example use case: Link button to learn more', render: () => ( <> <Button withSpacing>Save</Button> diff --git a/src/stories/ui/dropdown-button/DropdownButton.mdx b/src/stories/ui/dropdown-button/DropdownButton.mdx deleted file mode 100644 index 31d45f744..000000000 --- a/src/stories/ui/dropdown-button/DropdownButton.mdx +++ /dev/null @@ -1,76 +0,0 @@ -import { Canvas, Meta, Controls } from '@storybook/blocks'; - -import * as DropdownButtonStories from './DropdownButton.stories'; - -<Meta of={DropdownButtonStories} /> - -# Dropdown Button - -A dropdown button is a graphical user interface element that displays a list of options when it is clicked. - -Dropdown buttons can be used to present a compact and organized set of choices to the user. They are -often used in forms, search bars, navigation menus, and other user interfaces where space is limited or where the number -of options is too large to display at once. - -<Canvas of={DropdownButtonStories.Default} /> - -## Props - -<Controls /> - -## Usage guidelines -Use dropdowns for a list of related options and try to keep the list short. - -### Dos -- Use the dropdown as a navigation tool to goto a href related to the dropdown title - -### Don'ts - -- Use the dropdown as a select input - -## Variants - -### All variants at a glance - -<Canvas of={DropdownButtonStories.Variants} /> - -### Primary dropdown - -The primary dropdown should be used for the main or most important actions in the user interface. - -Use only one primary dropdown. Any remaining calls to action should be represented as variants with lower emphasis. - -<Canvas of={DropdownButtonStories.Primary} /> - -### Secondary dropdown - -The secondary dropdown should be used to provide additional options or actions to the user that are not as critical or -urgent as the primary actions. - -<Canvas of={DropdownButtonStories.Secondary} /> - -### With Icon - -<Canvas of={DropdownButtonStories.WithIcon} /> - -## Use cases - -### Navigation - -<Canvas of={DropdownButtonStories.Navigation} /> - -## SASS variables - -``` -$dv-primary-text-color -$dv-primary-text-shadow-color -$dv-primary-background-color -$dv-primary-background-color-disabled -$dv-primary-border-color - -$dv-secondary-text-color -$dv-secondary-text-shadow-color -$dv-secondary-background-color -$dv-secondary-border-color -$dv-secondary-background-color-disabled -``` \ No newline at end of file diff --git a/src/stories/ui/dropdown-button/DropdownButton.stories.tsx b/src/stories/ui/dropdown-button/DropdownButton.stories.tsx index bec6788c2..b3fe43492 100644 --- a/src/stories/ui/dropdown-button/DropdownButton.stories.tsx +++ b/src/stories/ui/dropdown-button/DropdownButton.stories.tsx @@ -4,9 +4,45 @@ import { DropdownButtonItem } from '../../../sections/ui/dropdown-button/dropdow import { Icon } from '../../../sections/ui/icon.enum' import { CanvasFixedHeight } from '../CanvasFixedHeight' +/** + * ## Description + * A dropdown button is a graphical user interface element that displays a list of options when it is clicked. + * + * Dropdown buttons can be used to present a compact and organized set of choices to the user. They are + * often used in forms, search bars, navigation menus, and other user interfaces where space is limited or where the number + * of options is too large to display at once. + * + * ## Usage guidelines + * Use dropdowns for a list of related options and try to keep the list short. + * + * ### Dos + * - Use the dropdown as a navigation tool to goto a href related to the dropdown title + * + * ### Don'ts + * + * - Use the dropdown as a select input + * + * ## SASS variables + * + * ``` + * $dv-primary-text-color + * $dv-primary-text-shadow-color + * $dv-primary-background-color + * $dv-primary-background-color-disabled + * $dv-primary-border-color + * + * $dv-secondary-text-color + * $dv-secondary-text-shadow-color + * $dv-secondary-background-color + * $dv-secondary-border-color + * $dv-secondary-background-color-disabled + * ``` + */ + const meta: Meta<typeof DropdownButton> = { title: 'UI/Dropdown Button', - component: DropdownButton + component: DropdownButton, + tags: ['autodocs'] } export default meta @@ -24,7 +60,7 @@ export const Default: Story = { ) } -export const Variants: Story = { +export const AllVariantsAtAGlance: Story = { render: () => ( <CanvasFixedHeight height={150}> <DropdownButton withSpacing title="Primary" id="dropdown-1" variant="primary"> @@ -41,7 +77,12 @@ export const Variants: Story = { ) } -export const Primary: Story = { +/** + * The primary dropdown should be used for the main or most important actions in the user interface. + * + * Use only one primary dropdown. Any remaining calls to action should be represented as variants with lower emphasis. + */ +export const PrimaryDropdown: Story = { render: () => ( <CanvasFixedHeight height={150}> <DropdownButton title="Primary" id="dropdown-primary" variant="primary"> @@ -53,7 +94,11 @@ export const Primary: Story = { ) } -export const Secondary: Story = { +/** + * The secondary dropdown should be used to provide additional options or actions to the user that are not as critical or + * urgent as the primary actions. + */ +export const SecondaryDropdown: Story = { render: () => ( <CanvasFixedHeight height={150}> <DropdownButton title="Secondary" id="dropdown-secondary" variant="secondary"> @@ -82,7 +127,11 @@ export const WithIcon: Story = { ) } -export const Navigation: Story = { +/** + * This is an example use case for a navigation dropdown button. + */ +export const UseCaseNavigation: Story = { + name: 'Example use case: Navigation', render: () => ( <CanvasFixedHeight height={150}> <DropdownButton withSpacing title="Edit" id="dropdown-navigation" variant="primary"> diff --git a/src/stories/ui/navbar/Navbar.stories.tsx b/src/stories/ui/navbar/Navbar.stories.tsx index fe08fcc31..7860c6456 100644 --- a/src/stories/ui/navbar/Navbar.stories.tsx +++ b/src/stories/ui/navbar/Navbar.stories.tsx @@ -65,6 +65,7 @@ export const Default: Story = { * This an example use case for a menu using the navbar component */ export const UseCaseMenu: Story = { + name: 'Example use case: Menu', render: () => ( <CanvasFixedHeight height={150}> <Navbar