chore: Improve headings and guidelines throughout documentation (#1565)

Co-authored-by: Aram <[email protected]>

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
 

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.

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
 

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
 

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.

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:
 

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
 

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
 

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.

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.

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.

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.

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
 

packages/css/src/components/skip-link/README.md

@@ -11,18 +11,13 @@ When the link is shown, it pushes the entire page down.
 
 ## Guidelines
 
-### How to Use
-
 - Place the Skip Link as the first element in `<body>` 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.
   On an article page, for example, it could be the title of the article; on a search page, it could be the search field.
 - 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.

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
 

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:
 

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.

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 `
 
 <Canvas of={AccordionStories.ExpandedByDefault} />
 
-## 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"`.
 
-<Canvas of={AccordionStories.TooManyLandmarks} />
+<Canvas of={AccordionStories.ReduceLandmarks} />
 
-## Technical considerations
+### Technical considerations
 
 ### The `Accordion` parent component
 

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: [

storybook/src/components/Alert/Alert.docs.mdx

@@ -8,17 +8,16 @@ import README from "../../../../packages/css/src/components/alert/README.md?raw"
 
 <Markdown>{README}</Markdown>
 
-## Examples
-
-The default Alert is a warning.
-
 <Primary />
 
 <Controls />
 
+## Examples
+
 ### Warning
 
 Display a warning when user action is required.
+This is the default severity.
 
 <Canvas of={AlertStories.Warning} />
 
@@ -41,19 +40,19 @@ An informative message can emphasize matters that are useful to follow.
 
 <Canvas of={AlertStories.Info} />
 
-### With Inline Link
+### With inline link
 
 Include an inline link in the text to guide the user.
 
 <Canvas of={AlertStories.WithInlineLink} />
 
-### With List
+### With list
 
 For clarification, formatted text can be included in the alert.
 
 <Canvas of={AlertStories.WithList} />
 
-### Without Heading
+### Without heading
 
 Sometimes, a heading is unnecessary.
 The icon automatically becomes slightly smaller.

storybook/src/components/AspectRatio/AspectRatio.docs.mdx

@@ -12,29 +12,31 @@ import README from "../../../../packages/css/src/components/aspect-ratio/README.
 
 <Controls />
 
-## Double extra wide
+## Examples
+
+### Double extra wide
 
 We only use this aspect ratio for a ‘hero’ image across the entire website width.
 
 <Canvas of={AspectRatioStories.DoubleExtraWide} />
 
-## Extra wide
+### Extra wide
 
 <Canvas of={AspectRatioStories.ExtraWide} />
 
-## Wide
+### Wide
 
 <Canvas of={AspectRatioStories.Wide} />
 
-## Square
+### Square
 
 <Canvas of={AspectRatioStories.Square} />
 
-## Tall
+### Tall
 
 <Canvas of={AspectRatioStories.Tall} />
 
-## Extra Tall
+### Extra tall
 
 This variant may be suitable for telephones.
 Most devices nowadays have an aspect ratio of 9:19.5.

storybook/src/components/Avatar/Avatar.docs.mdx

@@ -8,22 +8,20 @@ import README from "../../../../packages/css/src/components/avatar/README.md?raw
 
 <Markdown>{README}</Markdown>
 
-## Stories
-
-### Default
-
 <Primary />
 
 <Controls />
 
-### 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.
 
-<Canvas of={AvatarStories.WithPicture} />
+<Canvas of={AvatarStories.WithImage} />
 
-### Fallback Icon
+### Fallback icon
 
 A user icon displays if no label and image are provided.