chore: Write README for all packages except tokens (#1670)

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

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
 

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 [email protected]
@@ -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"

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

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.

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 <[email protected]>",
+  "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": {

packages/css/README.md

@@ -1,72 +1,101 @@
 <!-- @license CC0-1.0 -->
 
-# 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.
+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`
+## Introduction
 
-Theoretically you can include the components in your HTML page like so, but this is not the typical use case of this library:
+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.
+
+## 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
+```
+
+## 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.
+
+<!-- prettier-ignore -->
+```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 = () => (
+  <p className="ams-paragraph">Hello, world!</p>
+)
+```
+
+### In HTML
+
+Although it is not a typical use case, the stylesheet can be included in an HTML page directly.
 
 ```html
 <!doctype html>
 <html lang="en">
   <head>
-    <title>Example page</title>
-    <link rel="stylesheet" href="node_modules/@amsterdam/design-system-css" />
+    <link rel="stylesheet" href="node_modules/@amsterdam/design-system-assets/font/index.css" />
+    <link rel="stylesheet" href="node_modules/@amsterdam/design-system-css/dist/index.css" />
+    <link rel="stylesheet" href="node_modules/@amsterdam/design-system-tokens/dist/index.css" />
   </head>
-  <body>
+  <body class="ams-body">
     <p class="ams-paragraph">Hello, world!</p>
   </body>
 </html>
 ```
 
-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 (
-      <>
-        <p className={btn["ams-paragraph"]}>Hello, world!</p>
-      </>
-    );
-  }
-}
-```
-
-## 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 `<body>` 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).

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 <[email protected]>",
+  "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,

packages/react/README.md

@@ -1,18 +1,70 @@
 <!-- @license CC0-1.0 -->
 
-# 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.
+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.
+## Introduction
 
-## 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
+```
+
+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.
+
+<!-- prettier-ignore -->
+```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"
+
+const App = () => (
+  <Paragraph>Hello, world!</Paragraph>
+)
+
+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.
+
+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.
+
+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).

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:
 
+<!-- prettier-ignore -->
 ```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:

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 <[email protected]>",
+  "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": {