What Is It​

MCP (Model Context Protocol) is a standard way for AI tools to talk to external systems. The Storybook MCP addon exposes our component catalog over that protocol: while Storybook is running, it serves an MCP endpoint that an agent can connect to and query.

In practice, the agent stops guessing what a PrimaryButton looks like or which props QuickStakes accepts — it asks Storybook directly and gets the real stories, args, and source.

What This Unlocks​

• Grounded UI generation — Agents build screens from our actual components and props, not hallucinated APIs.
• Self-serve component discovery — "What do we have for X?" is answered from the live story catalog.
• Accurate prop usage — Variants, required props, and defaults come straight from the stories.
• Less back-and-forth — Fewer wrong imports and invented props means less time correcting AI output.

Getting Started​

Run Storybook locally as usual, then point your AI tool at the MCP endpoint it exposes: http://localhost:8000/mcp.

Claude Code​

Add it as an HTTP MCP server from the terminal:

claude mcp add --transport http storybook http://localhost:8000/mcp

Cursor​

Add the server to your .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "storybook": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Then enable storybook under Settings → MCP.

VS Code​

With GitHub Copilot's agent mode, add the server to .vscode/mcp.json:

{
  "servers": {
    "storybook": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Start the server from the MCP view (or the MCP: List Servers command), then use it from the Chat panel in Agent mode.

Note: Storybook must be running for the endpoint to be reachable. Start your AI tool's MCP connection after Storybook is up.

Examples of Usage​

Once connected, try prompts like:

• "Give me all the buttons we have." — the agent lists every button component in the catalog (PrimaryButton, SecondaryButton, SportsbookBetButton, …) with their variants and props.
• "Using our design system, build a bet confirmation screen with a primary action and a secondary cancel." — the agent pulls PrimaryButton / SecondaryButton with correct props.
• "What PrimaryButton variants do we have, and which props are required?" — answered from the live story catalog.
• "Add a stake selector to this view." — the agent finds QuickStakes and wires it up with valid args.
• "Show me how Switch is used in its stories." — the agent reads the real story source instead of guessing.

Why This Matters​

A design system only delivers value when teams actually reuse its components. By making Storybook readable by AI agents, we close the gap between "ask an agent for a UI" and "get a UI built on The Wall." Less reinvention, more consistency, and faster delivery — directly from the source of truth.

Links​

• Storybook MCP Addon
• Model Context Protocol

After a structured evaluation of third-party design system documentation platforms, we've decided to keep our current stack: Figma + Storybook + Style Dictionary + Docusaurus.

What We Evaluated​

We looked at two SaaS alternatives that have been gaining traction in the design system space:

• Supernova — a documentation + token platform with a WYSIWYG editor and direct Figma sync
• Zeroheight — a similar SaaS offering aimed at bridging design and development documentation

Both promise to reduce the friction of authoring docs and keeping tokens in sync with Figma. Both replace Docusaurus as the documentation layer.

Why We're Staying​

After a head-to-head comparison across 11 decision drivers, the result was close — 6–5. On raw numbers alone, the case for migrating was real. What broke the tie was AI integration.

The Decisive Factor: AI Integration​

Our docs are MDX files on disk in a Git repo. Claude Code, Cursor, and any MCP-based agent can read, write, refactor, and generate pages natively — no glue code, no custom integration, no API wrappers. That's not a small thing.

With Supernova or Zeroheight, content lives behind a vendor API. There is no first-party MCP server for either platform (as of May 2025). To get the same agent access we have today, we'd need to build and maintain our own integration layer. The delta between "agent can touch your files" and "agent has to call an API you built yourself" is compounding every quarter as we invest more in AI-assisted workflows.

Some concrete things that work today and would break with a platform migration:

• Claude Code reads and writes MDX pages natively via the filesystem
• Cursor indexes the full docs repo for inline suggestions and refactors
• Any MCP filesystem or GitHub server works out of the box
• Bulk content changes are a script, not a support ticket
• Docs are grep-able, diff-able, and reviewable in PRs

"Docs as files in Git" is increasingly an asset. We're not giving that up.

Other Reasons We're Staying​

Full ownership, zero lock-in​

Our content is static HTML and Markdown in Git — version-controlled, diffable, grep-able, deployable anywhere. Both Supernova and Zeroheight store content in their cloud. Export paths exist, but you lose the authoring UX and all automations on the way out. The switching cost compounds over time.

Cost​

Our current stack costs $0 in licensing. A 10-editor Pro plan on Supernova runs ~$2,880–$4,320/year. That's real budget for modest gain. The true cost of Docusaurus is engineering maintenance time (estimated at 2–5 dev-days/year), which we already absorb.

Versioning and i18n​

Docusaurus ships first-class versioned docs and i18n support. Both evaluated platforms have weaker or plan-gated equivalents.

Custom UX and components​

Our MDX pages use custom React components — recharts for token charts, interactive tables, image zoom. A block-based SaaS editor can't replicate this without a custom block API, which is bounded by the vendor's schema.

Search​

We run Lunr today and can upgrade to Algolia DocSearch (free for open projects) with a drop-in config change. Neither Supernova nor Zeroheight's built-in search matches that.

Where the Alternatives Win​

To be honest about the trade-offs:

• Authoring friction — designers can't edit MDX without filing a PR or asking engineering. Supernova's WYSIWYG editor solves this directly.
• Maintenance overhead — Docusaurus upgrades, React version drift, broken plugins, and lunr quirks are a real ongoing tax. With a SaaS, that burden shifts to the vendor.
• Documentation quality out-of-the-box — token tables, component specs, and asset pages come pre-built and Figma-synced on both platforms. With Docusaurus we build and maintain those ourselves.
• Figma → token → docs parity — both platforms sync Figma variables natively; our current pipeline (Figma → Style Dictionary → docs) has manual steps.
• Speed to publish — editing in a SaaS is minutes; our Git-based flow is hours.

These are real pain points. If docs were consistently falling out of date because designers can't make changes themselves, the calculation would be different.

What We're Doing Instead​

Rather than migrate platforms, we're addressing the authoring friction within our current stack:

• Improving Style Dictionary automation to reduce token drift
• Documenting a lightweight contribution guide for non-engineers
• Exploring AI-assisted doc generation (Claude Code already reads and writes our MDX)

Decision Scorecard​

Final score: 6–5 in favour of the current stack. The margin is narrow — AI agent integration was the tiebreaker. Without it, the case for migrating was credible.

Revisiting This Decision​

We'll revisit if any of the following changes:

• Token drift becomes a persistent, high-frequency complaint from design
• Supernova ships a first-party MCP server that makes it agent-friendly
• Budget allocation shifts and licensing cost is no longer a blocker

What It Does​

The Haptics API lets you trigger haptic feedback in response to user actions like button taps, successful transactions, or error states. It supports multiple feedback types: interaction, impact (light to heavy), and notifications (success, warning, error).

The API respects operating system haptic settings, so users who disable system haptics won't receive feedback.

Getting Started​

Use the useHaptics hook in React components or the Haptics API directly for non-component code.

Haptics are disabled by default. Enable them globally during app initialization with setHapticsEnabled(true).

Built-in Support​

Several shared components now include haptic feedback automatically, including PrimaryButton, SecondaryButton, Key, QuickStakes, SportsbookBetButton, and Switch.

Why This Matters​

Haptic feedback is part of our Delightful Experiences initiative, creating more engaging, responsive interactions. It provides immediate physical confirmation of actions, making them feel more natural and satisfying—especially valuable for high-stakes moments like placing bets or completing transactions.

What It Does​

Whenever you open a PR, an automatic template is created for contributors to fill in with details about the scope of their work. This update adds a new informational section that highlights known issues in the CI pipeline and provides steps on how to address them.

Important Notes​

We're currently testing this approach in the PR template. If you think this information would be more effective elsewhere, let the maintainers know!

Why This Matters​

Some CI workflows fail intermittently on contributor PRs due to issues maintainers are actively investigating. The known issues section acts as a preventive measure, helping contributors stay focused on their work and quickly determine whether test, baseline, or workflow inconsistencies are related to their changes or to a pre-existing issue.

What Are Semantic Tokens?​

Semantic tokens are design tokens that carry meaning beyond their raw values. Instead of using a color like #1a73e8, you use a token like SmColoursBackgroundStaticNeutralBase that describes its purpose. This makes your code more readable and ensures consistent theming across your application.

Theming Made Simple​

The semantic tokens adapt automatically when you switch themes. Use the same token names across different themes, and they update their values to match the active theme. This means you write your styling code once and it works across all supported brands.

You can find the semantic tokens in the themes under the semantic directory.

How to Use Them​

React Native​

Import the tokens from the base theme or your specific theme:

import { Text, View } from "react-native";
import styles from "./MyComponent.styles";

const MyComponent = () => {
  return (
    <View style={styles.container}>
      <Text style={styles.text}>Hello, World!</Text>
    </View>
  );
};

import { StyleSheet } from "react-native";
import { tokens } from "@ppb/the-wall-common/base-theme";

export default StyleSheet.create({
  container: {
    backgroundColor: tokens.SmColoursBackgroundStaticNeutralBase,
  },
  text: {
    color: tokens.SmColoursTextStaticNeutralBase,
  },
});

Web​

Import the CSS file containing the token definitions and use them as CSS custom properties:

import styles from "./MyComponent.module.css";

const MyComponent = () => {
  return (
    <div className={styles.container}>
      <p className={styles.text}>Hello, World!</p>
    </div>
  );
};

@import url("@ppb/the-wall-design-tokens/generated/agnostic/semantic/web/agnostic.default.css");

.container {
  background-color: var(--sm-colours-background-static-neutral-base);
}

.text {
  color: var(--sm-colours-text-static-neutral-base);
}

Learn More​

Check out the full Semantic Tokens documentation for detailed usage examples and the complete list of available tokens.

What's Included​

The dashboard tracks three key areas:

Tokens​

• Total count — Number of unique tokens defined across brands/themes
• Not used — Tokens that aren't referenced in code (helping identify cleanup opportunities)
• Misalignment — Differences between Figma and code (should always be 0 with automated sync)
• Bundle size — Combined size of token CSS chunks

Components​

• Total count — Number of React components in the-wall-web
• Not used — Components not imported by consumer applications
• Misalignment — Differences between Figma and code (manual tracking for now)
• A11y issues — Components with accessibility issues from Storybook tests

Icons​

• Total count — Number of SVG icons available per brand
• Not used — Icons not referenced in consuming code
• Bundle size by brand — JS bundle size for lazy-loaded icon chunks (Betfair, SkyBet, PokerStars, Paddy Power)

Interactive Charts​

Each section includes:

• Trend sparklines — Quick visual of metric evolution
• Delta indicators — See changes compared to last measurement
• Detailed trend charts — Full historical view with multiple metrics overlaid

Automated Collection​

The metrics are now collected automatically via a shell script that:

1. Counts tokens and checks usage across codebases
2. Runs accessibility tests against the live Storybook
3. Builds brand apps to measure bundle sizes
4. Updates the dashboard JSON automatically

Run it yourself with:

cd packages/the-wall-metrics
yarn collect

Check It Out​

Visit the Metrics page to see the dashboard in action!

For implementation details, see:

• PR #4997 — Initial metrics page
• PR #5306 — Automated collection and charts

What It Does​

The @github-ui/storybook-addon-performance-panel provides real-time performance metrics for your stories:

• Render time — How long components take to render
• Re-render tracking — Identify unnecessary re-renders
• Performance warnings — Highlights components with concerning metrics

How to Use It​

The addon is automatically available in Storybook. Look for the "Performance" tab in the addon panel when viewing any story.

Important Notes​

• The addon was developed for @storybook/react-vite, while we use @storybook/react-webpack5. Some values might not be 100% accurate, but it still helps identify outliers during development.
• Storybook was updated to version 10.1+ to ensure compatibility with this addon.

Why This Matters​

Performance issues are often discovered late in development or in production. By surfacing metrics during component development, you can:

• Catch performance regressions early
• Identify components that might need optimisation
• Make informed decisions about component complexity

Links​

• Storybook Performance Panel Documentation
• PR #5030

After the future defining decision to adopt a "semantic-first" approach for the snowflakes, we now have a plan to migrate the snowflakes to use the new semantic tokens.

Stay tuned for more updates on this topic, as we will be sharing more details and timelines in the coming weeks. In the meantime, if you have any questions or want to learn more about semantic tokens and how they will impact the snowflakes, feel free to reach out to the design system team!

The Problem​

Contributors often had a hard time understanding:

• Will my changes trigger a package release?
• Which packages will be affected?
• What will the changelog entry look like?

This uncertainty made it difficult to write good commit messages and understand the impact of changes.

The Solution​

A new GitHub workflow now runs on all pull requests and posts a comment showing:

• Which packages will be released — See exactly which packages are affected
• What type of release — Features, fixes, or dependency updates
• The actual changelog entries — Preview the exact text that will appear in the CHANGELOG

Example Output​

# Changelog Preview

<details><summary>@ppb/the-wall-native</summary>

### 🚀 Features

- improve docs #NA (669db4417)

### 🧱 Updated Dependencies

- Updated @ppb/the-wall-design-tokens to 60.0.1
- Updated @ppb/the-wall-common to 47.1.6

</details>

How It Works​

The workflow:

1. Runs yarn release --dry-run to simulate a release
2. Parses the output to extract changelog entries
3. Posts a formatted comment on the PR

This gives you immediate feedback on your commit messages and helps ensure changelogs are meaningful.

For more details, see PR #4745.

The Problem​

When design tokens are updated, the generated files can contain thousands of lines of changes. Reviewing these files individually is time-consuming and makes it easy to miss important changes or potential breaking changes.

The Solution​

The new token analyser script automatically runs on PRs that modify tokens and generates a summary report with:

• Categorised changes — Changes are grouped by type (colors, sizing, spacing, borders, shadows, typography, opacity)
• Status indicators — Each token is marked as 🆕 created, ✏️ edited, or ⚠️ removed (potential breaking change)
• Before/after values — See exactly what changed for each token
• Brand/theme grouping — Changes are organised by brand and theme for easy navigation

Example Output​

The analysis appears as a comment on your PR:

## 🎨 Token Changes

Found **15** token change(s) across **3** theme(s)

### Betfair - Sports Dark

#### 🌈 Color Changes

| Token                        | Before | After     |
| ---------------------------- | ------ | --------- |
| 🆕 created `--new-token`     | _new_  | `#ff0000` |
| ✏️ edited `--existing-token` | `#000` | `#111`    |
| ⚠️ removed `--old-token`     | `#fff` | _removed_ |

Technical Details​

The analyser:

• Iterates over CSS files in the generated/ folder
• Parses git diffs to detect added, modified, and removed tokens
• Categorises tokens based on naming patterns
• Generates a markdown report posted as a PR comment

For more details, see PR #4552.

What's New in Storybook 10​

Storybook 10 introduces several improvements:

• Faster builds — Improved bundling and compilation times
• Better TypeScript support — Enhanced type inference for stories
• Modernized addons — Updated addon APIs and improved compatibility
• React 19 support — Full compatibility with the latest React version

Migration Highlights​

The migration was mostly automated using npx storybook@latest upgrade, with a few manual fixes for runtime errors.

Web Package Updates​

• Updated all @storybook/* packages to 10.x
• Simplified addon configuration in .storybook/main.ts
• Updated eslint-plugin-storybook for compatibility

Native Package Updates​

• Migrated to @storybook/react-native 10.x
• Updated Metro bundler configuration for the new withStorybook API
• Changed action imports from storybook/internal/actions to storybook/actions

Useful Links​

• Storybook 10 Migration Guide
• React Native Storybook Migration
• PR #4376

You can check out the updated tokens structure diagram and explore the new documentation page here.

With this new structure, we’re excited to say we’re better prepared for the future. Specifically, it now allows us to:

• Quickly add new brands and themes
• Easily incorporate new dimensions such as device type (mobile, desktop, watch) and orientation (left-to-right, right-to-left) when needed

Plus, we’ve reduced our tokens file size by 20%, shrinking it from 56,177 lines to 44,735 lines — making it leaner and more efficient.

How It Works​

Previously, syncing icons to Prismic required manually triggering a GitHub workflow. This was easy to forget and could lead to outdated icons in Prismic.

Now, the sync happens automatically:

1. A new version of @ppb/the-wall-icons is released
2. The release creates a Git tag (e.g., @ppb/the-wall-icons@9.1.0)
3. This tag triggers the Prismic sync workflow
4. Icons are automatically updated in Prismic

Benefits​

• No manual steps — Icons are always in sync with the latest release
• Reduced errors — No risk of forgetting to trigger the sync
• Faster updates — Changes are available in Prismic immediately after release

Technical Details​

The automation was implemented by adding a push trigger to the existing sync-prismic-icons.yml workflow that listens for tags matching @ppb/the-wall-icons@*.

For more details, see PR #1482.

To ensure that everyone interested had the opportunity to participate and learn, we organized in-person sessions over two days in three different locations. This decentralized approach aimed to bring teams closer together and provide an inclusive space for knowledge sharing and idea exchange.

The conference was not only an opportunity to provide clarification but also to strengthen collaboration among teams. Participants were able to ask questions in real time, explore use cases, and exchange ideas about future improvements. Through interactive activities and open discussions, we fostered a spirit of community and alignment.

What is a design system? ​

If you want to learn more about what a Design System is, how the Design System is structured for the Betfair, Sky Bet, and Paddy Power brands, and what we have planned for the future, check out this video. It’s a comprehensive guide that dives into the core principles, showcases how we ensure consistency across multiple brands, and highlights our vision for the future.

Slides

Components, Snowflakes & Recipes ​

If you want to learn more about what a component or a recipe is, or if you’ve heard the term "snowflakes" but have no idea what it means, this video is for you! It breaks down these concepts in an easy-to-understand way and helps you see how they fit into our design and development processes. Watch it to get up to speed!

Slides

How To Use A Design System Effectively ​

If you want to learn more about how to use the Design System, which libraries to use, how to contribute, and the process for collaborating with design, this video has you covered! It provides a detailed walkthrough of the tools, workflows, and best practices to help you make the most out of the Design System.

Slides

What Is A Multi Brand Design System? ​

If you want to learn more about what a multi-brand Design System is, how icons work across different brands, and our vision for the future of the Design System. It explores the unique challenges and solutions behind managing a Design System for multiple brands, explains the role of icons in ensuring consistency, and shares our exciting plans for the future.

Slides

What Product Owners Need to Know about DS ​

Whether you’re a seasoned Product Owner or new to the field, this session provides actionable insights to help you leverage design systems for maximum impact. If you’re particularly interested in the unique role Channels POs play, this video is tailored for you.

Slides

A Brief Intro To The Wall ​

If you're looking for an introduction to The Wall Design System, this video is the perfect starting point! It covers everything you need to know, including where to find documentation, how we approach accessibility, and an overview of the monorepo structure. Whether you're new to the system or just looking to dive deeper, this video will guide you through the essentials and help you navigate the resources effectively.

Slides

Create My First Component Part 1 ​

If you're interested in creating your first component, setting up your environment and learning about tokenization. It walks you through the step-by-step process of building a component from scratch, setting up your development environment, and understanding the importance of tokenization in maintaining design consistency. You'll also learn why and how to implement tokenization effectively in your projects and how the find tokens inside figma.

Slides

Create My First Component Part 2 ​

If you're looking to understand how and where to open a pull request, which workflow to follow, and how to handle pre-releases and releases. It provides a clear, step-by-step guide on how to open a pull request, what workflow to run during the process, and the best practices for creating pre-releases and managing final releases. linked to your file.

Slides

A Brief Intro to Abacus ​

In this session, we introduced the Abacus Design System, covering its core principles and how it helps maintain consistency across projects. We also explored how we use GitHub to manage the system effectively, along with an overview of the supported token types that power its flexibility and scalability.

Slides

Abacus Integration in Gaming Projects ​

In this session, we explored the tools used to work with our design system, how to deal with design updates and manage versions, and discussed how we manage versions effectively. We also covered using Abacus in gaming products, applying tokens to GFE components, and highlighted key challenges and pitfalls to avoid.

Slides

By the end of the sessions, the positive impact of this initiative was evident. Many questions were answered, and new insights emerged, reinforcing the importance of initiatives like this for the success of collaborative projects. As next steps, the Design System team plans to consolidate the contributions received and continue promoting more educational and inclusive events.

The conference was a significant milestone in spreading knowledge and fostering a more collaborative culture around the Design System. We are excited about what lies ahead and confident that, together, we can achieve even more!