Skip to content

Commit

Permalink
Merge pull request #4 from IATI/sphinx-styles
Browse files Browse the repository at this point in the history
Add styles for IATI Sphinx theme
  • Loading branch information
tillywoodfield authored Jun 4, 2024
2 parents 1835199 + 9fa2d4f commit 8d58db9
Show file tree
Hide file tree
Showing 39 changed files with 675 additions and 79 deletions.
1 change: 1 addition & 0 deletions .nvmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
20
9 changes: 9 additions & 0 deletions .storybook/DocsTemplate.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
import { Meta, Title, Subtitle, Stories } from "@storybook/blocks";

<Meta isTemplate />

<Title />

<Subtitle />

<Stories />
7 changes: 0 additions & 7 deletions .storybook/StoriesOnlyTemplate.mdx

This file was deleted.

3 changes: 3 additions & 0 deletions .storybook/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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, {
Expand Down
4 changes: 3 additions & 1 deletion .storybook/preview.ts
Original file line number Diff line number Diff line change
@@ -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",
},
Expand Down
7 changes: 6 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
80 changes: 62 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
@@ -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`
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
1 change: 1 addition & 0 deletions src/scss/base/_index.scss
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
@forward "normalize";
@forward "reset";
@forward "mixins";
25 changes: 25 additions & 0 deletions src/scss/base/_mixins.scss
Original file line number Diff line number Diff line change
@@ -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;
}
15 changes: 15 additions & 0 deletions src/scss/base/_reset.scss
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
5 changes: 5 additions & 0 deletions src/scss/components/_index.scss
Original file line number Diff line number Diff line change
@@ -1 +1,6 @@
@forward "button/button";
@forward "callout/callout";
@forward "card/card";
@forward "icon/icon";
@forward "search-bar/search-bar";
@forward "table/table";
14 changes: 14 additions & 0 deletions src/scss/components/button/_button.scss
Original file line number Diff line number Diff line change
@@ -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;
}
}
14 changes: 14 additions & 0 deletions src/scss/components/button/button.stories.ts
Original file line number Diff line number Diff line change
@@ -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>`,
};
3 changes: 2 additions & 1 deletion src/scss/components/callout/_callout.scss
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
@use "../../tokens/color" as *;
@use "../../tokens/font" as *;
@use "../../tokens/spacing" as *;

.iati-callout {
Expand Down Expand Up @@ -39,6 +40,6 @@
&__title {
font-weight: bold;
font-size: 1.2rem;
line-height: 2;
line-height: $line-height-body;
}
}
8 changes: 0 additions & 8 deletions src/scss/components/callout/callout.stories.ts
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
31 changes: 31 additions & 0 deletions src/scss/components/card/_card.scss
Original file line number Diff line number Diff line change
@@ -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;
}
}
20 changes: 20 additions & 0 deletions src/scss/components/card/card.stories.ts
Original file line number Diff line number Diff line change
@@ -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>
`,
};
22 changes: 22 additions & 0 deletions src/scss/components/icon/_icon.scss
Original file line number Diff line number Diff line change
@@ -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>");
}
}
21 changes: 21 additions & 0 deletions src/scss/components/icon/icon.stories.ts
Original file line number Diff line number Diff line change
@@ -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>`,
};
Loading

0 comments on commit 8d58db9

Please sign in to comment.