diff --git a/src/components/Theme/Theme.mdx b/src/components/Theme/Theme.mdx new file mode 100644 index 00000000..38c76d2a --- /dev/null +++ b/src/components/Theme/Theme.mdx @@ -0,0 +1,164 @@ +import { Meta, Canvas } from '@storybook/blocks'; + +import * as ThemeStories from './Theme.stories.svelte'; + + + +# Theme + +The `Theme` component wraps your page content and uses [CSS variables](../?path=/docs/scss-css-variables--page) to set major colour and typography styles for your page. All the components from this library that are added to your page will use the CSS variables set by `Theme`. + +Use the [theme builder](?path=/docs/components-theming-theme-builder--docs) to test custom themes. + +```svelte + + + + + +``` + +> In Graphics Kit, the `Theme` is set in both `pages/+page.svelte` and in `App.svelte`. + + + +## Custom theme + +You can customise your page's theme in two ways: + +- Choose the `base` theme, either `light` or `dark` +- Pass a custom theme object to the `theme` prop, which will override styles in the `base` theme. + +Use the [theme builder](?path=/docs/components-theming-theme-builder--docs) to see what properties you can customise. + +```svelte + + + +``` + +> **Note:** The `Theme` component only styles child components or elements, so if you're changing the background colour of your page, make sure to also set the `background-color` on your `body` element in global SCSS. +> +> ```scss +> // global.scss +> body { +> background-color: #2e3440; +> } +> ``` + + + +## Custom font + +To use typefaces other than the defaults provided by the Graphics Kit, download the font files from services such as [Google Fonts](https://fonts.google.com/) or [Adobe Typekit](https://fonts.adobe.com/). Make a folder called `fonts` inside `statics/` and put the font file -- for example, `IndieFlower-Regular.ttf` downloaded from [Google Fonts](https://fonts.google.com/share?selection.family=Indie+Flower) -- in `statics/fonts/`. + +Then, declare it as a `@font-face` in `global.scss`: + +```scss +/* global.scss in Graphics Kit */ +@font-face { + // If you're unsure of the font-family name, + // click on "Get embed code" on the Google font page and check the CSS class. + font-family: 'Indie Flower'; + + // Path to the font file. Change format depending on the font file type. + src: url('/fonts/IndieFlower-Regular.ttf') format('truetype'); + font-weight: normal; // Optional + font-style: normal; // Optional +} +``` + +Finally, pass the font to the appropriate text type in `Theme`: + +```svelte + + + +``` + + + +## Background patterns + +To use a background pattern or image, set the background colour property in `Theme` to `transparent`: + +```svelte + + + +``` + +Then in `global.scss`, set your image, which should be stored in `statics/images/`, as `background-image`: + +```scss +/* global.scss */ +body { + background-image: url('/images/my-pattern.png'); +} +``` + +You may also want to override the background on the header nav if it conflicts with your background, especially the dropdown menu: + +```scss +/* global.scss +Main nav container */ +.nav-container .inner { + background: darkblue !important; + /* Dropdown menu */ + .dropdown { + background: darkblue !important; + } +} +/* Mobile nav overlay */ +header + .overlay { + background: darkblue !important; +} +``` + + + +## Inheritance + +Styles that use `Theme`'s CSS variables will always use those set by the nearest parent `Theme`. That lets you change the theme for parts of your page by simply wrapping that bit in a new `Theme` with different styles. + +The demo below shows a more complex example of nesting themes, but more likely you'll so something like this: + +```svelte + + + + + + + + + +``` + + diff --git a/src/components/Theme/Theme.stories.svelte b/src/components/Theme/Theme.stories.svelte index 987086af..b00835a9 100644 --- a/src/components/Theme/Theme.stories.svelte +++ b/src/components/Theme/Theme.stories.svelte @@ -1,64 +1,38 @@ - + +
+ + + +
+ - - - + - +
@@ -83,11 +57,14 @@ dek={'The beginning of a beautiful page'} section={'Global news'} /> +
- +
- + +
- +

Theme

@@ -131,7 +115,7 @@ diff --git a/src/components/Theme/stories/docs/component.md b/src/components/Theme/stories/docs/component.md deleted file mode 100644 index 8ab19009..00000000 --- a/src/components/Theme/stories/docs/component.md +++ /dev/null @@ -1,15 +0,0 @@ -The `Theme` component wraps your page content and uses [CSS variables](../?path=/docs/scss-css-variables--page) to set major colour and typography styles for your page. All of the components in this library will use those CSS variables for styling by default. - -Use our [theme builder](../?path=/docs/theming-theme-builder--docs) to customise your page's theme. - -```svelte - - - - - -``` - -> For Graphics Kit users, the `Theme` is set for you in your graphics homepage (`pages/+page.svelte`). You can customise it there for the whole page. diff --git a/src/components/Theme/stories/docs/customise-font.md b/src/components/Theme/stories/docs/customise-font.md deleted file mode 100644 index 4c847c86..00000000 --- a/src/components/Theme/stories/docs/customise-font.md +++ /dev/null @@ -1,52 +0,0 @@ -For some projects, you may need to use typefaces other than the defaults provided by the GraphicsKit. - -You will need to: - -- Import the fonts in your code. -- Declare the `font-family` in the corresponding CSS variables in the Theme. - -There are many ways to load fonts, but care should be taken that the font files load first before page render, to avoid layout shifts during font swapping after the font is downloaded. For this reason, we will use `` method in the page `head` instead of CSS imports. - -> ##### Importing custom fonts - -> In this sample from [Google Fonts](https://fonts.google.com/specimen/Bebas+Neue), once we have selected the font family, copy the `` code. - -> ```html -> -> -> href="https://fonts.googleapis.com/css2?family=Bebas+Neue&display=swap" -> rel="stylesheet" -> /> -> ``` - -> In your project, navigate to `src` > `template.html` and add the copied code in `head` section : - -> ```svelte -> -> -> -> -> href="https://fonts.googleapis.com/css2?family=Bebas+Neue&display=swap" -> rel="stylesheet" -> /> -> -> %sveltekit.head% -> -> ``` - -> Similarly, you can add fonts from [Adobe Typekit](https://fonts.adobe.com/) or custom local fonts with the correct paths to the URL. - -You can customise one or more of the pre-defined font families in the Theme. Do not directly apply the font family in your CSS. Always use the CSS variables defined in the Theme so that it configures and reflects across the page design. - -```svelte - - - -``` diff --git a/src/components/Theme/stories/docs/customise.md b/src/components/Theme/stories/docs/customise.md deleted file mode 100644 index 00296641..00000000 --- a/src/components/Theme/stories/docs/customise.md +++ /dev/null @@ -1,28 +0,0 @@ -You can customise the theme of your page in two ways: - -First, you can choose the `base` theme, either `light` or `dark`. - -From there, you can pass a custom theme object to the `theme` prop. Any custom styles you pass to `theme` will override styles in the `base` theme. - -Check out the "Control" column for `theme` in the properties table above to see what properties you can customise. - -> **Pro tip:** The `Theme` component only styles child components or elements, so if you're changing the background colour of your page, it's still a good idea to set a `background-color` on your `body` element in global SCSS. -> -> ```scss -> // global.scss -> body { -> background-color: #2e3440; -> } -> ``` - -```svelte - - - -``` diff --git a/src/components/Theme/stories/docs/gfonts.png b/src/components/Theme/stories/docs/gfonts.png deleted file mode 100644 index 9e36b0cd..00000000 Binary files a/src/components/Theme/stories/docs/gfonts.png and /dev/null differ diff --git a/src/components/Theme/stories/docs/inheritance.md b/src/components/Theme/stories/docs/inheritance.md deleted file mode 100644 index 7cf806b9..00000000 --- a/src/components/Theme/stories/docs/inheritance.md +++ /dev/null @@ -1,17 +0,0 @@ -Styles that use `Theme`'s CSS variables will always use those set by the nearest parent `Theme`. That lets you change the theme for parts of your page by simply wrapping that bit in a _new_ `Theme` with different styles. - -The demo below shows a more complex example of nesting themes, but more likely you'll so something like this: - -```svelte - - - - - - - - - -``` diff --git a/src/components/Theme/stories/docs/pattern.md b/src/components/Theme/stories/docs/pattern.md deleted file mode 100644 index b741ec7c..00000000 --- a/src/components/Theme/stories/docs/pattern.md +++ /dev/null @@ -1,40 +0,0 @@ -To use a background pattern or image, set the background colour property in your custom theme to `transparent`... - -```svelte - - - -``` - -... then set your background image in global SCSS: - -```scss -/* global.scss */ -body { - background-color: darkblue; - background-image: url('$assets/images/my-pattern.png'); -} -``` - -You may also want to override the background on the header nav if it conflicts with your background, especially the dropdown menu: - -```scss -/* global.scss -Main nav container */ -.nav-container .inner { - background: darkblue !important; - /* Dropdown menu */ - .dropdown { - background: darkblue !important; - } -} -/* Mobile nav overlay */ -header + .overlay { - background: darkblue !important; -} -```