@reuters-graphics/graphics-components 3.10.0 → 4.0.0

package/dist/llm-docs/guides/theming.md

@@ -0,0 +1,100 @@
+# CSS variables
+
+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.
+
+> **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);
+    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) and **use the [Theme builder](/docs/theming-theme-builder--docs)**.
+
+```svelte
+<Theme
+  base="light"
+  theme={{
+    colour: {
+      // This replaces the default text-secondary colour '#666666' for light theme
+      'text-secondary': '#213310',
+    },
+  }}
+>
+  <!-- page stuff -->
+</Theme>
+```
+
+## Adding extra variables
+
+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:
+
+```svelte
+<Theme
+  base="light"
+  theme={{
+    style: {
+      'border-radius': '22px',
+    },
+  }}
+>
+  <!-- page stuff -->
+</Theme>
+```
+
+... and then access the CSS variable in your code like this:
+
+```svelte
+<div class="card"></div>
+
+<style lang="scss">
+  .card {
+    border-radius: var(--theme-style-border-radius);
+  }
+</style>
+```
+
+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 change a variable's value based on some condition. For example, to set a smaller border radius on mobile screens, you might:
+
+```svelte
+<script>
+  // other code
+
+  let windowWidth;
+</script>
+
+<svelte:window bind:innerWidth={windowWidth} />
+
+<Theme
+  base="light"
+  theme={{
+    style: {
+      'border-radius': windowWidth > 475 ? '22px' : '11px',
+    },
+  }}
+>
+  <!-- page stuff -->
+</Theme>
+```

package/dist/llm-docs/guides/tokens.md

@@ -0,0 +1,150 @@
+# Style Tokens
+
+Import the main SCSS to access all token classes:
+
+```scss
+@use '@reuters-graphics/graphics-components/scss/main';
+```
+
+## Spacing
+
+Static spacing uses the Tailwind scale: 1 unit = 0.25rem. So `.m-4` = 1rem, `.m-8` = 2rem, `.my-6` = 1.5rem block margin.
+
+### Static margin
+
+| Prefix | Property |
+|--------|---------|
+| `m-{n}` | margin (all sides) |
+| `mt-{n}` | margin-block-start (top) |
+| `mb-{n}` | margin-block-end (bottom) |
+| `ml-{n}` | margin-inline-start (left) |
+| `mr-{n}` | margin-inline-end (right) |
+| `mx-{n}` | margin-inline (left + right) |
+| `my-{n}` | margin-block (top + bottom) |
+
+Available levels and their values:
+
+| Level | Value |
+|-------|-------|
+| `0` | `0` |
+| `0\.5` | `0.125rem` |
+| `1` | `0.25rem` |
+| `1\.5` | `0.375rem` |
+| `2` | `0.5rem` |
+| `2\.5` | `0.625rem` |
+| `3` | `0.75rem` |
+| `3\.5` | `0.875rem` |
+| `4` | `1rem` |
+| `5` | `1.25rem` |
+| `6` | `1.5rem` |
+| `7` | `1.75rem` |
+| `8` | `2rem` |
+| `9` | `2.25rem` |
+| `10` | `2.5rem` |
+| `11` | `2.75rem` |
+| `12` | `3rem` |
+| `14` | `3.5rem` |
+| `16` | `4rem` |
+| `20` | `5rem` |
+| `24` | `6rem` |
+| `28` | `7rem` |
+| `32` | `8rem` |
+| `36` | `9rem` |
+| `40` | `10rem` |
+| `44` | `11rem` |
+| `48` | `12rem` |
+| `52` | `13rem` |
+| `56` | `14rem` |
+| `60` | `15rem` |
+| `64` | `16rem` |
+| `72` | `18rem` |
+| `80` | `20rem` |
+| `96` | `24rem` |
+
+### Static padding
+
+Same scale as margin. Prefixes:
+
+| Prefix | Property |
+|--------|---------|
+| `p-{n}` | padding (all sides) |
+| `pt-{n}` | padding-block-start (top) |
+| `pb-{n}` | padding-block-end (bottom) |
+| `pl-{n}` | padding-inline-start (left) |
+| `pr-{n}` | padding-inline-end (right) |
+| `px-{n}` | padding-inline (left + right) |
+| `py-{n}` | padding-block (top + bottom) |
+
+### Fluid margin
+
+Fluid values scale with viewport width. Use SCSS `@extend` to apply: `@extend %fmy-4;`. Direct utility classes are also available for levels 0–9.
+
+| Class | Properties |
+|-------|------------|
+| `.fm-1` | `margin: clamp(0.31rem, 0.31rem + 0vw, 0.31rem);` |
+| `.fm-2` | `margin: clamp(0.56rem, 0.52rem + 0.21vw, 0.69rem);` |
+| `.fm-3` | `margin: clamp(0.88rem, 0.83rem + 0.21vw, 1rem);` |
+| `.fm-4` | `margin: clamp(1.13rem, 1.06rem + 0.31vw, 1.31rem);` |
+| `.fm-5` | `margin: clamp(1.69rem, 1.58rem + 0.52vw, 2rem);` |
+| `.fm-6` | `margin: clamp(2.25rem, 2.13rem + 0.63vw, 2.63rem);` |
+| `.fm-7` | `margin: clamp(3.38rem, 3.19rem + 0.94vw, 3.94rem);` |
+| `.fm-8` | `margin: clamp(4.5rem, 4.25rem + 1.25vw, 5.25rem);` |
+| `.fm-9` | `margin: clamp(6.75rem, 6.38rem + 1.88vw, 7.88rem);` |
+
+### Fluid padding
+
+Same scale as fluid margin. Prefix `fp` instead of `fm`.
+
+| Class | Properties |
+|-------|------------|
+| `.fp-1` | `padding: clamp(0.31rem, 0.31rem + 0vw, 0.31rem);` |
+| `.fp-2` | `padding: clamp(0.56rem, 0.52rem + 0.21vw, 0.69rem);` |
+| `.fp-3` | `padding: clamp(0.88rem, 0.83rem + 0.21vw, 1rem);` |
+| `.fp-4` | `padding: clamp(1.13rem, 1.06rem + 0.31vw, 1.31rem);` |
+| `.fp-5` | `padding: clamp(1.69rem, 1.58rem + 0.52vw, 2rem);` |
+| `.fp-6` | `padding: clamp(2.25rem, 2.13rem + 0.63vw, 2.63rem);` |
+| `.fp-7` | `padding: clamp(3.38rem, 3.19rem + 0.94vw, 3.94rem);` |
+| `.fp-8` | `padding: clamp(4.5rem, 4.25rem + 1.25vw, 5.25rem);` |
+| `.fp-9` | `padding: clamp(6.75rem, 6.38rem + 1.88vw, 7.88rem);` |
+
+## Typography
+
+### Font size
+
+| Class | Properties |
+|-------|------------|
+| `.text-xxs` | `font-size: var(--theme-font-size-xxs);` |
+| `.text-xs` | `font-size: var(--theme-font-size-xs);` |
+| `.text-sm` | `font-size: var(--theme-font-size-sm);` |
+| `.text-base` | `font-size: var(--theme-font-size-base);` |
+| `.text-lg` | `font-size: var(--theme-font-size-lg);` |
+| `.text-xl` | `font-size: var(--theme-font-size-xl);` |
+| `.text-2xl` | `font-size: var(--theme-font-size-2xl);` |
+| `.text-3xl` | `font-size: var(--theme-font-size-3xl);` |
+| `.text-4xl` | `font-size: var(--theme-font-size-4xl);` |
+| `.text-5xl` | `font-size: var(--theme-font-size-5xl);` |
+| `.text-6xl` | `font-size: var(--theme-font-size-6xl);` |
+
+### Font weight
+
+| Class | Properties |
+|-------|------------|
+| `.font-thin` | `font-weight: 100;` |
+| `.font-extralight` | `font-weight: 200;` |
+| `.font-light` | `font-weight: 300;` |
+| `.font-regular` | `font-weight: 400;` |
+| `.font-medium` | `font-weight: 500;` |
+| `.font-semibold` | `font-weight: 600;` |
+| `.font-bold` | `font-weight: 700;` |
+| `.font-extrabold` | `font-weight: 800;` |
+| `.font-black` | `font-weight: 900;` |
+
+### Line height
+
+| Class | Properties |
+|-------|------------|
+| `.leading-tighter` | `line-height: 1.15;` |
+| `.leading-tight` | `line-height: 1.3;` |
+| `.leading-normal` | `line-height: 1.5;` |
+| `.leading-loose` | `line-height: 1.7;` |
+| `.leading-looser` | `line-height: 1.9;` |

package/dist/llm-docs/index.md

@@ -0,0 +1,36 @@
+# @reuters-graphics/graphics-components
+
+A Svelte 5 component library built by the Graphics team at Reuters for producing data journalism and interactive graphics. Components cover page layout, text elements, multimedia, maps, data visualisation, and site infrastructure — all designed to match the visual and structural conventions of enterprise stories published on reuters.com.
+
+The library ships with a full SCSS design system: spacing tokens, typography utilities, a colour palette, and CSS custom properties for theming via the `Theme` component.
+
+**Install:** `pnpm add @reuters-graphics/graphics-components`
+
+**Import components:**
+
+```svelte
+<script>
+  import {
+    BodyText,
+    Legend,
+    ShareBar,
+  } from '@reuters-graphics/graphics-components';
+</script>
+```
+
+**Import SCSS:**
+
+```scss
+@use '@reuters-graphics/graphics-components/scss/main';
+```
+
+---
+
+## This reference
+
+- **[Components](./components/index.md)** — Per-component docs with props tables, TypeScript type definitions, and usage examples extracted from Storybook stories.
+- **[Guides](./guides/index.md)** — Integration guides, design system reference, theming, SCSS tokens, and colour palettes.
+
+To find a specific component, start with `./components/index.md` for the full list, then open the individual component file. To understand the design system (spacing, colours, typography), start with `./guides/index.md`.
+
+These docs are automatically generated from components' code structure, SCSS files and also from human-friendly documentation written using Storybook's MDX and Component Story Format syntax.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reuters-graphics/graphics-components",
-  "version": "3.10.0",
+  "version": "4.0.0",
   "type": "module",
   "private": false,
   "homepage": "https://reuters-graphics.github.io/graphics-components",
@@ -26,29 +26,23 @@
     "!dist/**/images"
   ],
   "engines": {
-    "node": ">=20.18"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.2",
-    "@chromatic-com/storybook": "^3.2.6",
+    "@chromatic-com/storybook": "^5.2.1",
     "@reuters-graphics/yaks-eslint": "^0.1.1",
     "@reuters-graphics/yaks-prettier": "^0.1.1",
-    "@storybook/addon-a11y": "^8.6.12",
-    "@storybook/addon-essentials": "^8.6.12",
-    "@storybook/addon-interactions": "^8.6.12",
-    "@storybook/addon-svelte-csf": "5.0.0-next.28",
-    "@storybook/blocks": "^8.6.12",
-    "@storybook/components": "^8.6.12",
-    "@storybook/manager-api": "^8.6.12",
-    "@storybook/svelte": "^8.6.12",
-    "@storybook/sveltekit": "^8.6.12",
-    "@storybook/test": "^8.6.12",
-    "@storybook/theming": "^8.6.12",
-    "@sveltejs/package": "^2.3.11",
-    "@sveltejs/vite-plugin-svelte": "^5.0.3",
+    "@storybook/addon-a11y": "^10.4.6",
+    "@storybook/addon-docs": "^10.4.6",
+    "@storybook/addon-svelte-csf": "5.1.2",
+    "@storybook/svelte": "^10.4.6",
+    "@storybook/sveltekit": "^10.4.6",
+    "@sveltejs/package": "^2.5.8",
+    "@sveltejs/vite-plugin-svelte": "^7.1.3",
     "@types/css": "^0.0.37",
     "@types/eslint": "^9.6.1",
     "@types/fs-extra": "^11.0.4",
@@ -69,7 +63,7 @@
     "eslint": "^9.25.0",
     "eslint-plugin-mdx": "^3.4.0",
     "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-storybook": "^0.12.0",
+    "eslint-plugin-storybook": "^10.4.6",
     "knip": "^5.50.5",
     "mermaid": "^10.9.3",
     "postcss": "^8.5.3",
@@ -87,22 +81,22 @@
     "remark-stringify": "^11.0.0",
     "rimraf": "^6.0.1",
     "sass": "^1.86.3",
-    "storybook": "^8.6.12",
-    "svelte": "^5.28.1",
-    "svelte-check": "^4.1.6",
+    "storybook": "^10.4.6",
+    "svelte": "^5.56.4",
+    "svelte-check": "^4.7.1",
     "ts-morph": "^28.0.0",
     "tsx": "^4.22.4",
     "typescript": "^5.8.3",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
-    "vite": "^6.3.2"
+    "vite": "^8.1.3"
   },
   "dependencies": {
     "@fortawesome/free-regular-svg-icons": "^6.7.2",
     "@fortawesome/free-solid-svg-icons": "^6.7.2",
     "@lottiefiles/dotlottie-web": "^0.52.2",
     "@reuters-graphics/svelte-markdown": "^0.0.3",
-    "@sveltejs/kit": "^2.0.0",
+    "@sveltejs/kit": "^2.69.1",
     "@types/geojson": "^7946.0.16",
     "dayjs": "^1.11.13",
     "es-toolkit": "^1.35.0",
@@ -113,11 +107,11 @@
     "proper-url-join": "^2.1.2",
     "pym.js": "^1.3.2",
     "slugify": "^1.6.6",
-    "storybook-addon-rtl": "^1.1.0",
+    "storybook-addon-rtl": "^3.0.2",
     "svelte-fa": "^4.0.4",
     "svelte-intersection-observer": "^1.0.0",
     "ua-parser-js": "^2.0.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.10"
   },
   "exports": {
     ".": {