diff --git a/.storybook/preview.js b/.storybook/preview.js index 4c634713..64f54904 100644 --- a/.storybook/preview.js +++ b/.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', '*'], diff --git a/.storybook/preview.scss b/.storybook/preview.scss index bded43b1..6c3d4cc1 100644 --- a/.storybook/preview.scss +++ b/.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 { diff --git a/src/components/Article/stories/docs/component.md b/src/components/Article/stories/docs/component.md index 55bbcbfe..1ca1c688 100644 --- a/src/components/Article/stories/docs/component.md +++ b/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 + + +``` + +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 + + +{#each content.blocks as block} + + + {:else if block.Type === 'profile-card'} + + + +{/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`. diff --git a/src/docs/guides/graphics-kit.stories.mdx b/src/docs/guides/graphics-kit.stories.mdx index cbc86d8d..98ee7a66 100644 --- a/src/docs/guides/graphics-kit.stories.mdx +++ b/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'; + Look for **🚀 QUICKIT** stories (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. + + + +(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 + + +{#each content.blocks as block} + + + + {:else if block.Type === 'photo'} + + +{/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) diff --git a/src/docs/guides/imgs/argstable.png b/src/docs/guides/imgs/argstable.png new file mode 100644 index 00000000..65cd041c Binary files /dev/null and b/src/docs/guides/imgs/argstable.png differ diff --git a/src/docs/guides/imgs/copy-code.png b/src/docs/guides/imgs/copy-code.png new file mode 100644 index 00000000..d0ebebe7 Binary files /dev/null and b/src/docs/guides/imgs/copy-code.png differ diff --git a/src/docs/guides/imgs/frame.png b/src/docs/guides/imgs/frame.png new file mode 100644 index 00000000..0cb60f4e Binary files /dev/null and b/src/docs/guides/imgs/frame.png differ diff --git a/src/docs/guides/imgs/intro.png b/src/docs/guides/imgs/intro.png new file mode 100644 index 00000000..f710edde Binary files /dev/null and b/src/docs/guides/imgs/intro.png differ diff --git a/src/docs/guides/imgs/more-stories.png b/src/docs/guides/imgs/more-stories.png new file mode 100644 index 00000000..c75e4f63 Binary files /dev/null and b/src/docs/guides/imgs/more-stories.png differ diff --git a/src/docs/guides/imgs/other-docs.png b/src/docs/guides/imgs/other-docs.png new file mode 100644 index 00000000..ef121f4e Binary files /dev/null and b/src/docs/guides/imgs/other-docs.png differ diff --git a/src/docs/guides/imgs/prop.png b/src/docs/guides/imgs/prop.png new file mode 100644 index 00000000..0b60e4ed Binary files /dev/null and b/src/docs/guides/imgs/prop.png differ diff --git a/src/docs/guides/imgs/quickit.png b/src/docs/guides/imgs/quickit.png new file mode 100644 index 00000000..c0b6d633 Binary files /dev/null and b/src/docs/guides/imgs/quickit.png differ diff --git a/src/docs/guides/imgs/scss-change.png b/src/docs/guides/imgs/scss-change.png new file mode 100644 index 00000000..94d7395c Binary files /dev/null and b/src/docs/guides/imgs/scss-change.png differ diff --git a/src/docs/guides/imgs/scss-highlight.png b/src/docs/guides/imgs/scss-highlight.png new file mode 100644 index 00000000..1f3b35a7 Binary files /dev/null and b/src/docs/guides/imgs/scss-highlight.png differ diff --git a/src/docs/guides/imgs/scss-inspector.png b/src/docs/guides/imgs/scss-inspector.png new file mode 100644 index 00000000..3637b7f3 Binary files /dev/null and b/src/docs/guides/imgs/scss-inspector.png differ diff --git a/src/docs/guides/imgs/scss-start.png b/src/docs/guides/imgs/scss-start.png new file mode 100644 index 00000000..249da7f2 Binary files /dev/null and b/src/docs/guides/imgs/scss-start.png differ diff --git a/src/docs/guides/imgs/scss-test.png b/src/docs/guides/imgs/scss-test.png new file mode 100644 index 00000000..1293e819 Binary files /dev/null and b/src/docs/guides/imgs/scss-test.png differ diff --git a/src/docs/guides/imgs/scss-winning.png b/src/docs/guides/imgs/scss-winning.png new file mode 100644 index 00000000..e1336a1a Binary files /dev/null and b/src/docs/guides/imgs/scss-winning.png differ diff --git a/src/docs/guides/imgs/slots.png b/src/docs/guides/imgs/slots.png new file mode 100644 index 00000000..dffa2b5f Binary files /dev/null and b/src/docs/guides/imgs/slots.png differ diff --git a/src/docs/guides/imgs/stories.png b/src/docs/guides/imgs/stories.png new file mode 100644 index 00000000..d1cc7db9 Binary files /dev/null and b/src/docs/guides/imgs/stories.png differ diff --git a/src/docs/guides/imgs/tabs.png b/src/docs/guides/imgs/tabs.png new file mode 100644 index 00000000..ed6b0a99 Binary files /dev/null and b/src/docs/guides/imgs/tabs.png differ diff --git a/src/docs/guides/using-docs.stories.mdx b/src/docs/guides/using-docs.stories.mdx index 4f2a07cb..d5aca3da 100644 --- a/src/docs/guides/using-docs.stories.mdx +++ b/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'; + ![](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: + + + +### 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. + + + +Next is a **frame** that shows how the component looks. Each story will have its own frame. + + + +Below the `Default` story frame is an **args table**. This is the most important part of every component's page. The args table documents all the props and slots a component has, i.e., all the ways you can customise it. + + + +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. + + + +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. + + + +From there, more stories show other ways you might use a component, also with a snippet you can copy into your own page. + + + +## Other docs pages + +Other docs pages are simple markdown documents that include useful snippets you can copy/paste into your code. + + diff --git a/src/docs/layout/intro.stories.mdx b/src/docs/layout/intro.stories.mdx index bb152bb8..41e6e3c1 100644 --- a/src/docs/layout/intro.stories.mdx +++ b/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: -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. diff --git a/src/scss/mixins/_body-text.scss b/src/scss/mixins/_body-text.scss index a585764e..111d87de 100644 --- a/src/scss/mixins/_body-text.scss +++ b/src/scss/mixins/_body-text.scss @@ -1,4 +1,4 @@ -@import "fonts"; +@import "./fonts"; @import "../typography/font-size"; @import "../colours/thematic/tr"; diff --git a/src/scss/mixins/_graphic.scss b/src/scss/mixins/_graphic.scss index 3bba0c7d..9a9ded1d 100644 --- a/src/scss/mixins/_graphic.scss +++ b/src/scss/mixins/_graphic.scss @@ -1,5 +1,5 @@ @import "../colours/thematic/tr"; -@import "fonts"; +@import "./fonts"; @mixin graphic-text { h3 { diff --git a/src/scss/mixins/_note-text.scss b/src/scss/mixins/_note-text.scss index ff59f72e..fd487fa1 100644 --- a/src/scss/mixins/_note-text.scss +++ b/src/scss/mixins/_note-text.scss @@ -1,4 +1,4 @@ -@import "fonts"; +@import "./fonts"; @mixin note-text { h2,