Merge pull request #126 from reuters-graphics/docs-scrub-1.0

Docs cleanup for 1.0

.storybook/preview.ts

@@ -42,7 +42,7 @@ export const parameters = {
         'Layout',
         ['Intro', '*'],
         'Theming',
-        ['Theme', '*'],
+        ['Theme', 'CSS variables', '*'],
         'Components',
         ['Intro', '*'],
         '*',

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

@@ -7,7 +7,7 @@ The `Article` component contains all the content of our story and also establish
   import { Article } from '@reuters-graphics/graphics-components';
 </script>
 
-<article>
+<Article>
   <!-- The story stuff goes in here! -->
-</article>
+</Article>
 ```

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

@@ -8,8 +8,6 @@ The `Article` component also creates several column dimensions inside our articl
 - `widest` Edge-to-edge, but _excluding_ the left and right padding on `Article`
 - `fluid` Fully edge-to-edge
 
-(Check out the below demo in the "Canvas" tab to better see the wider differences.)
-
 When combined with the `Block` component, you can set custom column widths by passing an object to the `columnWidths` prop with pixel values for the `narrower`, `narrow`, `normal`, `wide` and `wider` column widths.
 
 > **For most pages, you shouldn't customise the column widths.** Other tools, like our AI templates, use our default column widths, so customising those widths here has downstream consequences for graphics made outside your code. The main exception is SREP stories.

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

@@ -17,7 +17,7 @@ If you want to skip certain block widths entirely, you can add one or more class
 </Block>
 ```
 
-This is probably easier to see in action than explain in words, so check out the "Canvas" tab for the demo below and resize the window to get a better picture of how it all works.
+This is probably easier to see in action than explain in words, so resize the window to get a better picture of how it all works.
 
 > **NOTE:** The snap width breakpoints only work on `Block` components with widths `wider` and below. `widest` and `fluid` are both **always** fluid, since they go edge-to-edge.
 

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

@@ -1,7 +1,5 @@
 The `Scroller` component helps you quickly create basic scrollytelling graphics with several layout options.
 
-Check out the "Canvas" tab to play with the layout options available on this component.
-
 > This component is designed to handle most common layouts for scrollytelling. If you need something more complex, though, you should probably use [svelte-scroller](https://github.com/sveltejs/svelte-scroller), which is a lower level component you can more easily customize.
 
 ```svelte

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

@@ -1,7 +1,5 @@
 Reuters dotcom site header, ported from [Raptor UI components](https://github.com/tr/rcom-arc_raptor-ui/tree/develop/packages/rcom-raptor-ui_common/src/components/site-header).
 
-(Go to the "[Canvas](./?path=/story/components-siteheader--default)" tab to see this component better. It'll look a bit broken below... but it's NOT!)
-
 > **Note:** In the Graphics Kit, you can find this component in `pages/+page.svelte`. Customise it there for the default page.
 
 ```svelte

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

@@ -137,10 +137,8 @@ In rare cases, you can use the SCSS `:global` operator to style child elements i
 
 <style lang="scss">
   svg {
-    :global {
-      path {
-        stroke: black;
-      }
+    :global(path) {
+      stroke: black;
     }
   }
 </style>

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

@@ -7,11 +7,11 @@ import { parameters } from '$docs/utils/docsPage.js';
 
 # Using with Google docs
 
-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.
+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:
+Let's look at a basic component, a `ProfileCard`, with a demo that looks like this in the docs:
 
 ```svelte
 <script>
@@ -20,7 +20,7 @@ Let's look at a basic component, `ProfileCard`, with a demo that looks like this
 
 <ProfileCard
   name="Tom"
-  img="{'https://cats.com/cat1.jpg'}"
+  img="https://cats.com/cat1.jpg"
   birthday="{new Date('2020-09-25')}"
   bio="Some notes.\n\nWith multiple paragraphs."
   isStaff="{true}"
@@ -55,13 +55,18 @@ Now we can tie that data into your blocks loop like this:
 </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'} />
+  {: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}
 ```
 

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

@@ -14,12 +14,12 @@ import quickitImg from './imgs/quickit.png';
 
 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.
 
+## Quickit
+
 Look <span class="highlight">for <strong>🚀 QUICKIT</strong> 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
@@ -44,19 +44,13 @@ In most cases, that means you'll need to prefix relative paths with the special
 
 ```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}
+<FeautrePhoto src="{`${assets}/imgs/myImage.jpg`}" />
 ```
 
 ### How do I change this component's styles?

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

@@ -3,13 +3,11 @@ 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 }} />
 
@@ -23,13 +21,16 @@ The docs in this site include interactive examples of how to use our components,
 
 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:
+Each component has a Docs page and one or more "stories" or demos that show how the component works:
 
-<img src={storiesImg} width="150" style={{ margin: '0 0 2rem' }} />
+<img
+  src={storiesImg}
+  style={{ maxWidth: '300px', width: '100%', 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.
+Each component page starts with an intro that includes a little documentation and a code snippet. The intro always shows the simplest way to import and use a component.
 
 <img src={introImg} width="650" style={{ margin: '0 0 2rem' }} />
 
@@ -37,22 +38,18 @@ Next is a **frame** that shows how the component looks. Each story will have its
 
 <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.
+Below the 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](https://learn.svelte.dev/tutorial/declaring-props) and [slots](https://learn.svelte.dev/tutorial/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.
+The `Control` column in the table 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
@@ -60,13 +57,3 @@ From there, more stories show other ways you might use a component, also with a
   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/styles/colours/intro.stories.mdx

@@ -13,7 +13,7 @@ Colour palettes are provided as [CSS variables](https://developer.mozilla.org/en
 
 ```scss
 /* global.scss */
-@import '@reuters-graphics/graphics-components/dist/scss/colours/primary/_blue.scss';
+@import '@reuters-graphics/graphics-components/scss/colours/primary/blue';
 
 p {
   color: var(--grey-400); // Included by default

src/docs/styles/tokens/intro.stories.mdx

@@ -87,7 +87,7 @@ If you'd like to set the style in SCSS, you'd use the `Include` token like this:
 <p>Lorem ipsum...</p>
 
 <style lang="scss">
-  @import '@reuters-graphics/graphics-components/dist/scss/mixins';
+  @import '@reuters-graphics/graphics-components/scss/mixins';
 
   p {
     @include text-primary;

src/docs/theming/css-variables.stories.mdx

@@ -27,14 +27,14 @@ You can use any of the CSS variables the `Theme` component sets in your own code
 <style lang="scss">
   p {
     color: var(--theme-colour-text-primary);
-    font-family: var(--theme-typeface-monospace);
+    font-family: var(--theme-font-family-sans-serif);
   }
 </style>
 ```
 
 ## Customising variables
 
-You can redefine any of the above CSS variables in the `<Theme>` component. Read more in [the docs](/docs/theming-theme--custom-theme).
+You can redefine any of the above CSS variables in the `<Theme>` component. Read more in [the docs](/docs/theming-theme--custom-theme) and **use the [Theme builder](/docs/theming-theme-builder--docs)**.
 
 ```svelte
 <Theme
@@ -52,7 +52,7 @@ You can redefine any of the above CSS variables in the `<Theme>` component. Read
 
 ## Adding extra variables
 
-You can obviously add your own CSS variables to any page. While you could set your custom variables in, for example, a global SCSS stylesheet like `global.scss`, we generally recommend setting them directly through the `Theme` component.
+You can even add custom variables through the `Theme` component.
 
 For example, let's say you want to define a border radius for some card elements on your page. You can add a custom property to the `theme` prop like this:
 
@@ -81,9 +81,9 @@ For example, let's say you want to define a border radius for some card elements
 </style>
 ```
 
-Using the `Theme` component for your own CSS variables lets clients customise them the same as any of our default theme values.
+Using the `Theme` component for your own CSS variables helps unify important style values across a project. It also lets clients more easily customise those values for whatever matches their brand.
 
-You can also easily change a variable's value based on some condition. For example, to set a smaller border radius on mobile screens, you might:
+You can also change a variable's value based on some condition. For example, to set a smaller border radius on mobile screens, you might:
 
 ```svelte
 <script>