From d9670450356991879b22d22548978004ef7a840e Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Wed, 4 Sep 2024 14:26:02 +0200 Subject: [PATCH] chore: Improve headings and guidelines throughout documentation (#1565) Co-authored-by: Aram <37216945+alimpens@users.noreply.github.com> --- documentation/storybook.md | 5 +++- packages/css/src/components/avatar/README.md | 6 ++-- .../css/src/components/breadcrumb/README.md | 16 ++++------- packages/css/src/components/button/README.md | 2 ++ packages/css/src/components/field/README.md | 2 +- packages/css/src/components/footer/README.md | 8 +++--- packages/css/src/components/grid/README.md | 25 ++++++++--------- packages/css/src/components/header/README.md | 20 ++++++------- packages/css/src/components/label/README.md | 2 +- .../css/src/components/link-list/README.md | 5 ++-- packages/css/src/components/mark/README.md | 7 +---- .../css/src/components/ordered-list/README.md | 5 ++++ packages/css/src/components/screen/README.md | 16 +++++------ .../css/src/components/skip-link/README.md | 5 ---- .../css/src/components/spotlight/README.md | 2 +- packages/css/src/components/tabs/README.md | 4 ++- .../src/components/unordered-list/README.md | 6 ++++ .../components/Accordion/Accordion.docs.mdx | 12 ++++---- .../Accordion/Accordion.stories.tsx | 2 +- storybook/src/components/Alert/Alert.docs.mdx | 13 ++++----- .../AspectRatio/AspectRatio.docs.mdx | 14 ++++++---- .../src/components/Avatar/Avatar.docs.mdx | 12 ++++---- .../src/components/Avatar/Avatar.stories.tsx | 2 +- storybook/src/components/Badge/Badge.docs.mdx | 4 --- .../components/Breadcrumb/Breadcrumb.docs.mdx | 2 +- .../src/components/Button/Button.docs.mdx | 15 ++++------ storybook/src/components/Card/Card.docs.mdx | 6 ++-- .../CharacterCount/CharacterCount.docs.mdx | 4 ++- .../src/components/Column/Column.docs.mdx | 14 ++++------ .../src/components/Column/Column.stories.tsx | 2 +- .../DescriptionList/DescriptionList.docs.mdx | 4 ++- .../src/components/Dialog/Dialog.docs.mdx | 19 +++++++------ .../ErrorMessage/ErrorMessage.docs.mdx | 6 ++-- .../ErrorMessage/ErrorMessage.stories.tsx | 2 +- storybook/src/components/Field/Field.docs.mdx | 8 ++++-- .../src/components/FieldSet/FieldSet.docs.mdx | 6 ++-- .../components/FileInput/FileInput.docs.mdx | 8 +++--- .../FileInput/FileInput.stories.tsx | 4 +-- .../src/components/Footer/Footer.docs.mdx | 2 +- .../src/components/Footer/Footer.stories.tsx | 2 +- storybook/src/components/Grid/Grid.docs.mdx | 28 +++++++++---------- .../src/components/Grid/Grid.stories.tsx | 2 +- .../src/components/Header/Header.docs.mdx | 26 +++++++++-------- .../src/components/Header/Header.stories.tsx | 10 +++---- .../components/IconButton/IconButton.docs.mdx | 16 +++++------ storybook/src/components/Image/Image.docs.mdx | 8 +++--- storybook/src/components/Link/Link.docs.mdx | 6 ++-- .../src/components/LinkList/LinkList.docs.mdx | 19 +++++-------- storybook/src/components/Logo/Logo.docs.mdx | 12 ++++---- storybook/src/components/Mark/Mark.docs.mdx | 2 -- .../src/components/MegaMenu/MegaMenu.docs.mdx | 4 ++- .../OrderedList/OrderedList.docs.mdx | 23 ++++++--------- .../OrderedList/OrderedList.stories.tsx | 2 +- .../src/components/Overlap/Overlap.docs.mdx | 7 ++--- .../PageHeading/PageHeading.docs.mdx | 6 ++-- .../components/Paragraph/Paragraph.docs.mdx | 20 ++++++------- .../Paragraph/Paragraph.stories.tsx | 4 +-- storybook/src/components/Radio/Radio.docs.mdx | 2 +- storybook/src/components/Row/Row.docs.mdx | 8 ++---- .../src/components/Screen/Screen.docs.mdx | 4 ++- .../SearchField/SearchField.docs.mdx | 4 ++- .../src/components/Select/Select.docs.mdx | 12 ++++---- .../src/components/SkipLink/SkipLink.docs.mdx | 6 ++-- .../components/Spotlight/Spotlight.docs.mdx | 8 ++++-- .../Spotlight/Spotlight.stories.tsx | 2 +- .../TableOfContents/TableOfContents.docs.mdx | 6 ++-- .../TableOfContents.stories.tsx | 2 +- storybook/src/components/Tabs/Tabs.docs.mdx | 11 ++------ .../src/components/TextArea/TextArea.docs.mdx | 16 ++++++----- .../components/TimeInput/TimeInput.docs.mdx | 6 ++-- .../TopTaskLink/TopTaskLink.docs.mdx | 4 +-- .../TopTaskLink/TopTaskLink.stories.tsx | 2 +- .../UnorderedList/UnorderedList.docs.mdx | 20 +++++-------- .../UnorderedList/UnorderedList.stories.tsx | 2 +- .../src/docs/developer-guide/web-app.docs.mdx | 2 +- 75 files changed, 300 insertions(+), 311 deletions(-) diff --git a/documentation/storybook.md b/documentation/storybook.md index 630c570faf..00f7ad5d2d 100644 --- a/documentation/storybook.md +++ b/documentation/storybook.md @@ -16,7 +16,10 @@ The docs display: 3. The controls for the component, which displays all args for the component. 4. A canvas for every other story, each with an introduction. -We write our documentation in English, the stories are Dutch. +We write our documentation in English, the stories are in Dutch. + +All headings use sentence case. +Component names are in title case – starting each word with a capital letter – to make people recognise them as such. ## Best practices for controls diff --git a/packages/css/src/components/avatar/README.md b/packages/css/src/components/avatar/README.md index e27393b572..6c1e89a290 100644 --- a/packages/css/src/components/avatar/README.md +++ b/packages/css/src/components/avatar/README.md @@ -9,7 +9,7 @@ A circular badge representing a person. The avatar contains 1 or 2 initial letters from the person's full name, a picture, or a generic icon. The default background colour is dark blue. -## Usage +## Guidelines -Display an avatar for the person currently using the application, -or to associate a person with a content item. +- Display an avatar for the person currently using the application, + or to associate a person with a content item. diff --git a/packages/css/src/components/breadcrumb/README.md b/packages/css/src/components/breadcrumb/README.md index 757107d812..5e85233834 100644 --- a/packages/css/src/components/breadcrumb/README.md +++ b/packages/css/src/components/breadcrumb/README.md @@ -7,17 +7,11 @@ Users can use it to navigate. ## Guidelines -### Use like this - -Only use the breadcrumb trail if it adds something functional for the user and the structure is ‘static’. - -### Avoid this - -Do not display the breadcrumb trail on a form page. -It distracts the user from their task, or one can accidentally interpret it as a Progress Indicator. - -It is a secondary navigation pattern. -It can’t replace the main navigation. +- Only use the breadcrumb trail if it adds something functional for the user and the structure is ‘static’. +- Do not display the breadcrumb trail on a form page. + It distracts the user from their task, or one can accidentally interpret it as a Progress Indicator. +- This is a secondary navigation pattern. + It can’t replace the main navigation. ### Using links with routing libraries diff --git a/packages/css/src/components/button/README.md b/packages/css/src/components/button/README.md index 524f50a17d..435acf9402 100644 --- a/packages/css/src/components/button/README.md +++ b/packages/css/src/components/button/README.md @@ -11,6 +11,8 @@ Allows the user to perform actions and operate the user interface. - Use the correct type of button for the corresponding application. For example, a button within a form must always be of the type `submit`. - Make sure one can operate a button through a keyboard. +- Primary, secondary and tertiary buttons can be used side by side. + Skipping levels is allowed. ## Relevant WCAG requirements diff --git a/packages/css/src/components/field/README.md b/packages/css/src/components/field/README.md index 9f76f2e374..ac1a794f07 100644 --- a/packages/css/src/components/field/README.md +++ b/packages/css/src/components/field/README.md @@ -6,4 +6,4 @@ Wraps a single input and its related elements. May indicate that the input has a ## Guidelines -Only use Field to wrap a single input. Use [Field Set](/docs/components-forms-field-set--docs) to wrap multiple inputs. +- Only use Field to wrap a single input. Use [Field Set](/docs/components-forms-field-set--docs) to wrap multiple inputs. diff --git a/packages/css/src/components/footer/README.md b/packages/css/src/components/footer/README.md index 4c3600180a..48972e7fe1 100644 --- a/packages/css/src/components/footer/README.md +++ b/packages/css/src/components/footer/README.md @@ -6,10 +6,10 @@ Provides service information at the bottom of every page. ## Guidelines -The Footer consists of a dark blue [Spotlight](/docs/components-containers-spotlight--docs) and a [Page Menu](/docs/components-navigation-page-menu--docs). -It must be used on all websites for the City of Amsterdam. -For applications, only the Page Menu can be sufficient. -The Footer is the same on every page of the application. +- The Footer consists of a dark blue [Spotlight](/docs/components-containers-spotlight--docs) and a [Page Menu](/docs/components-navigation-page-menu--docs). + It must be used on all websites for the City of Amsterdam. +- For applications, only the Page Menu can be sufficient. +- The Footer is the same on every page of the application. The Spotlight offers space for various practical links: diff --git a/packages/css/src/components/grid/README.md b/packages/css/src/components/grid/README.md index 17f541da97..97eba5b83a 100644 --- a/packages/css/src/components/grid/README.md +++ b/packages/css/src/components/grid/README.md @@ -4,20 +4,17 @@ Divides the screen into columns to align the elements of a page. -## Usage - -Every page should use the grid as the foundation for its layout. -It is placed directly within the [Screen](/docs/components-layout-screen--docs). - -A [Footer](/docs/components-containers-footer--docs) and a [Spotlight](/docs/components-containers-spotlight--docs) are slightly wider than the grid. -You close one instance of the grid before these components. -Inside and optionally after them, you start a new one. -Multiple instances of the grid component are possible on a page, but the columns of all grids must align precisely. - -Within the grid, you create cells containing the desired content. -A cell often spans multiple columns of the grid. - -The Gap utility classes must not be used on the Grid component. +## Guidelines + +- Every page should use the grid as the foundation for its layout. + It is placed directly within the [Screen](/docs/components-layout-screen--docs). +- A [Footer](/docs/components-containers-footer--docs) and a [Spotlight](/docs/components-containers-spotlight--docs) are slightly wider than the grid. + You close one instance of the grid before these components. + Inside and optionally after them, you start a new one. + Multiple instances of the grid component are possible on a page, but the columns of all grids must align precisely. +- Within the grid, you create cells containing the desired content. + A cell often spans multiple columns of the grid. +- The Gap utility classes must not be used on the Grid component. ## Design diff --git a/packages/css/src/components/header/README.md b/packages/css/src/components/header/README.md index 2ae0df58f2..78e1e0f28d 100644 --- a/packages/css/src/components/header/README.md +++ b/packages/css/src/components/header/README.md @@ -7,17 +7,15 @@ Includes the name of the application if it is not the general website. ## Guidelines -The Header must be used on all websites and applications for the City of Amsterdam. -It includes the logo of the City or the organization, the site title (except for the general website), and a menu with links to commonly used pages. - -The Header is important because it conveys our corporate identity and is the first thing people see. -Using it consistently helps users recognize and trust the website. -It is the same on every page of the application. - -The page menu can contain a maximum of 5 items. -The last two will often be ‘Search’ and ‘Menu’. -Labels should be short to ensure the menu fits on one line, even on medium-wide screens. -An icon can be added to the end of a link to make its function easier to find. +- The Header must be used on all websites and applications for the City of Amsterdam. +- It includes the logo of the City or the organization, the site title (except for the general website), and a menu with links to commonly used pages. +- The Header is important because it conveys our corporate identity and is the first thing people see. + Using it consistently helps users recognize and trust the website. +- It is the same on every page of the application. +- The page menu can contain a maximum of 5 items. + The last two will often be ‘Search’ and ‘Menu’. +- Labels should be short to ensure the menu fits on one line, even on medium-wide screens. +- An icon can be added to the end of a link to make its function easier to find. ## References diff --git a/packages/css/src/components/label/README.md b/packages/css/src/components/label/README.md index 7851a28de1..de933e4df7 100644 --- a/packages/css/src/components/label/README.md +++ b/packages/css/src/components/label/README.md @@ -6,4 +6,4 @@ Describes a form control. ## Guidelines -Always associate a form element (such as an `input` or `textarea`) with a label. +- Always associate a form element (such as an `input` or `textarea`) with a label. diff --git a/packages/css/src/components/link-list/README.md b/packages/css/src/components/link-list/README.md index 0a9a56fb4c..cf84c2daa7 100644 --- a/packages/css/src/components/link-list/README.md +++ b/packages/css/src/components/link-list/README.md @@ -13,6 +13,5 @@ Therefore, it is blue and clickable. ## Guidelines -Use a Link List to present multiple links within a theme. - -For additional guidelines, refer to the [Link](/docs/components-navigation-link--docs) component. +- Use a Link List to present multiple links within a theme. +- For additional guidelines, refer to the [Link](/docs/components-navigation-link--docs) component. diff --git a/packages/css/src/components/mark/README.md b/packages/css/src/components/mark/README.md index 272fbb540a..b3932b3372 100644 --- a/packages/css/src/components/mark/README.md +++ b/packages/css/src/components/mark/README.md @@ -7,13 +7,8 @@ Provides strong emphasis on the text and draws attention to it. ## Guidelines -### How to Use - -- Use a maximum of 1 mark per page. +- Use a maximum of 1 Mark per page. - Limit the marked text to 1 sentence. - -### Avoid This - - Do not use it in titles and subtitles. Use a significant and engaging title if the entire paragraph is important. - Do not mark an entire paragraph. diff --git a/packages/css/src/components/ordered-list/README.md b/packages/css/src/components/ordered-list/README.md index eb7727bfa8..f70e36e139 100644 --- a/packages/css/src/components/ordered-list/README.md +++ b/packages/css/src/components/ordered-list/README.md @@ -7,3 +7,8 @@ This list can have 2 levels. The first level has numbers as list markers. The second level uses letters in alphabetical order. List items indent their text by a fixed distance. + +## Design + +The list uses ascending numbers as markers, providing enough space for numbers up to 99. +Extra white space between items enhances the distinction, mainly when they consist of multiple lines of text. diff --git a/packages/css/src/components/screen/README.md b/packages/css/src/components/screen/README.md index 0bbc7120c7..29991d61c0 100644 --- a/packages/css/src/components/screen/README.md +++ b/packages/css/src/components/screen/README.md @@ -4,15 +4,15 @@ Manages the maximum width and alignment of the entire website or application. -## Usage +## Guidelines -This should be the outermost component of your website or application. -Within it, combine components such as -[Grid](/docs/components-layout-grid--docs), -[Header](/docs/components-containers-header--docs), -[Footer](/docs/components-containers-footer--docs), -[Spotlight](/docs/components-containers-spotlight--docs), -and Figure. +- This should be the outermost component of your website or application. +- Within it, combine components such as + [Grid](/docs/components-layout-grid--docs), + [Header](/docs/components-containers-header--docs), + [Footer](/docs/components-containers-footer--docs), + [Spotlight](/docs/components-containers-spotlight--docs), + and Figure. ## Design diff --git a/packages/css/src/components/skip-link/README.md b/packages/css/src/components/skip-link/README.md index 8bf2b2742f..160262d603 100644 --- a/packages/css/src/components/skip-link/README.md +++ b/packages/css/src/components/skip-link/README.md @@ -11,8 +11,6 @@ When the link is shown, it pushes the entire page down. ## Guidelines -### How to Use - - Place the Skip Link as the first element in `` unless you have a cookie banner. In that case, place the Skip Link immediately after the cookie banner. - Use the Skip Link to navigate to the main content. @@ -20,9 +18,6 @@ When the link is shown, it pushes the entire page down. - Set `id="example-id"` on the container of that element and then use `href="#example-id"` on the Skip Link. - You can use more than one Skip Link for complex pages with multiple sections. In most cases, this is not necessary. - -### Avoid - - Skip Links are unnecessary on a simple page with only text and minimal navigation. The purpose of a Skip Link is to bypass recurring navigation blocks. If those blocks are not present, a Skip Link is not needed. diff --git a/packages/css/src/components/spotlight/README.md b/packages/css/src/components/spotlight/README.md index 051b22e1d8..05a0b0e545 100644 --- a/packages/css/src/components/spotlight/README.md +++ b/packages/css/src/components/spotlight/README.md @@ -6,7 +6,7 @@ Emphasizes a section on a page through a distinctive background colour. ## Guidelines -Refer to [this overview on Stijlweb](https://amsterdam.nl/stijlweb/basiselementen/kleuren/#PagCls_15671872) to determine whether you can use black or white text on the background colour of your choice. +- Refer to [this overview on Stijlweb](https://amsterdam.nl/stijlweb/basiselementen/kleuren/#PagCls_15671872) to determine whether you can use black or white text on the background colour of your choice. ## Relevant WCAG requirements diff --git a/packages/css/src/components/tabs/README.md b/packages/css/src/components/tabs/README.md index 5e71e75650..fbcb7ba5c7 100644 --- a/packages/css/src/components/tabs/README.md +++ b/packages/css/src/components/tabs/README.md @@ -4,11 +4,13 @@ Tabs are used to bundle related content in a compact overview within a page. Each tab has a short name, and these names indicate the relationship between the information displayed in each tab. -## How to use +## Guidelines - The content of each tab is viewable independently, not in the context of one another. - The content within each tab should have a similar structure. - Use when there is limited visual space and content needs to be divided into sections. +- Each tab consists of a button and a panel. + A `tab` prop with a corresponding value connects them. You can navigate tabs with your keyboard: diff --git a/packages/css/src/components/unordered-list/README.md b/packages/css/src/components/unordered-list/README.md index bb0b897390..7a2bfb3596 100644 --- a/packages/css/src/components/unordered-list/README.md +++ b/packages/css/src/components/unordered-list/README.md @@ -7,3 +7,9 @@ This list can have 2 levels. The first level consists of squares. The second level consists of en dashes (–). Text in the list items is indented by a fixed distance. + +## Design + +Items of an unordered list have square markers. +There is extra white space between the items. +This provides better distinction between the items, especially when they consist of multiple lines of text. diff --git a/storybook/src/components/Accordion/Accordion.docs.mdx b/storybook/src/components/Accordion/Accordion.docs.mdx index 60b08481b4..bc38f60656 100644 --- a/storybook/src/components/Accordion/Accordion.docs.mdx +++ b/storybook/src/components/Accordion/Accordion.docs.mdx @@ -23,15 +23,15 @@ If you want the contents of an accordion section to appear initially, pass the ` -## Too many landmarks +### Limit the amount of accessibility landmarks -By default, an accordion section uses the HTML tag `section` to render the content. -Having many accordion sections on your page (more than 6) can lead to too many landmark regions, confusing screen reader users. -In that case, use `sectionAs="div"`. +An Accordion Section renders a `section` element in HTML by default. +Each of them introduces a landmark region, but having many of them on a page can confuse screen reader users. +Let Accordions with 6 Sections or more render generic `div` elements through `sectionAs="div"`. - + -## Technical considerations +### Technical considerations ### The `Accordion` parent component diff --git a/storybook/src/components/Accordion/Accordion.stories.tsx b/storybook/src/components/Accordion/Accordion.stories.tsx index 5153940da1..d186dc3e8e 100644 --- a/storybook/src/components/Accordion/Accordion.stories.tsx +++ b/storybook/src/components/Accordion/Accordion.stories.tsx @@ -59,7 +59,7 @@ export const ExpandedByDefault: Story = { }, } -export const TooManyLandmarks: Story = { +export const ReduceLandmarks: Story = { args: { sectionAs: 'div', children: [ diff --git a/storybook/src/components/Alert/Alert.docs.mdx b/storybook/src/components/Alert/Alert.docs.mdx index f7f988f75d..41e25bce1b 100644 --- a/storybook/src/components/Alert/Alert.docs.mdx +++ b/storybook/src/components/Alert/Alert.docs.mdx @@ -8,17 +8,16 @@ import README from "../../../../packages/css/src/components/alert/README.md?raw" {README} -## Examples - -The default Alert is a warning. - +## Examples + ### Warning Display a warning when user action is required. +This is the default severity. @@ -41,19 +40,19 @@ An informative message can emphasize matters that are useful to follow. -### With Inline Link +### With inline link Include an inline link in the text to guide the user. -### With List +### With list For clarification, formatted text can be included in the alert. -### Without Heading +### Without heading Sometimes, a heading is unnecessary. The icon automatically becomes slightly smaller. diff --git a/storybook/src/components/AspectRatio/AspectRatio.docs.mdx b/storybook/src/components/AspectRatio/AspectRatio.docs.mdx index b30550897a..24a212a64a 100644 --- a/storybook/src/components/AspectRatio/AspectRatio.docs.mdx +++ b/storybook/src/components/AspectRatio/AspectRatio.docs.mdx @@ -12,29 +12,31 @@ import README from "../../../../packages/css/src/components/aspect-ratio/README. -## Double extra wide +## Examples + +### Double extra wide We only use this aspect ratio for a ‘hero’ image across the entire website width. -## Extra wide +### Extra wide -## Wide +### Wide -## Square +### Square -## Tall +### Tall -## Extra Tall +### Extra tall This variant may be suitable for telephones. Most devices nowadays have an aspect ratio of 9:19.5. diff --git a/storybook/src/components/Avatar/Avatar.docs.mdx b/storybook/src/components/Avatar/Avatar.docs.mdx index 09b6a2c647..c74868519c 100644 --- a/storybook/src/components/Avatar/Avatar.docs.mdx +++ b/storybook/src/components/Avatar/Avatar.docs.mdx @@ -8,22 +8,20 @@ import README from "../../../../packages/css/src/components/avatar/README.md?raw {README} -## Stories - -### Default - -### With Picture +## Examples + +### With image The Avatar can also display a photo or other image for the person. Make sure to scale the image down to around 100 pixels to prevent unnecessary data transfers. - + -### Fallback Icon +### Fallback icon A user icon displays if no label and image are provided. diff --git a/storybook/src/components/Avatar/Avatar.stories.tsx b/storybook/src/components/Avatar/Avatar.stories.tsx index e4c2095385..f9b55adb73 100644 --- a/storybook/src/components/Avatar/Avatar.stories.tsx +++ b/storybook/src/components/Avatar/Avatar.stories.tsx @@ -23,7 +23,7 @@ type Story = StoryObj export const Default: Story = {} -export const WithPicture: Story = { +export const WithImage: Story = { args: { label: 'PS', imageSrc: 'https://i.pravatar.cc/128', diff --git a/storybook/src/components/Badge/Badge.docs.mdx b/storybook/src/components/Badge/Badge.docs.mdx index a40a886a8c..230d706442 100644 --- a/storybook/src/components/Badge/Badge.docs.mdx +++ b/storybook/src/components/Badge/Badge.docs.mdx @@ -8,10 +8,6 @@ import README from "../../../../packages/css/src/components/badge/README.md?raw" {README} -## Stories - -### Default - diff --git a/storybook/src/components/Breadcrumb/Breadcrumb.docs.mdx b/storybook/src/components/Breadcrumb/Breadcrumb.docs.mdx index 380a0b2754..db2321dd78 100644 --- a/storybook/src/components/Breadcrumb/Breadcrumb.docs.mdx +++ b/storybook/src/components/Breadcrumb/Breadcrumb.docs.mdx @@ -10,6 +10,6 @@ import README from "../../../../packages/css/src/components/breadcrumb/README.md -## Usage +## Guidelines - A breadcrumb should not display more than 8 items. diff --git a/storybook/src/components/Button/Button.docs.mdx b/storybook/src/components/Button/Button.docs.mdx index 0789fe8ec7..4a3e258996 100644 --- a/storybook/src/components/Button/Button.docs.mdx +++ b/storybook/src/components/Button/Button.docs.mdx @@ -14,30 +14,27 @@ import README from "../../../../packages/css/src/components/button/README.md?raw ## Examples -Primary, secondary and tertiary buttons can be used side by side. -Skipping levels is allowed. - ### Primary -The most important call-to-action button. -One primary button may be used per screen. +The most important call-to-action. +One primary Button may be used per screen. ### Secondary -Use the secondary button for less prominent calls to action. -It is possible to use more than 1 secondary button. +Use the secondary Button for less prominent calls to action. +It is possible to use more than 1 secondary Button. ### Tertiary -Use tertiary buttons for unimportant calls to action – as many as necessary. +Use tertiary Buttons for unimportant calls to action – as many as necessary. -### Button with an icon +### With icon diff --git a/storybook/src/components/Card/Card.docs.mdx b/storybook/src/components/Card/Card.docs.mdx index 82f3aba4b7..30a039fd51 100644 --- a/storybook/src/components/Card/Card.docs.mdx +++ b/storybook/src/components/Card/Card.docs.mdx @@ -10,7 +10,9 @@ import README from "../../../../packages/css/src/components/card/README.md?raw"; -## With tagline +## Examples + +### With tagline A card can display a tagline above the heading, a short term like a category or type of information. Wrap the tagline and the heading in a `Card.HeadingGroup`. @@ -18,7 +20,7 @@ This ensures screen readers first read the heading and then the tagline. -## With image +### With image A card often displays the image of the detail page. Use [Aspect Ratio](/docs/layout-aspect-ratio--docs) for the correct aspect ratio. diff --git a/storybook/src/components/CharacterCount/CharacterCount.docs.mdx b/storybook/src/components/CharacterCount/CharacterCount.docs.mdx index c13948e7bf..605aa22955 100644 --- a/storybook/src/components/CharacterCount/CharacterCount.docs.mdx +++ b/storybook/src/components/CharacterCount/CharacterCount.docs.mdx @@ -12,7 +12,9 @@ import README from "../../../../packages/css/src/components/character-count/READ -## Error +## Examples + +### Error When the length exceeds the maximum length, the color of the text changes to red. diff --git a/storybook/src/components/Column/Column.docs.mdx b/storybook/src/components/Column/Column.docs.mdx index cd0008915f..d82c91aa55 100644 --- a/storybook/src/components/Column/Column.docs.mdx +++ b/storybook/src/components/Column/Column.docs.mdx @@ -8,21 +8,19 @@ import README from "../../../../packages/css/src/components/column/README.md?raw {README} -## How to Use +## Guidelines - Wrap a Column around a set of elements that need the same amount of white space between them. - The five sizes of [Component Space](/docs/brand-design-tokens-space--docs) are available for the width or height of the gap. - To add white space below a single element, you can add a [Margin Bottom](/docs/utilities-css-margin--docs) instead. - Align the elements horizontally or vertically through the alignment props. -## Examples - -### Default - +## Examples + ### Alignment Items in the column can be aligned vertically in several ways: @@ -52,10 +50,10 @@ This example centers three items horizontally. -### Use another HTML element +### Improve semantics -By default, a Column renders a `
`. +By default, a Column renders a `
` element in HTML. Use the `as` prop to make your markup more semantic. In this example, the Column uses a `
` element to group the heading and the cards. - + diff --git a/storybook/src/components/Column/Column.stories.tsx b/storybook/src/components/Column/Column.stories.tsx index 20d5de764c..65d8c40323 100644 --- a/storybook/src/components/Column/Column.stories.tsx +++ b/storybook/src/components/Column/Column.stories.tsx @@ -67,7 +67,7 @@ export const HorizontalAlignment: Story = { }, } -export const CustomTagName: Story = { +export const ImproveSemantics: Story = { args: { as: 'section', children: [ diff --git a/storybook/src/components/DescriptionList/DescriptionList.docs.mdx b/storybook/src/components/DescriptionList/DescriptionList.docs.mdx index d0ff0866d7..3cae55085a 100644 --- a/storybook/src/components/DescriptionList/DescriptionList.docs.mdx +++ b/storybook/src/components/DescriptionList/DescriptionList.docs.mdx @@ -12,7 +12,9 @@ import README from "../../../../packages/css/src/components/description-list/REA -## Multiple details +## Examples + +### Multiple details A term may have multiple details. diff --git a/storybook/src/components/Dialog/Dialog.docs.mdx b/storybook/src/components/Dialog/Dialog.docs.mdx index 2ec6f0c83a..2085b78c6a 100644 --- a/storybook/src/components/Dialog/Dialog.docs.mdx +++ b/storybook/src/components/Dialog/Dialog.docs.mdx @@ -12,26 +12,29 @@ import README from "../../../../packages/css/src/components/dialog/README.md?raw -## With Scrollbar +## Examples + +### With scrollbar Content taller than the dialog itself will scroll. -## Open Dialog Button +### Trigger Button -Click or tap the button to open a dialog. +Click or tap this Button to open the Dialog. -To open the dialog, use the `openDialog` function from the React package. -Pass the Dialog’s `id` to the function to select it. +#### Utility functions +To open the Dialog, use the `openDialog` function from the React package. +Pass the Dialog’s `id` to the function to select it. To close the Dialog, use the `closeDialog` function. -## Vertically Stacked Buttons +### Vertically stacked Buttons -If the buttons don’t fit next to each other, they will stack vertically and stretch to the full width. -This can occur with a narrow Dialog, long Button labels, a large text size or zooming in. +If the Buttons don’t fit next to each other, they will stack vertically and stretch to the full width. +This can occur with a narrow Dialog, long Button labels, a large text size, or when zooming in. diff --git a/storybook/src/components/ErrorMessage/ErrorMessage.docs.mdx b/storybook/src/components/ErrorMessage/ErrorMessage.docs.mdx index 9bcab4ca52..ce55a97394 100644 --- a/storybook/src/components/ErrorMessage/ErrorMessage.docs.mdx +++ b/storybook/src/components/ErrorMessage/ErrorMessage.docs.mdx @@ -12,10 +12,12 @@ import README from "../../../../packages/css/src/components/error-message/README -## With a custom prefix +## Examples + +### Custom prefix Error messages are automatically prefixed with a visually hidden text, the Dutch word "Invoerfout". This makes the error message more clear for screen reader users. If you want to change this prefix, to support another language for example, you can use the `prefix` prop. - + diff --git a/storybook/src/components/ErrorMessage/ErrorMessage.stories.tsx b/storybook/src/components/ErrorMessage/ErrorMessage.stories.tsx index 8e6c3e4312..3dc79cad2b 100644 --- a/storybook/src/components/ErrorMessage/ErrorMessage.stories.tsx +++ b/storybook/src/components/ErrorMessage/ErrorMessage.stories.tsx @@ -25,7 +25,7 @@ type Story = StoryObj export const Default: Story = {} -export const WithCustomPrefix: Story = { +export const CustomPrefix: Story = { args: { children: 'Enter an email address in the correct format, like name@example.com', prefix: 'Error', diff --git a/storybook/src/components/Field/Field.docs.mdx b/storybook/src/components/Field/Field.docs.mdx index b0bd3adb1c..67b66fdd46 100644 --- a/storybook/src/components/Field/Field.docs.mdx +++ b/storybook/src/components/Field/Field.docs.mdx @@ -12,7 +12,9 @@ import README from "../../../../packages/css/src/components/field/README.md?raw" -## With description +## Examples + +### With description A Field can have a description. Make sure to connect this description to the input in the Field, @@ -21,10 +23,10 @@ Add an `aria-describedby` attribute to the input and provide the `id` of the des -## With validation +### With validation A Field can indicate if the contained input has a validation error. -Use Error Message to describe the error. +Use an [Error Message](/docs/components-forms-error-message--docs) to describe the error. Make sure to connect the Error Message to the input in the Field, otherwise it won’t be read by a screen reader. Add an `aria-describedby` attribute to the input and provide the `id` of Error Message as its value. diff --git a/storybook/src/components/FieldSet/FieldSet.docs.mdx b/storybook/src/components/FieldSet/FieldSet.docs.mdx index 6e5dddebf0..4fe2c9856d 100644 --- a/storybook/src/components/FieldSet/FieldSet.docs.mdx +++ b/storybook/src/components/FieldSet/FieldSet.docs.mdx @@ -14,7 +14,7 @@ import README from "../../../../packages/css/src/components/field-set/README.md? ## Examples -## With description +### With description A Field Set can have a description. Make sure to connect this description to the Field Set or a specific input, @@ -24,10 +24,10 @@ and provide the `id` of the describing element as its value. -## With validation +### With validation A Field Set can indicate whether any of the inputs it contains has a validation error. -Use Error Message to describe the error. +Use an [Error Message](/docs/components-forms-error-message--docs) to describe the error. Make sure to connect the Error Message to the correct input in the Field Set, otherwise it won’t be read by a screen reader. Add an `aria-describedby` attribute to the input and provide the `id` of Error Message as its value. diff --git a/storybook/src/components/FileInput/FileInput.docs.mdx b/storybook/src/components/FileInput/FileInput.docs.mdx index b77776eb03..c62e6d8645 100644 --- a/storybook/src/components/FileInput/FileInput.docs.mdx +++ b/storybook/src/components/FileInput/FileInput.docs.mdx @@ -14,19 +14,19 @@ import README from "../../../../packages/css/src/components/file-input/README.md ## Examples -### Multiple Files +### Multiple files Allow multiple files to be selected. The label will update to show the number of files selected. - + -### Accept +### Restrict file types Limit the types of files that can be selected. Some examples are `image/*`, `video/*`, or `audio/*`. To limit to a specific file type, use the MIME type, such as `application/pdf`. - [MDN File Input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#limiting_accepted_file_types): More examples - + ### Disabled diff --git a/storybook/src/components/FileInput/FileInput.stories.tsx b/storybook/src/components/FileInput/FileInput.stories.tsx index 1acdbed5c1..405acb119d 100644 --- a/storybook/src/components/FileInput/FileInput.stories.tsx +++ b/storybook/src/components/FileInput/FileInput.stories.tsx @@ -40,11 +40,11 @@ type Story = StoryObj export const Default: Story = {} -export const Multiple: Story = { +export const MultipleFiles: Story = { args: { multiple: true }, } -export const Accept: Story = { +export const RestrictFileTypes: Story = { args: { accept: 'application/pdf' }, } diff --git a/storybook/src/components/Footer/Footer.docs.mdx b/storybook/src/components/Footer/Footer.docs.mdx index 80017d7615..3ccdd0c24c 100644 --- a/storybook/src/components/Footer/Footer.docs.mdx +++ b/storybook/src/components/Footer/Footer.docs.mdx @@ -17,4 +17,4 @@ import README from "../../../../packages/css/src/components/footer/README.md?raw The footer for a specific website can be a bit different. Here’s an example for the ‘Onderzoek en Statistiek’ department. - + diff --git a/storybook/src/components/Footer/Footer.stories.tsx b/storybook/src/components/Footer/Footer.stories.tsx index 9d553c9f9c..7fd780ec64 100644 --- a/storybook/src/components/Footer/Footer.stories.tsx +++ b/storybook/src/components/Footer/Footer.stories.tsx @@ -114,7 +114,7 @@ export const Default: Story = { }, } -export const Onderzoek: Story = { +export const OnderzoekEnStatistiek: Story = { args: { children: [ diff --git a/storybook/src/components/Grid/Grid.docs.mdx b/storybook/src/components/Grid/Grid.docs.mdx index de1fb946fb..bb7dd77ed7 100644 --- a/storybook/src/components/Grid/Grid.docs.mdx +++ b/storybook/src/components/Grid/Grid.docs.mdx @@ -8,17 +8,17 @@ import README from "../../../../packages/css/src/components/grid/README.md?raw"; {README} -## Examples + -The pink areas below represent the columns of the grid. -The spaces in between are white. + -The grid has 12 columns on wide screens, so all 12 cells in this example are in a row. -On narrow screens, you will see three rows of four columns; on medium-wide screens, one row of eight and one of four. +## Examples - +The pink areas represent the columns of the grid. +The gaps between the columns are transparent. - +The grid has 12 columns on wide screens, so all 12 cells in the example above are in a row. +On narrow screens, you will see three rows of four columns; on medium-wide screens, one row of eight and one of four. ### Vertical margin @@ -79,16 +79,16 @@ An example with `start={2}`: -### Use another HTML element +### Improve semantics -By default, a Grid Cell renders a `
`. +By default, a Grid Cell renders a `
` element in HTML. Use the `as` prop to make your markup more semantic. - + ## Guidelines -Ensure that the number of columns you assign to a cell matches the amount of columns in the grid for the respective window width. -The same applies to starting a cell in a later column. -If the total of both values is too large, the browser adds columns to the grid. -This is not allowed. +- Ensure that the number of columns you assign to a cell matches the amount of columns in the grid for the respective window width. +- The same applies to starting a cell in a later column. +- If the total of both values is too large, the browser adds columns to the grid. + This is not allowed. diff --git a/storybook/src/components/Grid/Grid.stories.tsx b/storybook/src/components/Grid/Grid.stories.tsx index a957bc04bb..536acd6c48 100644 --- a/storybook/src/components/Grid/Grid.stories.tsx +++ b/storybook/src/components/Grid/Grid.stories.tsx @@ -148,7 +148,7 @@ export const StartPosition: CellStory = { }, } -export const CustomTagName: CellStory = { +export const ImproveSemantics: CellStory = { ...CellStoryTemplate, args: { as: 'section', diff --git a/storybook/src/components/Header/Header.docs.mdx b/storybook/src/components/Header/Header.docs.mdx index ac0e71f057..a6aa627823 100644 --- a/storybook/src/components/Header/Header.docs.mdx +++ b/storybook/src/components/Header/Header.docs.mdx @@ -15,33 +15,35 @@ import { StatusBadge } from "../../docs/components/StatusBadge"; -## With logo variant +## Examples - +### For a sub-brand -## With app name + + +### With app name -## With menu +### With menu button - + -## With links +### With links Use a [Page Menu](/docs/components-navigation-page-menu--docs) to add links. A Page Menu in the Header should not wrap. -## With links and menu +### With links and menu button - + -## With app name and menu +### With app name and menu button - + -## With app name, links and menu +### With app name, links and menu button - + diff --git a/storybook/src/components/Header/Header.stories.tsx b/storybook/src/components/Header/Header.stories.tsx index 08da3fd90e..8c08a33001 100644 --- a/storybook/src/components/Header/Header.stories.tsx +++ b/storybook/src/components/Header/Header.stories.tsx @@ -19,7 +19,7 @@ type Story = StoryObj export const Default: Story = {} -export const WithLogoVariant: Story = { +export const ForSubBrand: Story = { args: { logoBrand: 'ggd-amsterdam', logoLink: 'https://www.ggd.amsterdam.nl/', @@ -47,13 +47,13 @@ export const WithLinks: Story = { }, } -export const WithMenu: Story = { +export const WithMenuButton: Story = { args: { menu: , }, } -export const WithLinksAndMenu: Story = { +export const WithLinksAndMenuButton: Story = { args: { links: ( @@ -68,14 +68,14 @@ export const WithLinksAndMenu: Story = { }, } -export const WithAppNameAndMenu: Story = { +export const WithAppNameAndMenuButton: Story = { args: { appName: 'Aan de Amsterdamse grachten', menu: , }, } -export const WithAppNameLinksAndMenu: Story = { +export const WithAppNameLinksAndMenuButton: Story = { args: { appName: 'Aan de Amsterdamse grachten', links: ( diff --git a/storybook/src/components/IconButton/IconButton.docs.mdx b/storybook/src/components/IconButton/IconButton.docs.mdx index a26cc7eba1..5cfb262303 100644 --- a/storybook/src/components/IconButton/IconButton.docs.mdx +++ b/storybook/src/components/IconButton/IconButton.docs.mdx @@ -30,25 +30,25 @@ import README from "../../../../packages/css/src/components/icon-button/README.m -### On a Coloured Background +### On a coloured background -An icon button on a coloured background must adjust its foreground colour to provide enough contrast. -We have lighter and darker background colours, and icon buttons behave differently on each. +An Icon Button on a coloured background must adjust its foreground colour to provide enough contrast. +We have lighter and darker background colours, and Icon Buttons behave differently on each. Stijlweb shows [which colours suit which backgrounds](https://amsterdam.nl/stijlweb/basiselementen/kleuren/). -Although they only address headings and paragraphs, the same principle applies to icon buttons. +Although they only address headings and paragraphs, the same principle applies to Icon Buttons. - Set the `contrastColor` prop on a yellow, orange or green background. - It will make the icon button black. + It will make the Icon Button black. - Use the `inverseColor` prop on a purple or dark blue background. - It will make the icon button white. + It will make the Icon Button white. - On the other background colours, choose either one, but do so consistently. - There is no current scenario to set both properties at the same time. For now, the 'inverse' appearance will prevail. -#### Contrast Colour +#### Contrast colour -#### Inverse Colour +#### Inverse colour diff --git a/storybook/src/components/Image/Image.docs.mdx b/storybook/src/components/Image/Image.docs.mdx index 95e2441c44..6c94c47466 100644 --- a/storybook/src/components/Image/Image.docs.mdx +++ b/storybook/src/components/Image/Image.docs.mdx @@ -8,13 +8,13 @@ import README from "../../../../packages/css/src/components/image/README.md?raw" {README} -## Examples - -## Provide multiple sources +## Examples + +### Provide multiple sources Use the srcSet prop, which controls the corresponding HTML attribute (see [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset)), to let the browser select the optimal source file for the image. A mobile device can often download a smaller file, saving the user’s bandwidth and time. @@ -22,7 +22,7 @@ Don’t forget to still include the required `src` attribute. -## Prevent unnecessary loading +### Prevent unnecessary loading Set the `loading` attribute (see [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading)) to `lazy` and the browser will wait to load the image until it is close to the viewport. Consider setting this for images below the top area of the page. diff --git a/storybook/src/components/Link/Link.docs.mdx b/storybook/src/components/Link/Link.docs.mdx index fd466a2518..4e7837e2cd 100644 --- a/storybook/src/components/Link/Link.docs.mdx +++ b/storybook/src/components/Link/Link.docs.mdx @@ -30,7 +30,7 @@ Don’t use too many inline links on the same page, as it may confuse the user. -### On a Coloured Background +### On a coloured background A link on a coloured background must adjust its text colour to provide enough contrast. We have lighter and darker background colours, and links behave differently on each. @@ -45,10 +45,10 @@ Although they only address headings and paragraphs, the same principle applies t - There is no current scenario to set both properties at the same time. For now, the 'inverse' appearance will prevail. -#### Contrast Colour +#### Contrast colour -#### Inverse Colour +#### Inverse colour diff --git a/storybook/src/components/LinkList/LinkList.docs.mdx b/storybook/src/components/LinkList/LinkList.docs.mdx index b7394e7b8f..5c466b8f17 100644 --- a/storybook/src/components/LinkList/LinkList.docs.mdx +++ b/storybook/src/components/LinkList/LinkList.docs.mdx @@ -8,23 +8,18 @@ import README from "../../../../packages/css/src/components/link-list/README.md? {README} -## Examples - -### Default - -The Link List has no props. -It is just a container for the items, rendering a `