docs and cleanup

.storybook/preview.js

@@ -33,11 +33,11 @@ export const parameters = {
         'Guides',
         [
           'Using these docs',
-          'Getting help',
           'Using with the Graphics Kit',
           'Using with Google docs',
           'Customising components with SCSS',
           '*',
+          'Getting help',
         ],
         'Layout',
         ['Intro', '*'],

.storybook/preview.scss

@@ -43,6 +43,14 @@ p.sbdocs-p, ul.sbdocs-ul, li.sbdocs-li {
   font-size: 18px;
   line-height: 29px;
   @include font-display;
+
+  .highlight {
+    background-color: rgb(254, 254, 160);
+    padding: 0 4px;
+  }
+  .bold {
+    font-weight: bold;
+  }
 }
 
 a.sbdocs-a {

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

@@ -1,6 +1,6 @@
 The `Article` component contains all the content of our story and also establishes the dimensions of our article well, the default central trunk of our page layout.
 
-> 📌 In most cases, you won't need to mess with the `Article` component because it's already included in our rigs for you!
+> 📌 In most cases, **you won't need to mess with the `Article` component** because it's already included in our rigs for you!
 
 ```svelte
 <script>

src/components/BeforeAfter/BeforeAfter.stories.svelte

@@ -17,7 +17,7 @@
 
   import {
     withComponentDocs,
-    withStoryDocs,
+    withStoryDocs
   } from '$lib/docs/utils/withParams.js';
 
   const meta = {
@@ -65,9 +65,7 @@
     <h6>Oct. 20, 2020</h6>
     <p>But then forces built up.</p>
   </div>
-  <aside slot="caption">
-    <p>Photos by MAXAR Technologies, 2021.</p>
-  </aside>
+  <p slot="caption">Photos by MAXAR Technologies, 2021.</p>
 </BeforeAfter>
 
 <style lang="scss">

src/components/BeforeAfter/BeforeAfter.svelte

@@ -9,7 +9,8 @@
   /** Height of the component */
   export let height = 600;
 
-  /** 
+
+  /**
    * If set, makes the height a ratio of the component's width.
    * @type {number}
    */
@@ -45,7 +46,7 @@
   /** Percentage of the component width the handle will travel ona key press */
   export let keyPressStep = 0.05;
 
-  /** Initial offset of the handle, between 0 and 1.*/
+  /** Initial offset of the handle, between 0 and 1. */
   export let offset = 0.5;
 
   const random4 = () =>
@@ -53,7 +54,11 @@
       .toString(16)
       .substring(1);
 
-  const id = 'before-after-' + random4() + random4();
+  /**
+   * Add an ID to target with SCSS.
+   * @type {string}
+   */
+  export let id: string = 'before-after-' + random4() + random4();
 
   let img;
   let imgOffset = null;
@@ -95,16 +100,16 @@
   const move = (e) => {
     if (sliding && imgOffset) {
       const el = e.touches ? e.touches[0] : e;
-      const figureOffset = figure
-        ? parseInt(window.getComputedStyle(figure).marginLeft.slice(0, -2))
-        : 0;
+      const figureOffset = figure ?
+        parseInt(window.getComputedStyle(figure).marginLeft.slice(0, -2)) :
+        0;
       let x = el.pageX - figureOffset - imgOffset.left;
       x =
-        x < handleMargin
-          ? handleMargin
-          : x > w - handleMargin
-          ? w - handleMargin
-          : x;
+        x < handleMargin ?
+          handleMargin :
+          x > w - handleMargin ?
+            w - handleMargin :
+            x;
       offset = x / w;
     }
   };
@@ -146,7 +151,7 @@
 />
 
 {#if beforeSrc && beforeAlt && afterSrc && afterAlt}
-  <Block {width} cls="photo before-after">
+  <Block {width} {id} cls="photo before-after">
     <div
       style="height: {containerHeight}px;"
       bind:clientWidth="{containerWidth}"
@@ -212,16 +217,17 @@
       </figure>
     </div>
     {#if $$slots.caption}
-      <section class="graphic caption {width}" id="{`${id}-caption`}">
+      <aside class="before-after-caption" id="{`${id}-caption`}">
         <!-- Caption for image credits -->
         <slot name="caption" />
-      </section>
+      </aside>
     {/if}
   </Block>
 {/if}
 
 <style lang="scss">
-  @import "@reuters-graphics/style-main/scss/fonts/mixins";
+  @import "../../scss/mixins/fonts";
+  @import "../../scss/colours/thematic/tr";
   figure.before-after-container {
     overflow: hidden;
     position: relative;
@@ -318,7 +324,33 @@
       border-right: 10px solid var(--before-after-handle-colour);
     }
   }
-  section.graphic.caption {
+  aside.before-after-caption {
     margin: 0 auto;
+    @include font-display;
+    :global {
+      p {
+        @include font-display;
+        color: $tr-medium-grey;
+        font-size: 0.9rem;
+        line-height: 1.2rem;
+        &:last-of-type {
+          margin-bottom: 0;
+        }
+        
+
+        @media(max-width: 540px) {
+          font-size: 0.8rem;
+          line-height: 1.1rem;
+        }
+
+        a {
+          color: currentColor;
+          text-decoration: underline;
+          &:hover {
+            text-decoration: underline;
+          }
+        }
+      }
+    }
   }
 </style>

src/components/Block/Block.stories.svelte

@@ -138,6 +138,7 @@
       border-radius: 4px;
       padding: 20px;
       color: white;
+      text-align: center;
     }
     div.row:first-child {
       div {

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

@@ -1,6 +1,6 @@
-Normally, `Block` containers resize fluidly below the original `width`. Sometimes, though, you may want the container to snap to the fixed widths of the article well -- for example, if you have a static graphic that looks fine at the set column breakpoints, but isn't so great at widths inbetween.
+Normally, `Block` containers resize fluidly below the original `width`. Sometimes, though, you may want the container to snap to the next breakpoint -- for example, if you have a static graphic that looks fine at the set block breakpoints, but isn't so great at widths inbetween.
 
-You can use the `snap` prop to force the container to snap to each column width successively as the window sizes down.
+You can use the `snap` prop to force the container to snap to each block width successively as the window sizes down.
 
 ```svelte
 <Block width="wider" snap={true}>
@@ -8,7 +8,7 @@ You can use the `snap` prop to force the container to snap to each column width
 </Block>
 ```
 
-If you want to skip certain column widths entirely, you can add one or more class of `skip-{column width}` to the `Block`.
+If you want to skip certain block widths entirely, you can add one or more class of `skip-{block width class}` to the `Block`.
 
 ```svelte
 <!-- Will skip wide and go straight to normal column width on resize. -->
@@ -23,7 +23,7 @@ This is probably easier to see in action than explain in words, so check out the
 
 #### Using with custom column widths
 
-Snap width breakpoints are hard-coded to the default article well column widths, so if you set custom `columnWidths` on the `Article` tag, you can't use this functionality without a little extra work.
+Snap width breakpoints are hard-coded to the default article well column widths, so if you set custom `columnWidths` on the `Article` tag (**rare!**), you can't use this functionality without a little extra work.
 
 Luckily, it's still pretty easy. Just add a `cls` or `id` to your `Block` so you can target it with some custom SCSS. Now, defined a few SCSS variables corresponding to your custom column widths and use the `block-snap-widths` SCSS mixin to get the same functionality at your custom breakpoints.
 

src/docs/components/intro.stories.mdx

@@ -1,12 +0,0 @@
-import { Meta } from '@storybook/addon-docs';
-import { parameters } from '$docs/utils/docsPage.js';
-
-<Meta title="Components/Intro" parameters={{ ...parameters }} />
-
-![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
-
-# Components
-
-The components in this section represent the components you're most likely to use when you make your page. They can be used in any Svelte-based project, but many of the demos are specifically written for use in the Graphics Kit.
-
-If you haven't already, check out the Guides section for more info on how to read the docs and use these components before you dive in.

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

@@ -1,22 +1,23 @@
 import { Meta } from '@storybook/addon-docs';
 import { parameters } from '$docs/utils/docsPage.js';
 
-<Meta title="Contributing/Component basics" parameters={{ ...parameters }} />
+<Meta
+  title="Contributing/Component guidelines"
+  parameters={{ ...parameters }}
+/>
 
 ![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
 
-# Component basics
+# Component guidelines
 
 ## Dependencies
 
-Components should be written to be included in any Svelte app. If your component needs, for example, values from SvelteKit stores, these should be passed in as props.
+Components should be written for any Svelte context. If your component needs, for example, values from SvelteKit stores, these should be passed in as props.
 
 ## Typescript
 
 By default, component's are written in TypeScript, which adds robust type-checking and helpful hints for people using your component in editors like Visual Studio Code.
 
-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'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

src/docs/contributing/story-recipes/story-with-custom-docs.stories.mdx

@@ -14,7 +14,7 @@ import '../../docStyles.scss';
 
 # Recipes: Story with custom docs
 
-It's always a good idea to write your own docs that introduce your component or describe how certain stories work. You can add custom markdown to your story page by importing and using markdown files.
+You can add custom markdown to your story page by importing and using markdown files.
 
 First, create a markdown file in a `stories` directory in your component folder like this:
 

src/docs/guides/customising-with-scss.stories.mdx

@@ -1,6 +1,13 @@
 import { Meta } from '@storybook/addon-docs';
 import { parameters } from '$docs/utils/docsPage.js';
 
+import startImg from './imgs/scss-start.png';
+import highlightImg from './imgs/scss-highlight.png';
+import inspectorImg from './imgs/scss-inspector.png';
+import changeImg from './imgs/scss-change.png';
+import testImg from './imgs/scss-test.png';
+import winningImg from './imgs/scss-winning.png';
+
 <Meta
   title="Guides/Customising components with SCSS"
   parameters={{ ...parameters }}
@@ -10,4 +17,76 @@ import { parameters } from '$docs/utils/docsPage.js';
 
 # Customising components with SCSS
 
-TK
+One of the most powerful ways to customise components isn't props or, even, Svelte.
+
+<p class="sbdocs-p">
+  <span class="highlight bold">It's SCSS and your web inspector!</span>
+</p>
+
+## How's that??
+
+Let's say you wanted to change our `BeforeAfter` component. You want the text overlays to be at the bottom of the image instead of the top like this:
+
+<img src={startImg} width="600" />
+
+The first thing you should do is <span class="highlight">check out the elements you want to change in your web inspector</span> and see if CSS can make the change you want.
+
+<img src={highlightImg} width="300" style={{ margin: '0 0 1rem' }} />
+
+<img src={inspectorImg} width="100%" />
+
+In our case, we want to change the absolute position of those elements. To test that'll actually work, we can <span class="highlight">try it directly in the inspector first!</span>
+
+<img src={changeImg} width="500" style={{ margin: '0 0 1rem' }} />
+
+<img src={testImg} width="600" style={{ margin: '0 0 1rem' }} />
+
+Now that we know we can change what we need through CSS it's time to write some SCSS.
+
+First, let's look at the class of the style rule we changed in the inspector:
+
+`figure.before-after-container.s-khJY-w4TYkp5 .overlay-container.before.s-khJY-w4TYkp5`
+
+The first thing we need to do is <span class="highlight">strip out any Svelte class names</span>, i.e., those weird `.s-khJY-w4TYkp5` classes. Why? Those are random classes Svelte adds to CSS, and we can't guarantee they won't change.
+
+That leaves us with:
+
+`figure.before-after-container .overlay-container.before`
+
+But we need our style rule to _beat_ the original style in the CSS cascade, and right now, it's less specific.
+
+The easiest way to make sure your style rule wins out is to <span class="highlight">add an ID either directly to the element or to a parent</span>. In our case, let's add an ID through the `BeforeAfter` `id` prop. Now we can use it! (For extra credit, though, we'll drop the `.before` so our new style rule applies to _both_ overlays.)
+
+```scss
+figure#my-before-after .overlay-container {
+  bottom: 0;
+}
+```
+
+Now our selector is more specific. We win!
+
+If you don't see a way to add an ID through a component's props, then just wrap the component in a `div` in your code:
+
+```svelte
+<div id="my-before-after">
+  <BeforeAfter />
+</div>
+```
+
+... and use that, instead!
+
+```scss
+div#my-before-after figure .overlay-container {
+  bottom: 0;
+}
+```
+
+We can <span class="highlight">confirm the new style rule is winning by looking at its order back in our web inspector!</span>
+
+<img src={winningImg} width="500" style={{ margin: '0 0 1rem' }} />
+
+Done!
+
+#### Can I just... `important!` it?
+
+Yep, as a last result. Just be sure your style rule is **very specific** and not something generic that might apply to other elements like `div.container`.

src/docs/guides/google-docs.stories.mdx

@@ -7,4 +7,67 @@ import { parameters } from '$docs/utils/docsPage.js';
 
 # Using with Google docs
 
-TK
+Most of the default examples in these docs show how to use components by passing data into them directly through props. In the Kit, though, you likely won't be hard-coding things like text strings in your code and instead will get them from a Google doc.
+
+It's usually easy to use a Google Doc to fill in the props for our components, but it may mean you need to write a tiny bit of code to translate strings from a doc into the data type our component's props expect.
+
+Let's look at a basic component, `ProfileCard`, with a demo that looks like this in the docs:
+
+```svelte
+<script>
+  import { ProfileCard } from '@reuters-graphics/graphics-components';
+</script>
+
+<ProfileCard
+  name="Tom"
+  img="{'https://cats.com/cat1.jpg'}"
+  birthday="{new Date('2020-09-25')}"
+  bio="Some notes.\n\nWith multiple paragraphs."
+  isStaff="{true}"
+/>
+```
+
+The data for the component's props includes strings, a date and a boolean.
+
+In our Google doc, we might fill out a block for this component like this:
+
+```yaml
+Type: profile-card
+Name: Tom
+Image: images/tom-the-cat.jpg
+Birthday: 2020-09-25
+Bio: Some notes.
+
+With multiple paragraphs.
+:end
+Staff: true
+```
+
+Now we can tie that data into your blocks loop like this:
+
+```svelte
+<script>
+  // These are usually already imported for you
+  import { assets } from '$app/paths';
+  import content from '$locales/en/content.json';
+
+  import { ProfileCard } from '@reuters-graphics/graphics-components';
+</script>
+
+{#each content.blocks as block}
+  <!-- ... other blocks -->
+
+  {:else if block.Type === 'profile-card'}
+    <ProfileCard
+      name="{block.Name}"
+      img={`${assets}/${block.Image}`}
+      birthday={new Date(block.Birthday)}
+      bio="{block.Bio}"
+      isStaff={block.Staff === 'true'}
+    />
+
+  <!-- ... other blocks -->
+{/each}
+```
+
+Notice how we're coercing some of our data from strings into other data types: a boolean for `isStaff`, a date for `birthday` and an absolute path for `img`.

src/docs/guides/graphics-kit.stories.mdx

@@ -1,6 +1,8 @@
 import { Meta } from '@storybook/addon-docs';
 import { parameters } from '$docs/utils/docsPage.js';
 
+import quickitImg from './imgs/quickit.png';
+
 <Meta
   title="Guides/Using with the Graphics Kit"
   parameters={{ ...parameters }}
@@ -10,4 +12,58 @@ import { parameters } from '$docs/utils/docsPage.js';
 
 # Using with the Graphics Kit
 
-Read more about using the components in the [Graphics Kit docs](https://reuters-graphics.github.io/docs_graphics-kit/for_developers/graphics-components/).
+If you haven't, check out ["Using Reuters Graphics Components" in the Graphics Kit docs](https://reuters-graphics.github.io/docs_graphics-kit/for_developers/graphics-components/) to get a general idea of how to use components.
+
+<span class="highlight">Look for **🚀 QUICKIT** stories</span> (Quick Kit 🤣🙄) for
+some of our most commonly used components. These stories include easy copy/paste
+snippets as well as Google Doc block examples that should shortcut getting a component
+working in the Graphics Kit.
+
+<img src={quickitImg} width="200" />
+
+(Want a QUICKIT story for another component? [Just ask us!](https://github.com/reuters-graphics/graphics-components/issues/new?labels=%F0%9F%93%9A%20documentation&assignees=hobbes7878))
+
+## FAQs
+
+### How do I write my Google Doc?
+
+Many component stories show passing data directly into component props. In the Kit, though, you likely won't be hard-coding things like text strings in your code and instead will get them from a Google Doc.
+
+Check out the guide devoted to [using components with Google Docs](?path=/docs/guides-using-with-google-docs--page) for a quick explanation of how to work with Google Docs.
+
+And, of course, look for a QUICKIT story for your component, which will have a Docs example specific to it.
+
+### How do I use this image/video/etc.?
+
+Remember, all references to images, videos and other media must be _absolute paths_:
+
+✅ `https://.../myImage.jpg`
+
+❌ `./myImage.jpg`
+
+In most cases, that means you'll need to prefix relative paths with the special `assets` Svelte module. Many examples in these docs show how to do it. But it's also easy enough to demo again here!
+
+```svelte
+<script>
+  import content from '$locales/en/content.json';
+  import { FeaturePhoto } from '@reuters-graphics/graphics-components';
+
+  // This is already imported for you in App.svelte
+  import { assets } from '$app/paths';
+</script>
+
+{#each content.blocks as block}
+  <!-- ... other blocks -->
+
+  <!-- Use assets to prefix the path to the image. -->
+  {:else if block.Type === 'photo'}
+    <FeautrePhoto
+      src={`${assets}/${block.PathToImage}`}
+    />
+
+{/each}
+```
+
+### How do I change this component's styles?
+
+Check out our guide on [customising components with SCSS](?path=/docs/guides-customising-components-with-scss--page)

src/docs/guides/using-docs.stories.mdx

@@ -1,14 +1,72 @@
 import { Meta } from '@storybook/addon-docs';
 import { parameters } from '$docs/utils/docsPage.js';
 
+import storiesImg from './imgs/stories.png';
+import introImg from './imgs/intro.png';
+import tabsImg from './imgs/tabs.png';
+import argsImg from './imgs/argstable.png';
+import frameImg from './imgs/frame.png';
+import copyImg from './imgs/copy-code.png';
+import propImg from './imgs/prop.png';
+import moreStoriesImg from './imgs/more-stories.png';
+import otherDocsImg from './imgs/other-docs.png';
+
 <Meta title="Guides/Using these docs" parameters={{ ...parameters }} />
 
 ![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
 
 # Using these docs
 
-TK...
+The docs in this site include interactive examples of how to use our components, explanations of how our basic design system works and helpful docs on SCSS tools you can use to customise your page.
 
-### QUICKIT docs
+## How component docs are organised
 
-Graphics Kit uses, look for **🚀 QUICKIT** stories in some of our most common components. These stories include easy copy/paste snippets, including Google doc block examples, that should shortcut getting components working in the Graphics Kit.
+Component docs are written using a framework called [Storybook](https://storybook.js.org/docs/svelte/get-started/introduction), which creates a page for each component. You can find those pages in left-hand nav on the site.
+
+Each component page then has one or more "stories" or demos of how the component works:
+
+<img src={storiesImg} width="150" style={{ margin: '0 0 2rem' }} />
+
+### Parts of a component page
+
+Each component page starts with an **intro** that includes a little documentation and a code snippet showing the simplest way to import and use a component.
+
+<img src={introImg} width="650" style={{ margin: '0 0 2rem' }} />
+
+Next is a **frame** that shows how the component looks. Each story will have its own frame.
+
+<img src={frameImg} width="650" style={{ margin: '0 0 2rem' }} />
+
+Below the `Default` story frame is an **args table**. <span class="highlight bold">This is the most important part of every component's page.</span> The args table documents all the props and slots a component has, i.e., all the ways you can customise it.
+
+<img src={argsImg} width="100%" style={{ margin: '0 0 2rem', maxWidth: 800 }} />
+
+Each prop includes its name and a description with the data type that prop expects as well as the default value, if there is one.
+
+The `Control` column gives you a way to play with the value of that prop in the live demo. Make changes here, and for most components, they'll update the demo frame to reflect your changes.
+
+Click the "Show code" button in the frame to see how your component looks with the props you set.
+
+<img src={copyImg} width="100%" style={{ margin: '2rem 0', maxWidth: 800 }} />
+
+You can also go to the `Canvas` tab at the top left of the page to get a better view of the component while you're playing with its controls.
+
+<img src={tabsImg} width="200" style={{ margin: '0 0 2rem' }} />
+
+From there, more stories show other ways you might use a component, also with a snippet you can copy into your own page.
+
+<img
+  src={moreStoriesImg}
+  width="100%"
+  style={{ margin: '2rem 0', maxWidth: 800 }}
+/>
+
+## Other docs pages
+
+Other docs pages are simple markdown documents that include useful snippets you can copy/paste into your code.
+
+<img
+  src={otherDocsImg}
+  width="100%"
+  style={{ margin: '2rem 0', maxWidth: 800 }}
+/>

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 preset block breakpoints that can be either wider or narrower.
+Generally, our page layout includes a central text well and a few preset block breakpoints, wider and narrower than the well.
 
-Here's a general look at how it works:
+Here's how it works:
 
 <img
   className="feature"
@@ -22,10 +22,8 @@ Here's a general look at how it works:
   style={{ margin: '3rem 0' }}
 />
 
-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.
+The `Article` component sets up the set dimensions of the well and the block breakpoints.
 
-In many cases, you won't need to mess with `Article`.
+The `Block` component is a wrapper for individual parts of a page that can be as wide as any of those breakpoints.
 
-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.)
-
-The docs in this section explain how to use our basic layout components to build the basic structure of your page and also how to break out of our default layout if you need to do something different.
+The docs in this section explain how to use our layout components to build the basic structure of your page and also how to break out of our default layout if you need to do something different.

src/scss/mixins/_body-text.scss

@@ -1,4 +1,4 @@
-@import "fonts";
+@import "./fonts";
 @import "../typography/font-size";
 @import "../colours/thematic/tr";
 

src/scss/mixins/_graphic.scss

@@ -1,5 +1,5 @@
 @import "../colours/thematic/tr";
-@import "fonts";
+@import "./fonts";
 
 @mixin graphic-text {
   h3 {

src/scss/mixins/_note-text.scss

@@ -1,4 +1,4 @@
-@import "fonts";
+@import "./fonts";
 
 @mixin note-text {  
   h2,