From fcddbea7058d2209f90684e768e7c549395c32f0 Mon Sep 17 00:00:00 2001 From: Tilly Woodfield <22456167+tillywoodfield@users.noreply.github.com> Date: Thu, 24 Oct 2024 11:03:55 +0300 Subject: [PATCH] docs: split usage instructions into multiple pages for more clarity --- .storybook/preview.ts | 11 ++++++++++- README.md | 45 +++---------------------------------------- src/contributing.mdx | 7 +++++++ src/installation.mdx | 37 +++++++++++++++++++++++++++++++++++ src/start.mdx | 10 ++++++---- src/usage.mdx | 16 +++++++++++++++ 6 files changed, 79 insertions(+), 47 deletions(-) create mode 100644 src/contributing.mdx create mode 100644 src/installation.mdx create mode 100644 src/usage.mdx diff --git a/.storybook/preview.ts b/.storybook/preview.ts index b2928da..1beb696 100644 --- 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 index e0677fc..87cab31 100644 --- 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 `` with the version you would like to use: - -```code -https://cdn.jsdelivr.net/npm/iati-design-system@/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 `` of your HTML pages: - -```html - -``` - -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 - -``` - -### 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 new file mode 100644 index 0000000..1e30e3a --- /dev/null +++ b/src/contributing.mdx @@ -0,0 +1,7 @@ +import { Meta, Title } from "@storybook/blocks"; + + + +Contributing to the IATI Design System + +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 new file mode 100644 index 0000000..79933f7 --- /dev/null +++ b/src/installation.mdx @@ -0,0 +1,37 @@ +import { Meta, Title } from "@storybook/blocks"; + + + +Installing the IATI Design System + +## 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 `` of your HTML pages, replacing `` 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 + + +``` + +## 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 index 98d0887..c4ac2c8 100644 --- 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"; -{ReadMe} +IATI Design System + +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 new file mode 100644 index 0000000..eb92873 --- /dev/null +++ b/src/usage.mdx @@ -0,0 +1,16 @@ +import { Canvas, Meta, Title } from "@storybook/blocks"; +import * as ButtonStories from "./scss/components/button/button.stories"; + + + +Using the IATI Design System + +After completing the installation 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. + +