WARNING: THIS SITE IS A MIRROR OF GITHUB.COM / IT CANNOT LOGIN OR REGISTER ACCOUNTS / THE CONTENTS ARE PROVIDED AS-IS / THIS SITE ASSUMES NO RESPONSIBILITY FOR ANY DISPLAYED CONTENT OR LINKS / IF YOU FOUND SOMETHING MAY NOT GOOD FOR EVERYONE, CONTACT ADMIN AT ilovescratch@foxmail.com
Skip to content

Commit c2ff61d

Browse files
tillywoodfieldtillywoodfield
committed
docs: split usage instructions into multiple pages for more clarity
1 parent fca93eb commit c2ff61d

File tree

6 files changed

+79
-47
lines changed

6 files changed

+79
-47
lines changed

‎.storybook/preview.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,16 @@ const preview: Preview = {
88
parameters: {
99
options: {
1010
storySort: {
11-
order: ["Get Started", "Brand", "Core", "Components", "Layout"],
11+
order: [
12+
"Get Started",
13+
"Installation",
14+
"Usage",
15+
"Contributing",
16+
"Brand",
17+
"Core",
18+
"Components",
19+
"Layout",
20+
],
1221
},
1322
},
1423
backgrounds: {

‎README.md‎

Lines changed: 3 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -4,50 +4,11 @@
44

55
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.
66

7-
## How do I use the IATI Design System?
7+
## Using the IATI Design System
88

9-
### CDN (Recommended)
9+
Please see the [Storybook site](https://iati.github.io/design-system/) for instructions.
1010

11-
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:
12-
13-
```code
14-
https://cdn.jsdelivr.net/npm/iati-design-system@<VERSION>/dist/css/iati.min.css
15-
```
16-
17-
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.
18-
19-
To include the CSS in a HTML project, add the following code inside the `<head>` of your HTML pages:
20-
21-
```html
22-
<link
23-
href="https://cdn.jsdelivr.net/npm/iati-design-system@<VERSION>/dist/css/iati.min.css"
24-
rel="stylesheet"
25-
/>
26-
```
27-
28-
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:
29-
30-
```html
31-
<button class="iati-button">Button</button>
32-
```
33-
34-
### NPM (Optional)
35-
36-
It is also possible to include the design system in a [Sass](https://sass-lang.com/) project.
37-
38-
First install with npm:
39-
40-
```code
41-
npm install iati-design-system
42-
```
43-
44-
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.
45-
46-
```css
47-
@use "pkg:iati-design-system";
48-
```
49-
50-
## How do I contribute to the IATI Design System?
11+
## Contributing to the IATI Design System
5112

5213
### Prerequisites
5314

‎src/contributing.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
import { Meta, Title } from "@storybook/blocks";
2+
3+
<Meta title="Contributing" />
4+
5+
<Title>Contributing to the IATI Design System</Title>
6+
7+
To contribute to the IATI Design System, please see the [Github repository](https://github.com/IATI/design-system).

‎src/installation.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
import { Meta, Title } from "@storybook/blocks";
2+
3+
<Meta title="Installation" />
4+
5+
<Title>Installing the IATI Design System</Title>
6+
7+
## CDN (Recommended)
8+
9+
The recommended installation method is including the CSS and Javascript files which we are distirbuted using the [jsDelivr](https://www.jsdelivr.com/) CDN.
10+
11+
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`.
12+
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).
13+
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.
14+
15+
```html
16+
<link
17+
href="https://cdn.jsdelivr.net/npm/iati-design-system@<VERSION>/dist/css/iati.min.css"
18+
rel="stylesheet"
19+
/>
20+
<script src="https://cdn.jsdelivr.net/npm/iati-design-system@<VERSION>/dist/js/iati.js"></script>
21+
```
22+
23+
## NPM (Optional)
24+
25+
It is also possible to include the design system in a [Sass](https://sass-lang.com/) project.
26+
27+
First install with npm:
28+
29+
```code
30+
npm install iati-design-system
31+
```
32+
33+
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.
34+
35+
```css
36+
@use "pkg:iati-design-system";
37+
```

‎src/start.mdx‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
1-
import { Markdown, Meta, Title } from "@storybook/blocks";
2-
3-
import ReadMe from "../README.md?raw";
1+
import { Meta, Title } from "@storybook/blocks";
42

53
<Meta title="Get Started" />
64

7-
<Markdown>{ReadMe}</Markdown>
5+
<Title>IATI Design System</Title>
6+
7+
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.
8+
9+
Please see [installation](../?path=/docs/installation--docs) to start using it.

‎src/usage.mdx‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import { Canvas, Meta, Title } from "@storybook/blocks";
2+
import * as ButtonStories from "./scss/components/button/button.stories";
3+
4+
<Meta title="Usage" />
5+
6+
<Title>Using the IATI Design System</Title>
7+
8+
After completing the <a href="../?path=/docs/installation--docs">installation</a> instructions,
9+
core styles, such as typography, should be applied to your site.
10+
11+
This Storybook shows the components available in the design system.
12+
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.
13+
14+
Click on **Show code** in the bottom right to see the HTML elements and classes being used and apply them to your own site.
15+
16+
<Canvas of={ButtonStories.Default} />

0 commit comments

Comments
 (0)