docs

.storybook/preview.js

@@ -57,7 +57,8 @@ export const parameters = {
           'Recipes: Story with custom docs',
           'Recipes: Story with custom controls',
           'Recipes: Story with media',
-          'Recipes: Story for a component with slots'
+          'Recipes: Story for a component with slots',
+          'Writing docs pages',
         ],
       ],
     },

src/actions/cssVariables/cssVariables.stories.mdx

@@ -7,11 +7,11 @@ import { parameters } from '$docs/utils/docsPage.js';
 
 # `cssVariables`
 
-A Svelte [action](https://svelte.dev/tutorial/actions) you can use to easily set [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) on HTML elements. Useful for passing JavaScript values to your component SCSS like this:
+An action you can use to easily set [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) on HTML elements. Useful for passing JavaScript values to your component SCSS like this:
 
 ```svelte
 <script>
-  import { cssVariables } from '@reuters-graphics/graphics-svelte-components';
+  import { cssVariables } from '@reuters-graphics/graphics-components';
 
   export let height = 300;
   export let textColour = 'red';

src/components/Block/stories/docs/component.md

@@ -9,7 +9,6 @@ Blocks are stacked vertically within the well created by the [`Article`](./?path
   import { Block } from '@reuters-graphics/graphics-components';
 </script>
 
-
 <Block width="normal">
   <!-- Your stuff for this block -->
 </Block>

src/components/DatawrapperChart/stories/docs/component.md

@@ -6,11 +6,11 @@ Easily add a responsive Datawrapper embed on your page.
 </script>
 
 <DatawrapperChart
-  title='Global abortion access'
-  ariaLabel='map'
-  id='abortion-rights-map'
-  src='https://graphics.reuters.com/USA-ABORTION/lgpdwggnwvo/media-embed.html'
- />
+  title="Global abortion access"
+  ariaLabel="map"
+  id="abortion-rights-map"
+  src="https://graphics.reuters.com/USA-ABORTION/lgpdwggnwvo/media-embed.html"
+/>
 ```
 
 ##### Getting the chart URL for `src`

src/components/EmbedPreviewerLink/stories/docs/component.md

@@ -7,5 +7,5 @@ An embed tool for development in graphics kit.
   import { dev } from '$app/env';
 </script>
 
-<EmbedPreviewerLink dev={dev} />
+<EmbedPreviewerLink dev="{dev}" />
 ```

src/components/Framer/stories/docs/component.md

@@ -7,5 +7,5 @@ An embed tool for development in the Graphics Kit.
   const embeds = ['/embeds/my-chart/index.html'];
 </script>
 
-<Framer embeds={embeds} />
+<Framer embeds="{embeds}" />
 ```

src/components/GraphicBlock/stories/docs/component.md

@@ -9,13 +9,12 @@ Many other components use this one to wrap graphics with styled text. When you u
   import { GraphicBlock } from '@reuters-graphics/graphics-components';
 </script>
 
-
 <GraphicBlock
   width="normal"
   title="Title for my chart"
   description="Pork loin t-bone jowl prosciutto, short loin flank kevin tri-tip cupim pig pork. Meatloaf tri-tip frankfurter short ribs, cupim brisket bresaola chislic tail jerky burgdoggen pancetta."
   notes="Note: Data current as of Aug. 2, 2022.\n\nSource: [Google research](https://google.com)"
 >
-  <div id="my-chart"/>
+  <div id="my-chart"></div>
 </GraphicBlock>
 ```

src/components/SEO/SEO.stories.svelte

@@ -10,11 +10,11 @@
 
   import {
     withComponentDocs,
-    withStoryDocs,
+    withStoryDocs
   } from '$lib/docs/utils/withParams.js';
 
   const meta = {
-    title: 'Utilities/SEO',
+    title: 'Components/SEO',
     component: SEO,
     ...withComponentDocs(componentDocs),
   };

src/components/SiteFooter/stories/docs/customReferrals.md

@@ -3,7 +3,7 @@ Pass up to four custom referrals to the `referrals` prop.
 ```svelte
 <script>
   import { SiteFooter } from '@reuters-graphics/graphics-components';
-  
+
   const customReferrals = [
     {
       url: 'https://graphics.reuters.com/world-coronavirus-tracker-and-maps/',

src/components/SiteFooter/stories/docs/darkTheme.md

@@ -15,12 +15,21 @@ The component also exports some preset themes you can use or customise:
 
 ```svelte
 <script>
-  import { SiteFooter, SiteFooterThemes } from '@reuters-graphics/graphics-components';
+  import {
+    SiteFooter,
+    SiteFooterThemes,
+  } from '@reuters-graphics/graphics-components';
 </script>
 
 <!-- Use a preset theme. -->
-<SiteFooter theme={SiteFooterThemes.dark} />
+<SiteFooter theme="{SiteFooterThemes.dark}" />
 
 <!-- Customise a couple colours in a theme. -->
-<SiteFooter theme={{ ...SiteFooterThemes.default, background: '#e0d3b8', rules: '#aaa' }} />
+<SiteFooter
+  theme="{{
+    ...SiteFooterThemes.default,
+    background: '#e0d3b8',
+    rules: '#aaa',
+  }}"
+/>
 ```

src/components/SiteHeader/stories/docs/darkTheme.md

@@ -15,12 +15,21 @@ The component also exports some preset themes you can use or customise:
 
 ```svelte
 <script>
-  import { SiteHeader, SiteHeaderThemes } from '@reuters-graphics/graphics-components';
+  import {
+    SiteHeader,
+    SiteHeaderThemes,
+  } from '@reuters-graphics/graphics-components';
 </script>
 
 <!-- Use a preset theme. -->
-<SiteHeader theme={SiteHeaderThemes.dark} />
+<SiteHeader theme="{SiteHeaderThemes.dark}" />
 
 <!-- Customise a couple colours in a theme. -->
-<SiteHeader theme={{ ...SiteHeaderThemes.default, background: '#e0d3b8', rules: '#aaa' }} />
+<SiteHeader
+  theme="{{
+    ...SiteHeaderThemes.default,
+    background: '#e0d3b8',
+    rules: '#aaa',
+  }}"
+/>
 ```

src/components/Video/stories/docs/withSound.md

@@ -6,11 +6,11 @@ If you have a video with sound, make sure to add the prop `muteVideo={false}`.
 Then you can either:
 
 - `allowSoundToAutoplay={false}` (default) : Don't allow the video to autoplay under any circumstances other than when the user clicks the 'play' on the video. Note that this
-works whether or not you have the controls visible, i.e. with `showControls` being `true` or `false`, as long as you allow
-play/pause behaviour with `possibleToPlayPause={true}` (default).
+  works whether or not you have the controls visible, i.e. with `showControls` being `true` or `false`, as long as you allow
+  play/pause behaviour with `possibleToPlayPause={true}` (default).
 
 - `allowSoundToAutoplay={true}` : Allow the video to autoplay when it comes into view as long as the user has interacted with the page preivously, i.e. they have clicked/tapped
-anywhere on the page.
+  anywhere on the page.
 
 You should keep `playVideoWhenInView={true}` (default). There is no option to autoplay video with sound when the user clicks on the page
 elsewhere if the video is not in view. In other words, you can't start playing sound for a video which is not in view with this component.
@@ -24,13 +24,13 @@ and go to the top. Click anywhere on the page before scrolling down to the video
   import { Video } from '@reuters-graphics/graphics-components';
 </script>
 
-<Video 
-  ariaDescription={"Compulsory description of your video for screen readers."}
-  src={'path-to-video-or-external-url'} 
-  size={'normal'}
-  controlsOpacity={1}
-  loopVideo={false}
-  muteVideo={false}
-  allowSoundToAutoplay={true}
+<Video
+  ariaDescription="{'Compulsory description of your video for screen readers.'}"
+  src="{'path-to-video-or-external-url'}"
+  size="{'normal'}"
+  controlsOpacity="{1}"
+  loopVideo="{false}"
+  muteVideo="{false}"
+  allowSoundToAutoplay="{true}"
 />
 ```

src/components/Visible/Visible.stories.svelte

@@ -14,7 +14,7 @@
   } from '$lib/docs/utils/withParams.js';
 
   const meta = {
-    title: 'Utilities/Visible',
+    title: 'Components/Visible',
     component: Visible,
     ...withComponentDocs(componentDocs),
   };

src/docs/actions/intro.stories.mdx

@@ -6,3 +6,11 @@ import { parameters } from '$docs/utils/docsPage.js';
 ![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
 
 # Actions
+
+Svelte [actions](https://svelte.dev/tutorial/actions) are arbitrary functions that run after Svelte "mounts" an element in the DOM.
+
+But let's try a _less_ technical definition: Svelte actions are extra topping you can add to your HTML once it comes out of the oven.
+
+These are little functions that do little, if often very useful, things on top of your code.
+
+Have a look through the actions we have in this section to get a better idea and watch this space for more TK.

src/docs/contributing/component.basics.stories.mdx

@@ -1,7 +1,7 @@
 import { Meta } from '@storybook/addon-docs';
 import { parameters } from '$docs/utils/docsPage.js';
 
-<Meta title="Contributing/Component Basics" parameters={{ ...parameters }} />
+<Meta title="Contributing/Component basics" parameters={{ ...parameters }} />
 
 ![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
 
@@ -17,7 +17,7 @@ By default, component's are written in TypeScript, which adds robust type-checki
 
 If you've never used TypeScript, you can check out the [5-minute intro](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html).
 
-If you're still a little uneasy about writing TypeScript, you can still write basically all your component logic in plain JavaScript, but we'll probably make sure your component's outermost props are typed before we merge your PR. (Reuters Graphics, can ask Jon for help with this.)
+> If you've never used TypeScript, you can check out the [5-minute intro](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html). If you're still uneasy writing TypeScript, don't sweat it! Just write your component in plain JavaScript/Svelte. We'll convert at least your component's props to TypeScript as part of the PR review.
 
 ### Typing and documenting component props
 
@@ -131,7 +131,7 @@ In rare cases, you can use the SCSS `:global` operator to style child elements i
 <style lang="scss">
   svg {
     :global {
-      path: {
+      path {
         stroke: black;
       }
     }

src/docs/contributing/writing-component-stories.stories.mdx

@@ -1,7 +1,7 @@
 import { Meta } from '@storybook/addon-docs';
 import { parameters } from '$docs/utils/docsPage.js';
 
-<Meta title="Contributing/Writing Stories" parameters={{ ...parameters }} />
+<Meta title="Contributing/Writing stories" parameters={{ ...parameters }} />
 
 ![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
 

src/docs/contributing/writing-docs-stories.stories.mdx

@@ -0,0 +1,39 @@
+import { Meta } from '@storybook/addon-docs';
+import { parameters } from '$docs/utils/docsPage.js';
+
+<Meta title="Contributing/Writing docs pages" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Writing docs-only pages
+
+You can write docs-only pages in simple markdown using MDX format.
+
+> MDX is _technically_ a mixture of markdown and React. Unforuntately, there isn't a native Svelte option for markdown pages in Storybook yet. Good news, though, you won't _really_ need to know React to use it. Just write in markdown and follow the template below for the React bits you'll need.
+
+### Quickstart
+
+Make a new `.stories.mdx` file for your docs page in the `src/docs/` directory.
+
+```
+src/
+  docs/
+    my-docs.stories.mdx
+```
+
+Add the following at the top of the file and customise the `title` property in the `Meta` component for where you want the page to live in the Storybook nav.
+
+```markdown
+import { Meta } from '@storybook/addon-docs';
+import { parameters } from '$docs/utils/docsPage.js';
+
+<Meta title="SCSS/Special rules" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# My docs page
+
+Your docs TK...
+```
+
+From there, write whatever you need in markdown.

src/docs/guides/getting-help.stories.mdx

@@ -7,19 +7,19 @@ import { parameters } from '$docs/utils/docsPage.js';
 
 # Getting help
 
-**If you're on deadline**, talk to your editor who can point you to the nearest developer.
+🚨 **If you're on deadline**, talk to your editor who can point you to the nearest developer.
 
-If you're off deadline, we use GitHub issues to track things that need fixing up or could be improved. Use one of the links below to create a new issue.
+If you're _off_ deadline, we use GitHub issues to track things that need fixing up or could be improved. Use one of the links below to create a new issue.
 
 ---
 
-### Is something wrong with a component or another piece of code?
+### Is something wrong in the code?
 
-🏷️ [Click here](https://github.com/reuters-graphics/graphics-components/issues/new?labels=%F0%9F%90%9B%20bug&assignees=hobbes7878) to create an issue on GitHub and report any bugs you've found. It's usually helpful if you also share a link to any repo you're working in where you've spotted the bug.
+🏷️ [Click here](https://github.com/reuters-graphics/graphics-components/issues/new?labels=%F0%9F%90%9B%20bug&assignees=hobbes7878) to create an issue on GitHub and report any bugs you've found. It's **very** helpful if you also share a link to any repo you're working in where you've spotted the bug.
 
 ---
 
-### Is something wrong with these docs?
+### Is something wrong in the docs?
 
 🏷️ [Click here](https://github.com/reuters-graphics/graphics-components/issues/new?labels=%F0%9F%93%9A%20documentation&assignees=hobbes7878) and tell us which docs are incorrect, unclear or could otherwise be improved.
 

src/docs/layout/intro.stories.mdx

@@ -11,9 +11,9 @@ import WellImg from './article-well.jpg';
 
 Layout components are special Svelte components that setup our default page layout.
 
-Generally, our page layout includes a central text well and a few block breakpoints that can be either wider or narrower.
+Generally, our page layout includes a central text well and a few preset block breakpoints that can be either wider or narrower.
 
-Here's how it works:
+Here's a general look at how it works:
 
 <img
   className="feature"
@@ -22,9 +22,9 @@ Here's how it works:
   style={{ margin: '3rem 0' }}
 />
 
-The `Layout` component sets up the set dimensions of the well and the block breakpoints. The `Block` component is a wrapper for individual parts of a page.
+The `Article` component sets up the set dimensions of the well and the block breakpoints. The `Block` component is a wrapper for individual parts of a page.
 
-In many cases, you won't need to mess with `Layout`.
+In many cases, you won't need to mess with `Article`.
 
 More regularly, you'll use a `Block` to wrap a graphic or some other part of the page. (Most of our pre-fab components already use `Block` to set up the width options for your content.)
 

src/docs/scss/classes.stories.mdx

@@ -0,0 +1,12 @@
+import { Meta } from '@storybook/addon-docs';
+import { parameters } from '$docs/utils/docsPage.js';
+
+<Meta title="SCSS/Classes" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# CSS classes
+
+Pre-written CSS classes you can add directly to elements.
+
+TK.

src/docs/scss/intro.stories.mdx

@@ -6,3 +6,18 @@ import { parameters } from '$docs/utils/docsPage.js';
 ![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
 
 # SCSS
+
+This library also includes our main SCSS stylesheets and pre-defined classes and SCSS mixins you can use to style your pages.
+
+### Importing our main stylesheet
+
+Import the SCSS directly in your top-level component. (This is done for you in the Graphics Kit.)
+
+```svelte
+<!-- pages/index.svelte -->
+<script>
+  // other imports and stuffs ...
+
+  import '@reuters-graphics/graphics-components/dist/scss/main.scss';
+</script>
+```

src/docs/scss/mixins.stories.mdx

@@ -0,0 +1,111 @@
+import { Meta } from '@storybook/addon-docs';
+import { parameters } from '$docs/utils/docsPage.js';
+
+<Meta title="SCSS/Mixins" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# SCSS Mixins
+
+### Prereqs
+
+Mixins allow you to re-use styles we've already defined in your components. Read more about how they work [here](https://sass-lang.com/documentation/at-rules/mixin) or just follow the examples below.
+
+## Available mixins
+
+### `font-{sans|serif|display|monospace}`
+
+Mixin our fonts.
+
+```svelte
+<p>
+  <span class="serif">Lorem</span>
+  <span class="sans">ipsum</span>
+  <span class="display">dolor</span>
+  <span class="mono">sit</span>
+</p>
+
+<style lang="scss">
+  // Import SCSS mixins
+  @import 'reuters-graphics/graphics-components/dist/scss/mixins';
+
+  // Use them with classes.
+  p {
+    .serif {
+      @include font-serif;
+    }
+    .sans {
+      @include font-sans;
+    }
+    .display {
+      @include font-display;
+    }
+    .mono {
+      @include font-monospace;
+    }
+  }
+</style>
+```
+
+### `body-text`
+
+Mixin our default body text styles.
+
+```svelte
+<div class="my-custom-text">
+  <h3>Lorem Ipsum</h3>
+  <p>Ig-pay atin-lay</p>
+</div>
+
+<style lang="scss">
+  // Import SCSS mixins
+  @import 'reuters-graphics/graphics-components/dist/scss/mixins';
+
+  div.my-custom-text {
+    // Use body-text rules for all text elements
+    // inside your custom element.
+    @include body-text;
+  }
+</style>
+```
+
+### `graphic-text`
+
+Graphic text styles.
+
+```svelte
+<div class="my-chart-container">
+  <h3>Things are going up</h3>
+  <p>Recent data point to a clear trend.</p>
+  <div id="chart"></div>
+  <aside>
+    <p>Source: Horoscopery</p>
+  </aside>
+</div>
+
+<style lang="scss">
+  @import 'reuters-graphics/graphics-components/dist/scss/mixins';
+
+  div.my-chart-container {
+    @include graphic-text;
+  }
+</style>
+```
+
+### `visually-hidden`
+
+Hide text meant for screen readers.
+
+```svelte
+<div class="hidden">
+  <p>A chart that shows many things.</p>
+</div>
+
+<style lang="scss">
+  @import 'reuters-graphics/graphics-components/dist/scss/mixins';
+
+  div.hidden {
+    @include visually-hidden;
+  }
+</style>
+```

src/docs/utilities/intro.stories.mdx

@@ -6,3 +6,9 @@ import { parameters } from '$docs/utils/docsPage.js';
 ![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
 
 # Utilities
+
+Utility components are a bit of a catch-all.
+
+They include components you're less likely to need to implement yourself, like development tools for the Graphics Kit.
+
+Either way, they're good to know about, even if they may not be the most common you'll use.