chore: Organize ‘Docs’ section (#1386)

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

NOTICE.md

@@ -1,6 +1,6 @@
 <!-- @license CC0-1.0 -->
 
-# Terms of Use
+# Copyright
 
 ## Branding, logo and authors’ rights
 
@@ -9,11 +9,12 @@ Authors’ rights and trademark rights apply to the logo.
 If you intend to use a modified version of the software for other purposes, you are not allowed to use the City of Amsterdam’s logo.
 Instead, you should design your own branding.
 
-## Fonts
+## Typefaces
+
+Not all typefaces used in the branding are free and open source.
+Please note that you must arrange a (paid) license if you use the provided typefaces.
+Alternatively, adjust the configuration to use fewer or different typefaces.
 
-Not all fonts used in the branding are free and open source.
-Please note that you must arrange a (paid) license if you use the provided fonts.
-Alternatively, adjust the configuration to use fewer or different fonts.
 Amsterdam Sans is licensed exclusively to the City of Amsterdam and amsterdam&partners.
 
 ## Permission

README.md

@@ -13,19 +13,19 @@ We aim to create libraries for, or support otherwise, Figma, CSS, React, React N
 
 ## Related resources
 
-[A Storybook portal](https://amsterdam.github.io/design-system/) demonstrates our components and documentation.
+[A Storybook portal](https://designsystem.amsterdam/) demonstrates our components and documentation.
 
 [Our Figma file](https://www.figma.com/file/9IGm6IdPUYizBNGsUnueBd/Amsterdam-Design-System?type=design&node-id=741-19633&mode=design&t=N8P3h3W67O0KNdga-0) contains the design of our components and patterns.
 
 ## Getting started
 
-See the [getting started documentation for developers](https://designsystem.amsterdam/?path=/docs/docs-getting-started-developers--docs) on how to use our React components.
+See the [getting started documentation for developers](https://designsystem.amsterdam/?path=/docs/docs-developer-guide-getting-started--docs) on how to use our React components.
 
 ## Contributing
 
 See the [documentation for contributors](./CONTRIBUTING.md).
 
-## Code of Conduct
+## Code of conduct
 
 We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
 Read [our Code of Conduct](https://github.com/Amsterdam/.github/blob/main/CODE_OF_CONDUCT.md) if you haven’t already.

documentation/storybook.md

@@ -4,7 +4,7 @@
 
 We use Storybook to display all components and allow interaction with them.
 
-We publish each merge to the `main` branch to [amsterdam.github.io/design-system](https://amsterdam.github.io/design-system/).
+We publish each merge to the `main` branch to [designsystem.amsterdam](https://designsystem.amsterdam/).
 
 ## Structure
 

packages/css/src/components/card/README.md

@@ -19,7 +19,7 @@ The link is mandatory.
   For referencing a thematic page, use a [top task link](/docs/components-navigation-top-task-link--docs).
   You can also use a [regular link](/docs/components-navigation-link--docs).
 
-## Screen Readers
+## Screen readers
 
 With a screen reader, you can navigate using headings and links in a document.
 The title of a card is a link within a heading, allowing you to utilize both navigation methods.

packages/css/src/components/checkbox/README.md

@@ -17,14 +17,14 @@ Allows users to make a selection or agree to terms.
 - A list of checkboxes should be in a `fieldset` with a `legend` describing what the list is about.
   For example, if the checkboxes are used to get answers to a question, the `legend` is the question.
 
-## Checkbox Labels
+## Checkbox labels
 
 A label starts with a capital letter.
 It does not have punctuation at the end if it is a single sentence, word, or fragment.
 It is written in the first person when asking the user to agree to the terms and conditions.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [WCAG 1.3.5](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html): It is clear for both users and programmatically what the purpose of a form field is.
 
-Checkbox is an interactive element; therefore, [the general requirements and guidelines for interactive elements](/docs/docs-design-guidelines-interactive-elements--docs) apply.
+Checkbox is an interactive element; therefore, [the general requirements and guidelines for interactivity](/docs/docs-developer-guide-interactivity--docs) apply.

packages/css/src/components/dialog/README.md

@@ -17,7 +17,7 @@ Sighted users will read the primary action first, in line with the natural readi
 The same goes for users of screen readers, who will hear the primary action first, and users of a keyboard, who will focus the primary action first.
 Also, this approach keeps the order of buttons consistent on both narrow and wide screens: if the buttons do not fit next to each other, they get stacked vertically with the primary action on top.
 
-## Keyboard Support
+## Keyboard support
 
 | key         | function                                                         |
 | :---------- | :--------------------------------------------------------------- |

packages/css/src/components/field-set/README.md

@@ -8,7 +8,7 @@ A component to group related form inputs.
 
 - Use Field Set when you need to show a relationship between multiple form inputs. For example, you may need to group a set of text inputs into a single Field Set when asking for an address.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [WCAG 1.3.5](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html): Field Set labels the purpose of a group of inputs.
 

packages/css/src/components/footer/README.md

@@ -6,7 +6,7 @@ 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](?path=/docs/components-navigation-page-menu--docs).
+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.

packages/css/src/components/grid/README.md

@@ -19,4 +19,4 @@ A cell often spans multiple columns of the grid.
 
 ## Design
 
-The [design choices](/docs/docs-design-guidelines-grid--docs) are described in the design guidelines.
+The [design choices](/docs/foundation-design-tokens-grid--docs) are described in the general documentation.

packages/css/src/components/heading/README.md

@@ -12,7 +12,7 @@ Use headings to allow the user to grasp the structure of the page quickly.
 - Use headings hierarchically, and do not skip heading levels.
   So, an `h1` heading should be followed by an `h2`, not an `h3`.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/quickref/#qr-content-structure-separation-programmatic):
   Text that looks like a heading is also recognized as a heading by a computer.

packages/css/src/components/icon-button/README.md

@@ -11,6 +11,6 @@ A button containing only an icon.
   Only use universally recognized icons, such as a close icon or a play icon.
 - Provide a label text that describes what the button does for screen reader users.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 The Icon Button follows [the same requirements and guidelines as a regular button](/docs/components-buttons-button--docs).

packages/css/src/components/icon/README.md

@@ -6,7 +6,7 @@ Icons are visual symbols used to represent ideas, themes, or actions.
 They communicate the message at a glance and draw attention to important (interactive) information.
 Always use an `Icon` component to encapsulate an SVG icon for proper styling and sizing.
 
-## Interactive Elements
+## Interactive elements
 
 Use an icon to support textual interactive elements like buttons and links.
 Always try to provide accompanying text for an icon.
@@ -28,8 +28,8 @@ Icons are aligned to the left of the text by default and vertically centred to t
 
 Icons use the same text levels as all typographic components to determine their size.
 This ensures easy alignment between icons and text.
-[Refer to the typography documentation for more information](/docs/docs-design-guidelines-typography--docs).
+[Refer to the typography documentation for more information](/docs/foundation-design-tokens-text--docs).
 
 ## Overview
 
-[You can find an overview of the available icons here](/docs/docs-assets-icons--docs).
+[You can find an overview of the available icons here](/docs/foundation-assets-icons--docs).

packages/css/src/components/image/README.md

@@ -17,7 +17,7 @@ Displays an image.
   Do this especially for the main image of a page, where the difference between sizes on a narrow and wide screen is most significant.
 - Ensure that the aspect ratio of the image is supported by the [Aspect Ratio](/docs/components-layout-aspect-ratio--docs) component.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [WCAG 1.1.1](https://www.w3.org/TR/WCAG22/#non-text-content): Non-text content must have a text alternative.
 - [WCAG 1.4.5](https://www.w3.org/TR/WCAG22/#images-of-text): Use text instead of images of text.

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

@@ -30,7 +30,7 @@ We discourage using styles for visited links because they often make the page le
 The inline link does have a visited style.
 It is not part of navigation elements that are frequently scanned.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [WCAG 1.4.3](https://www.w3.org/TR/WCAG21/#contrast-minimum)
 - [WCAG 2.4.4](https://www.w3.org/TR/WCAG21/#link-purpose-in-context)

packages/css/src/components/page-heading/README.md

@@ -11,7 +11,7 @@ Use this component for a name, title, or motto.
 - Only use this component once per page, typically only on the homepage.
 - Avoid using it if you need to display long pieces of text; the text should be short and precise.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 The page heading component is a variant of a heading level 1 with a distinct style.
 When using this component, ensure that the heading hierarchy of the page remains logical.

packages/css/src/components/page-menu/README.md

@@ -13,8 +13,8 @@ A small set of links for use in the Header and Footer.
 - The ‘Menu’ button opens the Mega Menu.
 - On narrow screens, menu items other than ‘Search’ and ‘Menu’ move from the Page Menu to the Mega Menu.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [Consistent Navigation (Level AA)](https://www.w3.org/WAI/WCAG21/Understanding/consistent-navigation.html)
 
-PageMenu is an interactive element, and the [general requirements and guidelines for interactive elements](/docs/docs-design-guidelines-interactive-elements--docs) apply.
+PageMenu is an interactive element, and the [general requirements and guidelines for interactivity](/docs/docs-developer-guide-interactivity--docs) apply.

packages/css/src/components/pagination/README.md

@@ -17,6 +17,6 @@ Pagination indicates the current page and allows users to navigate to other page
 - Start a page with an overview list at the top after changing the page.
 - Make sure that the visible and accessible labels for the ‘previous’ and ‘next’ buttons convey the same meaning at all times – e.g. don’t update one and forget the other.
 
-## Relevant WCAG Rules
+## Relevant WCAG rules
 
-Pagination is an interactive element, and the [general requirements and guidelines for interactive elements](/docs/docs-design-guidelines-interactive-elements--docs) apply.
+Pagination is an interactive element, and the [general requirements and guidelines for interactivity](/docs/docs-developer-guide-interactivity--docs) apply.

packages/css/src/components/paragraph/README.md

@@ -11,7 +11,7 @@ Represents a paragraph of running text, form instructions, and other standalone
 - Consider whether a paragraph with more than 7 sentences or 140 words would be clearer if you divide the text into two paragraphs.
   Texts with not overly long paragraphs are easier to understand, and grouping makes information quicker to locate.
 
-## Relevant WCAG Rules
+## Relevant WCAG rules
 
 - [WCAG 1.3.1](https://www.w3.org/TR/WCAG21/#info-and-relationships): Blocks that look like a paragraph are also recognized by a computer as a paragraph.
 - [WCAG 1.4.3](https://www.w3.org/TR/WCAG21/#contrast-minimum): The contrast of black text on a white background is high enough.

packages/css/src/components/search-field/README.md

@@ -32,4 +32,4 @@ These features can be disruptive for a user searching for part of a word, and `a
 - [WCAG 1.3.5](https://www.w3.org/TR/WCAG22/#identify-input-purpose): It is clear both to the user and programmatically what the purpose of a form field is.
 - [WCAG 2.4.6](https://www.w3.org/TR/WCAG22/#headings-and-labels): There is a label describing the purpose of the input.
 
-Search Field is an interactive element; therefore, [the general requirements and guidelines for interactive elements](/docs/docs-design-guidelines-interactive-elements--docs) apply.
+Search Field is an interactive element; therefore, [the general requirements and guidelines for interactivity](/docs/docs-developer-guide-interactivity--docs) apply.

packages/css/src/components/spotlight/README.md

@@ -8,7 +8,7 @@ Emphasizes a section on a page through a distinctive background colour.
 
 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
+## Relevant WCAG requirements
 
 - [WCAG 1.4.3](https://www.w3.org/TR/WCAG21/#contrast-minimum): Large-scale text and images of large-scale text have a contrast ratio of at least 3:1;
 

packages/css/src/components/switch/README.md

@@ -12,11 +12,11 @@ A switch applies to a page or the entire system, such as an on/off switch.
 - Use labels with a switch to make the action clear.
 - The action takes place immediately when the user operates the switch.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [WCAG 1.3.5](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html): it is both clear for a user and programmatically what the purpose of a form field is.
 
-The Switch is an interactive element; general requirements and guidelines for interactive elements apply [here](/docs/docs-design-guidelines-interactive-elements--docs).
+Switch is an interactive element; general requirements and guidelines for interactivity apply [here](/docs/docs-developer-guide-interactivity--docs).
 
 ## References
 

packages/css/src/components/tabs/README.md

@@ -4,7 +4,7 @@
 
 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
+## How to use
 
 - 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.

packages/react/documentation/coding-conventions.md

@@ -36,7 +36,7 @@ Subcomponents (e.g. `Grid.Cell`) are kept in separate files (e.g. `GridCell.tsx`
 
 ## Text for screen readers only
 
-Use [Visually Hidden](https://amsterdam.github.io/design-system/?path=/docs/react_containers-visually-hidden--docs) or the `ams-visually-hidden` utility class to hide content from sighted users but keep it accessible to non-visual user agents, such as screen readers.
+Use [Visually Hidden](https://designsystem.amsterdam/?path=/docs/components-containers-visually-hidden--docs) or the `ams-visually-hidden` utility class to hide content from sighted users but keep it accessible to non-visual user agents, such as screen readers.
 
 Do not use `aria-label`. Tools for automatic translation often [do not translate its value](https://adrianroselli.com/2019/11/aria-label-does-not-translate.html), and it may get overlooked when doing manual translation.
 

proprietary/assets/README.md

@@ -6,4 +6,5 @@ Assets for the City of Amsterdam
 
 ## Web app manifest, app icons and favicon
 
-See the Design System documentation for an [overview and examples of the manifest and these icons](https://amsterdam.github.io/design-system/?path=/docs/docs-assets-favicon-app-icons--docs).
+See the Design System documentation for guides on [the web manifest and application icons](https://designsystem.amsterdam/?path=/docs/docs-developer-guide-web-app--docs)
+and [the favicon](https://designsystem.amsterdam/?path=/docs/foundation-assets-favicon--docs).

storybook/config/preview.tsx

@@ -39,7 +39,8 @@ export const parameters = {
     storySort: {
       order: [
         'Docs',
-        ['Introduction', 'Getting started', 'Assets', 'Design Guidelines'],
+        ['Introduction', 'Developer Guide', ['Getting Started']],
+        'Foundation',
         'Components',
         ['Buttons', 'Containers', 'Feedback', 'Forms', 'Layout', 'Media', 'Navigation', 'Text'],
         'Pages',

storybook/src/components/Card/Card.docs.mdx

@@ -10,15 +10,15 @@ import README from "../../../../packages/css/src/components/card/README.md?raw";
 
 <Primary />
 
-## With Tagline
+## 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`.
 This ensures screen readers first read the heading and then the tagline.
 
 <Canvas of={CardStories.WithTagline} />
 
-## 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.

storybook/src/components/Column/Column.docs.mdx

@@ -10,7 +10,7 @@ import README from "../../../../packages/css/src/components/column/README.md?raw
 
 ## Design
 
-The five [space](/docs/docs-design-guidelines-space--docs) sizes are available for the size of the gap.
+The five [space](/docs/foundation-design-tokens-space--docs) sizes are available for the size of the gap.
 
 ## How to Use
 

storybook/src/components/DateInput/DateInput.docs.mdx

@@ -27,8 +27,8 @@ In other words, the input allows any valid combination of year, month, day, hour
 ### Invalid
 
 Indicates that the input value does not meet the specified constraints.
-An [Error Message](?path=/docs/components-forms-error-message--docs) must be displayed above the field.
-To highlight the error even more, the parent [Field](?path=/docs/components-forms-field--docs) component’s `invalid` prop must also be set.
+An [Error Message](/docs/components-forms-error-message--docs) must be displayed above the field.
+To highlight the error even more, the parent [Field](/docs/components-forms-field--docs) component’s `invalid` prop must also be set.
 
 <Canvas of={DateInputStories.Invalid} />
 

storybook/src/components/Field/Field.docs.mdx

@@ -12,7 +12,7 @@ import README from "../../../../packages/css/src/components/field/README.md?raw"
 
 <Controls />
 
-## With Description
+## With description
 
 A Field can have a description.
 Make sure to connect this description to the input in the Field,
@@ -21,7 +21,7 @@ Add an `aria-describedby` attribute to the input and provide the `id` of the des
 
 <Canvas of={FieldStories.WithDescription} />
 
-## With Error
+## With error
 
 A Field can indicate if the contained input has a validation error.
 Use Error Message to describe the error.

storybook/src/components/Grid/Grid.docs.mdx

@@ -20,7 +20,7 @@ On narrow screens, you will see three rows of four columns; on medium-wide scree
 
 <Controls />
 
-### Vertical Margin
+### Vertical margin
 
 Unlike the horizontal margins between columns, the vertical ones above and below are adjustable.
 The`paddingVertical`, `paddingTop`, and `paddingBottom` props add white space above and below the grid.
@@ -33,7 +33,7 @@ These white spaces also shrink and grow with the window width.
 
 <Canvas of={GridStories.VerticalSpace} />
 
-### Vertical White Space
+### Vertical white space
 
 A grid automatically creates multiple rows if the next cell no longer fits on the current row.
 
@@ -42,14 +42,14 @@ In some cases, more or less white space might be better.
 
 <Canvas of={GridStories.VerticalGap} />
 
-### Cells Spanning Columns
+### Cells spanning columns
 
 A cell defaults to spanning 1 column in the grid.
 Use the `span` prop to make a cell span more columns.
 
 <Canvas of={GridStories.SpanMultipleColumns} />
 
-### Different Widths
+### Different widths
 
 You can make the number of columns a cell spans depend on the window width.
 Use the `span` prop with 3 values for narrow, medium, and wide windows.
@@ -58,13 +58,13 @@ With `span={{ narrow: 4, medium: 6, wide: 8 }}`, this cell is 4 out of 4 columns
 
 <Canvas of={GridStories.ConfigureGridVariants} />
 
-### Full Width
+### Full width
 
 To make the cell full width – whether the grid has 4, 8, or 12 columns – use `span="all"`.
 
 <Canvas of={GridStories.SpanAllColumns} />
 
-### Start Position
+### Start position
 
 Each cell automatically starts in the next available position in the grid.
 You usually don’t need to specify a value of 1 explicitly.
@@ -79,7 +79,7 @@ An example with `start={2}`:
 
 <Canvas of={GridStories.StartPosition} />
 
-### Use Another HTML Element
+### Use another HTML element
 
 By default, a Grid Cell renders a `<div>`.
 Use the `as` prop to make your markup more semantic.