IATI · tillywoodfield · Jun 4, 2024 · May 29, 2024 · May 29, 2024 · May 29, 2024
diff --git a/.nvmrc b/.nvmrc
@@ -0,0 +1 @@
+20
diff --git a/.storybook/DocsTemplate.mdx b/.storybook/DocsTemplate.mdx
@@ -0,0 +1,9 @@
+import { Meta, Title, Subtitle, Stories } from "@storybook/blocks";
+
+<Meta isTemplate />
+
+<Title />
+
+<Subtitle />
+
+<Stories />
diff --git a/.storybook/StoriesOnlyTemplate.mdx b/.storybook/StoriesOnlyTemplate.mdx
diff --git a/.storybook/main.ts b/.storybook/main.ts
@@ -5,6 +5,9 @@ const config: StorybookConfig = {
   framework: "@storybook/web-components-vite",
   stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
   addons: ["@storybook/addon-essentials"],
+  docs: {
+    autodocs: true,
+  },
   async viteFinal(config) {
     const { mergeConfig } = await import("vite");
     return mergeConfig(config, {

diff --git a/.storybook/preview.ts b/.storybook/preview.ts
@@ -1,15 +1,17 @@
 import type { Preview } from "@storybook/web-components";
 
 import "../src/scss/iati.scss";
+import DocsTemplate from "./DocsTemplate.mdx";
 
 const preview: Preview = {
   parameters: {
     options: {
       storySort: {
-        order: ["Core", "Components"],
+        order: ["Get Started", "Core", "Components", "Layout"],
       },
     },
     docs: {
+      page: DocsTemplate,
       source: {
         format: "dedent",
       },

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -22,4 +22,9 @@ BREAKING CHANGE: removes the '.subcomponent' class.
 
 ### What is a breaking change?
 
-A breaking change is any "incompatible API change". In the context of this design system, the API consists of CSS classes and SASS variables/functions/mixins etc. Any change which removes or renames a part of the API must be labelled a breaking change.
+A breaking change is any "incompatible API change". In the context of this design system, the API consists of CSS classes and SASS variables/functions/mixins etc.
+
+Breaking changes include the following:
+
+- Any change which removes or renames a part of the API must be labelled a breaking change.
+- Any change which would require a downstream consumer to change their HTML.
diff --git a/README.md b/README.md
@@ -1,37 +1,81 @@
 # IATI Design System
 
-## Usage
+## What is the IATI Design System?
 
-### NPM
+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.
 
-```
-npm install iati-design-system
-```
+## How do I use the IATI Design System?
 
-### CDN
+### CDN (Recommended)
 
-```
-https://cdn.jsdelivr.net/npm/iati-design-system@[X.Y.Z]/dist/css/iati.css
+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
 ```
 
-## Development
+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.
 
-Start storybook:
+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"
+/>
 ```
-npm start
+
+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>
 ```
 
-## Production build
+### NPM (Optional)
 
-Build CSS:
+It is also possible to include the design system in a [Sass](https://sass-lang.com/) project.
 
-```
-npm run build
+First install with npm:
+
+```code
+npm install iati-design-system
 ```
 
-Build storybook:
+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";
 ```
-npm run build:storybook
-```
+
+## How do I contribute to the IATI Design System?
+
+### Prerequisites
+
+#### Node v20
+
+IATI Design System requires Node v20. We recommend installing [Node Version Manager](https://github.com/nvm-sh/nvm) and running the command `nvm use` to use the Node version set in the `.nvmrc` file at the root of the project.
+
+### Running locally
+
+To run Storybook locally, take the following steps:
+
+1. Install dependencies: `npm install`
+2. Start Storybook: `npm start`
+
+You will see live updates in the browser when you update styles or stories.
+
+### Production build
+
+#### CSS
+
+To check the CSS production build, take the following steps:
+
+1. Build the CSS: `npm run build`
+2. View the CSS file: `./dist/css/iati.css`.
+
+#### Storybook
+
+The check the Storybook production build, take the following steps:
+
+1. Build the Storybook: `npm run build:storybook`
+2. Serve the Storybook: `npm run serve:storybook`
diff --git a/package.json b/package.json
@@ -20,6 +20,7 @@
     "start": "storybook dev -p 6006",
     "build": "sass --pkg-importer=node --no-source-map --style=expanded src/scss:dist/css",
     "build:storybook": "storybook build",
+    "serve:storybook": "npx http-server -o ./storybook-static",
     "lint": "npm run lint:eslint && npm run lint:prettier",
     "lint:eslint": "eslint",
     "lint:prettier": "prettier . --check",

diff --git a/src/scss/base/_index.scss b/src/scss/base/_index.scss
@@ -1,2 +1,3 @@
 @forward "normalize";
 @forward "reset";
+@forward "mixins";
diff --git a/src/scss/base/_mixins.scss b/src/scss/base/_mixins.scss
@@ -0,0 +1,25 @@
+@use "../tokens/color" as *;
+@use "../tokens/spacing" as *;
+
+@mixin page-width-container {
+  width: 100%;
+  max-width: $page-width-max;
+  margin-left: auto;
+  margin-right: auto;
+  padding: $padding-block;
+}
+
+@mixin columns {
+  display: flex;
+  flex-flow: row nowrap;
+  justify-content: space-between;
+  align-items: center;
+  column-gap: $padding-block;
+  row-gap: $padding-block;
+}
+
+@mixin unstyled-list {
+  list-style-type: none;
+  margin: 0;
+  padding: 0;
+}
diff --git a/src/scss/base/_reset.scss b/src/scss/base/_reset.scss
@@ -16,3 +16,18 @@ strong {
 em {
   font-style: italic;
 }
+
+html {
+  height: 100%;
+}
+
+body {
+  height: 100%;
+  display: flex;
+  flex-flow: column;
+}
+
+a:has(i),
+a:has(img) {
+  text-decoration: none;
+}
diff --git a/src/scss/components/_index.scss b/src/scss/components/_index.scss
@@ -1 +1,6 @@
+@forward "button/button";
 @forward "callout/callout";
+@forward "card/card";
+@forward "icon/icon";
+@forward "search-bar/search-bar";
+@forward "table/table";
diff --git a/src/scss/components/button/_button.scss b/src/scss/components/button/_button.scss
@@ -0,0 +1,14 @@
+@use "../../tokens/color" as *;
+@use "../../tokens/spacing" as *;
+
+.iati-button {
+  background-color: $color-teal-90;
+  border: none;
+  color: white;
+  text-transform: uppercase;
+  padding: $padding-block;
+
+  &:hover {
+    background-color: $color-teal-80;
+  }
+}
diff --git a/src/scss/components/button/button.stories.ts b/src/scss/components/button/button.stories.ts
@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from "@storybook/web-components";
+
+import { html } from "lit";
+
+const meta: Meta = {
+  title: "Components/Button",
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Button: Story = {
+  render: () => html`<button class="iati-button">Button</button>`,
+};
diff --git a/src/scss/components/callout/_callout.scss b/src/scss/components/callout/_callout.scss
@@ -1,4 +1,5 @@
 @use "../../tokens/color" as *;
+@use "../../tokens/font" as *;
 @use "../../tokens/spacing" as *;
 
 .iati-callout {
@@ -39,6 +40,6 @@
   &__title {
     font-weight: bold;
     font-size: 1.2rem;
-    line-height: 2;
+    line-height: $line-height-body;
   }
 }
diff --git a/src/scss/components/callout/callout.stories.ts b/src/scss/components/callout/callout.stories.ts
@@ -1,16 +1,8 @@
 import type { Meta, StoryObj } from "@storybook/web-components";
 import { html } from "lit";
 
-import Template from "../../../../.storybook/StoriesOnlyTemplate.mdx";
-
 const meta: Meta = {
   title: "Components/Callout",
-  tags: ["autodocs"],
-  parameters: {
-    docs: {
-      page: Template,
-    },
-  },
 };
 
 export default meta;

diff --git a/src/scss/components/card/_card.scss b/src/scss/components/card/_card.scss
@@ -0,0 +1,31 @@
+@use "../../tokens/color" as *;
+@use "../../tokens/spacing" as *;
+
+.iati-card {
+  box-shadow: 0 4px 5px $color-grey-20;
+  background-color: white;
+  border-top: $border-width solid $color-teal-90;
+  padding: $padding-block;
+
+  & :first-child {
+    margin-top: 0;
+  }
+
+  & :last-child {
+    margin-bottom: 0;
+  }
+
+  &__title {
+    margin: 0;
+    font-weight: bold;
+    font-size: 1.2rem;
+  }
+
+  &__subtitle {
+    color: $color-teal-90;
+    font-size: 0.8rem;
+    font-weight: bold;
+    margin: 0;
+    text-transform: uppercase;
+  }
+}
diff --git a/src/scss/components/card/card.stories.ts b/src/scss/components/card/card.stories.ts
@@ -0,0 +1,20 @@
+import type { Meta, StoryObj } from "@storybook/web-components";
+
+import { html } from "lit";
+
+const meta: Meta = {
+  title: "Components/Card",
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Card: Story = {
+  render: () => html`
+    <div class="iati-card">
+      <p class="iati-card__title">Card Title</p>
+      <p class="iati-card__subtitle">Subtitle</p>
+      <p>Card content.</p>
+    </div>
+  `,
+};
diff --git a/src/scss/components/icon/_icon.scss b/src/scss/components/icon/_icon.scss
@@ -0,0 +1,22 @@
+.iati-icon {
+  display: inline-block;
+  height: 45px;
+  width: 45px;
+  border-radius: 100%;
+  background-color: white;
+  background-repeat: no-repeat;
+  background-size: 60%;
+  background-position: center;
+
+  &--youtube {
+    background-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' fill='%23FF0000' viewBox='0 0 16 16'><path d='M8.051 1.999h.089c.822.003 4.987.033 6.11.335a2.01 2.01 0 0 1 1.415 1.42c.101.38.172.883.22 1.402l.01.104.022.26.008.104c.065.914.073 1.77.074 1.957v.075c-.001.194-.01 1.108-.082 2.06l-.008.105-.009.104c-.05.572-.124 1.14-.235 1.558a2.01 2.01 0 0 1-1.415 1.42c-1.16.312-5.569.334-6.18.335h-.142c-.309 0-1.587-.006-2.927-.052l-.17-.006-.087-.004-.171-.007-.171-.007c-1.11-.049-2.167-.128-2.654-.26a2.01 2.01 0 0 1-1.415-1.419c-.111-.417-.185-.986-.235-1.558L.09 9.82l-.008-.104A31 31 0 0 1 0 7.68v-.123c.002-.215.01-.958.064-1.778l.007-.103.003-.052.008-.104.022-.26.01-.104c.048-.519.119-1.023.22-1.402a2.01 2.01 0 0 1 1.415-1.42c.487-.13 1.544-.21 2.654-.26l.17-.007.172-.006.086-.003.171-.007A100 100 0 0 1 7.858 2zM6.4 5.209v4.818l4.157-2.408z'/></svg>");
+  }
+
+  &--twitter {
+    background-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' fill='%231DA1F2' viewBox='0 0 16 16'><path d='M5.026 15c6.038 0 9.341-5.003 9.341-9.334q.002-.211-.006-.422A6.7 6.7 0 0 0 16 3.542a6.7 6.7 0 0 1-1.889.518 3.3 3.3 0 0 0 1.447-1.817 6.5 6.5 0 0 1-2.087.793A3.286 3.286 0 0 0 7.875 6.03a9.32 9.32 0 0 1-6.767-3.429 3.29 3.29 0 0 0 1.018 4.382A3.3 3.3 0 0 1 .64 6.575v.045a3.29 3.29 0 0 0 2.632 3.218 3.2 3.2 0 0 1-.865.115 3 3 0 0 1-.614-.057 3.28 3.28 0 0 0 3.067 2.277A6.6 6.6 0 0 1 .78 13.58a6 6 0 0 1-.78-.045A9.34 9.34 0 0 0 5.026 15'/></svg>");
+  }
+
+  &--linkedin {
+    background-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' fill='%230762C8' viewBox='0 0 16 16'><path d='M0 1.146C0 .513.526 0 1.175 0h13.65C15.474 0 16 .513 16 1.146v13.708c0 .633-.526 1.146-1.175 1.146H1.175C.526 16 0 15.487 0 14.854zm4.943 12.248V6.169H2.542v7.225zm-1.2-8.212c.837 0 1.358-.554 1.358-1.248-.015-.709-.52-1.248-1.342-1.248S2.4 3.226 2.4 3.934c0 .694.521 1.248 1.327 1.248zm4.908 8.212V9.359c0-.216.016-.432.08-.586.173-.431.568-.878 1.232-.878.869 0 1.216.662 1.216 1.634v3.865h2.401V9.25c0-2.22-1.184-3.252-2.764-3.252-1.274 0-1.845.7-2.165 1.193v.025h-.016l.016-.025V6.169h-2.4c.03.678 0 7.225 0 7.225z'/></svg>");
+  }
+}
diff --git a/src/scss/components/icon/icon.stories.ts b/src/scss/components/icon/icon.stories.ts
@@ -0,0 +1,21 @@
+import type { Meta, StoryObj } from "@storybook/web-components";
+import { html } from "lit";
+
+const meta: Meta = {
+  title: "Components/Icon",
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Youtube: Story = {
+  render: () => html`<i class="iati-icon iati-icon--youtube"></i>`,
+};
+
+export const Twitter: Story = {
+  render: () => html`<i class="iati-icon iati-icon--twitter"></i>`,
+};
+
+export const Linkedin: Story = {
+  render: () => html`<i class="iati-icon iati-icon--linkedin"></i>`,
+};