chore: Write README for all packages except tokens

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/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,27 +1,87 @@
 <!-- @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`
+## 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 = () => (
+  <div class="ams-screen">
+    <p className="ams-paragraph">Hello, world!</p>
+  </div>
+)
+```
+
+### 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" />
+    <title>Amsterdam Design System</title>
+    <link rel="stylesheet" href="node_modules/@amsterdam/design-system-css/dist/index.css" />
   </head>
-  <body>
+  <body class="ams-body">
     <p class="ams-paragraph">Hello, world!</p>
   </body>
 </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
@@ -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 `<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,92 @@
 <!-- @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.
+## 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 = () => (
+  <Screen>
+    <Paragraph>Hello world</Paragraph>
+  </Screen>
+)
+
+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).

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": {