@reuters-graphics/graphics-components 3.10.0 → 4.0.0

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

@@ -0,0 +1,443 @@
+# Colour Palettes
+
+CSS custom properties set on `:root`. Import a palette to use its variables:
+
+```scss
+// Example: import the blue palette
+@use '@reuters-graphics/graphics-components/scss/colours/primary/blue';
+```
+
+Then reference variables with `var(--blue-500)` etc.
+
+## Primary palettes
+
+### Amber
+
+| Variable | Value |
+|----------|-------|
+| `--amber-50` | `#fffbeb` |
+| `--amber-100` | `#fef3c7` |
+| `--amber-200` | `#fde68a` |
+| `--amber-300` | `#fcd34d` |
+| `--amber-400` | `#fbbf24` |
+| `--amber-500` | `#f59e0b` |
+| `--amber-600` | `#d97706` |
+| `--amber-700` | `#b45309` |
+| `--amber-800` | `#92400e` |
+| `--amber-900` | `#78350f` |
+| `--amber-950` | `#451a03` |
+
+### Blue
+
+| Variable | Value |
+|----------|-------|
+| `--blue-50` | `#eff6ff` |
+| `--blue-100` | `#dbeafe` |
+| `--blue-200` | `#bfdbfe` |
+| `--blue-300` | `#93c5fd` |
+| `--blue-400` | `#60a5fa` |
+| `--blue-500` | `#3b82f6` |
+| `--blue-600` | `#2563eb` |
+| `--blue-700` | `#1d4ed8` |
+| `--blue-800` | `#1e40af` |
+| `--blue-900` | `#1e3a8a` |
+| `--blue-950` | `#172554` |
+
+### Cyan
+
+| Variable | Value |
+|----------|-------|
+| `--cyan-50` | `#ecfeff` |
+| `--cyan-100` | `#cffafe` |
+| `--cyan-200` | `#a5f3fc` |
+| `--cyan-300` | `#67e8f9` |
+| `--cyan-400` | `#22d3ee` |
+| `--cyan-500` | `#06b6d4` |
+| `--cyan-600` | `#0891b2` |
+| `--cyan-700` | `#0e7490` |
+| `--cyan-800` | `#155e75` |
+| `--cyan-900` | `#164e63` |
+| `--cyan-950` | `#083344` |
+
+### Emerald
+
+| Variable | Value |
+|----------|-------|
+| `--emerald-50` | `#ecfdf5` |
+| `--emerald-100` | `#d1fae5` |
+| `--emerald-200` | `#a7f3d0` |
+| `--emerald-300` | `#6ee7b7` |
+| `--emerald-400` | `#34d399` |
+| `--emerald-500` | `#10b981` |
+| `--emerald-600` | `#059669` |
+| `--emerald-700` | `#047857` |
+| `--emerald-800` | `#065f46` |
+| `--emerald-900` | `#064e3b` |
+| `--emerald-950` | `#022c22` |
+
+### Fuchsia
+
+| Variable | Value |
+|----------|-------|
+| `--fuchsia-50` | `#fdf4ff` |
+| `--fuchsia-100` | `#fae8ff` |
+| `--fuchsia-200` | `#f5d0fe` |
+| `--fuchsia-300` | `#f0abfc` |
+| `--fuchsia-400` | `#e879f9` |
+| `--fuchsia-500` | `#d946ef` |
+| `--fuchsia-600` | `#c026d3` |
+| `--fuchsia-700` | `#a21caf` |
+| `--fuchsia-800` | `#86198f` |
+| `--fuchsia-900` | `#701a75` |
+| `--fuchsia-950` | `#4a044e` |
+
+### Green
+
+| Variable | Value |
+|----------|-------|
+| `--green-50` | `#f0fdf4` |
+| `--green-100` | `#dcfce7` |
+| `--green-200` | `#bbf7d0` |
+| `--green-300` | `#86efac` |
+| `--green-400` | `#4ade80` |
+| `--green-500` | `#22c55e` |
+| `--green-600` | `#16a34a` |
+| `--green-700` | `#15803d` |
+| `--green-800` | `#166534` |
+| `--green-900` | `#14532d` |
+| `--green-950` | `#052e16` |
+
+### Grey
+
+| Variable | Value |
+|----------|-------|
+| `--grey-50` | `#f9fafb` |
+| `--grey-100` | `#f3f4f6` |
+| `--grey-200` | `#e5e7eb` |
+| `--grey-300` | `#d1d5db` |
+| `--grey-400` | `#9ca3af` |
+| `--grey-500` | `#6b7280` |
+| `--grey-600` | `#4b5563` |
+| `--grey-700` | `#374151` |
+| `--grey-800` | `#1f2937` |
+| `--grey-900` | `#111827` |
+| `--grey-950` | `#030712` |
+
+### Indigo
+
+| Variable | Value |
+|----------|-------|
+| `--indigo-50` | `#eef2ff` |
+| `--indigo-100` | `#e0e7ff` |
+| `--indigo-200` | `#c7d2fe` |
+| `--indigo-300` | `#a5b4fc` |
+| `--indigo-400` | `#818cf8` |
+| `--indigo-500` | `#6366f1` |
+| `--indigo-600` | `#4f46e5` |
+| `--indigo-700` | `#4338ca` |
+| `--indigo-800` | `#3730a3` |
+| `--indigo-900` | `#312e81` |
+| `--indigo-950` | `#1e1b4b` |
+
+### Lime
+
+| Variable | Value |
+|----------|-------|
+| `--lime-50` | `#f7fee7` |
+| `--lime-100` | `#ecfccb` |
+| `--lime-200` | `#d9f99d` |
+| `--lime-300` | `#bef264` |
+| `--lime-400` | `#a3e635` |
+| `--lime-500` | `#84cc16` |
+| `--lime-600` | `#65a30d` |
+| `--lime-700` | `#4d7c0f` |
+| `--lime-800` | `#3f6212` |
+| `--lime-900` | `#365314` |
+| `--lime-950` | `#1a2e05` |
+
+### Neutral
+
+| Variable | Value |
+|----------|-------|
+| `--neutral-50` | `#fafafa` |
+| `--neutral-100` | `#f5f5f5` |
+| `--neutral-200` | `#e5e5e5` |
+| `--neutral-300` | `#d4d4d4` |
+| `--neutral-400` | `#a3a3a3` |
+| `--neutral-500` | `#737373` |
+| `--neutral-600` | `#525252` |
+| `--neutral-700` | `#404040` |
+| `--neutral-800` | `#262626` |
+| `--neutral-900` | `#171717` |
+| `--neutral-950` | `#0a0a0a` |
+
+### Orange
+
+| Variable | Value |
+|----------|-------|
+| `--orange-50` | `#fff7ed` |
+| `--orange-100` | `#ffedd5` |
+| `--orange-200` | `#fed7aa` |
+| `--orange-300` | `#fdba74` |
+| `--orange-400` | `#fb923c` |
+| `--orange-500` | `#f97316` |
+| `--orange-600` | `#ea580c` |
+| `--orange-700` | `#c2410c` |
+| `--orange-800` | `#9a3412` |
+| `--orange-900` | `#7c2d12` |
+| `--orange-950` | `#431407` |
+
+### Pink
+
+| Variable | Value |
+|----------|-------|
+| `--pink-50` | `#fdf2f8` |
+| `--pink-100` | `#fce7f3` |
+| `--pink-200` | `#fbcfe8` |
+| `--pink-300` | `#f9a8d4` |
+| `--pink-400` | `#f472b6` |
+| `--pink-500` | `#ec4899` |
+| `--pink-600` | `#db2777` |
+| `--pink-700` | `#be185d` |
+| `--pink-800` | `#9d174d` |
+| `--pink-900` | `#831843` |
+| `--pink-950` | `#500724` |
+
+### Purple
+
+| Variable | Value |
+|----------|-------|
+| `--purple-50` | `#faf5ff` |
+| `--purple-100` | `#f3e8ff` |
+| `--purple-200` | `#e9d5ff` |
+| `--purple-300` | `#d8b4fe` |
+| `--purple-400` | `#c084fc` |
+| `--purple-500` | `#a855f7` |
+| `--purple-600` | `#9333ea` |
+| `--purple-700` | `#7e22ce` |
+| `--purple-800` | `#6b21a8` |
+| `--purple-900` | `#581c87` |
+| `--purple-950` | `#3b0764` |
+
+### Red
+
+| Variable | Value |
+|----------|-------|
+| `--red-50` | `#fef2f2` |
+| `--red-100` | `#fee2e2` |
+| `--red-200` | `#fecaca` |
+| `--red-300` | `#fca5a5` |
+| `--red-400` | `#f87171` |
+| `--red-500` | `#ef4444` |
+| `--red-600` | `#dc2626` |
+| `--red-700` | `#b91c1c` |
+| `--red-800` | `#991b1b` |
+| `--red-900` | `#7f1d1d` |
+| `--red-950` | `#450a0a` |
+
+### Rose
+
+| Variable | Value |
+|----------|-------|
+| `--rose-50` | `#fff1f2` |
+| `--rose-100` | `#ffe4e6` |
+| `--rose-200` | `#fecdd3` |
+| `--rose-300` | `#fda4af` |
+| `--rose-400` | `#fb7185` |
+| `--rose-500` | `#f43f5e` |
+| `--rose-600` | `#e11d48` |
+| `--rose-700` | `#be123c` |
+| `--rose-800` | `#9f1239` |
+| `--rose-900` | `#881337` |
+| `--rose-950` | `#4c0519` |
+
+### Sky
+
+| Variable | Value |
+|----------|-------|
+| `--sky-50` | `#f0f9ff` |
+| `--sky-100` | `#e0f2fe` |
+| `--sky-200` | `#bae6fd` |
+| `--sky-300` | `#7dd3fc` |
+| `--sky-400` | `#38bdf8` |
+| `--sky-500` | `#0ea5e9` |
+| `--sky-600` | `#0284c7` |
+| `--sky-700` | `#0369a1` |
+| `--sky-800` | `#075985` |
+| `--sky-900` | `#0c4a6e` |
+| `--sky-950` | `#082f49` |
+
+### Slate
+
+| Variable | Value |
+|----------|-------|
+| `--slate-50` | `#f8fafc` |
+| `--slate-100` | `#f1f5f9` |
+| `--slate-200` | `#e2e8f0` |
+| `--slate-300` | `#cbd5e1` |
+| `--slate-400` | `#94a3b8` |
+| `--slate-500` | `#64748b` |
+| `--slate-600` | `#475569` |
+| `--slate-700` | `#334155` |
+| `--slate-800` | `#1e293b` |
+| `--slate-900` | `#0f172a` |
+| `--slate-950` | `#020617` |
+
+### Stone
+
+| Variable | Value |
+|----------|-------|
+| `--stone-50` | `#fafaf9` |
+| `--stone-100` | `#f5f5f4` |
+| `--stone-200` | `#e7e5e4` |
+| `--stone-300` | `#d6d3d1` |
+| `--stone-400` | `#a8a29e` |
+| `--stone-500` | `#78716c` |
+| `--stone-600` | `#57534e` |
+| `--stone-700` | `#44403c` |
+| `--stone-800` | `#292524` |
+| `--stone-900` | `#1c1917` |
+| `--stone-950` | `#0c0a09` |
+
+### Teal
+
+| Variable | Value |
+|----------|-------|
+| `--teal-50` | `#f0fdfa` |
+| `--teal-100` | `#ccfbf1` |
+| `--teal-200` | `#99f6e4` |
+| `--teal-300` | `#5eead4` |
+| `--teal-400` | `#2dd4bf` |
+| `--teal-500` | `#14b8a6` |
+| `--teal-600` | `#0d9488` |
+| `--teal-700` | `#0f766e` |
+| `--teal-800` | `#115e59` |
+| `--teal-900` | `#134e4a` |
+| `--teal-950` | `#042f2e` |
+
+### Violet
+
+| Variable | Value |
+|----------|-------|
+| `--violet-50` | `#f5f3ff` |
+| `--violet-100` | `#ede9fe` |
+| `--violet-200` | `#ddd6fe` |
+| `--violet-300` | `#c4b5fd` |
+| `--violet-400` | `#a78bfa` |
+| `--violet-500` | `#8b5cf6` |
+| `--violet-600` | `#7c3aed` |
+| `--violet-700` | `#6d28d9` |
+| `--violet-800` | `#5b21b6` |
+| `--violet-900` | `#4c1d95` |
+| `--violet-950` | `#2e1065` |
+
+### Yellow
+
+| Variable | Value |
+|----------|-------|
+| `--yellow-50` | `#fefce8` |
+| `--yellow-100` | `#fef9c3` |
+| `--yellow-200` | `#fef08a` |
+| `--yellow-300` | `#fde047` |
+| `--yellow-400` | `#facc15` |
+| `--yellow-500` | `#eab308` |
+| `--yellow-600` | `#ca8a04` |
+| `--yellow-700` | `#a16207` |
+| `--yellow-800` | `#854d0e` |
+| `--yellow-900` | `#713f12` |
+| `--yellow-950` | `#422006` |
+
+### Zinc
+
+| Variable | Value |
+|----------|-------|
+| `--zinc-50` | `#fafafa` |
+| `--zinc-100` | `#f4f4f5` |
+| `--zinc-200` | `#e4e4e7` |
+| `--zinc-300` | `#d4d4d8` |
+| `--zinc-400` | `#a1a1aa` |
+| `--zinc-500` | `#71717a` |
+| `--zinc-600` | `#52525b` |
+| `--zinc-700` | `#3f3f46` |
+| `--zinc-800` | `#27272a` |
+| `--zinc-900` | `#18181b` |
+| `--zinc-950` | `#09090b` |
+
+## Thematic palettes
+
+Import thematic palettes to access branded colour tokens used by the `Theme` component.
+
+### Nord
+
+| Variable | Value |
+|----------|-------|
+| `--nord-0` | `#2e3440` |
+| `--nord-polar-night-0` | `#2e3440` |
+| `--nord-black` | `#2e3440` |
+| `--nord-1` | `#3b4252` |
+| `--nord-polar-night-1` | `#3b4252` |
+| `--nord-2` | `#434c5e` |
+| `--nord-polar-night-2` | `#434c5e` |
+| `--nord-3` | `#4c566a` |
+| `--nord-polar-night-3` | `#4c566a` |
+| `--nord-4` | `#d8dee9` |
+| `--nord-snow-storm-0` | `#d8dee9` |
+| `--nord-5` | `#e5e9f0` |
+| `--nord-snow-storm-1` | `#e5e9f0` |
+| `--nord-6` | `#eceff4` |
+| `--nord-snow-storm-2` | `#eceff4` |
+| `--nord-white` | `#eceff4` |
+| `--nord-7` | `#8fbcbb` |
+| `--nord-frost-0` | `#8fbcbb` |
+| `--nord-8` | `#88c0d0` |
+| `--nord-frost-1` | `#88c0d0` |
+| `--nord-9` | `#81a1c1` |
+| `--nord-frost-2` | `#81a1c1` |
+| `--nord-10` | `#5e81ac` |
+| `--nord-frost-3` | `#5e81ac` |
+| `--nord-blue` | `#5e81ac` |
+| `--nord-11` | `#bf616a` |
+| `--nord-aurora-0` | `#bf616a` |
+| `--nord-red` | `#bf616a` |
+| `--nord-12` | `#d08770` |
+| `--nord-aurora-1` | `#d08770` |
+| `--nord-orange` | `#d08770` |
+| `--nord-13` | `#ebcb8b` |
+| `--nord-aurora-2` | `#ebcb8b` |
+| `--nord-yellow` | `#ebcb8b` |
+| `--nord-14` | `#a3be8c` |
+| `--nord-aurora-3` | `#a3be8c` |
+| `--nord-green` | `#a3be8c` |
+| `--nord-15` | `#b48ead` |
+| `--nord-aurora-4` | `#b48ead` |
+| `--nord-purple` | `#b48ead` |
+
+### Tr
+
+| Variable | Value |
+|----------|-------|
+| `--tr-orange` | `#fa6400` |
+| `--tr-dark-orange` | `#dc4300` |
+| `--tr-light-orange` | `#ffa100` |
+| `--tr-dark-grey` | `#404040` |
+| `--tr-medium-grey` | `#666666` |
+| `--tr-light-grey` | `#afafaf` |
+| `--tr-muted-grey` | `#d0d0d0` |
+| `--tr-contrast-grey` | `#949494` |
+| `--tr-hover-background-grey` | `#f8f8f8` |
+| `--tr-light-muted-grey` | `#f4f4f4` |
+| `--tr-ultra-light-grey` | `#fafafa` |
+| `--tr-dark-blue` | `#005da2` |
+| `--tr-light-blue` | `#0099c4` |
+| `--tr-muted-blue` | `#4386b9` |
+| `--tr-lighter-blue` | `#7facce` |
+| `--tr-superlight-blue` | `#e5eef5` |
+| `--tr-dark-purple` | `#621f95` |
+| `--tr-light-purple` | `#6e3ab7` |
+| `--tr-dark-red` | `#a00000` |
+| `--tr-light-red` | `#dc0a0a` |
+| `--tr-dark-green` | `#387c2b` |
+| `--tr-light-green` | `#77a22d` |
+| `--tr-black` | `#000` |
+| `--tr-white` | `#fff` |
+| `--tr-ad-placeholder` | `#ffb1b1` |

package/dist/llm-docs/guides/customising-with-scss.md

@@ -0,0 +1,61 @@
+# Customising components with SCSS
+
+One of the most powerful ways to customise components isn't props or, even, Svelte.
+
+## How's that??
+
+Let's say you wanted to change our `BeforeAfter` component. You want the text overlays to be at the bottom of the image instead of the top like this:
+
+The first thing you should do is  and see if CSS can make the change you want.
+
+In our case, we want to change the absolute position of those elements. To test that'll actually work, we can 
+
+Now that we know we can change what we need through CSS it's time to write some SCSS, either in your `global.scss` file or directly in a component like `App.svelte`.
+
+First, let's look at the class of the style rule we changed in the inspector:
+
+`figure.before-after-container.s-khJY-w4TYkp5 .overlay-container.before.s-khJY-w4TYkp5`
+
+One thing we always need to do is , i.e., those weird `.s-khJY-w4TYkp5` classes. Why? Those are random classes Svelte adds to CSS, and we can't guarantee they won't change.
+
+That leaves us with:
+
+`figure.before-after-container .overlay-container.before`
+
+But we need our style rule to _beat_ the original style in the CSS cascade, and right now, it's less specific without those class names we stripped.
+
+The easiest way to make sure your style rule wins out is to . In our case, let's add an ID through the `BeforeAfter` `id` prop. Now we can use it! (For extra credit, though, we'll drop the `.before` so our new style rule applies to _both_ overlays.)
+
+```scss
+figure#my-before-after .overlay-container {
+  bottom: 0;
+}
+```
+
+Now our selector is more specific. We win!
+
+If you don't see a way to add an ID through a component's props, then just wrap the component in a `div` in your code:
+
+```svelte
+<div id="my-before-after">
+  <BeforeAfter />
+</div>
+```
+
+... and use that, instead!
+
+```scss
+div#my-before-after figure .overlay-container {
+  bottom: 0;
+}
+```
+
+We can&#x20;
+
+Done!
+
+### Can I just... `important!` it?
+
+Yep! Just be sure your style rule is **very specific** and not something generic that might apply to other elements in your page like `div.container`.
+
+Many of the components have `class` or `id` props you can use to attach additional classes or an id that will add more specificity to your components.

package/dist/llm-docs/guides/graphics-kit.md

@@ -0,0 +1,25 @@
+# Using with the graphics kit
+
+Our graphics components are designed to work seemlessly with the [graphics kit](https://reuters-graphics.github.io/bluprint_graphics-kit/) as well as just about any Svelte-based page builder.
+
+**There is, however, one gotcha to watch out for:**
+
+When working with multimedia files like images or videos, components expect all paths to be 
+
+✅ `https://reuters.com/graphics/.../myImage.jpg`
+
+❌ `./myImage.jpg`
+
+In the graphics kit, that means you'll need to prefix relative paths with the special [`asset`](https://svelte.dev/docs/kit/$app-paths#asset) SvelteKit helper that resolves the path to the root URL for your project. Many examples in these docs show how to do it. But it's also easy enough to demo again here!
+
+```svelte
+<script>
+  import { FeaturePhoto } from '@reuters-graphics/graphics-components';
+
+  // Import the asset helper if it's not already there.
+  import { asset } from '$app/paths';
+</script>
+
+<!-- Use the asset helper to prefix the path to your image. -->
+<FeautrePhoto src={asset('/imgs/myImage.jpg')} />
+```

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

@@ -0,0 +1,16 @@
+# Guides
+
+Conceptual documentation, integration guides, and design system reference.
+
+| Guide | Description |
+|-------|-------------|
+| [@reuters-graphics/graphics-components](./intro.md) | Svelte components, SCSS and more you can use in graphics projects. |
+| [Layout](./layout.md) | Layout components setup our default page structure. |
+| [Styles](./styles.md) | This library also includes our main SCSS stylesheets with pre-defined classes you can use to style your page. |
+| [CSS variables](./theming.md) | The Theme?path=/docs/components-theme--default component uses CSS variableshttps://developer.mozilla.org/en-US/docs/Web/CSS/UsingCSScustomproperties to control major parts of your  |
+| [Using with the graphics kit](./graphics-kit.md) | Our graphics components are designed to work seemlessly with the graphics kithttps://reuters-graphics.github.io/bluprintgraphics-kit/ as well as just about any Svelte-based page bu |
+| [Using components with ArchieML docs](./archieml.md) | Most of the snippets in these docs show how to use components by passing data into their props directly. In most cases, though, you don't want to hard-code content in your project  |
+| [Customising components with SCSS](./customising-with-scss.md) | One of the most powerful ways to customise components isn't props or, even, Svelte. |
+| [LLM Docs](./llm-docs.md) | This library ships machine-readable documentation designed to be used as context for AI agents and LLMs. The docs are generated at build time from source — Svelte component props,  |
+| [Colour Palettes](./colours.md) | CSS custom properties for 24 colour families (primary + thematic). |
+| [Style Tokens](./tokens.md) | Spacing utilities (margin/padding), typography classes, and fluid spacers. |

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

@@ -0,0 +1,21 @@
+# @reuters-graphics/graphics-components
+
+Svelte components, SCSS and more you can use in graphics projects.
+
+## Getting started
+
+1. Install
+
+```bash
+pnpm i @reuters-graphics/graphics-components
+```
+
+2. Checkout the [guides](?path=/docs/guides-using-these-docs--docs), if you haven't, or dive straight into the docs to start using components.
+
+```svelte
+<script>
+  import { BodyText } from '@reuters-graphics/graphics-components';
+</script>
+
+<BodyText text={'Hello world!'} />
+```

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

@@ -0,0 +1,13 @@
+# Layout
+
+Layout components setup our default page structure.
+
+Generally, our page layout includes a central text well and a few preset block breakpoints, wider and narrower than the well.
+
+Here's how it works:
+
+The [`Article`](?path=/docs/layout-article--default) component sets up the set dimensions of the well and the block breakpoints.
+
+The [`Block`](?path=/docs/layout-block--default) component is a wrapper for individual parts of a page that can be as wide as any of those breakpoints.
+
+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.

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

@@ -0,0 +1,71 @@
+# LLM Docs
+
+This library ships machine-readable documentation designed to be used as context for AI agents and LLMs. The docs are generated at build time from source — Svelte component props, Storybook stories, MDX prose, and SCSS token files — and packaged inside the npm distribution so a consuming project can pull them in with a single command.
+
+## What gets generated
+
+Running `pnpm generate:llm-docs` produces a `dist/llm-docs/` directory with the following structure:
+
+```
+dist/llm-docs/
+  index.md              ← Library overview and section links
+  components/
+    index.md            ← All components with category and description
+    BodyText.md         ← Per-component: props table, types, usage examples
+    Legend.md
+    ...
+  guides/
+    index.md            ← All guides with descriptions
+    archieml.md         ← Integration guides extracted from MDX prose
+    colours.md          ← Full colour palette tables (generated from SCSS)
+    tokens.md           ← Spacing and typography utility class reference
+    theming.md
+    ...
+```
+
+Each component file contains a props table with types, defaults, and JSDoc descriptions; TypeScript type definitions for any exported types; and Svelte usage examples extracted from Storybook stories.
+
+## Using in a consuming project
+
+This library declares its LLM docs via the `"llms"` field in `package.json`:
+
+```json
+"llms": {
+  "description": ["..."],
+  "files": ["./dist/llm-docs/**/*"]
+}
+```
+
+Consuming projects — the Graphics Kit and any future projects — use a `sync:llm-docs` script that reads this field across all installed `@reuters-graphics/*` packages and copies the matched files to `.claude/llms/{package-name}/` in the project root, then writes a `CLAUDE.md` entry using the `description`. Running that sync script after `pnpm install` keeps all library docs current automatically.
+
+See the Graphics Kit for the sync script implementation.
+
+## Maintaining the generator
+
+The generation pipeline lives in `scripts/generate-llm-docs/` and runs as part of the `build` script. It has two plain-file configuration points that can be edited without touching any TypeScript.
+
+### docs-map.json
+
+`scripts/generate-llm-docs/docs-map.json` lists the MDX files from `src/docs/` that get extracted into `guides/`. Each entry maps a source path (relative to `src/docs/`) to an output filename and a fallback title:
+
+```json
+[
+  {
+    "srcPath": "guides/archieml.mdx",
+    "destFile": "archieml.md",
+    "title": "Using ArchieML"
+  }
+]
+```
+
+Add a new entry when a new guide is written in `src/docs/`. Remove or update entries when guides move or are renamed. The MDX extractor strips JSX components (`<Canvas>`, `<Meta>`, imports) and preserves the prose, so only files with meaningful prose content are worth including.
+
+Some files in `src/docs/` are intentionally omitted — `theme-builder/` (a React application with no extractable prose), `styles/tokens/` (interactive data tables with no prose), and `docs-components/` and `utils/` (internal tooling). The colour and token reference docs are generated directly from SCSS source instead.
+
+### master-index.md
+
+`scripts/generate-llm-docs/master-index.md` is the static `index.md` that lands at the root of `dist/llm-docs/`. Edit it directly to update the library overview, install instructions, or section descriptions. No code changes required.
+
+### Component docs
+
+Component documentation is generated automatically by scanning `src/components/` — no configuration needed. Every component directory that contains a `.svelte` file is processed. Props, defaults, and JSDoc descriptions come from the TypeScript `interface Props {}` block; usage examples come from `<Story>` elements in the `.stories.svelte` file; prose comes from the `.mdx` file. New components are picked up on the next build.

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

@@ -0,0 +1,16 @@
+# Styles
+
+This library also includes our main SCSS stylesheets with pre-defined classes you can use to style your page.
+
+### Importing our main stylesheet
+
+Import the SCSS directly in your top-level component. (This is done for you in the graphics kit.)
+
+```svelte
+<!-- pages/index.svelte -->
+<script>
+  // other imports and stuffs ...
+
+  import '@reuters-graphics/graphics-components/scss/main.scss';
+</script>
+```