wires/hypnagaga
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #59 from reuters-graphics/type-system-jon

Browse source
This commit is contained in:
Prasanta Kumar Dutta 2023-03-22 16:27:47 +05:30 committed by GitHub
commit 961be5a0e8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 148 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
.storybook/preview.js
View file

@ -42,7 +42,7 @@ export const parameters = {
'Layout',
['Intro', '*'],
'Theming',
['*'],
['Theme', '*'],
'Components',
['Intro', '*'],
'*',
@ -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',

84
src/docs/theme/css-variables.stories.mdx → src/docs/theming/css-variables.stories.mdx
View file

@ -7,26 +7,32 @@ import { parameters } from '$docs/utils/docsPage.js';
# CSS variables
Several [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) are provided by the [`Theme`](?path=/docs/components-theme--default) component. All other components in this library use these variables for styling basic colours and typography. You can (and probably _should_) use them in you own code, too.
The [`Theme`](?path=/docs/components-theme--default) component uses **[CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)** to control major parts of your page's theme.
All other components in this library use those variables for styling basic colours and typography, helping keep our pages uniform and making it easier to customise the theme. CSS variables also allow our clients to easily change elements of our theme to match their brand.
This doc explains which variables are set and how you can use them in custom components you create.
> In the future, client's may be allowed to override our CSS variables to match their own house styles. So when using CSS variables, it's a good idea to set a [fallback value](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties#custom_property_fallback_values), in case a client misconfigures a variable override.
>
> **Note:** CSS variables do not currently affect [ai2svelte](https://github.com/reuters-graphics/ai2svelte/) graphics, so you should continue to make sure your colours match the theme of your page directly in Adobe Illustrator for those graphics.
## Using CSS variables directly
If you're new to how CSS variables work, [here's a video](https://www.youtube.com/watch?v=PHO6TBq_auI) that does a decent job explaining what they are, how they work and why they're useful.
You can use any of the CSS variables the `Theme` component sets in your own code with the [`var()`](https://www.w3schools.com/css/css3_variables.asp) function.
```svelte
<p>My custom text</p>
<style lang="scss">
p {
color: var(--theme-colour-text-primary, #333);
font-family: var(--theme-font-family-body, Knowledge);
color: var(--theme-colour-text-primary);
font-family: var(--theme-typeface-monospace);
}
</style>
```
## Default theme variables
Read more about how to override or define your own CSS variables in the [Themes](/docs/theming-theme--custom-theme) section.
## Theme variables
### Colours
@ -40,24 +46,7 @@ Read more about how to override or define your own CSS variables in the [Themes]
| `--theme-colour-brand-rules` | Rules in header and footer | #d0d0d0 | rgb(255 255 255 / 25%) |
| `--theme-colour-brand-shadow` | Box shadow on header | rgb(64 64 64 / 80%) | rgb(255 255 255 / 10%) |
### Font family and sizes
| CSS variable | Role | Default values |
| ---------------------------- | ---------------------------------------------------------------------- | -------------------------------- |
| `--theme-font-family-hed` | Headline (`h1`) font family | var(--theme-typeface-display) |
| `--theme-font-family-subhed` | Subhead (`h2`-`h6`) font family | var(--theme-typeface-sans-serif) |
| `--theme-font-family-body` | Body (`.body-text > p`) font family | var(--theme-typeface-serif) |
| `--theme-font-family-note` | Note (`.note-text > p`, `.end-note > p`, `.foot-note > p`) font family | var(--theme-typeface-sans-serif) |
| `--theme-font-size-hed` | Headline (`h1`) font size | var(--theme-scale-size-1) |
| `--theme-font-size-subhed-1` | Subhead (`h2`) font size | var(--theme-scale-size-2) |
| `--theme-font-size-subhed-2` | Subhead (`h3`) font size | var(--theme-scale-size-3) |
| `--theme-font-size-subhed-3` | Subhead (`h4`-`h6`) font size | var(--theme-scale-size-6) |
| `--theme-font-size-body` | Body (`.body-text > p`) font size | var(--theme-scale-size-3) |
| `--theme-font-size-note-1` | Body description (`.note-text > p`) font size | var(--theme-scale-size-4) |
| `--theme-font-size-note-2` | Endnotes (`.end-note > p`) font size | var(--theme-scale-size-5) |
| `--theme-font-size-note-3` | Dateline/Caption (`.foot-note > p`) font size | var(--theme-scale-size-6) |
### Typefaces (Fonts)
### Typefaces
| CSS variable | Role | Default values |
| ----------------------------- | --------------------------- | -------------------------------------------------------------------- |
@ -66,7 +55,29 @@ Read more about how to override or define your own CSS variables in the [Themes]
| `--theme-typeface-sans-serif` | Base sans-serif font family | Knowledge, sans-serif |
| `--theme-typeface-monospace` | Base monospace font family | Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace |
### Size scale
### Font families
| CSS variable | Role | Default values |
| ---------------------------- | ---------------------------------------------------------------------- | -------------------------------- |
| `--theme-font-family-hed` | Headline (`h1`) font family | var(--theme-typeface-display) |
| `--theme-font-family-subhed` | Subhead (`h2`-`h6`) font family | var(--theme-typeface-sans-serif) |
| `--theme-font-family-body` | Body (`.body-text > p`) font family | var(--theme-typeface-serif) |
| `--theme-font-family-note` | Note (`.note-text > p`, `.end-note > p`, `.foot-note > p`) font family | var(--theme-typeface-sans-serif) |
### Font sizes
| CSS variable | Role | Default values |
| ---------------------------- | --------------------------------------------- | ------------------------- |
| `--theme-font-size-hed` | Headline (`h1`) font size | var(--theme-scale-size-1) |
| `--theme-font-size-subhed-1` | Subhead (`h2`) font size | var(--theme-scale-size-2) |
| `--theme-font-size-subhed-2` | Subhead (`h3`) font size | var(--theme-scale-size-3) |
| `--theme-font-size-subhed-3` | Subhead (`h4`-`h6`) font size | var(--theme-scale-size-6) |
| `--theme-font-size-body` | Body (`.body-text > p`) font size | var(--theme-scale-size-3) |
| `--theme-font-size-note-1` | Body description (`.note-text > p`) font size | var(--theme-scale-size-4) |
| `--theme-font-size-note-2` | Endnotes (`.end-note > p`) font size | var(--theme-scale-size-5) |
| `--theme-font-size-note-3` | Dateline/Caption (`.foot-note > p`) font size | var(--theme-scale-size-6) |
### Size scale (fonts, margin, padding)
| CSS variable | Role | Default values |
| -------------------------------- | -------------------------------- | --------------------------------------------- |
@ -81,7 +92,7 @@ Read more about how to override or define your own CSS variables in the [Themes]
## 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).
You can redefine any of the above CSS variables in the `<Theme>` component. Read more in [the docs](/docs/theming-theme--custom-theme).
```svelte
<Theme
@ -97,11 +108,11 @@ You can redefine any of the CSS variables by declaring it in your `<Theme>` comp
</Theme>
```
## Adding custom variables
## Adding extra 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.
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.
For example, you want to define the border radius for your info cards in you app. You can create a new set of styles in the `<Theme>` as follows –
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:
```svelte
<Theme
@ -114,6 +125,12 @@ For example, you want to define the border radius for your info cards in you app
>
<!-- page stuff -->
</Theme>
```
... and then access the CSS variable in your code like this:
```svelte
<div class="card"></div>
<style lang="scss">
.card {
@ -122,8 +139,9 @@ For example, you want to define the border radius for your info cards in you app
</style>
```
You can also use Svelte's variables to change the CSS values assigned on some condition.
e.g. A smaller border radius on mobile screens.
Using the `Theme` component for your own CSS variables lets clients customise them the same as any of our default theme values.
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:
```svelte
<script>

49
src/docs/typography/intro.stories.mdx
View file

@ -11,41 +11,9 @@ 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
<img
className="feature"
src={TypeGuides}
width="100%"
style={{ margin: '3rem 0' }}
/>
## How it works
<img
className="feature"
src={Typeset}
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 –
- Page title, subheads and section titles
- Body copy
- Graphic descriptions, captions and other notes
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 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"
@ -53,3 +21,16 @@ The styles are also applied to native HTML elements like the `H` and `p` tags.
width="100%"
style={{ margin: '3rem 0' }}
/>
## The type style system
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 typographic scale is set using the CSS variable in the `Theme` component. You can customise it there.
<img
className="feature"
src={TypeGuides}
width="100%"
style={{ margin: '3rem 0' }}
/>

0
src/docs/typography/using Normal file
View file

80
src/docs/typography/using-the-system.stories.mdx Normal file
View file

@ -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...