reframe of using docs

reuters-graphics · Mar 21, 2023 · b721c0b · b721c0b
1 parent c224971
commit b721c0b
Show file tree

Hide file tree

Showing 4 changed files with 88 additions and 27 deletions.
diff --git a/.storybook/preview.js b/.storybook/preview.js
@@ -51,7 +51,7 @@ export const parameters = {
         'SCSS',
         ['Intro', '*'],
         'Typography',
-        ['Intro', 'Using the system', ['Text styles', '*'], '*'],
+        ['Intro', 'Using the type system', ['Text styles', '*'], '*'],
         'Actions',
         ['Intro', '*'],
         'Contributing',

diff --git a/src/docs/typography/intro.stories.mdx b/src/docs/typography/intro.stories.mdx
@@ -11,45 +11,26 @@ import DemoImg from './demo.png';
 
 # Typography
 
-Our design system includes a typographic scale based on the scale of fifths to create six harmonic levels of font sizes. These will guide the basic sizing of headlines, body text and spacing in a graphics page.
+Our Reuters Graphics components include a basic typography system designed to make it easy to incorporate clean, balanced type styles in your project.
 
-The typographic scale is set using the CSS variable in the theme component. You can customise them if you need a bespoke typesetting for your project.
-
-## The type system
+The typography system includes all the levels of text heirarchy you'll need for graphics pages, including page title, subheads, section titles, body copy, graphic descriptions, captions and other notes.
 
 <img
   className="feature"
-  src={TypeGuides}
-  width="100%"
-  style={{ margin: '3rem 0' }}
-/>
-
-## How it works
-
-<img
-  className="feature"
-  src={Typeset}
+  src={DemoImg}
   width="100%"
   style={{ margin: '3rem 0' }}
 />
 
-Text styles are composed using [CSS variables](/docs/theming-css-variables--page) for size, family and colours from the `Theme`. The font size inherits `--theme-scale-size-*` and font family inherits `--theme-typeface-*`. See which CSS vars flow in to the type system in the [How to use text styles](/docs/typography-how-to-use--text-styles) section.
-
-## Default usage
-
-In your projects, you will use the typographic styles as per the function –
+## The type style system
 
-- Page title, subheads and section titles
-- Body copy
-- Graphic descriptions, captions and other notes
+The typographic scale is based on the scale of fifths to create six harmonic levels of font sizes. These create the sizing for headlines, body text and spacing.
 
-The styles are also applied to native HTML elements like the `H` and `p` tags.
-
-> For Graphics Kit users, the typographic styles are already imported and applied to the individual components.
+The typographic scale is set using the CSS variable in the `Theme` component. You can customise it there.
 
 <img
   className="feature"
-  src={DemoImg}
+  src={TypeGuides}
   width="100%"
   style={{ margin: '3rem 0' }}
 />
diff --git a/src/docs/typography/using b/src/docs/typography/using
diff --git a/src/docs/typography/using-the-system.stories.mdx b/src/docs/typography/using-the-system.stories.mdx
@@ -0,0 +1,80 @@
+import { Meta } from '@storybook/addon-docs';
+import { parameters } from '$docs/utils/docsPage.js';
+
+<Meta title="Typography/Using the type system" parameters={{ ...parameters }} />
+
+![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
+
+# Using the type system
+
+## Type style heirarchy
+
+The type styles consist of 3 elements: size, typeface and colour. TKTKTK
+
+## Using type styles
+
+Type styles are automatically applied to native HTML elements like `h` and `p` tags and to certain combinations of elements that represent specific text components.
+
+```svelte
+<div>
+  <h2>Here's a section title</h2>
+  <p>and some text to go with it...</p>
+</div>
+
+<div class="endnote">
+  <p><strong>Editors:</strong> Simon Scarr</p>
+</div>
+```
+
+Apply text styles to any element using CSS classes that correspond to each text element type.
+
+```svelte
+<div class="font-subhed-1">Subhed</div>
+<p class="font-note-1">Sans-serif text...</p>
+```
+
+The following text style elements and corresponding classes are available:
+
+| Style         | class            | mixin           | CSS vars used from Theme                                                                     |
+| ------------- | ---------------- | --------------- | -------------------------------------------------------------------------------------------- |
+| Page title    | `.font-hed`      | `font-hed`      | `--theme-font-size-hed`, `--theme-font-family-hed` , `--theme-colour-text-primary`           |
+| Section title | `.font-subhed-1` | `font-subhed-1` | `--theme-font-size-subhed-1`, `--theme-font-family-subhed` , `--theme-colour-text-primary`   |
+| Subhed        | `.font-subhed-2` | `font-subhed-2` | `--theme-font-size-subhed-2`, `--theme-font-family-subhed` , `--theme-colour-text-primary`   |
+| Smallhed      | `.font-subhed-3` | `font-subhed-3` | `--theme-font-size-subhed-3`, `--theme-font-family-subhed` , `--theme-colour-text-secondary` |
+| Body text     | `.font-body`     | `font-body`     | `--theme-font-size-body`, `--theme-font-family-body` , `--theme-colour-text-primary`         |
+| Body note     | `.font-note-1`   | `font-note-1`   | `--theme-font-size-note-1`, `--theme-font-family-note` , `--theme-colour-text-primary`       |
+| Endnotes      | `.font-note-2`   | `font-note-2`   | `--theme-font-size-note-2`, `--theme-font-family-note` , `--theme-colour-text-secondary`     |
+| Footnotes     | `.font-note-3`   | `font-note-3`   | `--theme-font-size-note-3`, `--theme-font-family-note` , `--theme-colour-text-secondary`     |
+
+TK Demo...
+
+### Type sizes
+
+The following classes apply specific text sizes to any element:
+
+| level | class          | mixin         | CSS vars used from Theme |
+| ----- | -------------- | ------------- | ------------------------ |
+| 1     | `.font-size-1` | `font-size-1` | `--theme-scale-size-1`   |
+| 2     | `.font-size-2` | `font-size-2` | `--theme-scale-size-2`   |
+| 3     | `.font-size-3` | `font-size-3` | `--theme-scale-size-3`   |
+| 4     | `.font-size-4` | `font-size-4` | `--theme-scale-size-4`   |
+| 5     | `.font-size-5` | `font-size-5` | `--theme-scale-size-5`   |
+| 6     | `.font-size-6` | `font-size-6` | `--theme-scale-size-6`   |
+
+> The text sizes are always a multiple of `size-base = 1.375`. On mobile
+> {max-width:510px}, levels 1, 2, 3, 4 scale down to `size-base-mobile = 1.125`
+
+TK Demo...
+
+### Typefaces
+
+The following classes apply typefaces to any element:
+
+| typeface        | class                  | mixin                 | CSS vars used from Theme      |
+| --------------- | ---------------------- | --------------------- | ----------------------------- |
+| Display font    | `.typeface-display`    | `typeface-display`    | `--theme-typeface-display`    |
+| Serif font      | `.typeface-serif`      | `typeface-serif`      | `--theme-typeface-serif`      |
+| Sans-serif font | `.typeface-sans-serif` | `typeface-sans-serif` | `--theme-typeface-sans-serif` |
+| Monospace font  | `.typeface-monospace`  | `typeface-monospace`  | `--theme-typeface-monospace`  |
+
+TK Demo...