From 2ee81f2632e88d9a018b01bb1e954798e168ec9f Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Fri, 19 Jul 2024 15:31:07 +0200 Subject: [PATCH] =?UTF-8?q?chore:=20Organize=20=E2=80=98Docs=E2=80=99=20se?= =?UTF-8?q?ction=20(#1386)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: alimpens Co-authored-by: Aram <37216945+alimpens@users.noreply.github.com> --- NOTICE.md | 11 +- README.md | 6 +- documentation/storybook.md | 2 +- packages/css/src/components/card/README.md | 2 +- .../css/src/components/checkbox/README.md | 6 +- packages/css/src/components/dialog/README.md | 2 +- .../css/src/components/field-set/README.md | 2 +- packages/css/src/components/footer/README.md | 2 +- packages/css/src/components/grid/README.md | 2 +- packages/css/src/components/heading/README.md | 2 +- .../css/src/components/icon-button/README.md | 2 +- packages/css/src/components/icon/README.md | 6 +- packages/css/src/components/image/README.md | 2 +- packages/css/src/components/link/README.md | 2 +- .../css/src/components/page-heading/README.md | 2 +- .../css/src/components/page-menu/README.md | 4 +- .../css/src/components/pagination/README.md | 4 +- .../css/src/components/paragraph/README.md | 2 +- .../css/src/components/search-field/README.md | 2 +- .../css/src/components/spotlight/README.md | 2 +- packages/css/src/components/switch/README.md | 4 +- packages/css/src/components/tabs/README.md | 2 +- .../react/documentation/coding-conventions.md | 2 +- proprietary/assets/README.md | 3 +- storybook/config/preview.tsx | 3 +- storybook/src/components/Card/Card.docs.mdx | 4 +- .../src/components/Column/Column.docs.mdx | 2 +- .../components/DateInput/DateInput.docs.mdx | 4 +- storybook/src/components/Field/Field.docs.mdx | 4 +- storybook/src/components/Grid/Grid.docs.mdx | 14 +-- .../src/components/Header/Header.docs.mdx | 2 +- storybook/src/components/Icon/Icon.docs.mdx | 4 +- storybook/src/components/Link/Link.docs.mdx | 4 +- .../src/components/PageMenu/PageMenu.docs.mdx | 4 +- storybook/src/components/Row/Row.docs.mdx | 12 +- .../components/TextInput/TextInput.docs.mdx | 6 +- storybook/src/docs/borders.docs.mdx | 22 ---- .../breakpoints.docs.mdx | 2 +- .../getting-started.docs.mdx} | 6 +- .../interactivity.docs.mdx} | 10 +- .../{ => developer-guide}/language.docs.mdx | 2 +- .../{ => developer-guide}/usability.docs.mdx | 2 +- .../{ => developer-guide}/web-app.docs.mdx | 24 ++-- storybook/src/docs/introduction.docs.mdx | 109 +++++++++++++++++- storybook/src/docs/introduction.md | 107 ----------------- .../copyright.docs.mdx} | 4 +- .../docs/{ => terms-of-use}/license.docs.mdx | 4 +- .../assets}/favicon.docs.mdx | 20 ++-- .../{docs => foundation/assets}/font.docs.mdx | 21 ++-- .../assets/icons.docs.mdx} | 6 +- .../foundation/design-tokens/border.docs.mdx | 20 ++++ .../design-tokens/colour.docs.mdx} | 6 +- .../design-tokens}/grid.docs.mdx | 6 +- .../design-tokens}/space.docs.mdx | 2 +- .../design-tokens/text.docs.mdx} | 10 +- storybook/src/pages/Introduction.docs.mdx | 13 +-- .../ArticlePage/ArticlePage.docs.mdx | 2 +- .../amsterdam/FormPage/FormPage.docs.mdx | 2 +- .../amsterdam/HomePage/HomePage.docs.mdx | 4 +- 59 files changed, 269 insertions(+), 274 deletions(-) delete mode 100644 storybook/src/docs/borders.docs.mdx rename storybook/src/docs/{ => developer-guide}/breakpoints.docs.mdx (93%) rename storybook/src/docs/{getting-started-developers.docs.mdx => developer-guide/getting-started.docs.mdx} (91%) rename storybook/src/docs/{interactive-elements.docs.mdx => developer-guide/interactivity.docs.mdx} (96%) rename storybook/src/docs/{ => developer-guide}/language.docs.mdx (97%) rename storybook/src/docs/{ => developer-guide}/usability.docs.mdx (95%) rename storybook/src/docs/{ => developer-guide}/web-app.docs.mdx (90%) delete mode 100644 storybook/src/docs/introduction.md rename storybook/src/docs/{notice.docs.mdx => terms-of-use/copyright.docs.mdx} (54%) rename storybook/src/docs/{ => terms-of-use}/license.docs.mdx (54%) rename storybook/src/{docs => foundation/assets}/favicon.docs.mdx (90%) rename storybook/src/{docs => foundation/assets}/font.docs.mdx (62%) rename storybook/src/{docs/icon-gallery.docs.mdx => foundation/assets/icons.docs.mdx} (60%) create mode 100644 storybook/src/foundation/design-tokens/border.docs.mdx rename storybook/src/{docs/color.docs.mdx => foundation/design-tokens/colour.docs.mdx} (90%) rename storybook/src/{docs => foundation/design-tokens}/grid.docs.mdx (98%) rename storybook/src/{docs => foundation/design-tokens}/space.docs.mdx (99%) rename storybook/src/{docs/typography.docs.mdx => foundation/design-tokens/text.docs.mdx} (97%) diff --git a/NOTICE.md b/NOTICE.md index b24548f642..b1cfd6d66b 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -1,6 +1,6 @@ -# 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 diff --git a/README.md b/README.md index 5dc7bc6053..a8c4fc6916 100644 --- a/README.md +++ b/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. diff --git a/documentation/storybook.md b/documentation/storybook.md index ffdaabf219..6e3b9804f3 100644 --- a/documentation/storybook.md +++ b/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 diff --git a/packages/css/src/components/card/README.md b/packages/css/src/components/card/README.md index 82ad6adfdc..f1d97870d5 100644 --- a/packages/css/src/components/card/README.md +++ b/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. diff --git a/packages/css/src/components/checkbox/README.md b/packages/css/src/components/checkbox/README.md index 3c10f08f20..50b285c450 100644 --- a/packages/css/src/components/checkbox/README.md +++ b/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. diff --git a/packages/css/src/components/dialog/README.md b/packages/css/src/components/dialog/README.md index 0de31488ac..b05e331c97 100644 --- a/packages/css/src/components/dialog/README.md +++ b/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 | | :---------- | :--------------------------------------------------------------- | diff --git a/packages/css/src/components/field-set/README.md b/packages/css/src/components/field-set/README.md index 6120ee5d5a..bbfc105152 100644 --- a/packages/css/src/components/field-set/README.md +++ b/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. diff --git a/packages/css/src/components/footer/README.md b/packages/css/src/components/footer/README.md index 5a1a4b5cd4..4c3600180a 100644 --- a/packages/css/src/components/footer/README.md +++ b/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. diff --git a/packages/css/src/components/grid/README.md b/packages/css/src/components/grid/README.md index 4a8fcb566f..5f3fd5fef7 100644 --- a/packages/css/src/components/grid/README.md +++ b/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. diff --git a/packages/css/src/components/heading/README.md b/packages/css/src/components/heading/README.md index 23fceb290f..7aa65cf7a0 100644 --- a/packages/css/src/components/heading/README.md +++ b/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. diff --git a/packages/css/src/components/icon-button/README.md b/packages/css/src/components/icon-button/README.md index 90089f9a78..a61fbe8018 100644 --- a/packages/css/src/components/icon-button/README.md +++ b/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). diff --git a/packages/css/src/components/icon/README.md b/packages/css/src/components/icon/README.md index 8edf828734..214bf4a85b 100644 --- a/packages/css/src/components/icon/README.md +++ b/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). diff --git a/packages/css/src/components/image/README.md b/packages/css/src/components/image/README.md index 22fe2a6c9b..da8fbbcfff 100644 --- a/packages/css/src/components/image/README.md +++ b/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. diff --git a/packages/css/src/components/link/README.md b/packages/css/src/components/link/README.md index 4ebdda5886..bab8a6d7ab 100644 --- a/packages/css/src/components/link/README.md +++ b/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) diff --git a/packages/css/src/components/page-heading/README.md b/packages/css/src/components/page-heading/README.md index 7942ecc000..24723b97f8 100644 --- a/packages/css/src/components/page-heading/README.md +++ b/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. diff --git a/packages/css/src/components/page-menu/README.md b/packages/css/src/components/page-menu/README.md index 0abe55bd49..650f014ea6 100644 --- a/packages/css/src/components/page-menu/README.md +++ b/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. diff --git a/packages/css/src/components/pagination/README.md b/packages/css/src/components/pagination/README.md index d34d7c4b03..49b9541e15 100644 --- a/packages/css/src/components/pagination/README.md +++ b/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. diff --git a/packages/css/src/components/paragraph/README.md b/packages/css/src/components/paragraph/README.md index 86902efe98..a607c27b91 100644 --- a/packages/css/src/components/paragraph/README.md +++ b/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. diff --git a/packages/css/src/components/search-field/README.md b/packages/css/src/components/search-field/README.md index 4141af0e3c..e3d22915c1 100644 --- a/packages/css/src/components/search-field/README.md +++ b/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. diff --git a/packages/css/src/components/spotlight/README.md b/packages/css/src/components/spotlight/README.md index 69430f152c..051b22e1d8 100644 --- a/packages/css/src/components/spotlight/README.md +++ b/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; diff --git a/packages/css/src/components/switch/README.md b/packages/css/src/components/switch/README.md index 235d7517ff..b5de489a77 100644 --- a/packages/css/src/components/switch/README.md +++ b/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 diff --git a/packages/css/src/components/tabs/README.md b/packages/css/src/components/tabs/README.md index f1173d97a5..5e71e75650 100644 --- a/packages/css/src/components/tabs/README.md +++ b/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. diff --git a/packages/react/documentation/coding-conventions.md b/packages/react/documentation/coding-conventions.md index a1c205ae2e..2408402e79 100644 --- a/packages/react/documentation/coding-conventions.md +++ b/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. diff --git a/proprietary/assets/README.md b/proprietary/assets/README.md index a2ebf9ad27..4d3622fa25 100644 --- a/proprietary/assets/README.md +++ b/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). diff --git a/storybook/config/preview.tsx b/storybook/config/preview.tsx index 0d83a4401c..9deca76257 100644 --- a/storybook/config/preview.tsx +++ b/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', diff --git a/storybook/src/components/Card/Card.docs.mdx b/storybook/src/components/Card/Card.docs.mdx index 9e1d735e63..82f3aba4b7 100644 --- a/storybook/src/components/Card/Card.docs.mdx +++ b/storybook/src/components/Card/Card.docs.mdx @@ -10,7 +10,7 @@ import README from "../../../../packages/css/src/components/card/README.md?raw"; -## 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`. @@ -18,7 +18,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/Column/Column.docs.mdx b/storybook/src/components/Column/Column.docs.mdx index 10e63cd1e0..fdb5a262ea 100644 --- a/storybook/src/components/Column/Column.docs.mdx +++ b/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 diff --git a/storybook/src/components/DateInput/DateInput.docs.mdx b/storybook/src/components/DateInput/DateInput.docs.mdx index 5540419f4f..906735bf30 100644 --- a/storybook/src/components/DateInput/DateInput.docs.mdx +++ b/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. diff --git a/storybook/src/components/Field/Field.docs.mdx b/storybook/src/components/Field/Field.docs.mdx index 1d0aabfd1b..365c046593 100644 --- a/storybook/src/components/Field/Field.docs.mdx +++ b/storybook/src/components/Field/Field.docs.mdx @@ -12,7 +12,7 @@ import README from "../../../../packages/css/src/components/field/README.md?raw" -## 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 -## With Error +## With error A Field can indicate if the contained input has a validation error. Use Error Message to describe the error. diff --git a/storybook/src/components/Grid/Grid.docs.mdx b/storybook/src/components/Grid/Grid.docs.mdx index 372f641a6f..de1fb946fb 100644 --- a/storybook/src/components/Grid/Grid.docs.mdx +++ b/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 -### 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. -### 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. -### 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. -### 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 -### Full Width +### Full width To make the cell full width – whether the grid has 4, 8, or 12 columns – use `span="all"`. -### 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}`: -### Use Another HTML Element +### Use another HTML element By default, a Grid Cell renders a `
`. Use the `as` prop to make your markup more semantic. diff --git a/storybook/src/components/Header/Header.docs.mdx b/storybook/src/components/Header/Header.docs.mdx index 8d55b525e9..ac0e71f057 100644 --- a/storybook/src/components/Header/Header.docs.mdx +++ b/storybook/src/components/Header/Header.docs.mdx @@ -29,7 +29,7 @@ import { StatusBadge } from "../../docs/components/StatusBadge"; ## With links -Use a [Page Menu](?path=/docs/components-navigation-page-menu--docs) to add links. +Use a [Page Menu](/docs/components-navigation-page-menu--docs) to add links. A Page Menu in the Header should not wrap. diff --git a/storybook/src/components/Icon/Icon.docs.mdx b/storybook/src/components/Icon/Icon.docs.mdx index 185e7f02b9..21965ae008 100644 --- a/storybook/src/components/Icon/Icon.docs.mdx +++ b/storybook/src/components/Icon/Icon.docs.mdx @@ -11,7 +11,7 @@ import { StatusBadge } from "../../docs/components/StatusBadge"; {README} -## Usage +## How to use Use the React Icon component together with a React SVG component from `@amsterdam/design-system-react-icons`. Import this SVG as follows: @@ -36,7 +36,7 @@ Then, you can use it in the component like this: Icons can be used alongside text. Using the same text levels for both the icon and text aligns them perfectly. -[Consult the documentation on typography for more information](/docs/docs-design-guidelines-typography--docs). +[Consult the documentation on typography for more information](/docs/foundation-design-tokens-text--docs). diff --git a/storybook/src/components/Link/Link.docs.mdx b/storybook/src/components/Link/Link.docs.mdx index a90b571bc1..84f8b96036 100644 --- a/storybook/src/components/Link/Link.docs.mdx +++ b/storybook/src/components/Link/Link.docs.mdx @@ -14,7 +14,7 @@ import README from "../../../../packages/css/src/components/link/README.md?raw"; ## Examples -### Standalone Links +### Standalone links Place standalone links directly after a piece of content. Don’t use them in sentences or paragraphs. @@ -22,7 +22,7 @@ They should never have an associated icon. -### Inline Links +### Inline links Use inline links within sentences or paragraphs of text. An icon can be added to inline links, positioned after the link. diff --git a/storybook/src/components/PageMenu/PageMenu.docs.mdx b/storybook/src/components/PageMenu/PageMenu.docs.mdx index caa3c19036..e2d9da95cc 100644 --- a/storybook/src/components/PageMenu/PageMenu.docs.mdx +++ b/storybook/src/components/PageMenu/PageMenu.docs.mdx @@ -19,14 +19,14 @@ import { StatusBadge } from "../../docs/components/StatusBadge"; ### Alignment -In the [Header](?path=/docs/components-containers-header--docs), the menu aligns to the end of the line. +In the [Header](/docs/components-containers-header--docs), the menu aligns to the end of the line. ### Wrapping If all menu items do not fit on a single line, e.g. on a narrow screen or with zoomed-in text, they wrap to new lines. -This is often useful in the [Footer](?path=/docs/components-containers-footer--docs). +This is often useful in the [Footer](/docs/components-containers-footer--docs). The Header has its own responsive behaviour; its Page Menu should be configured not to wrap. diff --git a/storybook/src/components/Row/Row.docs.mdx b/storybook/src/components/Row/Row.docs.mdx index e8e5f8396c..b43e869bec 100644 --- a/storybook/src/components/Row/Row.docs.mdx +++ b/storybook/src/components/Row/Row.docs.mdx @@ -10,9 +10,9 @@ import README from "../../../../packages/css/src/components/row/README.md?raw"; ## Design -The five [space](/docs/docs-design-guidelines-space--docs) sizes are available for the width of the gap. +The five [space](/docs/foundation-design-tokens-space--docs) sizes are available for the width of the gap. -## How to Use +## How to use Wrap a Row around a set of components that need the same amount of white space between them. @@ -24,7 +24,7 @@ Wrap a Row around a set of components that need the same amount of white space b -### Horizontal Alignment +### Horizontal alignment Items in the row can be aligned horizontally in several ways: @@ -43,13 +43,13 @@ This example ensures that the spaces between and around all items are equally wi -#### End-align a Single Child +#### End-align a single child To align a single component to the right (in left-to-right languages), wrap it in a `` and set the `align` prop to `end`. -#### Align Opposing Texts +#### Align opposing texts This example shows a right-aligned link next to a heading. Use `align="between"` to position them at opposing ends of the row. @@ -58,7 +58,7 @@ Include `wrap` to allow the link to wrap to a new line if both components don’ -### Vertical Alignment +### Vertical alignment Items in the row can be aligned vertically in several ways: diff --git a/storybook/src/components/TextInput/TextInput.docs.mdx b/storybook/src/components/TextInput/TextInput.docs.mdx index 113953e553..f399a2bf3f 100644 --- a/storybook/src/components/TextInput/TextInput.docs.mdx +++ b/storybook/src/components/TextInput/TextInput.docs.mdx @@ -75,7 +75,7 @@ This text appears in the field when it is empty. It can give a brief hint about Don’t try too hard to find a suitable text for a placeholder. Inputs without placeholder text are just fine – the label and a description should be clear enough. -Do not use a placeholder instead of a [Label](?path=/docs/components-forms-label--docs). +Do not use a placeholder instead of a [Label](/docs/components-forms-label--docs). Follow the [guidelines for placeholder text](https://www.nldesignsystem.nl/richtlijnen/formulieren/placeholders) by NL Design System. @@ -84,8 +84,8 @@ Follow the [guidelines for placeholder text](https://www.nldesignsystem.nl/richt ### 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. diff --git a/storybook/src/docs/borders.docs.mdx b/storybook/src/docs/borders.docs.mdx deleted file mode 100644 index 0385ee7463..0000000000 --- a/storybook/src/docs/borders.docs.mdx +++ /dev/null @@ -1,22 +0,0 @@ -{/* @license CC0-1.0 */} - -import { Meta } from "@storybook/blocks"; - - - -# Borders - -## Widths - -We have 4 border widths: - -| Size | px | rem | Token name | -| :-------------- | :-: | :----: | :-------------------- | -| **Small** | 1 | 0.0625 | `ams.border.width.sm` | -| **Medium** | 2 | 0.125 | `ams.border.width.md` | -| **Large** | 3 | 0.1875 | `ams.border.width.lg` | -| **Extra large** | 4 | 0.25 | `ams.border.width.xl` | - -Use these widths when defining borders, -`box-shadow`s that look like borders, -`text-decoration-thickness`, et cetera. diff --git a/storybook/src/docs/breakpoints.docs.mdx b/storybook/src/docs/developer-guide/breakpoints.docs.mdx similarity index 93% rename from storybook/src/docs/breakpoints.docs.mdx rename to storybook/src/docs/developer-guide/breakpoints.docs.mdx index 60a91e18a8..c1b87af33d 100644 --- a/storybook/src/docs/breakpoints.docs.mdx +++ b/storybook/src/docs/developer-guide/breakpoints.docs.mdx @@ -2,7 +2,7 @@ import { Meta } from "@storybook/blocks"; - + # Breakpoints diff --git a/storybook/src/docs/getting-started-developers.docs.mdx b/storybook/src/docs/developer-guide/getting-started.docs.mdx similarity index 91% rename from storybook/src/docs/getting-started-developers.docs.mdx rename to storybook/src/docs/developer-guide/getting-started.docs.mdx index 9afb18dcda..15beb4f365 100644 --- a/storybook/src/docs/getting-started-developers.docs.mdx +++ b/storybook/src/docs/developer-guide/getting-started.docs.mdx @@ -2,9 +2,9 @@ import { Meta } from "@storybook/blocks"; - + -# Getting started for developers +# Getting Started ## React @@ -35,7 +35,7 @@ function App() { export default App; ``` -## Compact mode +## Compact Mode For applications, the large text and ample white space of the theme can be counterproductive. That’s why there is a compact mode. diff --git a/storybook/src/docs/interactive-elements.docs.mdx b/storybook/src/docs/developer-guide/interactivity.docs.mdx similarity index 96% rename from storybook/src/docs/interactive-elements.docs.mdx rename to storybook/src/docs/developer-guide/interactivity.docs.mdx index 76aee2052a..889bcc488a 100644 --- a/storybook/src/docs/interactive-elements.docs.mdx +++ b/storybook/src/docs/developer-guide/interactivity.docs.mdx @@ -2,9 +2,9 @@ import { Meta } from "@storybook/blocks"; - + -# Interactive elements +# Interactivity By this, we mean elements with which the user can interact, such as links, buttons and form fields. They must be clearly recognisable and easily distinguishable from non-interactive elements. @@ -18,7 +18,7 @@ Don’t use generic text fragments like “Click here” or “Read more” for A more meaningful text helps sighted users scan the page, and screen reader users navigate between links. It’s also beneficial to search engines. -### Relevant WCAG requirements: +### Relevant WCAG requirements - [WCAG 2.4.4](https://www.w3.org/TR/WCAG22/#link-purpose-in-context): it is clear to users what it means to click on a link - [WCAG 2.4.6](https://www.w3.org/TR/WCAG22/#headings-and-labels): use a label to describe interactive elements @@ -34,7 +34,7 @@ We use red for interactive elements that are part of an error message. Colour should not be the only indicator of interactivity so that people with difficulty perceiving colour differences can still see that an element is interactive. -### Relevant WCAG requirements: +### Relevant WCAG requirements - [WCAG 1.4.1](https://www.w3.org/TR/WCAG22/#use-of-color): color should not be the only way to indicate that something is interactive - [WCAG 1.4.3](https://www.w3.org/TR/WCAG21/#contrast-minimum): text has sufficient contrast with the background @@ -43,7 +43,7 @@ Colour should not be the only indicator of interactivity so that people with dif Interactive elements are at least 24 by 24 pixels in size, so they are easy to use for a large group of users. -### Relevant WCAG requirements: +### Relevant WCAG requirements - [WCAG 2.5.8](https://w3c.github.io/wcag/guidelines/22/#target-size-minimum): interactive elements are at least 24 by 24 pixels in size diff --git a/storybook/src/docs/language.docs.mdx b/storybook/src/docs/developer-guide/language.docs.mdx similarity index 97% rename from storybook/src/docs/language.docs.mdx rename to storybook/src/docs/developer-guide/language.docs.mdx index c9af206189..1360fe00b0 100644 --- a/storybook/src/docs/language.docs.mdx +++ b/storybook/src/docs/developer-guide/language.docs.mdx @@ -2,7 +2,7 @@ import { Meta } from "@storybook/blocks"; - + # Language diff --git a/storybook/src/docs/usability.docs.mdx b/storybook/src/docs/developer-guide/usability.docs.mdx similarity index 95% rename from storybook/src/docs/usability.docs.mdx rename to storybook/src/docs/developer-guide/usability.docs.mdx index d30ef3be37..312007433c 100644 --- a/storybook/src/docs/usability.docs.mdx +++ b/storybook/src/docs/developer-guide/usability.docs.mdx @@ -2,7 +2,7 @@ import { Meta } from "@storybook/blocks"; - + # Usability diff --git a/storybook/src/docs/web-app.docs.mdx b/storybook/src/docs/developer-guide/web-app.docs.mdx similarity index 90% rename from storybook/src/docs/web-app.docs.mdx rename to storybook/src/docs/developer-guide/web-app.docs.mdx index 6a147d3e3d..1325b1fdfa 100644 --- a/storybook/src/docs/web-app.docs.mdx +++ b/storybook/src/docs/developer-guide/web-app.docs.mdx @@ -1,22 +1,22 @@ {/* @license CC0-1.0 */} import { Meta } from "@storybook/blocks"; -import { WebAppIcons } from "./components/AppIcons"; +import { WebAppIcons } from "../components/AppIcons"; - + -# Progressive Web App: manifest and icons +# Web App -Turn a website into a Progressive Web App (PWA) with a Web Manifest and app icons. +Turn a website into a Progressive Web App (PWA) with a web manifest and app icons. Here’s how to publish a web app with the proper app names and icons. This set covers all combinations of common operating systems (Android, iOS, macOS, and Windows) and browsers (Chrome, Safari, Edge, and Firefox). -> There is seperate documentation on [how to add a website icon (a “favicon”)](/docs/docs-assets-web-app--docs). +> There is seperate documentation on [how to add a website icon (a “favicon”)](/docs/foundation-assets-favicon--docs). -## Usage +## How to use -### Install the assets +### Install assets First, install these assets as they come with the [Amsterdam Design System Assets](https://www.npmjs.com/package/@amsterdam/design-system-assets): @@ -24,7 +24,7 @@ First, install these assets as they come with the [Amsterdam Design System Asset npm i @amsterdam/design-system-assets ``` -### Link the installed assets +### Link assets You can manually [symlink (symbolic link)](https://en.wikipedia.org/wiki/Symbolic_link#POSIX_and_Unix-like_operating_systems) and copy the files to the root or a `public` folder next to where the `index.html` is located in your project. An advantage of symlinking is that it tracks changes to the assets when there are package updates. Symlinks are basically shortcuts to files or directories. @@ -79,13 +79,11 @@ Then link all these assets by placing the following tags in the ``: ``` -### Submit the changes +### Submit changes The symlink(s) and copied and edited files can be committed to the repository. -## Overview & examples - -### Web App Icons +## Web app icons @@ -109,7 +107,7 @@ Link the Web Manifest in the ``: > Note: only include a Web Manifest if you want the website to be installable as a Progressive Web App (PWA). > Browsers [may prompt the user to install the app](https://web.dev/learn/pwa/installation-prompt) on their device if a manifest is found. -## Further Reading +## Further reading - [_Web App Manifest_ on web.dev](https://web.dev/learn/pwa/web-app-manifest) - [_Web app manifests: Icons_ on MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Manifest/icons) diff --git a/storybook/src/docs/introduction.docs.mdx b/storybook/src/docs/introduction.docs.mdx index 5609ce004b..a0033d90aa 100644 --- a/storybook/src/docs/introduction.docs.mdx +++ b/storybook/src/docs/introduction.docs.mdx @@ -1,8 +1,111 @@ {/* @license CC0-1.0 */} -import { Markdown, Meta } from "@storybook/blocks"; -import introduction from "./introduction.md?raw"; +import { Meta } from "@storybook/blocks"; -{introduction} +# Amsterdam Design System + +This is the library for the user interfaces (UI) of all digital products offered by the City of Amsterdam. +It provides reusable components, patterns, and guidelines for teams working on websites and applications. + +It helps everyone work together faster and better, with more time to create actual value. +It makes it easier to align all software we create, purchase and use with our corporate identity. +By using it in all our channels, they appear the same, work similarly, are widely accessible, and inspire trust. + +## How does it work + +The most concrete products of the Amsterdam Design System are the reusable user interface components, such as buttons, text components, menus, and form fields. +They adhere to the City’s branding: colour, typography and dimensions. +They adapt responsively to different screens and devices and are accessible to everyone. + +We make these components available in various libraries so that designers and developers can use them in their work: + +### Figma + +[Find our Figma Library here](https://www.figma.com/file/9IGm6IdPUYizBNGsUnueBd/Amsterdam-Design-System?type=design&node-id=2927%3A29177&mode=design&t=6KlrHnKkHU2uZ9s9-1). +Various components, text styles and grid styles are ready to use in your designs. +Several others are in progress or being reviewed. +Refer to the introduction and legend on the cover page. + +### React + +On this website, you will find the React Library and documentation – use the table of contents on the left (on wide windows) or under the ‘Sidebar’ tab (on narrow ones). +These components can be installed and used in your application [via npm](https://www.npmjs.com/search?q=%40amsterdam%2Fdesign-system). + +### React Native + +While developing the Amsterdam App, many UI components have been built according to the updated corporate identity. +They are still [in that repository](https://github.com/Amsterdam/amsterdam-app-frontend) but will eventually be transferred to the design system for other apps to use. + +### CSS + +The components are usable without React by applying the correct classes. +If you would like to follow this approach, please let us know. + +### Salesforce + +For the new amsterdam.nl, we provide a library of correctly designed Lightning Web Components usable in Salesforce CMS. + +### Mendix + +We help applications implemented in this low-code platform match the corporate identity. + +## We build on the NL Design System + +Amsterdam Design System uses the architecture of [NL Design System](https://nldesignsystem.nl/). + +Thanks to the NL Design System, the entire government in the Netherlands can work together to provide understandable, user-friendly and accessible online services. +A service that is logical and coherent but not necessarily uniform, because it allows room for the identity of government organizations. + +The choice to connect to NL Design System also makes it easier for us to create different libraries. + +## Contact us + +### Join Teams + +If you work for the City of Amsterdam, [register now for the Design System team](https://teams.microsoft.com/l/team/19%3afYKS_RD2n1q4UhguA9jwEJk0A_VjYPO4TiLQjYlG_bo1%40thread.tacv2/conversations?groupId=381b5f11-b342-4a3a-8a78-8b371a90457d&tenantId=72fca1b1-2c2e-4376-a445-294d80196804) on MS Teams. +This way, you can easily stay informed, and we can keep in touch. +The channels have a lot of information you can read, and of course you are more than welcome to participate in threads. + +### Watch the demo + +For an overview of what’s new, you are welcome to our four-weekly Tuesday demo at 11:00 AM. +You can also ask questions and provide feedback here. +You can find the invitation in the ‘Sprint review’ channel in MS Teams. +We record the sessions for later viewing. + +### Contribute via Git + +[The code repository is on GitHub](http://github.com/Amsterdam/design-system) and is open source. +Your pull requests and issues are welcome. + +### Send a message + +Do you want to know how the design system can help you? Questions about our working method or suggestions for the roadmap? +Let us know; we are happy to work with you. + +Don’t hesitate to get in touch with us by email at [designsystem@amsterdam.nl](designsystem@amsterdam.nl). + +The current core team: +Aram Limpens, +Bas Kroese, +Inge de Bondt (lead), +Niels Roozemond, +Ruben Sibon, +and +Vincent Smedinga (lead). + +Contributions by: +Bettina Slee, +Hee Chan van der Haar, +Jesper Duinker, +Justin Straver, +Laurens van den Akker, +Mike Alders, +Nico Druif, +Renate Schwarzler, +Rick Zweers, +Soesanto Arp, +and +Tanja van der Heide. diff --git a/storybook/src/docs/introduction.md b/storybook/src/docs/introduction.md deleted file mode 100644 index 3b9889ba83..0000000000 --- a/storybook/src/docs/introduction.md +++ /dev/null @@ -1,107 +0,0 @@ - - -# Amsterdam Design System - -This is the library for the user interfaces (UI) of all digital products offered by the City of Amsterdam. -It provides reusable components, patterns, and guidelines for teams working on websites and applications. - -It helps everyone work together faster and better, with more time to create actual value. -It makes it easier to align all software we create, purchase and use with our corporate identity. -By using it in all our channels, they appear the same, work similarly, are widely accessible, and inspire trust. - -## How does it work - -The most concrete products of the Amsterdam Design System are the reusable user interface components, such as buttons, text components, menus, and form fields. -They adhere to the City’s branding: colour, typography and dimensions. -They adapt responsively to different screens and devices and are accessible to everyone. - -We make these components available in various libraries so that designers and developers can use them in their work: - -### Figma - -[Find our Figma Library here](https://www.figma.com/file/9IGm6IdPUYizBNGsUnueBd/Amsterdam-Design-System?type=design&node-id=2927%3A29177&mode=design&t=6KlrHnKkHU2uZ9s9-1). -Various components, text styles and grid styles are ready to use in your designs. -Several others are in progress or being reviewed. -Refer to the introduction and legend on the cover page. - -### React - -On this website, you will find the React Library and documentation – use the table of contents on the left (on wide windows) or under the ‘Sidebar’ tab (on narrow ones). -These components can be installed and used in your application [via npm](https://www.npmjs.com/search?q=%40amsterdam%2Fdesign-system). - -### React Native - -While developing the Amsterdam App, many UI components have been built according to the updated corporate identity. -They are still [in that repository](https://github.com/Amsterdam/amsterdam-app-frontend) but will eventually be transferred to the design system for other apps to use. - -### CSS - -The components are usable without React by applying the correct classes. -If you would like to follow this approach, please let us know. - -### Salesforce - -For the new amsterdam.nl, we provide a library of correctly designed Lightning Web Components usable in Salesforce CMS. - -### Mendix - -We help applications implemented in this low-code platform match the corporate identity. - -## We build on the NL Design System - -Amsterdam Design System uses the architecture of [NL Design System](https://nldesignsystem.nl/). - -Thanks to the NL Design System, the entire government in the Netherlands can work together to provide understandable, user-friendly and accessible online services. -A service that is logical and coherent but not necessarily uniform, because it allows room for the identity of government organizations. - -The choice to connect to NL Design System also makes it easier for us to create different libraries. - -## Contact us - -### Join Teams - -If you work for the City of Amsterdam, [register now for the Design System team](https://teams.microsoft.com/l/team/19%3afYKS_RD2n1q4UhguA9jwEJk0A_VjYPO4TiLQjYlG_bo1%40thread.tacv2/conversations?groupId=381b5f11-b342-4a3a-8a78-8b371a90457d&tenantId=72fca1b1-2c2e-4376-a445-294d80196804) on MS Teams. -This way, you can easily stay informed, and we can keep in touch. -The channels have a lot of information you can read, and of course you are more than welcome to participate in threads. - -### Watch the demo - -For an overview of what’s new, you are welcome to our four-weekly Tuesday demo at 11:00 AM. -You can also ask questions and provide feedback here. -You can find the invitation in the ‘Sprint review’ channel in MS Teams. -We record the sessions for later viewing. - -### Contribute via Git - -[The code repository is on GitHub](http://github.com/Amsterdam/design-system) and is open source. -Your pull requests and issues are welcome. - -### Send a message - -Do you want to know how the design system can help you? Questions about our working method or suggestions for the roadmap? -Let us know; we are happy to work with you. - -Don’t hesitate to get in touch with us by email at . - -The current core team: -Aram Limpens, -Bas Kroese, -Inge de Bondt (lead), -Jesper Duinker, -Niels Roozemond, -Ruben Sibon, -and -Vincent Smedinga (lead). - -Contributions by: -Bettina Slee, -Hee Chan van der Haar, -Justin Straver, -Laurens van den Akker, -Mike Alders, -Nico Druif, -Renate Schwarzler, -Rick Zweers, -Soesanto Arp, -and -Tanja van der Heide. diff --git a/storybook/src/docs/notice.docs.mdx b/storybook/src/docs/terms-of-use/copyright.docs.mdx similarity index 54% rename from storybook/src/docs/notice.docs.mdx rename to storybook/src/docs/terms-of-use/copyright.docs.mdx index 1fe0c1fda1..a8a520e817 100644 --- a/storybook/src/docs/notice.docs.mdx +++ b/storybook/src/docs/terms-of-use/copyright.docs.mdx @@ -1,8 +1,8 @@ {/* @license CC0-1.0 */} import { Markdown, Meta } from "@storybook/blocks"; -import NOTICE from "../../../NOTICE.md?raw"; +import NOTICE from "../../../../NOTICE.md?raw"; - + {NOTICE} diff --git a/storybook/src/docs/license.docs.mdx b/storybook/src/docs/terms-of-use/license.docs.mdx similarity index 54% rename from storybook/src/docs/license.docs.mdx rename to storybook/src/docs/terms-of-use/license.docs.mdx index ada2ccf9b1..22d9784c30 100644 --- a/storybook/src/docs/license.docs.mdx +++ b/storybook/src/docs/terms-of-use/license.docs.mdx @@ -1,8 +1,8 @@ {/* @license CC0-1.0 */} import { Markdown, Meta } from "@storybook/blocks"; -import LICENSE from "../../../LICENSE.md?raw"; +import LICENSE from "../../../../LICENSE.md?raw"; - + {LICENSE} diff --git a/storybook/src/docs/favicon.docs.mdx b/storybook/src/foundation/assets/favicon.docs.mdx similarity index 90% rename from storybook/src/docs/favicon.docs.mdx rename to storybook/src/foundation/assets/favicon.docs.mdx index 087e478a23..0e9e305b86 100644 --- a/storybook/src/docs/favicon.docs.mdx +++ b/storybook/src/foundation/assets/favicon.docs.mdx @@ -1,22 +1,22 @@ {/* @license CC0-1.0 */} import { Meta } from "@storybook/blocks"; -import { AppleTouchIcon, Favicon, SvgIcon } from "./components/AppIcons"; +import { AppleTouchIcon, Favicon, SvgIcon } from "../../docs/components/AppIcons"; - + -# Favicon: the website's icon +# Favicon Represent the website in bookmarks, on home screens, in syndication and other tools. Here’s how to display a website icon (a favicon) in the web browser. This set covers all common browsers (Chrome, Safari, Edge, and Firefox). -> There is seperate documentation on [how to publish a web app with the proper app names and icons](/docs/docs-assets-web-app--docs). +> There is seperate documentation on [how to publish a web app with the proper app names and icons](/docs/docs-developer-guide-web-app--docs). -## Usage +## How to use -### Install the assets +### Install assets First, install these assets as they come with the [Amsterdam Design System Assets](https://www.npmjs.com/package/@amsterdam/design-system-assets): @@ -24,7 +24,7 @@ First, install these assets as they come with the [Amsterdam Design System Asset npm i @amsterdam/design-system-assets ``` -### Link the installed assets +### Link assets You can manually [symlink (symbolic link)](https://en.wikipedia.org/wiki/Symbolic_link#POSIX_and_Unix-like_operating_systems) and copy the files to the root or a `public` folder next to where the `index.html` is located in your project. An advantage of symlinking is that it tracks changes to the assets when there are package updates. Symlinks are basically shortcuts to files or directories. @@ -60,11 +60,11 @@ Then link all these assets by placing the following tags in the ``: ``` -### Submit the changes +### Submit Changes The symlink(s) and edited files can be committed to the repository. -## Overview & examples +## Examples ### Favicon @@ -96,7 +96,7 @@ An iPhone or iPad uses this image when adding the webpage as a shortcut to your ``` -## Further Reading +## Further reading - [_How to Favicon in 2024: Six files that fit most needs_ by Andrey Sitnik](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs) - [_Definitive edition of “How to Favicon” in 2023_ by Masa Kudamatsu](https://dev.to/masakudamatsu/favicon-nightmare-how-to-maintain-sanity-3al7) diff --git a/storybook/src/docs/font.docs.mdx b/storybook/src/foundation/assets/font.docs.mdx similarity index 62% rename from storybook/src/docs/font.docs.mdx rename to storybook/src/foundation/assets/font.docs.mdx index 6e02986987..242b70cb7c 100644 --- a/storybook/src/docs/font.docs.mdx +++ b/storybook/src/foundation/assets/font.docs.mdx @@ -2,16 +2,16 @@ import { Meta, Typeset } from "@storybook/blocks"; - + # Font -We use the Amsterdam Sans font. +We have our own font: Amsterdam Sans. -This is a typeface with a clear, open appearance that complements the Andreaskruisen well. +Its clear, open appearance complements the St. Andrew’s Crosses in the logo. The font is legible both offline and online, so we use it for all communication means. -In this sentence, you can see how all letters and numbers look: +This sentence shows how all letters and numbers look: -## Installation +## How to use If you are working with npm, include our package `@amsterdam/design-system-assets` in your dependencies. Then import `@amsterdam/design-system-assets/font/index.css` at the beginning of your stylesheet. @@ -28,8 +28,8 @@ Then import `@amsterdam/design-system-assets/font/index.css` at the beginning of You can also host the font yourself and include it in your application. Request it through the form below. -If it’s not possible to use Amsterdam Sans, apply the Arial font, or the generic sans-serif font of the device. -In all cases, specify these alternatives in case downloading the font for the user fails, or while it is in progress: +If it is impossible to use Amsterdam Sans, use the Arial font, or the device’s generic sans-serif. +Always specify these alternatives if downloading the font for the user fails, or while it is in progress: ```css .class { @@ -37,13 +37,12 @@ In all cases, specify these alternatives in case downloading the font for the us } ``` -## Requests +## Requesting a license The font is explicitly not freely available. -Amsterdam Sans is exclusively for use by employees of the City of Amsterdam, amsterdam&partners, and suppliers working for these organizations. - +Amsterdam Sans is licensed exclusively to the City of Amsterdam and amsterdam&partners. Request the font files through the [Amsterdam Sans request form](https://formulier.amsterdam.nl/thema/huisstijl/amsterdam-sans-aanvragen). -## More Information +## More information For additional details about the font, refer to [Typography on Stijlweb](https://amsterdam.nl/stijlweb/basiselementen/typografie/). diff --git a/storybook/src/docs/icon-gallery.docs.mdx b/storybook/src/foundation/assets/icons.docs.mdx similarity index 60% rename from storybook/src/docs/icon-gallery.docs.mdx rename to storybook/src/foundation/assets/icons.docs.mdx index 6158721d78..739f1acf89 100644 --- a/storybook/src/docs/icon-gallery.docs.mdx +++ b/storybook/src/foundation/assets/icons.docs.mdx @@ -1,10 +1,10 @@ {/* @license CC0-1.0 */} import { Meta } from "@storybook/blocks"; -import { AmsterdamIconGallery } from "./components/AmsterdamIconGallery"; -import { StatusBadge } from "./components/StatusBadge"; +import { AmsterdamIconGallery } from "../../docs/components/AmsterdamIconGallery"; +import { StatusBadge } from "../../docs/components/StatusBadge"; - + diff --git a/storybook/src/foundation/design-tokens/border.docs.mdx b/storybook/src/foundation/design-tokens/border.docs.mdx new file mode 100644 index 0000000000..d1e890de12 --- /dev/null +++ b/storybook/src/foundation/design-tokens/border.docs.mdx @@ -0,0 +1,20 @@ +{/* @license CC0-1.0 */} + +import { Meta } from "@storybook/blocks"; + + + +# Border + +Elements that have a border, outline or underline use one of these widths. + +## Widths + +We have 4 border widths: + +| Size | px | rem | Token name | Example | +| :-------------- | :-: | :----: | :-------------------- | ----------------------------------------------------------------------------------------- | +| **Small** | 1 | 0.0625 | `ams.border.width.sm` |
| +| **Medium** | 2 | 0.125 | `ams.border.width.md` |
| +| **Large** | 3 | 0.1875 | `ams.border.width.lg` |
| +| **Extra large** | 4 | 0.25 | `ams.border.width.xl` |
| diff --git a/storybook/src/docs/color.docs.mdx b/storybook/src/foundation/design-tokens/colour.docs.mdx similarity index 90% rename from storybook/src/docs/color.docs.mdx rename to storybook/src/foundation/design-tokens/colour.docs.mdx index 8180cd3ef7..fc547670cf 100644 --- a/storybook/src/docs/color.docs.mdx +++ b/storybook/src/foundation/design-tokens/colour.docs.mdx @@ -2,10 +2,10 @@ import tokens from "@amsterdam/design-system-tokens/dist/index.json"; import { Meta } from "@storybook/blocks"; -import { ColorPalette } from "./components/ColorPalette"; -import { StatusBadge } from "./components/StatusBadge"; +import { ColorPalette } from "../../docs/components/ColorPalette"; +import { StatusBadge } from "../../docs/components/StatusBadge"; - + diff --git a/storybook/src/docs/grid.docs.mdx b/storybook/src/foundation/design-tokens/grid.docs.mdx similarity index 98% rename from storybook/src/docs/grid.docs.mdx rename to storybook/src/foundation/design-tokens/grid.docs.mdx index 62398ab152..b53d440b10 100644 --- a/storybook/src/docs/grid.docs.mdx +++ b/storybook/src/foundation/design-tokens/grid.docs.mdx @@ -2,7 +2,7 @@ import { Meta } from "@storybook/blocks"; - + # Grid @@ -192,7 +192,7 @@ Layout and text relate in various ways. ### Scaling typography -Like the grid, the [text sizes](/docs/docs-design-guidelines-typography--docs) respond to the window width. +Like the grid, the [text sizes](/docs/foundation-design-tokens-text--docs) respond to the window width. This ensures that content looks good on as many window widths and with various personal settings. ### Zooming or enlarged text @@ -202,6 +202,6 @@ The dimensions of the grid take this into account. The breakpoints scale with the effective text size. This way, the amount of columns changes earlier, and large content still fits well. -## Related Components +## Related components - [Grid](/docs/components-layout-grid--docs) diff --git a/storybook/src/docs/space.docs.mdx b/storybook/src/foundation/design-tokens/space.docs.mdx similarity index 99% rename from storybook/src/docs/space.docs.mdx rename to storybook/src/foundation/design-tokens/space.docs.mdx index e571fa4382..c959909682 100644 --- a/storybook/src/docs/space.docs.mdx +++ b/storybook/src/foundation/design-tokens/space.docs.mdx @@ -2,7 +2,7 @@ import { Meta } from "@storybook/blocks"; - + # Space diff --git a/storybook/src/docs/typography.docs.mdx b/storybook/src/foundation/design-tokens/text.docs.mdx similarity index 97% rename from storybook/src/docs/typography.docs.mdx rename to storybook/src/foundation/design-tokens/text.docs.mdx index 183be58796..9539f68006 100644 --- a/storybook/src/docs/typography.docs.mdx +++ b/storybook/src/foundation/design-tokens/text.docs.mdx @@ -2,11 +2,11 @@ import { Meta, Typeset } from "@storybook/blocks"; - + -# Typography +# Text -## Text Size +## Size ### Seven Text Levels @@ -180,10 +180,10 @@ When the mouse hovers over the link, the line at the top becomes one pixel thick ### Letter spacing -The space between letters (kerning) has been optimized in the typeface. +The space between letters (kerning) has been optimized in the font file. Adjusting kerning is not allowed. -## Other Properties +## Other properties ### Contrast diff --git a/storybook/src/pages/Introduction.docs.mdx b/storybook/src/pages/Introduction.docs.mdx index a5f6bf6eb5..cece88f999 100644 --- a/storybook/src/pages/Introduction.docs.mdx +++ b/storybook/src/pages/Introduction.docs.mdx @@ -4,25 +4,25 @@ import { Meta } from "@storybook/blocks"; -# Introduction +# Pages -This section demonstrates how to compose pages using the Design System’s components. +This section demonstrates how to compose entire pages using the Design System’s components. It uses the latest release of the libraries, without any customizations, giving an honest representation of what can be achieved with them and how they work in the browser. -Currently, we offer a home page and an article page for the upcoming Amsterdam.nl website. +We offer a home page, an article page and a form for the upcoming Amsterdam.nl website. ## Documentation -The ‘Docs’ page explains the design decisions for this type of page and how to build it. +The ‘Docs’ page for each page explains its design decisions and how to build it. ## Examples -Each example, of which the first is called ‘Default’, shows the actual page in its entirety. +The ‘Default’ example shows the actual page in its entirety. ### Flexible content Reload an example to get new random texts and images. -Use the Control tab to experiment with your own content. +Use the Control tab to fill in your own content and see how that looks. ### Test for accessibility and see HTML output @@ -36,4 +36,3 @@ The buttons in the toolbar offer various features, of which the ‘three layered ### See the page full-screen Use the ‘Go to full screen’ (or press `alt+F`) or ‘Open canvas in new tab’ buttons to the top right to see the entire page. -Alternatively, press `alt+S,T,A` to hide the three panels. diff --git a/storybook/src/pages/amsterdam/ArticlePage/ArticlePage.docs.mdx b/storybook/src/pages/amsterdam/ArticlePage/ArticlePage.docs.mdx index b25db9d7ea..0816da31a3 100644 --- a/storybook/src/pages/amsterdam/ArticlePage/ArticlePage.docs.mdx +++ b/storybook/src/pages/amsterdam/ArticlePage/ArticlePage.docs.mdx @@ -5,6 +5,6 @@ import * as ArticleStories from "./ArticlePage.stories.tsx"; -# Article Page +# Article page This page type is for news or similar kinds of articles. diff --git a/storybook/src/pages/amsterdam/FormPage/FormPage.docs.mdx b/storybook/src/pages/amsterdam/FormPage/FormPage.docs.mdx index 3bb065c851..dba57f606d 100644 --- a/storybook/src/pages/amsterdam/FormPage/FormPage.docs.mdx +++ b/storybook/src/pages/amsterdam/FormPage/FormPage.docs.mdx @@ -5,6 +5,6 @@ import * as FormStories from "./FormPage.stories.tsx"; -# Form Page +# Form page This simple example presents various types of fields. diff --git a/storybook/src/pages/amsterdam/HomePage/HomePage.docs.mdx b/storybook/src/pages/amsterdam/HomePage/HomePage.docs.mdx index db51cd843a..cc2f7e30da 100644 --- a/storybook/src/pages/amsterdam/HomePage/HomePage.docs.mdx +++ b/storybook/src/pages/amsterdam/HomePage/HomePage.docs.mdx @@ -5,7 +5,9 @@ import * as HomeStories from "./HomePage.stories.tsx"; -# Home Page +# Home page + +The starting page of an application generally provides a broad overview of subjects, common tasks, and recent articles. ## Layout