describe style classes and mixins

.storybook/preview.js

@@ -51,7 +51,7 @@ export const parameters = {
         'SCSS',
         ['Intro', '*'],
         'Typography',
-        ['Intro', 'How to use', ['Text styles', '*'], '*'],
+        ['Intro', 'Using the system', ['Text styles', '*'], '*'],
         'Actions',
         ['Intro', '*'],
         'Contributing',

src/components/Theme/themes/dark.js

@@ -35,7 +35,7 @@ export default {
     background: '#2e3440',
     'text-primary': '#ffffff',
     'text-secondary': 'rgb(255 255 255 / 60%)',
-    accent: ' #ef3c2a',
+    accent: '#ef3c2a',
     'brand-logo': '#ffffff',
     'brand-rules': 'rgb(255 255 255 / 25%)',
     'brand-shadow': 'rgb(255 255 255 / 10%)',

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

@@ -79,6 +79,24 @@ Read more about how to override or define your own CSS variables in the [Themes]
 | `--theme-scale-size-5`           | Size level 5                     | calc(var(--theme-scale-size-base) \* 0.72rem) |
 | `--theme-scale-size-6`           | Size level 6                     | calc(var(--theme-scale-size-base) \* 0.66rem) |
 
+## Customising variables
+
+You can redefine any of the CSS variables by declaring it in your `<Theme>` component with the new values. Read more on how to [customise theme](/docs/theming-theme--custom-theme).
+
+```svelte
+<Theme
+  base="light"
+  theme="{{
+    colour: {
+      // This replaces the default text-secondary colour '#666666' for light theme
+      'text-secondary': '#213310',
+    },
+  }}"
+>
+  <!-- page stuff -->
+</Theme>
+```
+
 ## Adding custom variables
 
 For some projects, you may need more style attributes that you can define globally while allowing it to be customisable. You may be doing so using SCSS variable in your `main.scss` but that prevent those styles from being customised/overridden from the client side. Hence, it is a good practice to define such thematic styles in the `Theme` component using CSS variables.

src/docs/typography/custom-fonts.stories.mdx

@@ -31,6 +31,8 @@ In this sample from [Google Fonts](https://fonts.google.com/), once we have sele
 
 In your project, navigate to `Pages` > `layout.svelte` and add the code in `svelte:head` fragment as follows:
 
+If you don't have the layout file, add it.
+
 ```svelte
 <svelte:head>
   <!-- Replace this with your own font url-->

src/docs/typography/docs/style.md

@@ -27,27 +27,106 @@ These are the available **text styles** and their **corresponding tokens**. The
 Add the `font-` class to any element for the classes to take effect.
 
 ```svelte
-<!-- Text using body font style --><div class="font-body">your text here</div>
+<!-- div using body font style -->
+<div class="font-body">
+  Two hardy boxing kangaroos jet from Sydney to Zanzibar on quicksilver pinions.
+</div>
+
+<!-- Text using body font style -->
+<p class="font-body">
+  Back in my quaint garden jaunty zinnias vie with flaunting phlox.
+</p>
+```
+
+It is a good practice to not use `<h>` tags unless it is a heading level due to _a11y_ concerns. You should use the CSS styles instead for your elements to style it like a heading.
+
+```svelte
+<!-- Text which is not a heading, but using a heading style -->
+<p class="font-subhed-3">
+  The vegetarian menu included gazpacho, piquant julienne beets, rusk rounds
+  with yogurt, and excellent flan.
+</p>
+```
+
+You can also use the clases for styling text elemnets in SVG charts.
+
+```svelte
+<!-- Text which is not a heading, but using a heading style -->
+<text class="font-note-3">Gazpacho</text>
+<text class="font-note-3">Baguette</text>
+<text class="font-note-3">Lamb Biryani</text>
 ```
 
 ## Styling with with SCSS mixins
 
-> This is useful when you need to compose styles for elements using your own classes.
+[Mixins](https://sass-lang.com/documentation/at-rules/mixin) allow you to define styles that can be re-used throughout your stylesheet. This is useful when you need to compose styles for elements using your own classes, while using some predefined styles.
 
 Include the mixins in your SCSS code block as shown below.
 
 ```svelte
-<div class="my-class">...your text here</div>
+<div class="my-class">
+  The July sun caused a fragment of black pine wax to ooze on the velvet quilt.
+</div>
 
 <style lang="scss">
   @import '@reuters-graphics/graphics-components/dist/scss/typography/_main.scss';
 
   .my-class {
-    @include font-body;
+    @include font-note-3;
   }
 </style>
 ```
 
+The mixins also allow you to add the styles as `!important` to overrule any other styles. You can specify it using `($i: true)` arg while including the mixin.
+
+```scss
+.my-class {
+  @include font-note-3($i: true);
+  // more style declarations...
+}
+```
+
+The above code will effectively compile to the following CSS:
+
+```scss
+.my-class {
+  font-size: var(--theme-font-size-note-3) !important;
+  font-family: var(--theme-font-family-note) !important;
+  font-weight: 400 !important;
+  line-height: 1.4 !important;
+  color: var(--theme-colour-text-secondary) !important;
+  // more style declarations...
+}
+```
+
+## Customising text styles
+
+Since the styles are inherited from the `--theme-font-*` and `--theme-colour-*`CSS variables, any modifcation must happen in the `<Theme>` component in `page.svelte`. Read how to [customise CSS variables](../?path=/docs/theming-theme--custom-theme).
+
+### Example: Changing the font family for the page title
+
+Page title uses `--theme-font-family-hed` to define the font family, which inherits `--theme-typeface-display` (refer the [CSS variables](../?path=/docs/theming-css-variables--page)). Hence, in this case, you should redefine the `--theme-typeface-display` and the changes should reflect on your page.
+
+If you want to redefine `--theme-font-family-hed` independently, you should add a new CSS typeface variable (e.g. `--theme-typeface-hed`) and assign it to the text style variable.
+
+```svelte
+<Theme
+  base="light"
+  theme="{{
+    typeface: {
+      // New CSS variable
+      hed: 'Playfair Display',
+    },
+    font: {
+      // Assign the new typeface variable
+      'family-hed': 'var(--theme-typeface-hed)',
+    },
+  }}"
+>
+  <!-- page stuff -->
+</Theme>
+```
+
 ## See the styles in action
 
 Select a style from the menu in the `control` column and see it added to the text.

src/docs/typography/using-faces.stories.svelte

@@ -12,7 +12,7 @@
   import face from './docs/face.md?raw';
 
   const meta = {
-    title: 'Typography/How to use',
+    title: 'Typography/Using the system',
     component: FaceDemo,
     ...withComponentDocs(face),
     argTypes: {

src/docs/typography/using-sizes.stories.svelte

@@ -12,7 +12,7 @@
   import size from './docs/size.md?raw';
 
   const meta = {
-    title: 'Typography/How to use',
+    title: 'Typography/Using the system',
     component: SizeDemo,
     ...withComponentDocs(size),
     argTypes: {

src/docs/typography/using-styles.stories.svelte

@@ -12,7 +12,7 @@
   import style from './docs/style.md?raw';
 
   const meta = {
-    title: 'Typography/How to use',
+    title: 'Typography/Using the system',
     component: StyleDemo,
     ...withComponentDocs(style),
     argTypes: {

src/scss/typography/_classes.scss

@@ -1,74 +1,74 @@
 /* FONT SIZE CLASSES */
 .font-size-1 {
-  @include font-size-1($i: true);
+  @include font-size-1($i: false);
 }
 
 .font-size-2 {
-  @include font-size-2($i: true);
+  @include font-size-2($i: false);
 }
 
 .font-size-3 {
-  @include font-size-3($i: true);
+  @include font-size-3($i: false);
 }
 
 .font-size-4 {
-  @include font-size-4($i: true);
+  @include font-size-4($i: false);
 }
 
 .font-size-5 {
-  @include font-size-5($i: true);
+  @include font-size-5($i: false);
 }
 
 .font-size-6 {
-  @include font-size-6($i: true);
+  @include font-size-6($i: false);
 }
 
 /* TYPEFACE CLASSES */
 .typeface-display {
-  @include typeface-display($i: true);
+  @include typeface-display($i: false);
 }
 
 .typeface-serif {
-  @include typeface-serif($i: true);
+  @include typeface-serif($i: false);
 }
 
 .typeface-sans-serif {
-  @include typeface-sans-serif($i: true);
+  @include typeface-sans-serif($i: false);
 }
 
 .typeface-monospace {
-  @include typeface-monospace($i: true);
+  @include typeface-monospace($i: false);
 }
 
 /* FONT STYLE TOKEN CLASSES */
 .font-hed {
-  @include font-hed($i: true);
+  @include font-hed($i: false);
 }
 
 .font-subhed-1 {
-  @include font-subhed-1($i: true);
+  @include font-subhed-1($i: false);
 }
 
 .font-subhed-2 {
-  @include font-subhed-2($i: true);
+  @include font-subhed-2($i: false);
 }
 
 .font-subhed-3 {
-  @include font-subhed-3($i: true);
+  @include font-subhed-3($i: false);
 }
 
 .font-body {
-  @include font-body($i: true);
+  @include font-body($i: false);
 }
 
 .font-note-1 {
-  @include font-note-1($i: true);
+  @include font-note-1($i: false);
 }
 
 .font-note-2 {
-  @include font-note-2($i: true);
+  @include font-note-2($i: false);
 }
 
 .font-note-3 {
-  @include font-note-3($i: true);
+  @include font-note-3($i: false);
 }