docs: split usage instructions into multiple pages for more clarity

IATI · Oct 24, 2024 · fcddbea · fcddbea
1 parent 8d9ab3c
commit fcddbea
Show file tree

Hide file tree

Showing 6 changed files with 79 additions and 47 deletions.
diff --git a/.storybook/preview.ts b/.storybook/preview.ts
@@ -8,7 +8,16 @@ const preview: Preview = {
   parameters: {
     options: {
       storySort: {
-        order: ["Get Started", "Brand", "Core", "Components", "Layout"],
+        order: [
+          "Get Started",
+          "Installation",
+          "Usage",
+          "Contributing",
+          "Brand",
+          "Core",
+          "Components",
+          "Layout",
+        ],
       },
     },
     backgrounds: {

diff --git a/README.md b/README.md
@@ -4,50 +4,11 @@
 
 The IATI Design System is a set of reusable styles and components which should be used in IATI web products, along with guidance on how to use them.
 
-## How do I use the IATI Design System?
+## Using the IATI Design System
 
-### CDN (Recommended)
+Please see the [Storybook site](https://iati.github.io/design-system/) for instructions.
 
-The recommended way to use the design system in an IATI product is by including the CSS from the CDN, using the url below, replacing `<VERSION>` with the version you would like to use:
-
-```code
-https://cdn.jsdelivr.net/npm/iati-design-system@<VERSION>/dist/css/iati.min.css
-```
-
-This project is versioned using [Semantic Versioning](https://semver.org/). Versions can be specified as a major, minor, or patch version e.g. `1`, `1.2`, or `1.2.3`. The latest version is shown on the [GitHub releases page](https://github.com/IATI/design-system/releases). We recommend fixing to a specific patch version so that upgrades can be checked explicitly before deployment, but as a minimum you should fix to a major version to prevent unexpected breaking changes.
-
-To include the CSS in a HTML project, add the following code inside the `<head>` of your HTML pages:
-
-```html
-<link
-  href="https://cdn.jsdelivr.net/npm/iati-design-system@<VERSION>/dist/css/iati.min.css"
-  rel="stylesheet"
-/>
-```
-
-Once this link is included, core styles will be applied, and all component and layout CSS classes will be available to apply to HTML elements, for example the `.iati-button` class:
-
-```html
-<button class="iati-button">Button</button>
-```
-
-### NPM (Optional)
-
-It is also possible to include the design system in a [Sass](https://sass-lang.com/) project.
-
-First install with npm:
-
-```code
-npm install iati-design-system
-```
-
-Then import the package in your `.scss` file. The [Node.js Package Importer](https://sass-lang.com/documentation/at-rules/use/#node-js-package-importer) is required to use this syntax.
-
-```css
-@use "pkg:iati-design-system";
-```
-
-## How do I contribute to the IATI Design System?
+## Contributing to the IATI Design System
 
 ### Prerequisites
 

diff --git a/src/contributing.mdx b/src/contributing.mdx
@@ -0,0 +1,7 @@
+import { Meta, Title } from "@storybook/blocks";
+
+<Meta title="Contributing" />
+
+<Title>Contributing to the IATI Design System</Title>
+
+To contribute to the IATI Design System, please see the [Github repository](https://github.com/IATI/design-system).
diff --git a/src/installation.mdx b/src/installation.mdx
@@ -0,0 +1,37 @@
+import { Meta, Title } from "@storybook/blocks";
+
+<Meta title="Installation" />
+
+<Title>Installing the IATI Design System</Title>
+
+## CDN (Recommended)
+
+The recommended installation method is including the CSS and Javascript files which we are distirbuted using the [jsDelivr](https://www.jsdelivr.com/) CDN.
+
+Add the following code inside the `<head>` of your HTML pages, replacing `<VERSION>` with the version you want to use, e.g. `1.2.3`.
+This project is versioned using [Semantic Versioning](https://semver.org/), and the latest version is shown on the [GitHub releases page](https://github.com/IATI/design-system/releases).
+You can [watch the Github repository](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository) to be notified when a new version is released.
+
+```html
+<link
+  href="https://cdn.jsdelivr.net/npm/iati-design-system@<VERSION>/dist/css/iati.min.css"
+  rel="stylesheet"
+/>
+<script src="https://cdn.jsdelivr.net/npm/iati-design-system@<VERSION>/dist/js/iati.js"></script>
+```
+
+## NPM (Optional)
+
+It is also possible to include the design system in a [Sass](https://sass-lang.com/) project.
+
+First install with npm:
+
+```code
+npm install iati-design-system
+```
+
+Then import the package in your `.scss` file. The [Node.js Package Importer](https://sass-lang.com/documentation/at-rules/use/#node-js-package-importer) is required to use this syntax.
+
+```css
+@use "pkg:iati-design-system";
+```
diff --git a/src/start.mdx b/src/start.mdx
@@ -1,7 +1,9 @@
-import { Markdown, Meta, Title } from "@storybook/blocks";
-
-import ReadMe from "../README.md?raw";
+import { Meta, Title } from "@storybook/blocks";
 
 <Meta title="Get Started" />
 
-<Markdown>{ReadMe}</Markdown>
+<Title>IATI Design System</Title>
+
+The IATI Design System is a set of reusable styles and components which should be used in IATI web products, along with guidance on how to use them.
+
+Please see [installation](../?path=/docs/installation--docs) to start using it.
diff --git a/src/usage.mdx b/src/usage.mdx
@@ -0,0 +1,16 @@
+import { Canvas, Meta, Title } from "@storybook/blocks";
+import * as ButtonStories from "./scss/components/button/button.stories";
+
+<Meta title="Usage" />
+
+<Title>Using the IATI Design System</Title>
+
+After completing the <a href="../?path=/docs/installation--docs">installation</a> instructions,
+core styles, such as typography, should be applied to your site.
+
+This Storybook shows the components available in the design system.
+For each component, the **Docs** page shows available variants of the component, like the example shown below for the default variant of the Button component.
+
+Click on **Show code** in the bottom right to see the HTML elements and classes being used and apply them to your own site.
+
+<Canvas of={ButtonStories.Default} />