feat: Allow installing only the React or CSS package

documentation/publishing.md

@@ -63,3 +63,47 @@ Release Please will not create a new release PR if it thinks there is a pending
 To fix this, check whether any closed PRs still have the `autorelease: pending` or `autorelease: triggered` labels, and remove them.
 
 [See the Release Please docs for more information](https://github.com/googleapis/release-please?tab=readme-ov-file#release-please-bot-does-not-create-a-release-pr-why).
+
+## Dependencies between packages
+
+We’ve defined (peer) dependencies between our packages, in order to simplify the install process.
+For example, our React package has a peer dependency on our CSS package.
+When installing our React package, the correct version of our CSS package is automatically installed with it.
+
+The dependency tree looks like this:
+
+```mermaid
+graph LR
+  RI["React icons"] --> React
+  Tokens --> CSS
+  Assets --> CSS
+  CSS --> React
+```
+
+These dependencies mean we have to pay some extra attention when publishing.
+Generally, the dependencies between our packages our defined using [PNPM’s `workspace:*` feature](https://pnpm.io/workspaces#publishing-workspace-packages).
+This means that when publishing our upstream packages (CSS and React), the latest version of our downstream packages (tokens, assets and React icons)
+are defined as dependencies.
+
+This works, as long as the publish at least includes new versions of both our CSS and React packages.
+But say we do a publish which only includes a new version of our tokens and assets packages.
+They get a new version, but our CSS and React packages don’t have any changes, which means they don’t get new versions.
+This means the latest version of our CSS package has a peer dependency on an older version of our tokens package.
+
+To fix this, we can manually add the latest version of our tokens package as a peer dependency of our CSS package.
+In other words, we’d replace `"@amsterdam/design-system-tokens": "workspace:*"` with `"@amsterdam/design-system-tokens": "1.2.3"`.
+After this, don’t forget to run `pnpm i` to update the lockfile.
+The changes to the `package.json` and the lockfile mean we can release a new version of our CSS package, which will contain the correct peer dependency.
+
+Seeing as our CSS package is itself also a peer dependency of our React package, in the most extreme case we would have to do something like:
+
+1. Release a new version of our tokens and / or assets packages only.
+2. Manually change the peer dependency of our CSS package and release that.
+3. Manually change the peer dependency of our React package and release that.
+
+This probably won’t happen very often, seeing as we usually make changes to both our CSS and React packages in between publishes,
+but in the future it might.
+
+Manually changing a peer dependency of an upstream package means it’s defined statically, not dynamically.
+For the next release of our upstream package, we probably want to change it back to a dynamic definition (i.e. `workspace:*`).
+Don’t forget to run `pnpm i` after doing this, to update the lockfile.

packages/css/package.json

@@ -19,7 +19,10 @@
     "clean": "rimraf dist/"
   },
   "devDependencies": {
-    "@amsterdam/design-system-tokens": "workspace:*",
     "sass": "1.75.0"
+  },
+  "peerDependencies": {
+    "@amsterdam/design-system-tokens": "workspace:*",
+    "@amsterdam/design-system-assets": "workspace:*"
   }
 }

packages/react/README.md

@@ -5,9 +5,8 @@
 The `@amsterdam/design-system-react` package contains React implementations of various components.
 You can use this package in React apps.
 
-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.
-
-<!-- TODO: make this easier? -->
+The design tokens and CSS used in these components are published in separate npm packages,
+which are automatically installed when you install the React package.
 
 ## Stability of the components
 
@@ -19,11 +18,11 @@ Make sure you specify the exact version as dependency, so you can schedule to up
 
 ## Getting started
 
-Install the packages you need, for instance:
+Install the React packages, like so:
 
-`npm install @amsterdam/design-system-react @amsterdam/design-system-tokens @amsterdam/design-system-assets @amsterdam/design-system-css`
+`npm install @amsterdam/design-system-react`
 
-Import the packages you need.
+Import the components and CSS you need, for example:
 
 ```javascript
 import { Paragraph } from "@amsterdam/design-system-react";

packages/react/package.json

@@ -72,6 +72,7 @@
     "tslib": "2.6.2"
   },
   "peerDependencies": {
+    "@amsterdam/design-system-css": "workspace:*",
     "react": "16 - 18",
     "react-dom": "16 - 18"
   }