Skip to content

Commit 8222182

Browse files
codemacabrecodemacabre
authored
Merge pull request #61 from IATI/incremental-migration
Enable incremental migration
2 parents 6011323 + 1b33842 commit 8222182

File tree

10 files changed

+539
-399
lines changed

10 files changed

+539
-399
lines changed

‎.storybook/preview.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import type { Preview } from "@storybook/web-components";
2+
import { html } from "lit";
23

34
import "../src/js/main.js";
45
import "../src/scss/main.scss";
@@ -32,9 +33,22 @@ const preview: Preview = {
3233
page: DocsTemplate,
3334
source: {
3435
format: "dedent",
36+
excludeDecorators: true,
3537
},
3638
},
39+
designSystemEnabled: true,
3740
},
41+
decorators: [
42+
(storyFn, { parameters }) => {
43+
const { designSystemEnabled } = parameters;
44+
if (designSystemEnabled) {
45+
return html`<div class="iati-design-system--enabled">
46+
${storyFn()}
47+
</div>`;
48+
}
49+
return storyFn();
50+
},
51+
],
3852
};
3953

4054
export default preview;

‎package-lock.json‎

Lines changed: 407 additions & 372 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,11 @@
3333
"@commitlint/cli": "^19.3.0",
3434
"@commitlint/config-conventional": "^19.2.2",
3535
"@eslint/js": "^9.0.0",
36-
"@storybook/addon-essentials": "^8.0.10",
37-
"@storybook/addon-links": "^8.0.10",
38-
"@storybook/blocks": "^8.0.10",
39-
"@storybook/web-components": "^8.0.10",
40-
"@storybook/web-components-vite": "^8.0.10",
36+
"@storybook/addon-essentials": "^8.6.12",
37+
"@storybook/addon-links": "^8.6.12",
38+
"@storybook/blocks": "^8.6.12",
39+
"@storybook/web-components": "^8.6.12",
40+
"@storybook/web-components-vite": "^8.6.12",
4141
"eslint": "^8.57.0",
4242
"eslint-config-flat-gitignore": "^0.1.5",
4343
"eslint-config-prettier": "^9.1.0",
@@ -46,7 +46,7 @@
4646
"prettier-plugin-organize-imports": "^3.2.4",
4747
"sass": "^1.75.0",
4848
"semantic-release": "^23.1.1",
49-
"storybook": "^8.0.10",
49+
"storybook": "^8.6.12",
5050
"typescript": "^5.4.5",
5151
"typescript-eslint": "^7.7.0",
5252
"vite": "^5.4.4"

‎src/scss/layout/page/page.stories.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,3 +110,35 @@ export const LongPageLayout: Story = {
110110
${Footer.render?.call({ ...args })}
111111
`,
112112
};
113+
114+
export const IncrementalMigration: Story = {
115+
parameters: {
116+
designSystemEnabled: false,
117+
},
118+
render: (args) => html`
119+
<div class="iati-design-system--enabled">
120+
${Header.render?.call({ ...args })}
121+
</div>
122+
<h1>Incremental Migration</h1>
123+
<p>This example shows how to apply the IATI Design System incrementally.</p>
124+
<p>
125+
By wrapping the
126+
<code>header</code>and <code>footer</code> in the
127+
<code>.iati-design-system--enabled</code> class, the IATI Design System
128+
styles are applied only to those sections of the page, leaving the rest
129+
as-is.
130+
</p>
131+
<p>
132+
See the
133+
<a href="/?path=/docs/installation--docs#incremental-migration-version"
134+
>installation</a
135+
>
136+
and
137+
<a href="/?path=/docs/usage--docs#incremental-migration">usage</a> docs
138+
for more information.
139+
</p>
140+
<div class="iati-design-system--enabled">
141+
${Footer.render?.call({ ...args })}
142+
</div>
143+
`,
144+
};

‎src/scss/main.scss‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,23 @@
11
@use "sass:meta";
2-
@use "base";
32
@use "tokens";
4-
@use "typography";
5-
@use "components";
6-
@use "layout";
7-
@use "utilities";
83

94
// Expose tokens as Sass variables
105
@forward "tokens";
116

7+
// Load fonts
8+
@import "typography/fonts";
9+
10+
.iati-design-system--enabled {
11+
@import "base";
12+
@import "tokens";
13+
@import "typography";
14+
@import "components";
15+
@import "layout";
16+
@import "utilities";
17+
18+
@include body-styles();
19+
}
20+
1221
// Expose tokens as CSS custom properties
1322
:root {
1423
@each $name, $value in meta.module-variables("tokens") {

‎src/scss/typography/_body.scss‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,18 @@
22
@use "../tokens/font" as *;
33
@use "../tokens/spacing" as *;
44

5-
body {
5+
// Typography styles that are usually applied at the `body` level
6+
// must be placed within this mixin so that they can be pulled into the
7+
//`.iati-design-system--enabled` class in `main-incremental.scss`
8+
@mixin body-styles {
69
font-family: $font-stack-body;
710
font-weight: $font-weight-body;
811
color: $color-grey-90;
12+
line-height: 1.15;
13+
}
14+
15+
body {
16+
@include body-styles();
917
}
1018

1119
.iati-dark-background {

‎src/scss/typography/_fonts.scss‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
@import url("https://fonts.googleapis.com/css2?family=Hanken+Grotesk:ital,wght@0,100..900;1,100..900&display=swap");
2+
@import url("https://fonts.googleapis.com/css2?family=Nunito+Sans:ital,opsz,wght@0,6..12,200..1000;1,6..12,200..1000&display=swap");
3+
@import url("https://fonts.googleapis.com/css2?family=Roboto+Mono:ital,wght@0,100..700;1,100..700&display=swap");

‎src/scss/typography/_index.scss‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,4 @@
11
@forward "body";
22
@forward "code";
3+
@forward "fonts";
34
@forward "headings";
4-
5-
@import url("https://fonts.googleapis.com/css2?family=Hanken+Grotesk:ital,wght@0,100..900;1,100..900&display=swap");
6-
@import url("https://fonts.googleapis.com/css2?family=Nunito+Sans:ital,opsz,wght@0,6..12,200..1000;1,6..12,200..1000&display=swap");
7-
@import url("https://fonts.googleapis.com/css2?family=Roboto+Mono:ital,wght@0,100..700;1,100..700&display=swap");

‎src/usage.mdx‎

Lines changed: 51 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,58 @@ The IATI Design System is intended to increase the visual consistency of the IAT
99

1010
It is continuously being updated. If, when updating a website to use the design system, you find that an important question is unanswered, open a GitHub issue to discuss. In the meantime, continue to use your best judgement for the task at hand.
1111

12-
After completing the <a href="../?path=/docs/installation--docs">installation</a> instructions, core styles, such as typography, should be applied to your site.
12+
## Enable the Design System
1313

14-
This Storybook shows the components available in the design system.
15-
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.
14+
After completing the <a href="../?path=/docs/installation--docs">installation</a> instructions,
15+
you must enable the design system styles, by applying the `.iati-design-system--enabled` class on the `<body>` element of your page.
16+
This will apply core styles, such as typography, to the site, and enable you to use components from the design system.
1617

17-
Click on **Show code** in the bottom right to see the HTML elements and classes being used and apply them to your own site.
18+
```html
19+
<body class="iati-design-system--enabled">
20+
<!-- The rest of your page content -->
21+
</body>
22+
```
23+
24+
## Using Components
25+
26+
This Storybook site shows all the components available in the design system.
27+
For each component, the **"Docs"** page shows available variants of the component.
28+
29+
Click on **Show code** in the bottom right to see a HTML snippet which shows which CSS classes to use.
30+
For example, the snippet for the example below shows us that the `.iati-button` class has been applied to a `<button>` element.
1831

1932
<Canvas of={ButtonStories.Default} />
33+
34+
## Incremental Migration
35+
36+
For larger projects migrating to the IATI Design System, it can be useful to roll-out the styles incrementally instead of globally, to avoid clashes with existing styles.
37+
38+
To support this this, instead of appling the `.iati-design-system--enabled` class to the `<body>` element,
39+
it is possible to wrap any section of the page in a container with the `.iati-design-system--enabled` class,
40+
so that the IATI Design System styles are only applied to that section.
41+
This can be used on large components like the Header or for smaller elements like a Button.
42+
43+
### Example
44+
45+
The following code shows how to apply the IATI Design System to the header and footer,
46+
leaving the rest of the page as-is:
47+
48+
For a working example, see the <a href="/?path=/story/layout-page--incremental-migration">Incremental Migration story</a>.
49+
50+
```html
51+
<body>
52+
<div class="iati-design-system--enabled">
53+
<header class="iati-header">
54+
<!-- IATI Design System header code -->
55+
</header>
56+
</div>
57+
58+
<!-- The rest of your page content -->
59+
60+
<div class="iati-design-system--enabled">
61+
<footer class="iati-footer">
62+
<!-- IATI Design System footer code -->
63+
</footer>
64+
</div>
65+
</body>
66+
```

‎vite.config.js‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,23 +8,18 @@ export default defineConfig({
88
lib: {
99
entry: {
1010
iati: path.resolve(__dirname, "src/js/main.js"),
11-
css: path.resolve(__dirname, "src/scss/main.scss"),
11+
"css/iati": path.resolve(__dirname, "src/scss/main.scss"),
1212
},
1313
fileName: "iati",
1414
formats: ["es"],
1515
},
1616
rollupOptions: {
1717
output: {
1818
entryFileNames: "js/[name].js",
19-
assetFileNames: (assetInfo) => {
20-
if (assetInfo.name == "style.css") {
21-
return `css/iati.css`;
22-
}
23-
return assetInfo.name;
24-
},
2519
},
2620
},
2721
cssMinify: false,
22+
cssCodeSplit: true,
2823
},
2924
css: {
3025
preprocessorOptions: {

0 commit comments

Comments
 (0)