From 4c141fc778db2c4f8b92befaa94c1471fd03fdba Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Wed, 16 Oct 2024 15:25:58 +0200 Subject: [PATCH 01/17] Remove mentions of Salesforce --- README.md | 2 +- documentation/storybook.md | 8 -------- storybook/src/docs/introduction.docs.mdx | 4 ---- 3 files changed, 1 insertion(+), 13 deletions(-) diff --git a/README.md b/README.md index a8c4fc6916..095f2c4de9 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ This helps everyone work faster and better, with more time to create value. To our citizens and businesses, all our channels look the same and work similarly; they are broadly accessible and evoke trust. -We aim to create libraries for, or support otherwise, Figma, CSS, React, React Native, Salesforce, and Mendix. +We aim to create libraries for, or support otherwise, Figma, CSS, React, React Native, and Mendix. ## Related resources diff --git a/documentation/storybook.md b/documentation/storybook.md index 89c00f6276..6894e63553 100644 --- a/documentation/storybook.md +++ b/documentation/storybook.md @@ -90,11 +90,3 @@ argTypes: { Decorators are not shown in the code view, `args.children` are. 3. Always check your stories’ code view. 4. `args.children` can be an array, separated by commas and given ascending numbers as keys. - -## Future plans - -We are considering what to document for each component in the various libraries. - -We aim to document each implementation of each component – CSS, React, React Native, and Salesforce Lightning Web Components. - -We’re eager to get the most out of Storybook features for accessibility, testing, and more. diff --git a/storybook/src/docs/introduction.docs.mdx b/storybook/src/docs/introduction.docs.mdx index a0033d90aa..a85a5ee298 100644 --- a/storybook/src/docs/introduction.docs.mdx +++ b/storybook/src/docs/introduction.docs.mdx @@ -43,10 +43,6 @@ They are still [in that repository](https://github.com/Amsterdam/amsterdam-app-f 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. From e4094e7e7f2a2b1dc9aeb58435aa72b51aa5b4f5 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Wed, 16 Oct 2024 15:56:36 +0200 Subject: [PATCH 02/17] Make all titles consistent --- packages/css/README.md | 2 +- packages/react/README.md | 2 +- proprietary/assets/README.md | 2 +- proprietary/react-icons/README.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/css/README.md b/packages/css/README.md index 22f13f76de..0489e5a53b 100644 --- a/packages/css/README.md +++ b/packages/css/README.md @@ -1,6 +1,6 @@ -# CSS Components +# Amsterdam Design System: CSS components CSS components are developed using BEM class names and the stylesheets can be included in your page without side-effects. Apply the class names to your elements to make them stylable using design tokens. diff --git a/packages/react/README.md b/packages/react/README.md index 5b60d8e2a0..66db2db2dd 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -1,6 +1,6 @@ -# Component library for React apps +# Amsterdam Design System: React components The `@amsterdam/design-system-react` package contains React implementations of various components. You can use this package in React apps. diff --git a/proprietary/assets/README.md b/proprietary/assets/README.md index 561c71101f..894c49f988 100644 --- a/proprietary/assets/README.md +++ b/proprietary/assets/README.md @@ -1,6 +1,6 @@ -# Assets +# Amsterdam Design System: Assets Assets for the City of Amsterdam diff --git a/proprietary/react-icons/README.md b/proprietary/react-icons/README.md index 23dd5361a9..d54feb262c 100644 --- a/proprietary/react-icons/README.md +++ b/proprietary/react-icons/README.md @@ -1,5 +1,5 @@ -# Icons React +# Amsterdam Design System: React icons Icon svgs as React components From 06e793f7d56b5dca0971430bbb86864b44ea049d Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Thu, 17 Oct 2024 15:04:09 +0200 Subject: [PATCH 03/17] Update README for other four packages --- packages/css/README.md | 109 ++++++++++++++++++++++++------ packages/react/README.md | 94 +++++++++++++++++++++++--- proprietary/assets/README.md | 68 +++++++++++++++++-- proprietary/react-icons/README.md | 45 +++++++++++- 4 files changed, 279 insertions(+), 37 deletions(-) diff --git a/packages/css/README.md b/packages/css/README.md index 0489e5a53b..b8248dcc7e 100644 --- a/packages/css/README.md +++ b/packages/css/README.md @@ -2,26 +2,86 @@ # Amsterdam Design System: CSS components -CSS components are developed using BEM class names and the stylesheets can be included in your page without side-effects. -Apply the class names to your elements to make them stylable using design tokens. +This package provides stylesheets for all components in the [Amsterdam Design System](https://designsystem.amsterdam) and some general utilities. +Use it to apply the visual design of the City of Amsterdam to your HTML elements or non-React components. -`npm install @amsterdam/design-system-css` +## About -Theoretically you can include the components in your HTML page like so, but this is not the typical use case of this library: +The set of classes for a component can be seen as a blueprint for its markup and features. +An `.ams-component` root selector applies the essential styles of the component to its element, and additional classes like `.ams-component--variant` modify its appearance or behaviour. + +Our [React components](https://www.npmjs.com/package/@amsterdam/design-system-react) use these classes in the HTML they render. +You should use that package if your application uses React. + +The classes employ the [naming convention of NL Design System](https://nldesignsystem.nl/handboek/developer/architectuur#bem-class-names-voor-css). +Other communities only need to overwrite design tokens to use our components with their branding. + +## Motivation + +Publishing the stylesheets as a separate package saves a lot of work when replicating components in other libraries, platforms, or Saas-applications. +This is a powerful approach to implement the design system across different technologies. + +The classes act like a contract between the component’s definition and its implementations. +As a bonus, updates to tokens or styles can be propagated to all of them. + +## Installation + +The stylesheets reference our [design tokens](https://www.npmjs.com/package/@amsterdam/design-system-tokens). +Both packages need to be installed. + +```sh +npm install + @amsterdam/design-system-css + @amsterdam/design-system-tokens +``` + +```sh +pnpm add + @amsterdam/design-system-css + @amsterdam/design-system-tokens +``` + +```sh +yarn add + @amsterdam/design-system-css + @amsterdam/design-system-tokens +``` + +## Usage + +### In JavaScript + +Import the main stylesheet and use the class names in your markup. + +```ts +import "@amsterdam/design-system-tokens/dist/index.css"; + +export const App = () => ( +
+

Hello, world!

+
+) +``` + +### In HTML + +Although it is not a typical use case, the stylesheet can be included in an HTML page directly. ```html - Example page - + Amsterdam Design System + - +

Hello, world!

``` +### With CSS Modules + The BEM class names can be particularly useful to include only the CSS you need using [CSS modules](https://css-tricks.com/css-modules-part-1-need/) ([in React](https://css-tricks.com/css-modules-part-3-react/)). ```js @@ -39,34 +99,39 @@ export default class ExamplePage extends React.Component { } ``` -## 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. -To use the compact mode, import the compact css **after** theme css, like so: +[Load the compact tokens](https://github.com/Amsterdam/design-system/blob/main/proprietary/tokens/README.md) to use the compact appearance of the design system, e.g. for applications. +They override the spacious ones; the stylesheets can remain unchanged. -```javascript -import "@amsterdam/design-system-tokens/dist/index.css"; -import "@amsterdam/design-system-tokens/dist/compact.css"; -``` - -## Global styles +### Global styles Some elements of your document are out of reach for the Design System components. However, their styles can influence the appearance of the components. -### Base font size +#### Keep the base font size Do not change the base font-size – e.g. through `html { font-size: 62.5% }`. Out typography system expects `1rem` to be the browser default of 16 pixels. -If your application does use a rule like this and you can’t easily remove it, adopt the Design System components gradually by setting `font-size: 100%` on the parts that use them. +If you can’t easily remove such an approach from your application, adopt the Design System components gradually by setting `font-size: 100%` on elements that use them. -### Remove body margin +#### Remove the body margin If you haven’t removed the margin on the `` element that browsers set by default, you can add our `ams-body` class to it to do so. -### Use our extra bold font weight +#### Use extra bold text We only use the regular and extra bold weights of our font, Amsterdam Sans. -Apply `font-weight: var(--ams-text-font-weight-bold)` to elements that display bold text, e.g. `b`, `strong`, and `dt`. +Apply `font-weight: var(--ams-text-font-weight-bold)` to elements that display bold text like `b`, `strong`, and `dt`. + +## Updating + +We follow semantic versioning and publish a [change log](https://github.com/Amsterdam/design-system/blob/main/packages/css/CHANGELOG.md) to guide you through updates. +The classes are a public API of the design system. +Note that detecting changed or deleted classes is still a manual process. + +## Support + +Contact us if you have a question, find an issue, or want to contribute. +Find ways to reach us on [designsystem.amsterdam](https://designsystem.amsterdam/?path=/docs/docs-introduction--docs#send-a-message). diff --git a/packages/react/README.md b/packages/react/README.md index 66db2db2dd..bebf71bdaf 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -2,17 +2,91 @@ # Amsterdam Design System: React components -The `@amsterdam/design-system-react` package contains React implementations of various components. -You can use this package in React apps. +This package provides all React components from the [Amsterdam Design System](https://designsystem.amsterdam). +Use it to compose pages in your website or application. -The design tokens and CSS used in these components are published in separate npm packages, -so don’t forget to install and include `@amsterdam/design-system-tokens` and `@amsterdam/design-system-css` too. +## About -## Stability of the components +This package is the primary entry point for digital services that we build in-house. +We’ve adopted the architecture of [NL Design System](https://nldesignsystem.nl/). -The React Library has not yet reached a 1.0.0 version. -However, most of them are stable enough to be used in production. -Components that have known issues, or for which we anticipate API changes, show a ‘beta’ badge on their page. +## Installation -Make sure you specify the exact version as dependency. -You can then schedule an upgrade to the latest version when you have time to test for regressions. +The components reference our +[stylesheets](https://www.npmjs.com/package/@amsterdam/design-system-css), +[design tokens](https://www.npmjs.com/package/@amsterdam/design-system-tokens) +[assets](https://www.npmjs.com/package/@amsterdam/design-system-assets), +and [React icons](https://www.npmjs.com/package/@amsterdam/design-system-react-icons). +Install all packages. + +```sh +npm install + @amsterdam/design-system-assets + @amsterdam/design-system-css + @amsterdam/design-system-react + @amsterdam/design-system-react-icons + @amsterdam/design-system-tokens +``` + +```sh +pnpm add + @amsterdam/design-system-assets + @amsterdam/design-system-css + @amsterdam/design-system-react + @amsterdam/design-system-react-icons + @amsterdam/design-system-tokens +``` + +```sh +yarn add + @amsterdam/design-system-assets + @amsterdam/design-system-css + @amsterdam/design-system-react + @amsterdam/design-system-react-icons + @amsterdam/design-system-tokens +``` + +The React components themselves are unstyled. +[Override the design tokens](https://github.com/Amsterdam/design-system/blob/main/proprietary/tokens/README.md) to use them with a different branding. + +## Usage + +Import the stylesheets for the fonts, tokens, and components. +Then import and use the components in your JSX. + +```ts +import "@amsterdam/design-system-assets/font/index.css"; +import "@amsterdam/design-system-css/dist/index.css"; +import "@amsterdam/design-system-tokens/dist/index.css"; +import { Paragraph, Screen } from "@amsterdam/design-system-react"; + +const App = () => ( + + Hello world + +) + +export default App; +``` + +## Updating + +We follow semantic versioning and publish a [change log](https://github.com/Amsterdam/design-system/blob/main/packages/react/CHANGELOG.md) to guide you through updates. +The React components are a public API of the design system. +TypeScript helps to detect changed or deleted components, props, or prop values. + +### Stability + +Despite being on ‘major version zero’, most components are stable enough to be used in production. +Various of our public-facing websites and applications already do. + +We’re finalizing the design and modelling of foundational concepts like typography, spacing, and colour. +After that, and a final review of the API of all current components, we’ll release version 1.0 of the entire design system. +Then, we’ll consider publishing all components separately to allow for more granular updates. + +Components for which we anticipate API changes show a ‘beta’ badge at the top of their page in the [Design System handbook](https://designsystem.amsterdam/). + +## Support + +Contact us if you have a question, find an issue, or want to contribute. +Find ways to reach us on [designsystem.amsterdam](https://designsystem.amsterdam/?path=/docs/docs-introduction--docs#send-a-message). diff --git a/proprietary/assets/README.md b/proprietary/assets/README.md index 894c49f988..2921d1497a 100644 --- a/proprietary/assets/README.md +++ b/proprietary/assets/README.md @@ -2,9 +2,69 @@ # Amsterdam Design System: Assets -Assets for the City of Amsterdam +This package provides all assets from the [Amsterdam Design System](https://designsystem.amsterdam). +Use it to include the correct fonts, icons or logos in your website or application. -## Web app manifest, app icons and favicon +## Installation -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/brand-assets-favicon--docs). +Install this package by itself if you want or need to reference assets directly in your project. + +Note that our [React components](https://www.npmjs.com/package/@amsterdam/design-system-react) provide more functionality for some of the assets and use them automatically. +You should use that package if your application uses React. + +```sh +npm install @amsterdam/design-system-assets +``` + +```sh +pnpm add @amsterdam/design-system-assets +``` + +```sh +yarn add @amsterdam/design-system-assets +``` + +## Usage + +### Application icons + +The Design System handbook helps using [a favicon](https://designsystem.amsterdam/?path=/docs/brand-assets-favicon--docs) or [a web manifest and application icons](https://designsystem.amsterdam/?path=/docs/docs-developer-guide-web-app--docs) for home screens of devices in your website or application. + +### Font files + +The package contains our Amsterdam Sans font in OpenType format (.otf) and Web Open Format Font (.woff). +Import our stylesheet to make all of them available to your project. + +```ts +import "@amsterdam/design-system-assets/font/index.css"; +``` + +The Design System Handbook offers [more guidance in using the font](https://designsystem.amsterdam/?path=/docs/brand-assets-font--docs). + +Note that the font is proprietary. Using it requires [a license](https://designsystem.amsterdam/?path=/docs/docs-terms-of-use-copyright--docs). + +### Icons + +The Design System Handbook offers an [overview of our icon library](https://designsystem.amsterdam/?path=/docs/brand-assets-icons--docs). + +You can import the SVG files to use icons in your website or application. + +In a React project, use the [Icon component](https://designsystem.amsterdam/?path=/docs/components-media-icon--docs) instead. +It offers a convenient API for using the icons and streamlines alignment with text. + +### Logos + +The logo of the City of Amsterdam is available as an SVG image, as well as logos for various departments and services. + +In a React project, use the [Logo component](https://designsystem.amsterdam/?path=/docs/components-media-logo--docs) instead. + +## Updating + +We follow semantic versioning and publish a [change log](https://github.com/Amsterdam/design-system/blob/main/proprietary/assets/CHANGELOG.md) to guide you through updates. +The assets are a public API of the design system. +Note that detecting changed or deleted assets is still a manual process. + +## Support + +Contact us if you have a question, find an issue, or want to contribute. +Find ways to reach us on [designsystem.amsterdam](https://designsystem.amsterdam/?path=/docs/docs-introduction--docs#send-a-message). diff --git a/proprietary/react-icons/README.md b/proprietary/react-icons/README.md index d54feb262c..ce672f00f4 100644 --- a/proprietary/react-icons/README.md +++ b/proprietary/react-icons/README.md @@ -2,4 +2,47 @@ # Amsterdam Design System: React icons -Icon svgs as React components +This package provides all icons as React components from the [Amsterdam Design System](https://designsystem.amsterdam). +Use it to use the correct icons in your React project. + +## Installation + +Install this package by itself if you want or need to use icons directly in your React project. + +Note that our [React components](https://www.npmjs.com/package/@amsterdam/design-system-react) contains an [Icon component](https://designsystem.amsterdam/?path=/docs/components-media-icon--docs) that offers a convenient API for using the icons and streamlines alignment with text. + +```sh +npm install @amsterdam/design-system-react-icons +``` + +```sh +pnpm add @amsterdam/design-system-react-icons +``` + +```sh +yarn add @amsterdam/design-system-react-icons +``` + +## Usage + +Import the component for the icon you need and use it in your JSX. + +```ts +import { SearchIcon } from '@amsterdam/design-system-react-icons' + +export const App = () => ( +
+ +
+) +``` + +## Updating + +When updating to a new release of this package, check the [change log](https://github.com/Amsterdam/design-system/blob/develop/proprietary/react-icons/CHANGELOG.md) for breaking changes. +If there are any, update your application accordingly. + +## Support + +Contact us if you have a question, find an issue, or want to contribute. +Find ways to reach us on [designsystem.amsterdam](https://designsystem.amsterdam/?path=/docs/docs-introduction--docs#send-a-message). From 1d8260792e55ce1abb384b16be6bef689dce93c3 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Thu, 17 Oct 2024 15:04:39 +0200 Subject: [PATCH 04/17] Remove roadmap and fix grammer in tokens README --- proprietary/tokens/README.md | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/proprietary/tokens/README.md b/proprietary/tokens/README.md index 0bab95ffc2..ebfc394165 100644 --- a/proprietary/tokens/README.md +++ b/proprietary/tokens/README.md @@ -4,7 +4,7 @@ This package provides all design tokens from the [Amsterdam Design System](https://designsystem.amsterdam). Use it to apply its visual design to your website or application. -The tokens are exported in multiple formats, including CSS custom properties and JSON, making them compatible with most if not all technology stacks. +The tokens are exported in multiple formats, including CSS custom properties and JSON, making them compatible with most, if not all, technology stacks. ## About @@ -32,13 +32,13 @@ All tokens together form a theme that encodes the entire branding of the City of ## Installation -Use this package by itself if you want or need to reference the tokens directly in your stylesheets. +Install this package by itself if you want or need to reference tokens directly in your stylesheets. Note that our [CSS components](https://www.npmjs.com/package/@amsterdam/design-system-css) and [React components](https://www.npmjs.com/package/@amsterdam/design-system-react) provide more functionality and apply the tokens automatically. -You should use these packages if your application uses React, or if it allows applying our HTML classes. +You should use those packages if your application uses React or if it allows you to apply our HTML classes. ```sh -npm i @amsterdam/design-system-tokens +npm install @amsterdam/design-system-tokens ``` ```sh @@ -113,7 +113,7 @@ Find the [list of brand tokens](https://github.com/Amsterdam/design-system/tree/ #### Common tokens Related components share visual design characteristics. -E.g. all kinds of links have the same colour, and the borders of various form inputs are equally thick. +For example, all links have the same colour, and the borders of various form inputs are equally thick. Common tokens express these relations and streamline future changes. Design system components use common tokens where possible. @@ -154,7 +154,7 @@ Find the [list of component tokens](https://github.com/Amsterdam/design-system/t ### Overriding tokens -This package allows creating a theme to reuse our components for a different brand. +This package allows the creation of a theme to reuse our components for a different brand. This is a key feature of [NL Design System](https://nldesignsystem.nl/) of which we are part. However, websites and applications for the City of Amsterdam must follow the design system as closely as possible. @@ -208,18 +208,11 @@ The tokens are used in our [Figma Library](https://www.figma.com/file/9IGm6IdPUY ## Updating -When updating to a new release of this package, check the [change log](https://github.com/Amsterdam/design-system/blob/main/proprietary/tokens/CHANGELOG.md) for breaking changes. -If there are any, update your application accordingly. - -## Roadmap - -We are considering the following features: - -- Overviews of all tokens in our Storybook -- Packaging tokens separately for each component -- Adding tokens to implement dark mode +We follow semantic versioning and publish a [change log](https://github.com/Amsterdam/design-system/blob/main/proprietary/tokens/CHANGELOG.md) to guide you through updates. +The tokens are a public API of the design system. +Note that detecting changed or deleted tokens is still a manual process. ## Support Contact us if you have a question, find an issue, or want to contribute. -Find ways to reach us on [designsystem.amsterdam](https://designsystem.amsterdam/?path=/docs/docs-introduction--docs#send-a-message).. +Find ways to reach us on [designsystem.amsterdam](https://designsystem.amsterdam/?path=/docs/docs-introduction--docs#send-a-message). From ec3d0ea97a7ded8841e3acd263688b09e647a2f6 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Thu, 17 Oct 2024 15:19:19 +0200 Subject: [PATCH 05/17] Populate some fields consistently in all package files --- package.json | 14 +++++++++++--- packages/css/package.json | 9 +++++++-- packages/react/package.json | 11 ++++++++--- proprietary/assets/package.json | 9 +++++++-- proprietary/react-icons/package.json | 9 +++++++-- proprietary/tokens/package.json | 4 ++-- storybook/package.json | 11 ++++++++--- 7 files changed, 50 insertions(+), 17 deletions(-) diff --git a/package.json b/package.json index 76859d9c23..427db68d6f 100644 --- a/package.json +++ b/package.json @@ -1,11 +1,19 @@ { "version": "0.0.0", - "author": "Community for NL Design System", - "description": "Design system based on the NL Design System architecture", + "author": "Design System Team, City of Amsterdam ", + "description": "Reusable components, patterns and guidelines powering the City of Amsterdam’s digital services.", + "homepage": "https://designsystem.amsterdam/", "license": "EUPL-1.2", "name": "@amsterdam/design-system", "keywords": [ - "nl-design-system" + "amsterdam", + "amsterdam-design-system", + "assets", + "css", + "design-system", + "icons", + "nl-design-system", + "react" ], "private": true, "engines": { diff --git a/packages/css/package.json b/packages/css/package.json index 83cf0293b6..e6f7afcd00 100644 --- a/packages/css/package.json +++ b/packages/css/package.json @@ -1,10 +1,15 @@ { "version": "0.11.1", - "author": "Community for NL Design System", - "description": "CSS files for components for the City of Amsterdam based on the NL Design System architecture", + "author": "Design System Team, City of Amsterdam ", + "description": "Stylesheets for all components from the Amsterdam Design System and some general utilities. Use it to apply the visual design of the City of Amsterdam to your HTML elements or non-React components.", + "homepage": "https://designsystem.amsterdam/", "license": "EUPL-1.2", "name": "@amsterdam/design-system-css", "keywords": [ + "amsterdam", + "amsterdam-design-system", + "css", + "design-system", "nl-design-system" ], "private": false, diff --git a/packages/react/package.json b/packages/react/package.json index 0ae51e2465..7fc25b8143 100644 --- a/packages/react/package.json +++ b/packages/react/package.json @@ -1,11 +1,16 @@ { "version": "0.11.1", - "author": "Community for NL Design System", - "description": "React component library bundle for the City of Amsterdam based on the NL Design System architecture", + "author": "Design System Team, City of Amsterdam ", + "description": "All React components from the Amsterdam Design System. Use it to compose pages in your website or application.", + "homepage": "https://designsystem.amsterdam/", "license": "EUPL-1.2", "name": "@amsterdam/design-system-react", "keywords": [ - "nl-design-system" + "amsterdam", + "amsterdam-design-system", + "design-system", + "nl-design-system", + "react" ], "private": false, "publishConfig": { diff --git a/proprietary/assets/package.json b/proprietary/assets/package.json index a89be55d33..aa0c3c2cc7 100644 --- a/proprietary/assets/package.json +++ b/proprietary/assets/package.json @@ -1,10 +1,15 @@ { "version": "0.2.1", - "author": "Community for NL Design System", - "description": "Assets for the City of Amsterdam", + "author": "Design System Team, City of Amsterdam ", + "description": "All assets from the Amsterdam Design System. Use it to include the correct fonts, icons or logos in your website or application.", + "homepage": "https://designsystem.amsterdam/", "license": "SEE LICENSE IN LICENSE.md", "name": "@amsterdam/design-system-assets", "keywords": [ + "amsterdam", + "amsterdam-design-system", + "assets", + "design-system", "nl-design-system" ], "private": false, diff --git a/proprietary/react-icons/package.json b/proprietary/react-icons/package.json index 6a02597472..7a90e9dc7b 100644 --- a/proprietary/react-icons/package.json +++ b/proprietary/react-icons/package.json @@ -1,10 +1,15 @@ { "version": "0.1.12", - "author": "Community for NL Design System", - "description": "React icon components for the City of Amsterdam", + "author": "Design System Team, City of Amsterdam ", + "description": "All icons as React components from the Amsterdam Design System. Use it to use the correct icons in your React project.", + "homepage": "https://designsystem.amsterdam/", "license": "SEE LICENSE IN LICENSE.md", "name": "@amsterdam/design-system-react-icons", "keywords": [ + "amsterdam", + "amsterdam-design-system", + "design-system", + "icons", "nl-design-system" ], "private": false, diff --git a/proprietary/tokens/package.json b/proprietary/tokens/package.json index aa94282ad6..2362118fbe 100644 --- a/proprietary/tokens/package.json +++ b/proprietary/tokens/package.json @@ -10,8 +10,8 @@ "amsterdam", "amsterdam-design-system", "design-system", - "design-tokens", - "nl-design-system" + "nl-design-system", + "tokens" ], "private": false, "publishConfig": { diff --git a/storybook/package.json b/storybook/package.json index 408e01c5d5..87e34d2a7c 100644 --- a/storybook/package.json +++ b/storybook/package.json @@ -1,11 +1,16 @@ { "version": "0.0.0", - "author": "Community for NL Design System", - "description": "Storybook React website for the City of Amsterdam based on the NL Design System architecture", + "author": "Design System Team, City of Amsterdam ", + "description": "The handbook for the Amsterdam Design System, created with Storybook.", + "homepage": "https://designsystem.amsterdam/", "license": "EUPL-1.2", "name": "@amsterdam/storybook", "keywords": [ - "nl-design-system" + "amsterdam", + "amsterdam-design-system", + "design-system", + "nl-design-system", + "storybook" ], "private": true, "repository": { From 5e89076ff094d5da0b29d594d37ebf31126be74a Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Mon, 21 Oct 2024 15:50:57 +0200 Subject: [PATCH 06/17] Apply suggestions from code review Co-authored-by: Aram <37216945+alimpens@users.noreply.github.com> --- proprietary/react-icons/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proprietary/react-icons/README.md b/proprietary/react-icons/README.md index ce672f00f4..7c0a927bc9 100644 --- a/proprietary/react-icons/README.md +++ b/proprietary/react-icons/README.md @@ -9,7 +9,7 @@ Use it to use the correct icons in your React project. Install this package by itself if you want or need to use icons directly in your React project. -Note that our [React components](https://www.npmjs.com/package/@amsterdam/design-system-react) contains an [Icon component](https://designsystem.amsterdam/?path=/docs/components-media-icon--docs) that offers a convenient API for using the icons and streamlines alignment with text. +Note that our [React components](https://www.npmjs.com/package/@amsterdam/design-system-react) contain an [Icon component](https://designsystem.amsterdam/?path=/docs/components-media-icon--docs) that offers a convenient API for using the icons and streamlines alignment with text. ```sh npm install @amsterdam/design-system-react-icons @@ -31,7 +31,7 @@ Import the component for the icon you need and use it in your JSX. import { SearchIcon } from '@amsterdam/design-system-react-icons' export const App = () => ( -
+
) From e86d2e9445b2023206b250f41a490b08a9b1c13d Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Mon, 21 Oct 2024 15:15:37 +0200 Subject: [PATCH 07/17] Prevent burying the lede --- packages/css/README.md | 23 +++++++++-------------- packages/react/README.md | 2 +- proprietary/tokens/README.md | 20 ++------------------ 3 files changed, 12 insertions(+), 33 deletions(-) diff --git a/packages/css/README.md b/packages/css/README.md index b8248dcc7e..96c83a18b6 100644 --- a/packages/css/README.md +++ b/packages/css/README.md @@ -5,25 +5,14 @@ This package provides stylesheets for all components in the [Amsterdam Design System](https://designsystem.amsterdam) and some general utilities. Use it to apply the visual design of the City of Amsterdam to your HTML elements or non-React components. -## About +## Introduction -The set of classes for a component can be seen as a blueprint for its markup and features. -An `.ams-component` root selector applies the essential styles of the component to its element, and additional classes like `.ams-component--variant` modify its appearance or behaviour. +We publish our components’ stylesheets as a separate package to help replicating them in other libraries, platforms, or Saas-applications. +The classes are a contract between the component’s definition and its implementations and they facilitate ongoing upgrades. Our [React components](https://www.npmjs.com/package/@amsterdam/design-system-react) use these classes in the HTML they render. You should use that package if your application uses React. -The classes employ the [naming convention of NL Design System](https://nldesignsystem.nl/handboek/developer/architectuur#bem-class-names-voor-css). -Other communities only need to overwrite design tokens to use our components with their branding. - -## Motivation - -Publishing the stylesheets as a separate package saves a lot of work when replicating components in other libraries, platforms, or Saas-applications. -This is a powerful approach to implement the design system across different technologies. - -The classes act like a contract between the component’s definition and its implementations. -As a bonus, updates to tokens or styles can be propagated to all of them. - ## Installation The stylesheets reference our [design tokens](https://www.npmjs.com/package/@amsterdam/design-system-tokens). @@ -49,6 +38,12 @@ yarn add ## Usage +The set of classes for a component can be seen as a blueprint for its markup and features. +An `.ams-component` root selector applies the essential styles of the component to its element, and additional classes like `.ams-component--variant` modify its appearance or behaviour. + +The classes employ the [naming convention of NL Design System](https://nldesignsystem.nl/handboek/developer/architectuur#bem-class-names-voor-css). +Other communities only need to overwrite design tokens to use our components with their branding. + ### In JavaScript Import the main stylesheet and use the class names in your markup. diff --git a/packages/react/README.md b/packages/react/README.md index bebf71bdaf..4dfdd27cd8 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -5,7 +5,7 @@ This package provides all React components from the [Amsterdam Design System](https://designsystem.amsterdam). Use it to compose pages in your website or application. -## About +## Introduction This package is the primary entry point for digital services that we build in-house. We’ve adopted the architecture of [NL Design System](https://nldesignsystem.nl/). diff --git a/proprietary/tokens/README.md b/proprietary/tokens/README.md index ebfc394165..02ac8d95f9 100644 --- a/proprietary/tokens/README.md +++ b/proprietary/tokens/README.md @@ -6,28 +6,11 @@ This package provides all design tokens from the [Amsterdam Design System](https Use it to apply its visual design to your website or application. The tokens are exported in multiple formats, including CSS custom properties and JSON, making them compatible with most, if not all, technology stacks. -## About +## Introduction Every design token is a variable representing a single visual design choice. Tokens exist for colours, various aspects of text, spacing lengths, border widths, the configuration of animations, and more. The value of every token is valid in CSS. - -Some examples: - -```css -:root { - --ams-color-blue: #004699; - --ams-text-font-weight-bold: 800; - --ams-border-width-medium: 0.125rem; - --ams-button-padding-inline: 1.5rem; - --ams-space-xl: clamp(2.25rem, 2.0625rem + 0.9375vw, 3rem); - --ams-text-input-invalid-border-color: var(--ams-color-red); -} -``` - -Tokens start their name with a prefix of `--ams-` in CSS. -The name of a component token (see below) ends with the property that uses it, e.g. `-font-size`. - All tokens together form a theme that encodes the entire branding of the City of Amsterdam. ## Installation @@ -52,6 +35,7 @@ yarn add @amsterdam/design-system-tokens ## Usage in CSS Tokens are typically used as custom properties in CSS. +Their name starts with a prefix of `--ams-`; that of a component token (see below) with the property that uses it, e.g. `-font-size`. ### Main stylesheet From a166f920606b33afaef4d9d848d8528befdc8c25 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Mon, 21 Oct 2024 15:38:58 +0200 Subject: [PATCH 08/17] Simplify shell commands --- documentation/git.md | 4 +-- documentation/publishing.md | 4 +-- packages/css/README.md | 16 +----------- packages/react/README.md | 25 +------------------ proprietary/assets/README.md | 8 ------ proprietary/react-icons/README.md | 8 ------ proprietary/tokens/README.md | 8 ------ .../developer-guide/getting-started.docs.mdx | 2 +- 8 files changed, 7 insertions(+), 68 deletions(-) diff --git a/documentation/git.md b/documentation/git.md index 2e3cbe19a8..ec712fbf98 100644 --- a/documentation/git.md +++ b/documentation/git.md @@ -26,7 +26,7 @@ Configure this immediately after downloading. From the directory that holds the repository: -```bash +```sh git config user.name Your Name git config user.email your.email@amsterdam.nl @@ -139,7 +139,7 @@ For users of Git via the CLI, it may be helpful to create aliases for some commo You can save this in a configuration file of your shell. For example: -```bash +```sh alias gcd="git checkout develop" alias gcp="git checkout -" alias gh="git push" diff --git a/documentation/publishing.md b/documentation/publishing.md index 9acb996b38..5502cbd891 100644 --- a/documentation/publishing.md +++ b/documentation/publishing.md @@ -32,7 +32,7 @@ This will cause a major version bump in both packages on release and add its des 1. Locally merge the latest version of `develop` into `main` using a fast-forward merge, and push to the remote: - ```shell + ```sh git checkout main git pull git merge --ff-only origin/develop @@ -46,7 +46,7 @@ This will cause a major version bump in both packages on release and add its des 3. When complete, the Action adds a new release commit to `main`. Locally merge this commit back into `develop` and push it to the remote: - ```shell + ```sh git checkout develop git pull git merge --ff-only origin/main diff --git a/packages/css/README.md b/packages/css/README.md index 96c83a18b6..dee07c14c2 100644 --- a/packages/css/README.md +++ b/packages/css/README.md @@ -19,21 +19,7 @@ The stylesheets reference our [design tokens](https://www.npmjs.com/package/@ams Both packages need to be installed. ```sh -npm install - @amsterdam/design-system-css - @amsterdam/design-system-tokens -``` - -```sh -pnpm add - @amsterdam/design-system-css - @amsterdam/design-system-tokens -``` - -```sh -yarn add - @amsterdam/design-system-css - @amsterdam/design-system-tokens +npm install @amsterdam/design-system-css @amsterdam/design-system-tokens ``` ## Usage diff --git a/packages/react/README.md b/packages/react/README.md index 4dfdd27cd8..94b6a257e0 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -20,30 +20,7 @@ and [React icons](https://www.npmjs.com/package/@amsterdam/design-system-react-i Install all packages. ```sh -npm install - @amsterdam/design-system-assets - @amsterdam/design-system-css - @amsterdam/design-system-react - @amsterdam/design-system-react-icons - @amsterdam/design-system-tokens -``` - -```sh -pnpm add - @amsterdam/design-system-assets - @amsterdam/design-system-css - @amsterdam/design-system-react - @amsterdam/design-system-react-icons - @amsterdam/design-system-tokens -``` - -```sh -yarn add - @amsterdam/design-system-assets - @amsterdam/design-system-css - @amsterdam/design-system-react - @amsterdam/design-system-react-icons - @amsterdam/design-system-tokens +npm install @amsterdam/design-system-assets @amsterdam/design-system-css @amsterdam/design-system-react @amsterdam/design-system-react-icons @amsterdam/design-system-tokens ``` The React components themselves are unstyled. diff --git a/proprietary/assets/README.md b/proprietary/assets/README.md index 2921d1497a..ab9156062c 100644 --- a/proprietary/assets/README.md +++ b/proprietary/assets/README.md @@ -16,14 +16,6 @@ You should use that package if your application uses React. npm install @amsterdam/design-system-assets ``` -```sh -pnpm add @amsterdam/design-system-assets -``` - -```sh -yarn add @amsterdam/design-system-assets -``` - ## Usage ### Application icons diff --git a/proprietary/react-icons/README.md b/proprietary/react-icons/README.md index 7c0a927bc9..83325e3931 100644 --- a/proprietary/react-icons/README.md +++ b/proprietary/react-icons/README.md @@ -15,14 +15,6 @@ Note that our [React components](https://www.npmjs.com/package/@amsterdam/design npm install @amsterdam/design-system-react-icons ``` -```sh -pnpm add @amsterdam/design-system-react-icons -``` - -```sh -yarn add @amsterdam/design-system-react-icons -``` - ## Usage Import the component for the icon you need and use it in your JSX. diff --git a/proprietary/tokens/README.md b/proprietary/tokens/README.md index 02ac8d95f9..2dfa27d43b 100644 --- a/proprietary/tokens/README.md +++ b/proprietary/tokens/README.md @@ -24,14 +24,6 @@ You should use those packages if your application uses React or if it allows you npm install @amsterdam/design-system-tokens ``` -```sh -pnpm add @amsterdam/design-system-tokens -``` - -```sh -yarn add @amsterdam/design-system-tokens -``` - ## Usage in CSS Tokens are typically used as custom properties in CSS. diff --git a/storybook/src/docs/developer-guide/getting-started.docs.mdx b/storybook/src/docs/developer-guide/getting-started.docs.mdx index d00f8cebb9..ce51e6b1d5 100644 --- a/storybook/src/docs/developer-guide/getting-started.docs.mdx +++ b/storybook/src/docs/developer-guide/getting-started.docs.mdx @@ -10,7 +10,7 @@ import { Meta } from "@storybook/blocks"; Install the packages you need, for instance: -```bash +```sh npm install @amsterdam/design-system-assets @amsterdam/design-system-css @amsterdam/design-system-react @amsterdam/design-system-react-icons @amsterdam/design-system-tokens ``` From 70d705c5e5d5f3ed9f76a960f83c457595f2127f Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Mon, 21 Oct 2024 15:40:37 +0200 Subject: [PATCH 09/17] Add missing imports in examples --- packages/css/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/css/README.md b/packages/css/README.md index dee07c14c2..57aeb65eb2 100644 --- a/packages/css/README.md +++ b/packages/css/README.md @@ -35,6 +35,8 @@ Other communities only need to overwrite design tokens to use our components wit Import the main stylesheet and use the class names in your markup. ```ts +import "@amsterdam/design-system-assets/font/index.css"; +import "@amsterdam/design-system-css/dist/index.css"; import "@amsterdam/design-system-tokens/dist/index.css"; export const App = () => ( From 55780b7d093778cea9415aea626970c5fccb8b37 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Mon, 21 Oct 2024 15:45:35 +0200 Subject: [PATCH 10/17] Restore cautioning about major version zero --- packages/react/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/react/README.md b/packages/react/README.md index 94b6a257e0..0fdd2525ef 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -57,6 +57,8 @@ TypeScript helps to detect changed or deleted components, props, or prop values. Despite being on ‘major version zero’, most components are stable enough to be used in production. Various of our public-facing websites and applications already do. +Make sure you specify the exact version as dependency and test for regressions when upgrading to the latest version. + We’re finalizing the design and modelling of foundational concepts like typography, spacing, and colour. After that, and a final review of the API of all current components, we’ll release version 1.0 of the entire design system. Then, we’ll consider publishing all components separately to allow for more granular updates. From 1ab7c275cf6af8b0d5414262b75757e34749c795 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Mon, 21 Oct 2024 15:46:58 +0200 Subject: [PATCH 11/17] =?UTF-8?q?Move=20=E2=80=98as=20React=20components?= =?UTF-8?q?=E2=80=99=20to=20end=20of=20sentence?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- proprietary/react-icons/README.md | 2 +- proprietary/react-icons/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/proprietary/react-icons/README.md b/proprietary/react-icons/README.md index 83325e3931..36f83bcc5d 100644 --- a/proprietary/react-icons/README.md +++ b/proprietary/react-icons/README.md @@ -2,7 +2,7 @@ # Amsterdam Design System: React icons -This package provides all icons as React components from the [Amsterdam Design System](https://designsystem.amsterdam). +This package provides all icons from the [Amsterdam Design System](https://designsystem.amsterdam) as React components. Use it to use the correct icons in your React project. ## Installation diff --git a/proprietary/react-icons/package.json b/proprietary/react-icons/package.json index 7a90e9dc7b..60790de521 100644 --- a/proprietary/react-icons/package.json +++ b/proprietary/react-icons/package.json @@ -1,7 +1,7 @@ { "version": "0.1.12", "author": "Design System Team, City of Amsterdam ", - "description": "All icons as React components from the Amsterdam Design System. Use it to use the correct icons in your React project.", + "description": "All icons from the Amsterdam Design System as React components. Use it to use the correct icons in your React project.", "homepage": "https://designsystem.amsterdam/", "license": "SEE LICENSE IN LICENSE.md", "name": "@amsterdam/design-system-react-icons", From b5784a565247ba7f5933336d58821f4fbdbe22f9 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Mon, 21 Oct 2024 15:58:27 +0200 Subject: [PATCH 12/17] Replace misleading title with required stylesheet imports --- packages/css/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/css/README.md b/packages/css/README.md index 57aeb65eb2..d7f6bf819a 100644 --- a/packages/css/README.md +++ b/packages/css/README.md @@ -54,8 +54,9 @@ Although it is not a typical use case, the stylesheet can be included in an HTML - Amsterdam Design System + +

Hello, world!

From f10845e6754913db6bb569d3a71e179a7a9b6d69 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Wed, 23 Oct 2024 10:54:39 +0200 Subject: [PATCH 13/17] Make hello world examples minimal and consistent --- packages/css/README.md | 4 +--- packages/react/README.md | 6 ++---- storybook/src/docs/developer-guide/getting-started.docs.mdx | 5 ++--- 3 files changed, 5 insertions(+), 10 deletions(-) diff --git a/packages/css/README.md b/packages/css/README.md index d7f6bf819a..825548d286 100644 --- a/packages/css/README.md +++ b/packages/css/README.md @@ -40,9 +40,7 @@ import "@amsterdam/design-system-css/dist/index.css"; import "@amsterdam/design-system-tokens/dist/index.css"; export const App = () => ( -
-

Hello, world!

-
+

Hello, world!

) ``` diff --git a/packages/react/README.md b/packages/react/README.md index 0fdd2525ef..98d8ee9e6c 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -35,12 +35,10 @@ Then import and use the components in your JSX. import "@amsterdam/design-system-assets/font/index.css"; import "@amsterdam/design-system-css/dist/index.css"; import "@amsterdam/design-system-tokens/dist/index.css"; -import { Paragraph, Screen } from "@amsterdam/design-system-react"; +import { Paragraph } from "@amsterdam/design-system-react"; const App = () => ( - - Hello world - + Hello, world! ) export default App; diff --git a/storybook/src/docs/developer-guide/getting-started.docs.mdx b/storybook/src/docs/developer-guide/getting-started.docs.mdx index ce51e6b1d5..67e0f585d6 100644 --- a/storybook/src/docs/developer-guide/getting-started.docs.mdx +++ b/storybook/src/docs/developer-guide/getting-started.docs.mdx @@ -17,14 +17,13 @@ npm install @amsterdam/design-system-assets @amsterdam/design-system-css @amster Import the components and stylesheets you need, for example: ```javascript -import { Paragraph } from "@amsterdam/design-system-react"; - import "@amsterdam/design-system-assets/font/index.css"; import "@amsterdam/design-system-css/dist/index.css"; import "@amsterdam/design-system-tokens/dist/index.css"; +import { Paragraph } from "@amsterdam/design-system-react"; function App() { - return Hello world; + return Hello, world!; } export default App; From 50507954e7f4103266c6b8f81d1f589f79717b9f Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Wed, 23 Oct 2024 10:58:34 +0200 Subject: [PATCH 14/17] Use the Icon component in a React example --- proprietary/react-icons/README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/proprietary/react-icons/README.md b/proprietary/react-icons/README.md index 36f83bcc5d..7fe4eb2d92 100644 --- a/proprietary/react-icons/README.md +++ b/proprietary/react-icons/README.md @@ -17,15 +17,14 @@ npm install @amsterdam/design-system-react-icons ## Usage -Import the component for the icon you need and use it in your JSX. +Import the component for the icon you need, as well as the generic Icon component, and use them in your JSX. ```ts +import { Icon } from '@amsterdam/design-system-react' import { SearchIcon } from '@amsterdam/design-system-react-icons' export const App = () => ( -
- -
+ ) ``` From 72d77e82aed135600329514388cf10bf3f1bee13 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Wed, 23 Oct 2024 11:00:11 +0200 Subject: [PATCH 15/17] Remove CSS Modules example --- packages/css/README.md | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/packages/css/README.md b/packages/css/README.md index 825548d286..fc8012c888 100644 --- a/packages/css/README.md +++ b/packages/css/README.md @@ -62,25 +62,6 @@ Although it is not a typical use case, the stylesheet can be included in an HTML ``` -### With CSS Modules - -The BEM class names can be particularly useful to include only the CSS you need using [CSS modules](https://css-tricks.com/css-modules-part-1-need/) ([in React](https://css-tricks.com/css-modules-part-3-react/)). - -```js -import React from "react"; -import style from "@amsterdam/design-system-css"; - -export default class ExamplePage extends React.Component { - render() { - return ( - <> -

Hello, world!

- - ); - } -} -``` - ### Compact mode [Load the compact tokens](https://github.com/Amsterdam/design-system/blob/main/proprietary/tokens/README.md) to use the compact appearance of the design system, e.g. for applications. From 7e5ca3f5cf350fbd8bf193369a450b59e24f3f88 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Wed, 23 Oct 2024 11:28:58 +0200 Subject: [PATCH 16/17] Remove semicolons from JavaScript code examples in plain Markdown --- packages/css/README.md | 7 +++--- packages/react/README.md | 11 ++++---- .../react/documentation/coding-conventions.md | 7 +++--- proprietary/assets/README.md | 3 ++- proprietary/tokens/README.md | 25 +++++++++++-------- 5 files changed, 31 insertions(+), 22 deletions(-) diff --git a/packages/css/README.md b/packages/css/README.md index fc8012c888..836ac8723b 100644 --- a/packages/css/README.md +++ b/packages/css/README.md @@ -34,10 +34,11 @@ Other communities only need to overwrite design tokens to use our components wit Import the main stylesheet and use the class names in your markup. + ```ts -import "@amsterdam/design-system-assets/font/index.css"; -import "@amsterdam/design-system-css/dist/index.css"; -import "@amsterdam/design-system-tokens/dist/index.css"; +import "@amsterdam/design-system-assets/font/index.css" +import "@amsterdam/design-system-css/dist/index.css" +import "@amsterdam/design-system-tokens/dist/index.css" export const App = () => (

Hello, world!

diff --git a/packages/react/README.md b/packages/react/README.md index 98d8ee9e6c..8535fde08e 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -31,17 +31,18 @@ The React components themselves are unstyled. Import the stylesheets for the fonts, tokens, and components. Then import and use the components in your JSX. + ```ts -import "@amsterdam/design-system-assets/font/index.css"; -import "@amsterdam/design-system-css/dist/index.css"; -import "@amsterdam/design-system-tokens/dist/index.css"; -import { Paragraph } from "@amsterdam/design-system-react"; +import "@amsterdam/design-system-assets/font/index.css" +import "@amsterdam/design-system-css/dist/index.css" +import "@amsterdam/design-system-tokens/dist/index.css" +import { Paragraph } from "@amsterdam/design-system-react" const App = () => ( Hello, world! ) -export default App; +export default App ``` ## Updating diff --git a/packages/react/documentation/coding-conventions.md b/packages/react/documentation/coding-conventions.md index 34dc5b4bcd..ed38613983 100644 --- a/packages/react/documentation/coding-conventions.md +++ b/packages/react/documentation/coding-conventions.md @@ -9,10 +9,11 @@ Barrel files allow a consumer to do this: Instead of a separate import for each component, while even reaching into the `dist` directory: + ```js -import Heading from "@amsterdam/design-system-react/dist/Heading/Heading"; -import Link from "@amsterdam/design-system-react/dist/Link/Link"; -import Paragraph from "@amsterdam/design-system-react/dist/Paragraph/Paragraph"; +import Heading from "@amsterdam/design-system-react/dist/Heading/Heading" +import Link from "@amsterdam/design-system-react/dist/Link/Link" +import Paragraph from "@amsterdam/design-system-react/dist/Paragraph/Paragraph" ``` However, barrel files have 2 potential pitfalls: diff --git a/proprietary/assets/README.md b/proprietary/assets/README.md index ab9156062c..6f57e91459 100644 --- a/proprietary/assets/README.md +++ b/proprietary/assets/README.md @@ -27,8 +27,9 @@ The Design System handbook helps using [a favicon](https://designsystem.amsterda The package contains our Amsterdam Sans font in OpenType format (.otf) and Web Open Format Font (.woff). Import our stylesheet to make all of them available to your project. + ```ts -import "@amsterdam/design-system-assets/font/index.css"; +import "@amsterdam/design-system-assets/font/index.css" ``` The Design System Handbook offers [more guidance in using the font](https://designsystem.amsterdam/?path=/docs/brand-assets-font--docs). diff --git a/proprietary/tokens/README.md b/proprietary/tokens/README.md index 2dfa27d43b..9c2dada27b 100644 --- a/proprietary/tokens/README.md +++ b/proprietary/tokens/README.md @@ -34,15 +34,17 @@ Their name starts with a prefix of `--ams-`; that of a component token (see belo This package offers a main stylesheet containing all tokens. They are declared as global CSS variables through the `:root` selector. + ```ts -import "@amsterdam/design-system-tokens/dist/index.css"; +import "@amsterdam/design-system-tokens/dist/index.css" ``` If that doesn’t work for your project, use `index.theme.css` instead, which uses an `.ams-theme` selector. Add that class to a root element of your application. + ```ts -import "@amsterdam/design-system-tokens/dist/index.theme.css"; +import "@amsterdam/design-system-tokens/dist/index.theme.css" ``` ```html @@ -60,9 +62,10 @@ A compact stylesheet is available for applications that require less white space Note that the compact stylesheet is not independent – it only contains overrides. Import it after the main stylesheet for the correct result. + ```ts -import "@amsterdam/design-system-tokens/dist/index.css"; -import "@amsterdam/design-system-tokens/dist/compact.css"; +import "@amsterdam/design-system-tokens/dist/index.css" +import "@amsterdam/design-system-tokens/dist/compact.css" ``` ### Three layers @@ -161,21 +164,23 @@ Import the JSON file to use the tokens in TypeScript or JavaScript. Here, tokens start their name with a prefix of `ams.`. Use ‘dot notation’ or square brackets to access the tokens. + ```ts -import tokens from "@amsterdam/design-system-tokens/dist/index.json"; +import tokens from "@amsterdam/design-system-tokens/dist/index.json" -const buttonBackgroundColor = tokens.ams.color["primary-blue"]; -const rowGap = tokens.ams.space.md; +const buttonBackgroundColor = tokens.ams.color["primary-blue"] +const rowGap = tokens.ams.space.md ``` Import and merge the compact tokens if you need them. Then you can use the tokens in scripting or css-in-js libraries. + ```ts -import spaciousTokens from "@amsterdam/design-system-tokens/dist/index.json"; -import compactTokens from "@amsterdam/design-system-tokens/dist/compact.json"; +import spaciousTokens from "@amsterdam/design-system-tokens/dist/index.json" +import compactTokens from "@amsterdam/design-system-tokens/dist/compact.json" -const tokens = { ...spaciousTokens, ...compactTokens }; +const tokens = { ...spaciousTokens, ...compactTokens } ``` ## Usage in Figma From f5eced340c39c5abaae11e413633762b11b7e464 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Wed, 23 Oct 2024 14:43:00 +0200 Subject: [PATCH 17/17] =?UTF-8?q?Remove=20keywords=20for=20package=20that?= =?UTF-8?q?=20we=20don=E2=80=99t=20publish?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- storybook/package.json | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/storybook/package.json b/storybook/package.json index 7e5484a950..a4c8708f52 100644 --- a/storybook/package.json +++ b/storybook/package.json @@ -5,13 +5,7 @@ "homepage": "https://designsystem.amsterdam/", "license": "EUPL-1.2", "name": "@amsterdam/storybook", - "keywords": [ - "amsterdam", - "amsterdam-design-system", - "design-system", - "nl-design-system", - "storybook" - ], + "keywords": [], "private": true, "repository": { "type": "git",