Category: Coding

  • Scroll-Driven Animations in CSS: What UK Frontend Developers Need to Know Before Using Them in Production

    Scroll-Driven Animations in CSS: What UK Frontend Developers Need to Know Before Using Them in Production

    CSS scroll-driven animations have been the spec that frontend developers have been quietly excited about for a couple of years, and in 2026 the browser support picture has finally shifted enough that teams are seriously considering shipping them. I’ve been watching this one closely. The syntax is genuinely clever, the possibilities are real, and the performance story is mostly good. But “mostly” is doing a lot of work in that sentence, and there are enough edge cases around accessibility and progressive enhancement to make a careless implementation properly painful.

    Let me give you a clear-eyed look at what the spec actually does, where support stands for UK production audiences right now, and how to use it without breaking things for users who aren’t on Chrome 115+.

    Frontend developer writing CSS scroll-driven animations code at a modern studio desk
    Photo by Daniil Komov on Pexels

    What CSS scroll-driven animations actually do

    The traditional way to trigger an animation based on scroll position involved JavaScript: an IntersectionObserver, a requestAnimationFrame loop, or a library like GSAP’s ScrollTrigger. They work fine, but they run on the main thread, meaning scroll-linked visual effects can jank badly under load.

    The CSS Scroll-Driven Animations spec, now a W3C standard, handles scroll progress entirely off the main thread. It introduces two new animation timeline types: ScrollTimeline, which ties animation progress to a scroll container’s position, and ViewTimeline, which tracks when an element enters and exits the viewport. You wire these up using the animation-timeline property, and the browser compositor handles the rest. No JavaScript required for the animation itself, which means no main-thread blocking, no dropped frames from a busy event loop.

    A simple parallax header, a progress indicator at the top of a long article, a sticky navigation bar that transitions its opacity as you scroll, all of these become a handful of CSS declarations. For something like a reading progress bar, the code is almost insultingly short compared to the old approach. That’s genuinely exciting.

    Browser support in 2026: the honest picture

    According to Can I Use, CSS scroll-driven animations have strong support in Chromium-based browsers (Chrome, Edge, Opera, Samsung Internet) and are now shipping in Firefox 132+ without a flag. Safari is the sticking point. As of early 2026, Safari still lacks full support, sitting behind an experimental flag in the Technology Preview builds.

    For UK production audiences this matters. According to Statcounter’s UK browser data, Safari on iPhone accounts for roughly 26-28% of mobile sessions in the UK, driven by Apple’s continued dominance in the British smartphone market. That’s not a negligible fraction you can wave away with a comment in the pull request. Desktop Safari is a smaller concern but still double digits among professional audiences, particularly in creative and publishing sectors.

    My read: you can ship CSS scroll-driven animations in 2026, but you must treat them as a progressive enhancement, not a core experience requirement. If the animation’s absence degrades the page to something broken or confusing, that’s a design problem, not a browser support problem.

    Browser developer tools showing CSS scroll-driven animations properties in the animation panel
    Photo by Daniil Komov on Pexels

    How to write it safely with @supports

    The right pattern is to wrap any scroll-driven animation declarations in a feature query. @supports (animation-timeline: scroll()) returns true only in browsers that understand the property. Everything inside that block is ignored elsewhere. Your fallback state, meaning the non-animated version, should be the default, not an afterthought.

    This is the same approach we’ve needed for years with container queries (which, as I covered in the container queries piece from earlier this year, finally reached a point where teams could confidently adopt them). The pattern is identical: define the base experience for everyone, layer the enhancement for capable browsers.

    For the ViewTimeline use case specifically, think about what your element looks like when the animation hasn’t run. If a card fades in as it enters the viewport, it must start at full opacity in the fallback. An invisible card on Safari 17 is a content bug. Use animation-fill-mode: both carefully and always check the unsupported state manually.

    The performance case, and where it breaks down

    The off-main-thread execution story is real, but it has limits. Animating transform and opacity stays on the compositor and is fast. Animating layout-triggering properties like width, height, margin, or top forces reflow even in a scroll-driven context. The spec doesn’t magically make expensive properties cheap.

    I’d also flag that tying many simultaneous animations to a single scroll container can still produce jank on lower-powered devices, particularly mid-range Android handsets. UK audiences skew more Android than many assume outside London; roughly 45% of UK mobile users are on Android according to Statcounter. Test on real mid-range hardware, not just a MacBook’s device emulator.

    If your scroll-driven animation scenario is complex, it’s worth benchmarking against a well-optimised JavaScript approach. GSAP’s ScrollTrigger with will-change hints can still outperform a naive CSS implementation on cluttered pages. CSS scroll-driven animations win most of the time, but “most” again is doing work. For teams at agencies managing campaigns across multiple channels, where page performance is one piece of a larger conversion puzzle, vendors like dijitul Marketing will tell you that Core Web Vitals scores and visual flair need to coexist, not compete. A showy parallax effect that tanks your LCP score is a bad trade.

    On the topic of performance and production readiness, I’d point you to the data in the UK Core Web Vitals piece we published earlier this year. The numbers there give useful context for how much headroom UK sites typically have before scroll-linked visual effects start eating into real performance budgets.

    Accessibility: the part most tutorials skip

    This is where I see the most careless implementations. The prefers-reduced-motion media query must wrap or override your scroll-driven animation declarations. Users who’ve opted into reduced motion in their OS settings have done so for a reason, often vestibular disorders or photosensitive conditions. Scroll-linked parallax effects are particularly disorienting for this group because the animation is continuous and tied directly to user input.

    The correct pattern is either to remove the animation entirely under prefers-reduced-motion: reduce, or to substitute a fade (which is generally tolerable) for a large position-based movement. Do not just slow the animation down; that’s not what the user asked for.

    There’s also a focus management concern if you’re using ViewTimeline to reveal content. If keyboard users tab into content that’s currently in a visually hidden state (opacity 0, or translated off-screen by an animation that hasn’t triggered yet), you have an invisible focus trap. This is fixable with visibility: hidden toggled alongside the opacity, but it requires deliberate thought rather than a copy-pasted animation snippet.

    For anyone building design systems with motion at their core, the work I covered on building a design token pipeline with Style Dictionary applies here too. Motion tokens, durations, easing curves, and reduced-motion overrides can all live in your token system, making consistent and accessible animation much easier to maintain at scale.

    Practical uses worth shipping right now

    Given everything above, where does it make sense to actually use CSS scroll-driven animations today? Reading progress indicators are a no-brainer: they’re purely decorative, invisible absence is harmless, and the CSS is six lines. Sticky header opacity transitions work well. Subtle scale or fade effects on section headers as they enter the viewport add polish with minimal risk, provided the @supports and prefers-reduced-motion guards are in place.

    Avoid: scroll-driven animations that carry meaning (i.e., the animation isn’t decorative but reveals content), complex parallax layers with multiple competing timelines, or anything that requires pixel-perfect timing across browsers, because the Safari gap makes that unreliable for now.

    The spec is solid. The implementation is getting there. Ship it as an enhancement, test it properly, guard it correctly, and it genuinely improves the feel of a page without the JavaScript overhead we’ve been living with for years.

  • Tailwind CSS v4 in Production: What UK Development Teams Actually Found After Six Months

    Tailwind CSS v4 in Production: What UK Development Teams Actually Found After Six Months

    Tailwind CSS v4 landed with a proper bang. The CSS-first configuration model, the new high-performance Rust-based engine (Oxide), the slimmed-down setup story, on paper it looked like the framework had finally grown up. I’ve been watching UK development teams field this across client work and internal product builds for the better part of six months now, and the picture is more textured than the release notes let on. Some of it is genuinely impressive. Some of it will catch you off guard on a deadline.

    Developer working on Tailwind CSS v4 in production at a modern UK office desk
    Photo by Daniil Komov on Pexels

    What CSS-first configuration actually means in practice

    The biggest philosophical shift in Tailwind CSS v4 in production is the move away from tailwind.config.js. Your design tokens, your theme extensions, your custom utilities, all of it now lives in a @theme block inside a CSS file. That’s a meaningful change, and for teams that already think in terms of design tokens, it clicks immediately.

    In practice, I’ve seen two camps. Teams who had already invested in a structured token system (think semantic colour layers, spacing scales, type ramps) found the migration almost pleasant. The CSS custom properties that Oxide generates map directly onto what those teams already had in their heads. For them, the config file was always a slightly awkward intermediary, and removing it felt like cutting out a middleman.

    The other camp, and this is most teams, if I’m honest, had their Tailwind config as a sprawling JavaScript object full of one-off values and plugin hacks accumulated across two or three years of client work. For them, the migration was a proper archaeology project. Not impossible, but not the afternoon job some blog posts implied. If your team is in that position, I’d strongly suggest reading up on building a proper design token pipeline with Style Dictionary before you try to port your config, it’ll save you repeating the same sins in a new format.

    The Oxide engine: where the performance wins are real

    Oxide is fast. That’s not marketing. A Tailwind v3 full build on a medium-complexity Next.js project I looked at was sitting around 1.8 seconds on a reasonably modern MacBook Pro. The same project with v4 and Oxide dropped to under 200 milliseconds. Incremental rebuilds in watch mode feel instantaneous, we’re talking sub-20ms on most saves.

    For developer experience on UK agency projects where you’re sometimes running three or four services locally, that matters. The CPU headroom you get back is real. It’s the kind of change that makes you wonder why the JS ecosystem took so long to reach for Rust tooling, but here we are.

    Code editor showing Tailwind CSS v4 theme configuration in a dark theme environment
    Photo by Stanislav Kondratiev on Pexels

    The output CSS story is also much cleaner. v4 generates far less bloat because the engine has a better understanding of which utilities are actually reachable from your source. On one SaaS dashboard project, the production CSS bundle dropped from 28kB (gzipped) to around 11kB without any additional purging configuration. That has a measurable knock-on effect on Core Web Vitals scores, particularly LCP on slower mobile connections, something UK teams building for diverse audiences across patchy 4G coverage genuinely need to care about.

    Where the workflow still has rough edges

    Right. Here’s the honest part that fewer people are writing about.

    The IntelliSense extension for VS Code is not fully caught up. As of early 2026, autocomplete for custom theme values defined in @theme blocks is inconsistent. You get suggestions for core utilities reliably, but your own spacing tokens or custom colour ramps? Hit or miss depending on how you’ve structured the CSS file. For teams where designers and developers share the same editor setup, this creates friction. Not a dealbreaker, but annoying enough that I’ve seen junior devs quietly reach for inline styles when autocomplete fails them, which rather defeats the point.

    Plugin compatibility is another honest headache. The v3 plugin API is gone. Anything you were pulling in that depended on plugin() or addUtilities() from the old API needs a rewrite or a replacement. Community plugins like @tailwindcss/typography and @tailwindcss/forms have official v4 versions now, but third-party ecosystem plugins are patchy. If your project has bespoke plugins for client-specific utility classes, budget time for a proper rewrite.

    The @apply directive also behaves differently, specifically, it no longer works across component boundaries in certain CSS module setups. This caught several teams using CSS Modules alongside Tailwind for scoped component styles. The workaround exists (using CSS layers manually), but it’s not well documented and you’ll likely find it through Stack Overflow at 11pm rather than through the official docs.

    Real decisions teams are making about adoption

    From what I’ve seen across a handful of UK agencies and product teams, the pragmatic decision looks like this: new projects should start on v4 from day one. The clean-slate experience is good, the performance is genuinely better, and the CSS-first approach encourages better token discipline. The solo developers shipping Micro-SaaS products I’ve spoken to have taken to it particularly well, because they’re not dragging legacy config debt along with them.

    Existing projects are a different calculation. If your v3 codebase is large, has custom plugins, and is actively generating revenue, the migration cost needs to sit in a proper sprint. Not a Friday afternoon. One London-based product team I’m aware of spent three weeks migrating a mid-sized B2B SaaS product, and they found bugs in their own component library that had been masked by v3’s slightly more permissive utility generation. So there’s an accidental quality benefit too, if you’re patient enough to find it.

    For teams doing client delivery work where the project switches between Tailwind versions depending on the client’s stack, the cognitive overhead is real but manageable. The mental model for both versions is similar enough that context-switching is fine once you’ve internalised where your theme configuration now lives.

    One thing that doesn’t get discussed enough: Tailwind v4’s cascade layer architecture makes it much more composable with existing CSS from third-party libraries or design systems. Teams integrating component libraries alongside Tailwind (say, Radix UI primitives with custom Tailwind-based styling) are finding fewer specificity conflicts. That’s a structural improvement that compounds over the lifetime of a project.

    A note on tooling integrations and the broader stack

    Tailwind v4 ships with first-class Vite integration, and if you’re on a Vite-based stack it’s probably the smoothest setup experience the framework has ever had. The Webpack integration exists but feels like a second-class citizen, which, given where the tooling ecosystem is heading, is probably fine. The GOV.UK style guidance aside, there’s no regulatory reason UK teams need to be on Webpack, but plenty of enterprise codebases still are, and those teams will need to factor that into their timeline.

    For teams building on Next.js App Router, v4 works well but requires some care around server component boundaries and how styles are emitted. It’s not a blocker, but the Tailwind docs are still catching up to the App Router mental model. A few developers I know have ended up cross-referencing framework-specific community threads alongside the official docs to get the setup exactly right.

    On the subject of integrations: if your team works with a wider development partner for backend and API work, you’re generally fine, Tailwind’s output is just CSS, so any backend stack is unaffected. Dijitul Developments is a good example of a UK shop building tight business logic integrations where the frontend stack is genuinely irrelevant to what they’re doing on the server side, which is worth remembering when scoping projects with mixed frontend and backend concerns.

    The honest summary: Tailwind CSS v4 in production is a meaningful upgrade, not a cosmetic one. The performance gains are real, the CSS-first approach is architecturally sound, and the rough edges are all fixable with a bit of patience. Just don’t expect a frictionless migration if you’ve been on v3 for years. Plan properly, audit your plugins first, and start your next greenfield project on v4 from line one.

    Frequently Asked Questions

    Is Tailwind CSS v4 backwards compatible with v3 projects?

    Not directly. Tailwind v4 introduces a new CSS-first configuration model and a rewritten plugin API that breaks compatibility with v3 config files and third-party plugins built on the old API. Migrating an existing v3 project requires manually porting your theme configuration into a @theme CSS block and rewriting or replacing any custom plugins.

    How much faster is Tailwind CSS v4's build compared to v3?

    The Oxide engine (Rust-based) makes full builds roughly 5-10x faster in typical projects, with incremental rebuilds in watch mode often dropping to under 20 milliseconds. Real-world results vary with project size, but the improvement is substantial enough to notice immediately during development.

    Does Tailwind CSS v4 work with Next.js App Router?

    Yes, but it requires some configuration care around server component boundaries and CSS emission. The Vite integration is the most polished path; if you’re on Next.js with Webpack, expect a slightly rougher setup experience until tooling documentation catches up.

    What happens to @apply in Tailwind CSS v4?

    @apply still works in v4, but it behaves differently in certain CSS Module setups, specifically, it can fail across component boundaries. Teams using CSS Modules alongside Tailwind for scoped component styles should test this early and be prepared to use manual CSS layer declarations as a workaround.

    Should new UK projects start with Tailwind CSS v4 or stick with v3?

    For new projects, v4 is the right choice: better performance, smaller output CSS, and a cleaner configuration model that encourages proper token discipline from the start. For existing v3 projects actively in production, migration is worthwhile but should be planned as a dedicated sprint rather than a quick upgrade.

  • Building a Design Token Pipeline With Style Dictionary: A UK Agency’s Practical Walkthrough

    Building a Design Token Pipeline With Style Dictionary: A UK Agency’s Practical Walkthrough

    Managing brand tokens across six client accounts simultaneously is, to put it plainly, a nightmare without the right tooling. Colours drift between Figma files and code, spacing scales get hard-coded into components by a developer who never saw the original spec, and then a rebrand lands and you’re hunting through three separate codebases trying to find every instance of #1A73E8. I’ve been there. Most UK agency frontend teams have. The fix, as of 2026, is a properly configured Style Dictionary pipeline, and this walkthrough covers exactly how to set one up in a way that actually survives contact with real client work.

    Developer building a Style Dictionary design token pipeline at a dual-monitor desk setup
    Photo by Daniil Komov on Pexels

    What Style Dictionary actually is (and why it’s not just a JSON file)

    Style Dictionary, built by Amazon and maintained as an open-source project, is a build system that takes your design tokens, defined as structured JSON or JavaScript objects, and transforms them into whatever output format a given platform needs. That means CSS custom properties for your web builds, Swift variables for an iOS team, XML for Android, Sass maps if your project is still on that, and so on. All from a single source of truth.

    The critical word there is transform. Style Dictionary’s real power isn’t storage, it’s the transform pipeline. You define what your tokens mean at an abstract level, then the tool handles the mechanical conversion to whatever format a developer, app team, or platform actually consumes. For a UK agency juggling, say, a fintech rebrand alongside a heritage retail brand and a B2B SaaS product, this is the difference between a design system that scales and one that quietly collapses under the weight of one-off overrides.

    Structuring your token files for multi-client agency work

    The folder structure is where most teams go wrong out of the gate. The temptation is one flat JSON file per client. Resist that.

    A structure I’ve settled on, after several iterations across agency projects, looks like this:

    tokens/
      global/
        color.json
        spacing.json
        typography.json
      clients/
        acme-corp/
          color.json
          brand.json
        northfield-retail/
          color.json
          brand.json
    config.js

    The global layer holds your primitive tokens, raw values like blue-500: #2563EB or space-4: 16px, that have no semantic meaning yet. Client folders hold semantic tokens that reference those primitives: color.brand.primary: {value: "{color.blue-500}"}. This layering means that when Acme Corp decides their primary colour is now teal, you change one line in one file. Nothing downstream breaks unless you want it to.

    Style Dictionary’s reference syntax, the curly-brace notation, handles that aliasing natively. It resolves chains of references, so button.background can point to color.brand.primary which points to color.blue-500, and the final build output will resolve all the way down to the hex value. Tidy.

    Screen showing a Style Dictionary design token colour system with semantic naming
    Photo by cottonbro studio on Pexels

    Configuring the build for Figma handoff and CSS output

    The config.js file is where you wire everything together. Here’s a stripped-down but real example for a web-first client project:

    module.exports = {
      source: [
        'tokens/global/**/*.json',
        'tokens/clients/acme-corp/**/*.json'
      ],
      platforms: {
        css: {
          transformGroup: 'css',
          prefix: 'acme',
          buildPath: 'dist/acme-corp/',
          files: [{
            destination: 'tokens.css',
            format: 'css/variables'
          }]
        }
      }
    };

    Running style-dictionary build against this spits out a CSS file full of custom properties prefixed with --acme-, which you then import into your component library or bundle. Dead simple on the surface, but that prefix is crucial in an agency context because you can import multiple clients’ token files in a demo or shared environment without collisions.

    For Figma specifically, the handoff story has improved considerably in 2026. The Figma Tokens plugin and its successor integrations can read from a GitHub-hosted JSON file, meaning your single source of truth in the repo stays synchronised with what designers see in Figma. When a designer updates a spacing value in Figma’s token panel, a pull request is opened. When a developer merges it, the CSS rebuild runs. That’s the loop you want. I’d strongly recommend reading up on the current state of Figma’s Dev Mode before setting this up, because how your tokens surface in Dev Mode inspects has changed meaningfully this year.

    Custom transforms for UK-specific needs

    Out of the box, Style Dictionary’s CSS transform group handles most scenarios. But UK agency work throws up a few edge cases worth building custom transforms for.

    Fluid typography is a common one. If you’re using clamp() values for your type scale (which you should be, if you aren’t already), you’ll want those as computed strings rather than raw pixel values. You can register a custom transform that takes a min, max, and viewport range from a token’s attributes and outputs a proper clamp() string. Something like:

    StyleDictionary.registerTransform({
      name: 'size/fluid',
      type: 'value',
      matcher: token => token.attributes.fluid,
      transformer: token => {
        const { min, max, minVw, maxVw } = token.original.attributes;
        return `clamp(${min}px, calc(${min}px + (${max - min}) * ((100vw - ${minVw}px) / (${maxVw - minVw}))), ${max}px)`;
      }
    });

    That’s one registration, and every fluid type token across every client build uses it consistently. This kind of thing compounds nicely, especially once you have four or five custom transforms covering your agency’s standard patterns.

    Colour token naming is another area where getting the structure right early pays off enormously. If you’ve read our piece on colour token naming and contrast grids, you’ll know the semantic layer matters more than the primitive layer for day-to-day developer use. Style Dictionary makes enforcing that semantic naming convention in your JSON schema straightforward, because the dot-notation in your token paths maps directly to CSS custom property names.

    Running this across multiple clients without losing your mind

    The multi-client setup needs a build script, not just a single Style Dictionary config. I use a small Node script that iterates over a clients/ directory, dynamically generates a config for each client by merging global tokens with client-specific overrides, and runs a build. The output is a dist/ folder with one subdirectory per client, each containing their own token CSS file, ready to be consumed by whatever frontend stack that project runs on.

    This scales. I’ve run this against eight simultaneous client configs in under four seconds on a modest laptop. For a UK agency doing quarterly brand refreshes and annual rebrands, that turnaround matters.

    Version control is non-negotiable here. Every token change goes through Git, with a meaningful commit message, so you have a full audit trail of when a colour changed and why. This is useful not just for debugging but for client conversations: “your brand primary changed on 14 March, here’s the commit.” Clients, especially those in regulated industries, appreciate that level of traceability.

    For a sense of the broader landscape that UK product teams are operating in, the government accessibility requirements for websites and apps are worth keeping in your peripheral vision, particularly when your token system needs to account for WCAG contrast compliance across multiple brand palettes.

    Connecting your token system to the wider product workflow

    A token pipeline doesn’t live in isolation. It touches your component library, your Storybook instance, your CI build, and your Figma workflow. Getting those connections right is as important as the Style Dictionary config itself.

    One pattern I’ve seen work well at UK agencies is hooking the Style Dictionary build into a GitHub Action that fires on any change to the tokens/ directory. The action builds the tokens, commits the updated CSS to a dist branch, and optionally publishes to npm if the component library consumes tokens as a package. The whole thing runs in under thirty seconds. Developers get updated tokens without touching the config themselves, and designers don’t need to manually sync anything.

    If your agency also runs paid media for clients alongside the design work, the same discipline around structured, auditable systems applies. Agencies like dijitul Marketing bring that kind of systematic rigour to campaign management, which is a useful parallel: structured inputs, predictable outputs, traceable decisions.

    The token system also connects naturally to your test data story. If you’re prototyping UI states with realistic data, as covered in our walkthrough on using Faker.js and seed scripts to replace lorem ipsum, having your design tokens already resolved means your component demos use real brand colours and spacing, not placeholder guesses. The whole system starts to feel coherent rather than cobbled together.

    The things that will still trip you up

    A few honest gotchas, because no walkthrough should pretend this is frictionless.

    First, circular references. If token A references token B which references token A, Style Dictionary will throw an error at build time. That’s the right behaviour, but it means you need to be disciplined about your token graph. Primitives never reference semantics. Semantics reference primitives. Components reference semantics. One direction only.

    Second, token naming conventions need team buy-in. If one designer names something color.ui.button.primary and another names it button.primary.color, your JSON will become incoherent fast. Document your naming convention in your repo’s README on day one. Enforce it in code review.

    Third, the Figma plugin ecosystem for token sync is still more fragmented than it should be in 2026. Test your chosen plugin against a real client file before committing to it as your agency standard. Some plugins handle nested token groups cleanly; others flatten everything and lose the hierarchy that Style Dictionary depends on.

    None of these are deal-breakers. They’re friction points that good setup decisions eliminate early. Get the folder structure right, document the naming convention, and the pipeline genuinely does become the boring, reliable infrastructure it should be.

    Frequently Asked Questions

    What is Style Dictionary and how does it work with design tokens?

    Style Dictionary is an open-source build system that takes design tokens defined as JSON and transforms them into platform-specific outputs, such as CSS custom properties, Swift variables, or Sass maps. You define tokens once and the tool handles the conversion, meaning one source of truth serves every platform your product ships on.

    How do I manage multiple client brand systems with a single Style Dictionary setup?

    The recommended approach is a layered folder structure: a global layer for primitive tokens (raw colour values, spacing scales) and per-client folders for semantic tokens that reference those primitives. A build script iterates over client directories and generates a separate token output for each, so there’s no collision between brand systems.

    Can Style Dictionary output tokens that Figma can read?

    Yes. Style Dictionary’s JSON output can be consumed by Figma token plugins, with several integrations supporting a GitHub-hosted JSON file as the sync source. When a designer updates a token in Figma, the change opens a pull request; when merged, the Style Dictionary build runs and updates the CSS. It’s not entirely frictionless yet, but it works reliably for most agency setups.

  • Edge Functions for Frontend Designers: What Cloudflare Workers and Vercel Edge Actually Mean for UK Web Performance

    Edge Functions for Frontend Designers: What Cloudflare Workers and Vercel Edge Actually Mean for UK Web Performance

    Edge computing sounds like something a backend engineer should explain to you whilst you nod politely and think about font weights. I get it. The infrastructure layer has historically been not-your-problem, and for a long time that was fine. But edge functions have crossed a line. They are now genuinely useful to frontend designers and developers in ways that directly affect the things you spend your days obsessing over: page speed, personalisation, A/B testing, and whether your LCP score makes you want to cry.

    This is my attempt to explain edge functions as a frontend concern, not an ops concern, with real-world patterns UK teams are actually shipping in 2026.

    Frontend developer writing edge functions for performance improvements on a dark-themed code editor
    Photo by Daniil Komov on Pexels

    What edge functions actually are (without the waffle)

    A traditional web request goes: user’s browser, CDN cache, your origin server somewhere in a data centre. The origin might be in London if you’re lucky, Dublin if you’re using AWS eu-west-1, or somewhere entirely unhelpful if you never thought about it. Every uncached request hits that server, adds latency, and makes your Time to First Byte worse.

    Edge functions run code at CDN nodes, physically close to the user. Cloudflare has over 300 data centre locations globally. Vercel’s edge network is similar in concept. When a request comes in, instead of bouncing all the way to your origin, a small piece of JavaScript (or TypeScript) runs at the nearest node and returns a response. We’re talking single-digit millisecond execution in many cases.

    The key constraint worth knowing: edge functions are not Node.js. They run in a V8 isolate environment, which means no file system access, limited APIs, and very short execution windows. That constraint is actually what makes them useful for the frontend layer, because it forces you to keep edge logic small and sharp.

    Why this matters for edge functions frontend performance UK specifically

    UK users suffer more latency than they should from services hosted without European region configuration. If your Next.js app’s API routes are running serverless functions in us-east-1 because nobody changed the default, every dynamic request is crossing the Atlantic. Vercel’s edge runtime and Cloudflare Workers both put execution closer to the UK, and the difference in TTFB can be 200-400ms on uncached requests. That is not trivial when UK Core Web Vitals data shows that LCP and INP failures correlate directly with conversion drops on British e-commerce and SaaS sites.

    The Cloudflare network has a major presence in London (Docklands), Manchester, and Edinburgh. Vercel routes UK traffic through Frankfurt and Amsterdam primarily, with London capacity added in 2024. Either way, you are getting dramatically closer to your users than a single-region origin server.

    Three concrete things you can do with edge functions without a backend engineer

    1. Personalisation without client-side flicker

    The standard approach to personalisation in a React or Next.js app is: render the generic page, load JavaScript, check a cookie or API call, then swap in the personalised content. Users see a flash of the wrong content. It is grim, and it tanks your LCP because the meaningful content arrives late.

    Edge functions fix this by reading cookies and headers before the HTML is assembled. A Vercel Edge Middleware file (literally middleware.ts in your project root) can inspect the incoming request, check a user segment cookie, and rewrite the URL to a different version of the page before the browser sees anything. The user gets personalised HTML on the first response. No flicker, no extra round trip, no bespoke backend logic required.

    A practical example: a UK SaaS product serving both SME and enterprise tiers can serve entirely different homepage layouts based on a cookie set at signup, handled entirely in around 20 lines of TypeScript at the edge. No server, no database call, no delay.

    2. A/B testing that doesn’t torch your Core Web Vitals

    Client-side A/B testing with tools like Google Optimize (now retired) or its replacements typically inject test logic after the page loads. The result is layout shift, delayed LCP, and Cumulative Layout Shift scores that your performance audit will flag immediately. Edge-based A/B testing sidesteps this entirely.

    The pattern is straightforward. Your edge function generates or reads a test bucket (usually a random assignment stored in a cookie), then serves bucket A or bucket B of your HTML before the response leaves the CDN. From the browser’s perspective, there is only ever one version of the page. The Cloudflare Workers documentation has solid examples of this pattern using the HTMLRewriter API, which lets you modify HTML at the edge without reconstructing the entire response.

    I’ve used this pattern on a Next.js project for a UK fintech startup. We ran a button colour test (yes, really, the client insisted) across 50,000 monthly visitors without touching the origin deployment or writing a single line of backend code. The Lighthouse scores stayed identical between variants because the HTML was identical in structure, just different in content.

    3. Geolocation-based content without a postcode lookup API

    Cloudflare Workers and Vercel Edge both expose request geolocation headers automatically. cf-ipcountry in Cloudflare, and x-vercel-ip-country and x-vercel-ip-city in Vercel. You can use these to show UK-specific pricing (£ GBP, VAT-inclusive), route Scottish users to Scottish Gaelic content variants, or surface region-relevant promotions, all without a database call or a paid IP geolocation API.

    This is particularly useful for UK e-commerce sites that need to show duty-included pricing to GB users whilst showing export pricing to EU visitors post-Brexit. Handling that at the edge means the correct price is in the HTML from the first byte. No price flicker, no client-side currency swap, no additional JavaScript bundle weight.

    The Vercel vs Cloudflare choice for UK frontend teams

    If you are already deploying on Vercel, the edge runtime is the path of least resistance. Your middleware.ts file is just part of the project, it deploys automatically, and the routing primitives are well-documented. The limitation is that Vercel’s edge functions are tightly coupled to their platform, so you are buying into that ecosystem.

    Cloudflare Workers are more portable and more powerful. You can run them in front of any origin, including a Vercel deployment, which is a combination I have seen UK agencies use to get the best of both. Workers also have access to Cloudflare’s KV store (a globally replicated key-value database) and Durable Objects for stateful logic, which opens up patterns that Vercel middleware simply cannot do.

    For a solo developer or small UK agency, Vercel’s free tier is generous enough for most projects. Cloudflare Workers’ free tier gives you 100,000 requests per day, which is reasonable for prototyping. The paid tiers for both are reasonable once you are shipping something with real traffic.

    What edge functions cannot do (and why you still need some backend)

    Edge functions are stateless and fast, which means they are the wrong tool for heavy computation, database writes, large payload processing, or anything requiring persistent connections. You still need an actual backend (or a serverless function in a proper runtime) for those things. The edge layer is the routing and transformation layer, not the application logic layer.

    I’d also point out that cold start times, whilst dramatically better than traditional serverless functions, are not zero. Vercel’s edge functions typically have sub-1ms cold starts. Cloudflare Workers are similar. But if your logic becomes complex enough, you will want to profile it. The edge environment rewards small, focused functions.

    One thing this connects to for design teams: if you are building a Micro-SaaS product as a solo developer and you have been putting off personalisation because it felt like infrastructure work, edge middleware genuinely removes that blocker. You do not need a dedicated backend engineer to implement sensible routing logic in 2026.

    Getting started without breaking anything

    My recommendation: start with a read-only middleware. Something that inspects a cookie or a header and adds it to a request header for downstream consumption. This is zero-risk, teaches you the API surface, and gives you something to show in a pull request. Once that is merged and boring, move to URL rewrites. Then cookie setting. Then A/B bucket assignment. Each step is independently reversible.

    The Vercel middleware documentation is genuinely good. The Cloudflare Workers quick-start is also excellent, and the playground at workers.cloudflare.com lets you write and test Workers in the browser with live request inspection. Both platforms have strong TypeScript support, which matters if you are working on a codebase where designer-developer handoff is already type-driven.

    Edge functions are not magic, but they are one of the more genuinely useful infrastructure concepts to land in the frontend toolkit in the last few years. The performance gains are real, the personalisation patterns are practical, and the barrier to entry is low enough that a frontend developer comfortable with TypeScript can be productive within an afternoon. That is a rare combination in infrastructure land.

  • The Case for Designing With Real Data From the Start: How UK Product Teams Are Using Faker.js and Seed Scripts to Kill Lorem Ipsum

    The Case for Designing With Real Data From the Start: How UK Product Teams Are Using Faker.js and Seed Scripts to Kill Lorem Ipsum

    There is a specific kind of design review horror that every UK product designer eventually experiences. The prototype looks immaculate. The components are tight, the spacing is perfect, and the typography sings. Then someone asks: “What happens when the user’s surname is Featherstonehaugh?” Or: “Our biggest client has a 47-character company name.” The room goes quiet. The designer opens Figma and starts dragging a text box wider. The dream is over.

    That scenario is almost entirely caused by one bad habit: designing with placeholder content. Lorem ipsum is comfortable. It fills space without asking difficult questions. But it lies to everyone in the room, and I’d argue it’s one of the most underrated sources of production bugs and last-minute design rework in UK product teams today. Replacing it with realistic test data UI design UK practice isn’t a nice-to-have; it’s a discipline that changes the quality of every design review you run.

    Product designer reviewing realistic test data UI design UK dashboard on a large monitor
    Photo by SHVETS production on Pexels

    Why lorem ipsum is a design smell

    Placeholder text masks problems that only emerge with real content. A navigation label that reads “Lorem” fits neatly. “Accessibility Settings” might not. A dashboard card with “Lorem ipsum dolor” as the description looks fine at 16px. “You have 3 outstanding invoices totalling £4,280.00 (VAT inclusive)” at the same size might wrap awkwardly, break a flex container, or push a CTA button off-screen entirely.

    These aren’t edge cases. They’re the norm for UK products that serve real British users with British addresses, postcodes, phone numbers, and names drawn from an extraordinarily varied pool. The Office for National Statistics publishes population data that illustrates just how linguistically diverse the UK is. If your app serves the public, your test data needs to reflect that diversity or you’ll ship interfaces that break on perfectly normal inputs.

    The fix isn’t complicated, but it does require a shift in how teams think about the design-to-development handoff. And Faker.js with the en_GB locale is the cleanest place to start.

    What Faker.js en_GB actually gives you

    Faker.js is a widely used JavaScript library for generating synthetic but structurally accurate fake data. The en_GB locale setting is the part most UK teams skip, and it matters enormously. Without it, you get American-formatted phone numbers, US-style zip codes, and first names weighted heavily towards an American demographic distribution. With en_GB, you get UK mobile numbers in the 07xxx xxxxxx format, British postcodes like SW1A 1AA or M1 1AE, and names that actually reflect the British population: Priya, Mohammed, Cillian, Aoife alongside James, Sarah, and David.

    Here’s the kind of seed script I’d use to generate a realistic dataset for a UK SaaS dashboard review:

    import { faker } from '@faker-js/faker/locale/en_GB';
    
    const generateUser = () => ({
      id: faker.string.uuid(),
      name: `${faker.person.firstName()} ${faker.person.lastName()}`,
      email: faker.internet.email(),
      phone: faker.phone.number(),
      postcode: faker.location.zipCode(),
      company: faker.company.name(),
      plan: faker.helpers.arrayElement(['Starter', 'Growth', 'Enterprise']),
      invoiceTotal: faker.finance.amount({ min: 50, max: 12000, dec: 2, symbol: '£' }),
      joinedAt: faker.date.past({ years: 3 }).toLocaleDateString('en-GB'),
    });
    
    const users = Array.from({ length: 50 }, generateUser);
    console.log(JSON.stringify(users, null, 2));

    Run that once and you have 50 structurally honest user records. Drop them into your design tool via a JSON plugin, or pipe them into a Storybook story, and suddenly your design review is testing something real.

    How realistic data changes design reviews

    I’ve sat in enough design crits to know that lorem ipsum reviews have a particular rhythm: everyone nods at the aesthetics and nobody catches the layout bugs. Swap in real data and the conversation changes completely. People start asking the right questions immediately.

    Long company names break table rows. Very short names (“Jo”, “Ed”) create awkward avatar initials. Financial figures with varying digit counts expose alignment issues in data tables. British postcodes have variable lengths (“E1 6RF” versus “SW1A 2AA”) that will absolutely break a fixed-width input if nobody tested it. Dates formatted as en-GB (“21 April 2026”) behave differently from ISO strings in ways that affect column widths.

    This connects directly to a broader problem I’ve written about with British SaaS dashboards failing at data visualisation: the visual layer only tells you something useful if the data underneath it is honest. A chart seeded with placeholder values of similar magnitude will look balanced. Real financial data with outliers will expose whether your Y-axis scaling is any good.

    Integrating seed scripts into the design workflow

    The practical question is where this data actually lives in a team’s process. There are a few patterns worth knowing.

    Figma + JSON plugins: Tools like Figma’s own “Content Reel” or the “JSON to Figma” community plugin let you paste a JSON array and populate component instances automatically. Generate your Faker data, export it, load it in. Takes about three minutes once the script exists.

    Storybook stories with seeded data: For component-level work, writing Storybook stories that import from a shared seed script is even more powerful. Every developer on the team sees the same realistic data when they open the component browser. If you’re doing any work that touches solo micro-SaaS UI development, this is a genuinely weekend-implementable improvement to your workflow.

    Shared seed fixtures in the repo: The most mature version of this is a /fixtures directory in the codebase with a set of deterministic seed scripts (using a fixed random seed so the data is reproducible). Designers reference the same fixture files that QA engineers use. Suddenly “the data in the mockup” and “the data in the test environment” are the same thing, which eliminates an entire category of “it looked fine in Figma” conversations.

    The locale details that actually matter for UK products

    Beyond names and postcodes, there are some locale-specific data patterns that UK products get wrong constantly:

    Phone numbers: UK mobiles start with 07. UK landlines vary by region: 020 for London, 0161 for Manchester, 0131 for Edinburgh. If your input field only fits 11 digits with no space formatting, you need to know that before you ship.

    VAT numbers: UK VAT registration numbers follow the format GB followed by 9 digits. Faker’s en_GB locale doesn’t generate these natively, but a simple custom helper wrapping faker.string.numeric(9) with the GB prefix gets you there.

    Bank sort codes and account numbers: The UK uses 6-digit sort codes (formatted as XX-XX-XX) and 8-digit account numbers. Again, Faker doesn’t generate these by default, but they’re trivial to construct and essential if you’re building any fintech-adjacent interface.

    Names with apostrophes and hyphens: O’Brien, Al-Hassan, Lloyd-Jones. If your database schema or your UI component hasn’t been tested with these, it probably breaks somewhere. Seed your data with a handful of deliberately awkward names and find out before a real user does.

    All of this feeds into why teams doing genuinely differentiated UK B2B SaaS product design tend to have stronger QA cultures too. The design and development disciplines start to blur productively when the artefacts they work with share the same data reality.

    A note on edge cases as first-class design concerns

    One thing I’d push back on is the framing of long names or unusual characters as “edge cases”. In a UK product with any meaningful user base, they’re just… cases. The ONS data on name diversity, the variation in UK address formats across England, Scotland, Wales, and Northern Ireland (where some postcodes behave differently), and the variety of business entity types (Ltd, LLP, PLC, sole trader) all mean that the surface area of “normal” is wider than most teams design for.

    Seed scripts with realistic test data are the mechanism that makes this visible early. A design review where someone spots that the table breaks on a Welsh business name is infinitely cheaper than a support ticket from a real user in Llanfairpwllgwyngyll.

    The tooling is lightweight, the setup time is minimal, and the improvement to design review quality is immediate. Lorem ipsum had a good run. It’s time to retire it.

  • Micro-SaaS Product Design on a Shoestring: How UK Solo Developers Are Shipping Polished UIs Without a Designer

    Micro-SaaS Product Design on a Shoestring: How UK Solo Developers Are Shipping Polished UIs Without a Designer

    There is a very specific kind of despair that hits at around 11pm on a Tuesday, when your micro-SaaS is functionally complete, your Stripe integration works, your auth is solid, and then you open the browser and look at the interface you have built. It looks like a university coursework submission from 2014. This is the micro-SaaS UI design problem, and if you are a UK solo developer, it is probably the gap between shipping and actually getting paying customers.

    I have been watching this space closely for the past couple of years, and what has genuinely changed is that the tooling has caught up. The combination of mature component libraries, properly designed token systems, and headless UI primitives means a solo developer who is willing to spend a focused weekend can produce an interface that looks completely credible. Not just “passable”. Actually good. Here is how UK indie developers are doing it in 2026.

    UK solo developer working on micro-SaaS UI design at a desk late at night
    Photo by Daniil Komov on Pexels

    Why most indie developer UIs fail before the first demo

    The problem is almost never technical. Solo developers who can ship a multi-tenant backend with row-level security in Supabase are not struggling because UI is hard. They are struggling because good UI design requires a set of decisions that compound: spacing scales, colour relationships, type hierarchies, interaction states. Miss one layer and the whole thing looks wrong in ways that are hard to diagnose.

    The instinct is to grab a component library and bolt it on. That works, up to a point. But unstyled Tailwind with default shadcn/ui components looks exactly like unstyled Tailwind with default shadcn/ui components. Every micro-SaaS on Product Hunt right now has the same slightly-too-grey sidebar, the same Inter font at 14px, the same ghost buttons that vanish on light backgrounds. The trick is not just picking a library. It is understanding the layer underneath it: design tokens.

    Design tokens: the thing most solo developers skip entirely

    A design token is just a named variable for a design decision. --color-surface-primary instead of #ffffff. --space-4 instead of 16px. That sounds trivial until you have to change your brand colour across 47 components, or you need to add a dark mode, or your first enterprise customer asks if they can have a white-labelled version with their own colours.

    The W3C Design Tokens Community Group has been working on a standardised token format, and tools like Style Dictionary (maintained by Amazon) have made it possible to define tokens once and compile them to CSS custom properties, Tailwind config, and even iOS/Android values simultaneously. For a solo developer, this is huge. You define your spacing, colour, and typography decisions in one JSON file and let the toolchain propagate them everywhere.

    I would recommend starting with a minimal token set: five or six semantic colour roles (surface, on-surface, primary, on-primary, border, error), a spacing scale based on a 4px base unit, and two or three type sizes. That is genuinely enough to make an interface feel coherent. Resist the urge to over-engineer it before you have paying customers. If you are interested in how professional UK design teams handle token naming at scale, the contrast grids and colour token naming patterns being adopted by UK product teams are worth reading before you set up your own system.

    Design token system and component library used for micro-SaaS UI design on a monitor
    Photo by Ann H on Pexels

    The component libraries UK indie developers are actually shipping with

    Here is what I am seeing in the wild, from conversations in the Indie Hackers UK community and from poking around the public repos of recently-launched British micro-SaaS products.

    shadcn/ui with Radix primitives

    This is the dominant stack right now, and for good reason. shadcn/ui is not a traditional component library you install as a dependency. You copy the components directly into your project, which means you own the code. Radix UI provides the accessible, unstyled primitives underneath: dialogs, dropdowns, tooltips, all with keyboard navigation and ARIA attributes handled correctly. You get the accessibility baseline for free and the styling is entirely yours to control via Tailwind and your token layer.

    The downside is that the default aesthetic is quite neutral. You have to actually make design decisions on top of it, which is the point, but it means you cannot just install it and call it done.

    Mantine

    Mantine is the alternative I keep recommending to solo developers who want more out of the box. It has 120-plus components, a built-in theming system that maps closely to design tokens, and genuinely good defaults. The dark mode support is excellent. It is also well-maintained, with the Mantine team pushing consistent releases. The trade-off is bundle size and the fact that you are more constrained by the library’s design decisions. For a solo developer shipping fast, that constraint is often a feature, not a bug.

    Headless UI (from Tailwind Labs)

    Headless UI is narrower in scope than the others but worth mentioning for React and Vue developers already deep in the Tailwind ecosystem. It covers the components where behaviour is the hard part: listboxes, comboboxes, disclosure panels, transitions. If you are building a data-heavy SaaS with custom filtering UI, it handles the interaction logic cleanly.

    Making it look less like a template

    This is where the gap between “functional UI” and “credible UI” actually lives, and it is almost entirely about typography and whitespace. I cannot stress this enough. The single highest-return intervention a solo developer can make is to slow down and actually think about their type scale.

    Use a proper modular scale. Tools like Utopia.fyi let you define fluid type and space scales in CSS that interpolate between a minimum and maximum viewport width. Pair this with a good font: Geist (from Vercel, free) is excellent for product interfaces. Inter is fine but it is everywhere. Instrument Sans has a slightly warmer personality that works well for B2C SaaS. If you want to dig into the open-source font pairings that UK designers are currently using to stand out, the combinations worth actually using in 2026 cover this in proper depth.

    Beyond typography, the most common UI failure I see in indie products is insufficient spacing. Developers add padding that feels “enough” but does not give elements room to breathe. Double your padding values everywhere, then pull back by 20 per cent. You will almost always end up in a better place.

    Handling the conversion layer: landing pages and onboarding

    The app interface is only half the problem. For micro-SaaS, the marketing site and the first-run onboarding experience are where most revenue is won or lost. UK solo developers are increasingly treating these as separate design problems with different tooling.

    For landing pages, Astro with a component library like Flowbite Blocks or a purchased Tailwind UI template is a common approach. The layout decisions that actually differentiate UK B2B SaaS homepages are worth reviewing before you settle on a structure, because the default hero-features-pricing layout is doing no one any favours.

    For onboarding, the principle is simpler: show value as fast as possible, and do not ask for information you do not need yet. Progressive disclosure is your friend. Build the empty states deliberately. An empty dashboard that says “No data yet” is a conversion killer. An empty state that shows a greyed-out example with a clear single action is not.

    Getting eyes on your work early

    One thing that consistently separates the UK indie developers who ship polished products from those who do not is that they get external feedback before they think they are ready. The GOV.UK Service Standard has a principle around this: show the thing, not the idea. It applies equally well to commercial micro-SaaS.

    Post to the Indie Hackers UK Slack, share on X (Twitter), get a friend who is not a developer to try the onboarding. When I have spoken to solo developers who built products that actually convert, virtually all of them describe a moment where someone pointed out something completely obvious that they had been blind to because they were too close to it.

    For getting distribution sorted once you have a product worth promoting, tools like LinkPress are the kind of thing solo developers should be aware of as part of their broader go-to-market approach.

    The GOV.UK Service Manual design guidance is also genuinely useful reading even for commercial products. The thinking behind how they approach interaction design and user research is applicable well beyond public sector work.

    A realistic timeline for a solo developer

    Here is my honest estimate of what is achievable. Set up your token system and base Tailwind config: three to four hours. Implement shadcn/ui or Mantine and style it to your tokens: one full day. Land a coherent marketing page: another day. That is a weekend, realistically a long one. What you ship at the end of that will not be award-winning, but it will be clean, consistent, and credible enough to convert genuinely interested users.

    The mistake is treating design as something that happens at the end. Wire it into your development workflow from day one. Define your tokens before you write your first component. Pick your library before you scaffold your first page. The compounding benefit is enormous.

    Micro-SaaS UI design is solvable for solo developers. The tooling exists. The open-source resources exist. What it requires is treating design decisions as engineering decisions: deliberate, early, and documented.

    Frequently Asked Questions

    What is the best component library for a UK solo developer building a micro-SaaS in 2026?

    shadcn/ui with Radix primitives is the most popular choice because you own the code and have full styling control via Tailwind. Mantine is a strong alternative if you want more pre-built components and a built-in theming system without as many configuration decisions upfront.

    Do I need to understand design tokens to ship a polished UI?

    Not deeply, but you need the basic concept. At minimum, define your semantic colour roles and spacing scale as CSS custom properties before you write a single component. This single step will make your entire interface more consistent and saves significant time later when you need dark mode or white-labelling.

    How long does it realistically take to go from rough UI to polished interface?

    For a focused solo developer working with a good component library and a pre-defined token system, a weekend (roughly 12 to 16 hours of deliberate work) is enough to produce a credible, consistent interface for a small micro-SaaS product. Marketing page included.

    Is Tailwind CSS enough on its own for a micro-SaaS UI?

    Tailwind alone is a low-level utility layer, not a design system. Without a component library on top and a deliberate set of design tokens underneath, you will end up with an inconsistent interface that requires a lot of duplicated decision-making. Combine it with shadcn/ui or Mantine for best results.

    How do UK indie developers handle accessibility in their UIs without a specialist?

    Radix UI primitives and Mantine both handle the most common accessibility requirements out of the box: keyboard navigation, ARIA attributes, focus management. You still need to check colour contrast against WCAG AA standards, which you can do with free tools like the WebAIM Contrast Checker, but the structural accessibility is largely handled by the library.

  • The Real Cost of Ignoring Web Performance: What UK Core Web Vitals Data Actually Tells Us in 2026

    The Real Cost of Ignoring Web Performance: What UK Core Web Vitals Data Actually Tells Us in 2026

    There’s a number sitting inside the Chrome UX Report right now that should make every British frontend developer uncomfortable. Across a sample of UK e-commerce domains analysed through the CrUX dashboard earlier this year, fewer than 55% passed the INP (Interaction to Next Paint) threshold of 200ms. For context, INP became a Core Web Vital in March 2024, replacing FID, and Google has had over two years to let the ranking signal bed in. If your UK Core Web Vitals scores are still red, that’s not a future problem. That’s money leaving your client’s business today.

    Frontend developer analysing UK Core Web Vitals data on performance dashboard monitors
    Photo by ThisIsEngineering on Pexels

    I’ve spent a fair amount of time digging through CrUX field data for UK-hosted sites across retail, SaaS, and publishing verticals. What I keep seeing is a gap between what developers think their site scores and what real users on real networks in Birmingham, Manchester, or rural Scotland are actually experiencing. Lab scores in Lighthouse look fine. Field data is a mess. The delta is always user diversity: 4G on an ageing Android handset, a slow broadband connection in a terraced house with three people streaming simultaneously. That’s your actual audience for a huge chunk of UK traffic.

    What the CrUX data actually shows for UK sites

    Google’s CrUX (Chrome User Experience Report) aggregates real-world performance data from opted-in Chrome users, which in the UK means a reasonably representative slice of actual browsing conditions. You can query it directly via BigQuery, or use the PageSpeed Insights API to pull field data for any URL. I’d recommend doing both.

    A few patterns I keep seeing in 2026 UK data specifically:

    INP is the problem nobody fixed. LCP (Largest Contentful Paint) has improved significantly since 2022 because lazy-loading images and server-side rendering became standard. But INP measures responsiveness across the full page lifetime, not just load. JavaScript-heavy React and Vue SPAs tend to hammer INP because long tasks on the main thread block the browser’s ability to respond to user input. A user clicking a filter on an e-commerce PLP (product listing page) and waiting 600ms for anything to happen is having a bad time, even if the page loaded quickly.

    CLS is still broken on a surprising number of UK news and publishing sites. Cumulative Layout Shift above 0.1 is the threshold, and ad-heavy editorial properties routinely fail it. Late-loading ad slots that push content down, cookie banners that reflow the page, and web fonts swapping on render are the usual culprits.

    LCP on UK SaaS dashboards is frequently image-free but still slow. When the LCP element is a large text block rendered by JavaScript rather than a server-side HTML string, you get LCP scores of 4-6 seconds on mid-range devices. This catches out a lot of React-heavy product teams who never questioned whether their marketing site needed a client-side router at all.

    What sluggish scores are doing to conversions

    The Portent research (now a few years old but consistently replicated) put the penalty at roughly a 4.42% drop in conversion rate per additional second of load time in the 0-5 second window. More recent data from Cloudflare and Google’s own web.dev case studies backs this up across verticals. For UK SaaS with a £50/month average contract value and 10,000 monthly visitors, shaving 1.5 seconds off LCP and bringing INP under 200ms can shift conversion rates by 1-2 percentage points. Run that maths. It’s not a small number.

    E-commerce is even more sensitive. Basket abandonment on mobile is already brutal in the UK, where consumers expect fast experiences after years of conditioning by Amazon and ASOS. A slow PDP (product detail page) on a 4G connection isn’t just annoying; it’s a user who went back to Google, clicked the next result, and bought elsewhere. You don’t see that in your analytics beyond an exit rate and a nagging feeling.

    Laptop screen showing UK Core Web Vitals analytics and conversion rate charts
    Photo by RDNE Stock project on Pexels

    How to actually fix INP on a JavaScript-heavy site

    INP is harder to fix than LCP because it’s not a single moment but a score built from all interactions across a session. Here’s where I’d start.

    Profile long tasks in Chrome DevTools. Open the Performance panel, record a session, and look for red bars in the main thread. Any task over 50ms is a long task; anything over 200ms is the INP killer. You’re looking for event handlers that do too much synchronous work, or third-party scripts that block the main thread during user interaction.

    Yield to the main thread deliberately. The scheduler.yield() API (now available in all modern Chromium-based browsers and with a polyfill for Firefox/Safari) lets you break up long tasks explicitly. Wrapping expensive state updates in scheduler.postTask() with a ‘user-blocking’ priority gives the browser space to respond to input before continuing the heavier computation.

    Audit your event listeners. A React component that fires a synchronous setState inside an onInput handler for a search field, triggering a full re-render of a large list on every keystroke, is a classic INP wrecker. Debounce it, or defer the render using useTransition to mark the update as non-urgent.

    Move work off the main thread. Web Workers are underused in frontend codebases, particularly in UK agency projects where the brief was always “just make it work.” Filtering large datasets, parsing JSON from APIs, or running any sort of calculation that doesn’t touch the DOM is a strong candidate for a Worker.

    LCP: the quick wins that are still being missed

    If your LCP element is a hero image (check using the Performance panel or PerformanceObserver in the browser console), preloading it is the single highest-ROI fix available. A <link rel='preload' as='image'> in the document head, combined with correctly sized srcset attributes and a format like AVIF or WebP, will knock seconds off LCP scores for image-led pages. I’ve seen UK retail sites drop from 4.8 seconds to under 2 seconds LCP on mobile just from this change alone.

    If the LCP element is text, the priority is Time to First Byte (TTFB). Slow server response times, which are common on shared hosting and poorly configured WordPress installs (still ubiquitous in UK small business e-commerce), cascade into every other metric. A CDN with edge caching for static assets and full-page HTML caching where possible is non-negotiable. Cloudflare’s free tier handles this adequately for most small UK sites.

    Font loading is the other LCP trap. Using font-display: swap is not a complete solution; it trades invisible text for layout shift. The better approach is to subset your font files aggressively (only the characters you actually use), preload the critical weights, and keep the number of font families to two at most. I’ve written before about how open source font pairing is an increasingly smart approach for UK designers, partly because the files tend to be smaller and better optimised than some commercial typeface packages.

    Tools worth adding to your workflow right now

    Beyond PageSpeed Insights, the CrUX API is queryable for free and returns 28-day rolling field data. Pair it with Treo’s CrUX visualiser or build your own dashboard; I pointed to a walkthrough of that kind of project in a previous article on building a personal design dashboard using Railway and the Notion API, which is worth reading if you’re the type who’d rather have the data in front of you constantly than check it manually.

    Web Vitals Chrome Extension gives you field and lab data side by side while you browse. It’s the fastest way to gut-check any URL during development. Combine it with Webpagetest.org (run a UK test node, Dulles is not your audience) for waterfall analysis.

    For security-conscious teams handling client sites, anything that touches production performance should be monitored consistently. A compromised script injected into your bundle will tank INP immediately; if you ever notice a sudden unexplained regression in your INP scores, check your third-party scripts first. Services like dijitul Support handle malware removal and script injection issues specifically, which is relevant given how often performance regressions turn out to have a security root cause.

    The uncomfortable truth about UK Core Web Vitals in 2026 is that the tooling to diagnose and fix these issues has never been better, the data has never been more accessible, and yet the median UK site is still underperforming on INP specifically. The gap isn’t knowledge; it’s prioritisation. Performance work doesn’t get a ticket raised because it rarely has a visible face. It shows up as a sluggish feeling, a higher bounce rate, a slightly lower conversion rate than last quarter. Put a number to it, surface it to whoever controls the roadmap, and suddenly it gets prioritised. The CrUX data is the number. Use it.

    If you work across design and build (which is most of us on smaller UK teams), performance is a design decision as much as a technical one. The number of image carousels, the weight of a custom typeface, the choice to render a menu client-side instead of server-side: all of it lands in the field data eventually. Understanding what constrained design systems like GOV.UK get right is partly an object lesson in how limiting your component palette keeps your bundle lean and your users happy.

    Frequently Asked Questions

    What are UK Core Web Vitals and why do they matter for my site?

    Core Web Vitals are three metrics Google uses to measure real-world user experience: LCP (loading), INP (interactivity), and CLS (visual stability). They matter because Google uses them as a ranking signal, and poor scores directly correlate with higher bounce rates and lower conversion rates on UK e-commerce and SaaS sites.

    How do I check my site's Core Web Vitals field data for UK users specifically?

    Use the PageSpeed Insights API or query the Chrome UX Report (CrUX) via Google BigQuery to get 28-day rolling field data. Run Webpagetest.org tests using a London or Manchester server node to simulate realistic UK network conditions rather than US-based test servers.

    What is INP and why is it harder to fix than LCP?

    INP (Interaction to Next Paint) measures how quickly a page responds to user input across the entire session, not just at load. It’s harder to fix than LCP because it depends on all JavaScript running on the main thread throughout the user’s visit, including third-party scripts, event handlers, and framework re-renders.

    How much can improving Core Web Vitals actually improve conversion rates?

    Research consistently shows a 4-5% drop in conversions per additional second of load time. Fixing LCP and INP on a UK SaaS product or retail site can shift conversion rates by 1-2 percentage points, which at meaningful traffic volumes represents significant revenue. Google’s own case studies document similar improvements across e-commerce clients.

  • Contrast Grids and Colour Token Naming: How UK Design Teams Are Finally Solving Their Semantic Colour System Problems

    Contrast Grids and Colour Token Naming: How UK Design Teams Are Finally Solving Their Semantic Colour System Problems

    Colour decisions in product design look deceptively simple until your rebrand lands, someone switches to dark mode, and your carefully chosen palette turns into a contrast disaster that fails WCAG AA at about twelve different points. I’ve watched this happen to teams who thought they had a proper colour system, only to discover they had a colour list with a system-shaped name badge on it. There is a meaningful difference, and design system colour tokens UK teams are increasingly using to close that gap are finally mature enough to be worth writing about seriously.

    Designer reviewing design system colour tokens UK documentation on a large monitor
    Photo by cottonbro studio on Pexels

    What a real semantic colour token system actually looks like

    The core idea is layered naming. You have primitive tokens at the bottom: raw values like blue-500: #2563EB. Above that sit semantic tokens that describe function rather than appearance: colour-interactive-default, colour-surface-elevated, colour-feedback-error. The primitive never goes directly into a component. The semantic token does. The layer in between is where the magic happens, because when a rebrand requires swapping blue-500 for teal-600, you change one reference and everything that consumes colour-interactive-default updates automatically.

    This three-tier approach, often called primitive, semantic, and component-level tokens, has been championed by Salesforce’s Lightning Design System for years, but UK product teams have been slower to adopt it fully. Part of that is legacy: many British SaaS companies built their design systems before design tokens were a coherent concept, and the technical debt of retrofitting a flat Sass variable file into a structured token architecture is real. The other part is that tooling only recently caught up.

    Why naming conventions matter more than most teams realise

    Here’s where I’d argue most colour system conversations go wrong. Teams spend weeks debating whether blue-500 should be #1D4ED8 or #2563EB, and approximately twenty minutes on naming conventions. Then they ship tokens with names like primaryBlue, brandGreen, and accentColor1, which are essentially useless the moment a new designer joins or the brand team decides teal is the new blue.

    A robust naming convention is schema-first. The structure I’ve seen work best in UK teams follows: [namespace]-[category]-[property]-[variant]-[state]. So ds-colour-text-primary-hover instead of textHoverMain. The namespace scopes the token to your system and prevents collisions if you’re working in a monorepo with multiple products, which plenty of UK B2B companies are. Category and property describe what the token affects. Variant and state handle the stuff that trips everyone up: default versus disabled, rest versus hover versus focus.

    The W3C Design Tokens Community Group published their format specification to standardise how tokens are stored and transferred between tools. It’s not a finished standard yet, but it’s close enough that Figma’s variables implementation and Style Dictionary both align with it reasonably well. If you’re building a token system in 2026 and not at least glancing at that spec, you’re probably building something you’ll have to rebuild in two years.

    Contrast grids: the tooling that makes WCAG compliance tractable

    WCAG 2.1 AA requires a contrast ratio of 4.5:1 for normal text and 3:1 for large text and UI components. WCAG 2.2, which the UK public sector accessibility requirements point to for public sector digital services, doesn’t change those ratios but adds a clearer expectation that you’ve done the work systematically. The problem is that checking every foreground-background combination manually is genuinely tedious. A palette with twelve colours has 66 unique pairs. If you’re also considering dark mode, you’ve effectively doubled your matrix.

    Contrast grids, popularised by Eightshapes’ free tool, solve this by visualising the entire foreground-background matrix at once. You input your palette, and the grid shows every combination colour-coded by whether it passes AA, AAA, or fails entirely. This is enormously useful not just for compliance checking but for making design decisions. When you can see that your neutral-700 passes AA on both your surface-primary and surface-secondary but fails on surface-tertiary, you can encode that constraint directly into your token documentation rather than waiting for it to surface in a QA pass.

    Several UK product teams I’m aware of have started integrating automated contrast checking into their CI pipelines using tools like @accessibility-checker/contrast or custom scripts built on the wcag-contrast npm package. The idea is that a token file change that introduces a failing combination gets flagged in the pull request before it ever reaches a designer’s screen. That’s the right direction. Catching contrast failures at the system level rather than the component level is much cheaper to fix.

    Dark mode is where token systems either prove themselves or collapse

    Dark mode is the stress test every semantic colour token system has to pass eventually. If you’ve built a flat system where components reference primitive values directly, implementing dark mode means touching every component. If you’ve built a properly layered system, dark mode is just a second theme file that remaps your semantic tokens to different primitives.

    In practice, this looks like having two sets of semantic token values: one for light mode, one for dark. colour-surface-primary maps to neutral-100 in light and neutral-900 in dark. A CSS custom property implementation handles the swap via prefers-color-scheme or a data attribute on the root element. Style Dictionary can output both token sets as separate CSS files or as a single file with media query scoping.

    Where teams go wrong is assuming their colour palette works symmetrically in both modes. It almost never does. A contrast grid for your dark mode token mappings is not optional; it’s a separate exercise from your light mode grid, because the contrast ratios change when you flip surfaces. I’d recommend running both grids simultaneously when you’re building out a dual-mode system, and locking the acceptable pairings into your token documentation so that designers can’t accidentally use colour-text-secondary on colour-surface-overlay just because it looks fine in one mode.

    This connects directly to work happening at the component level too. If you’re already thinking carefully about how CSS container queries are reshaping component architecture for UK frontend teams, it’s worth considering how your colour token layer interacts with component-scoped theming. A component that can respond to its container’s size should probably also respond to a locally-scoped theme token rather than relying solely on document-level custom properties.

    Surviving a rebrand with a token system intact

    Rebrands are where semantic token systems pay back every hour of upfront investment. The UK financial services sector goes through brand refreshes constantly, and I’ve seen what happens to design systems that were built around hex values rather than token references. It’s not pretty. Months of find-and-replace work, inevitably inconsistent across products, with rogue legacy values lurking in edge cases until someone files a bug six months later.

    A token system handles this cleanly. Your primitive tier changes. Your semantic tier doesn’t. Your components certainly don’t. If your new brand blue is #1A56DB instead of #2563EB, you update one value, run your contrast grid to confirm nothing broke, and ship. That’s the whole thing.

    Teams building more complex multi-brand or white-label products need to go one level further. Rather than a single primitive-to-semantic mapping, they maintain multiple primitive tiers (one per brand) that all map to the same semantic layer. This is the approach used in sophisticated public sector design systems, and it scales well into the kind of multi-tenant SaaS architecture where a single codebase serves several clients with different brand guidelines.

    The toolchain that makes this tractable in 2026 is roughly: Figma variables for design-side token management, Style Dictionary for transformation and output to CSS, JSON, Swift, Kotlin or whatever your platforms need, and a contrast grid check baked into your release process. None of these tools are particularly new. The difference is that they now work well together, and the naming conventions are stable enough that a token defined in Figma actually means the same thing when it emerges from Style Dictionary on the other side.

    If you’re also thinking about how design system decisions affect the designer-developer handoff, the current state of Figma’s Dev Mode is relevant here; token visibility in dev mode has improved substantially, and a well-structured token system makes the handoff cleaner regardless of which side of the gap you’re on.

    The teams doing this well right now are not necessarily the largest UK product organisations. Some of the most rigorous colour token work I’ve come across is happening at mid-size British fintechs and healthtech companies where the contrast requirements are non-negotiable and the rebrand cycle is fast. Necessity, as always, is doing most of the architectural work.

  • Designing for the NHS App Ecosystem: What Third-Party Health Developers Need to Know About NHS Design Patterns

    Designing for the NHS App Ecosystem: What Third-Party Health Developers Need to Know About NHS Design Patterns

    If you’ve ever tried to build a companion app or integration layer for the NHS ecosystem, you’ll know the experience is somewhere between solving a puzzle with missing pieces and navigating a labyrinth designed by committee. The documentation exists. The NHS Digital Service Manual is actually one of the better-maintained design systems in the UK public sector. The problem isn’t the documentation. The problem is that most health tech startups read it the way people read terms and conditions: quickly, selectively, and with total confidence they’ve understood the important bits.

    They haven’t. I’ve seen the same mistakes repeat across a dozen health tech projects, from GP appointment add-ons to mental health tracking apps trying to slot into NHS workflows. So let’s go through what’s actually being misunderstood, because some of these errors go beyond aesthetics into genuinely risky territory.

    Tablet displaying NHS design patterns in a clinical setting
    Photo by Matheus Bertelli on Pexels

    Why NHS design patterns are not just a visual style guide

    The first and most common misconception: teams treat NHS design patterns as a branding exercise. Copy the blue. Use the logo typeface (Frutiger, or the open-source Fraunhofer approximation). Borrow the card components. Job done, looks credible.

    That’s backwards. The NHS design system is built around a set of interaction principles and a specific clinical context that most commercial UI thinking doesn’t account for at all. The GOV.UK Design System, which shares some DNA, at least gets discussed in design circles (I wrote about what GOV.UK gets right that private sector UI libraries get wrong a while back), but the NHS variant has additional constraints layered on top, because the users and stakes are different.

    Consider one obvious example: error messaging. In a typical SaaS product, an error message is a minor friction point. In a clinical UI, an error message about a dosage input or an appointment slot could cause a patient to take the wrong action. The NHS Service Manual specifies error summary patterns precisely because the consequences of user confusion in health contexts are categorically different from, say, a failed checkout flow. The pattern is not decoration. It is a risk mitigation tool.

    What health tech startups consistently get wrong about accessibility

    WCAG 2.2 compliance gets mentioned in every NHS digital service assessment, and most teams know this, at least in theory. In practice, I see two failure modes.

    The first is treating accessibility as a checklist rather than a design constraint. Teams run an automated audit with axe or Lighthouse, fix the obvious contrast ratios, add some aria-labels, and declare compliance. But automated tools catch roughly 30-40% of WCAG issues. The remainder, focus order, screen reader narrative flow, meaningful alternative text, timeout behaviour for users with cognitive impairments, only surfaces in manual testing with real assistive technology.

    The second failure mode is misunderstanding the NHS user base. NHS app users are not a homogeneous tech-savvy audience. As I covered in my piece on designing for older users and accessibility, the over-55 demographic represents a huge proportion of NHS service users, and they interact with digital interfaces in ways that invalidate many assumptions baked into modern component libraries. Small tap targets, hover-only states, icons without labels, modals that trap keyboard focus badly: all of these become genuine barriers at scale when your user base skews older and potentially has reduced motor control or vision impairment.

    Developer writing code for NHS design patterns component library
    Photo by Harold Vasquez on Pexels

    The NHS explicitly requires user research with real patients as part of service assessments. Not personas. Not assumed user journeys mapped on a whiteboard. Actual sessions with actual people. Teams that skip this stage almost always pay for it later, either in failed assessments or in post-launch complaints that damage the trust relationship with NHS partners.

    Trust signals in clinical UI: where commercial design intuitions break down

    Here’s where it gets philosophically interesting. Commercial product design has spent the last decade optimising for conversion: clear CTAs, reduced friction, bright colour on primary actions, social proof via user counts and review scores. Health tech apps that import these patterns wholesale often end up looking untrustworthy to clinical users, and sometimes to patients.

    Clinical trust operates differently. A patient interacting with a mental health app doesn’t want it to feel like a productivity tool. They want it to feel safe, unhurried, and unambiguous. This means generous whitespace (which commercial designers sometimes read as “wasted space”), plain language at a reading age appropriate for a wide public audience, and absolutely no dark patterns near anything related to consent or data sharing.

    The NHS has very specific guidance on data handling UI precisely because health data is special category data under UK GDPR. The ICO and NHS England both publish guidance on this. If your consent flows borrow the kind of nudge patterns you’d find on a subscription cancellation screen (pre-ticked boxes, vague opt-in language, confusing toggle states), you are not just creating bad UX. You are potentially creating a legal and regulatory problem. I wrote about UK consumer protection and UX design in a different context, but the principle around manipulation through UI design is directly applicable here.

    The NHS digital service standard: what the assessment process actually demands

    Teams building apps that will connect to NHS systems, or carry NHS branding, typically need to pass a Digital Technology Assessment Criteria (DTAC) review. This is not the same as simply passing an NHS design assessment, and conflating them is a common error.

    DTAC covers clinical safety (DCB0129 compliance), data protection, technical security, interoperability (FHIR R4 where relevant), and usability. The clinical safety requirement alone, which requires a named Clinical Safety Officer and a documented hazard log, catches many startups completely off guard. This is not a box-ticking exercise. A hazard log means identifying the ways your software could harm a patient if it behaves unexpectedly, and documenting what you’ve done to mitigate each risk.

    I’ve seen teams, including a couple of otherwise well-run companies that handle complex integrations, treat the DTAC process as a hurdle to clear rather than a framework that makes their product genuinely safer. The distinction matters enormously when something goes wrong. Agencies building products with technical integration complexity, like Dijitul Developments, understand that integration architecture decisions made early have compliance implications downstream, and the same is true in spades for health tech builds touching NHS infrastructure.

    Component library choices and why “looks NHS” is not enough

    The NHS frontend library is open source and available on GitHub. It covers form components, navigation patterns, warning callouts, and action links. Using it is sensible. But a few nuances trip people up.

    First, the library is React-agnostic by design, but most health tech teams are building in React or React Native. The official components are vanilla HTML/CSS/JS. There are community-maintained React wrappers, but these are not officially supported, and their fidelity to the latest NHS frontend version varies. Teams need to own the maintenance overhead if they use them.

    Second, the NHS design system has specific guidance on what components to use for clinical decision support contexts versus patient-facing contexts. Using a summary card component (designed for showing appointment details to a patient) inside a clinician-facing dashboard creates cognitive dissonance for clinical staff who have built up a mental model of what each pattern means. Context collapse in UI is a real problem that purely visual pattern-matching doesn’t prevent.

    What building well actually looks like

    The teams I’ve seen do this well share a few habits. They read the NHS service manual properly, including the content design guidance, which is where a lot of the philosophy is actually explained. They involve a clinical safety lead from the start rather than bolting one on before submission. They conduct genuine usability testing with NHS staff and patients, not just developers who have become blind to their own interface.

    They also build with the understanding that NHS design patterns are living documents. The manual updates. Guidance around things like app accessibility and FHIR integration evolves. Setting up a process to track changes, rather than treating the design system as a one-time reference, is the difference between a product that stays compliant and one that quietly drifts out of alignment.

    Getting this right is genuinely hard. But the NHS has done a lot of the thinking for you, if you’re willing to engage with it seriously rather than skin-deep.

  • Building a Personal Design Dashboard With Notion API and Railway: A UK Freelancer’s Weekend Project Walkthrough

    Building a Personal Design Dashboard With Notion API and Railway: A UK Freelancer’s Weekend Project Walkthrough

    I built this on a rainy Saturday in February, mostly out of frustration with juggling four browser tabs to answer one client question. A Notion database for projects here, a spreadsheet for invoices in GBP over there, a folder structure that made sense three months ago and now just feels like archaeology. The result was a self-hosted Railway app that pulls everything through the Notion API into a single, genuinely useful dashboard. It took a weekend. Here’s exactly how I did it.

    Before we get into the code, a quick note on why Railway specifically. For UK-based freelancers who want a self-hosted feel without maintaining a VPS at 2am, Railway’s free tier (and its £5/month hobby plan) is a reasonable middle ground. You get persistent deploys, environment variables, and a Postgres instance if you need one. It’s not perfect, but it’s fast to set up and the deployment pipeline is git-push simple. If you want a deeper look at framework choices for self-hosted tooling, the open source alternatives UK indie developers are actually shipping with article on this blog covers the broader landscape well.

    Developer workspace with a Notion API dashboard for freelancers displayed on a laptop screen
    Photo by cottonbro studio on Pexels

    Setting up your Notion API integration

    Log into Notion, head to notion.so/my-integrations, and create a new integration. Give it a sensible name, something like “Freelance Dashboard”, and grab the Internal Integration Token. Store it somewhere safe. You’ll need it as an environment variable in Railway shortly.

    Now, the important bit that trips people up: Notion integrations don’t automatically have access to your databases. You have to share each database with the integration manually. Open the database you want to connect, click the three-dot menu in the top right, go to “Add connections”, and select your integration. Do this for every database you plan to query. I have three: one for client projects, one for invoices, and one for design asset pipelines.

    Your database IDs live in the URL. When you open a full-page database in Notion, the URL looks like notion.so/yourworkspace/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX?v=.... The 32-character string before the query parameter is your database ID. Copy these out and store them alongside your token.

    Structuring your Notion databases for the API

    The Notion API returns data in a fairly verbose JSON structure, so it pays to keep your databases clean before you start querying them. For the client projects database, I use these properties: Client Name (title), Status (select: Active, On Hold, Complete), Start Date (date), Deadline (date), Project Value (number, formatted as GBP), and Brief (rich text). The API will hand all of these back as typed objects, which makes parsing straightforward.

    For invoices, I track: Invoice Number (title), Client (relation to the projects database), Amount (number), VAT (number), Paid (checkbox), Issue Date (date), and Due Date (date). The relation property is particularly useful because it lets you join data across databases in your app layer without building a separate relational database. Notion is doing that join for you, and the API respects it.

    The asset pipeline database is simpler: Asset Name (title), Project (relation), Type (select: Logo, UI Kit, Illustration, Icon Set), Status (select: Draft, Review, Approved, Delivered), and File Link (URL).

    Node.js code for a Notion API dashboard for freelancers shown in a terminal and editor
    Photo by Daniil Komov on Pexels

    Building the Railway app: Node.js + Express

    I went with Node.js and Express here. Nothing exotic. Create a new project directory, run npm init -y, then install your dependencies:

    npm install express @notionhq/client dotenv

    The official @notionhq/client package handles all the auth headers and request formatting. Create a .env file at the root:

    NOTION_TOKEN=secret_yourTokenHere
    PROJECTS_DB_ID=yourProjectsDatabaseId
    INVOICES_DB_ID=yourInvoicesDatabaseId
    ASSETS_DB_ID=yourAssetsDatabaseId
    PORT=3000

    Now the core of the app. Create index.js:

    require('dotenv').config();
    const express = require('express');
    const { Client } = require('@notionhq/client');
    
    const app = express();
    const notion = new Client({ auth: process.env.NOTION_TOKEN });
    
    async function queryDatabase(databaseId, filter = {}) {
      const response = await notion.databases.query({
        database_id: databaseId,
        ...filter
      });
      return response.results;
    }
    
    app.get('/api/projects', async (req, res) => {
      try {
        const pages = await queryDatabase(process.env.PROJECTS_DB_ID);
        const projects = pages.map(page => ({
          id: page.id,
          client: page.properties['Client Name'].title[0]?.plain_text ?? 'Unnamed',
          status: page.properties['Status'].select?.name ?? 'Unknown',
          value: page.properties['Project Value'].number ?? 0,
          deadline: page.properties['Deadline'].date?.start ?? null
        }));
        res.json(projects);
      } catch (err) {
        res.status(500).json({ error: err.message });
      }
    });
    
    app.get('/api/invoices', async (req, res) => {
      try {
        const pages = await queryDatabase(process.env.INVOICES_DB_ID);
        const invoices = pages.map(page => ({
          id: page.id,
          invoiceNumber: page.properties['Invoice Number'].title[0]?.plain_text ?? '',
          amount: page.properties['Amount'].number ?? 0,
          vat: page.properties['VAT'].number ?? 0,
          paid: page.properties['Paid'].checkbox,
          dueDate: page.properties['Due Date'].date?.start ?? null
        }));
        res.json(invoices);
      } catch (err) {
        res.status(500).json({ error: err.message });
      }
    });
    
    app.get('/api/assets', async (req, res) => {
      try {
        const pages = await queryDatabase(process.env.ASSETS_DB_ID);
        const assets = pages.map(page => ({
          id: page.id,
          name: page.properties['Asset Name'].title[0]?.plain_text ?? '',
          type: page.properties['Type'].select?.name ?? 'Other',
          status: page.properties['Status'].select?.name ?? 'Draft'
        }));
        res.json(assets);
      } catch (err) {
        res.status(500).json({ error: err.message });
      }
    });
    
    app.listen(process.env.PORT, () => {
      console.log(`Dashboard API running on port ${process.env.PORT}`);
    });

    Three endpoints, each pulling from a separate Notion database and shaping the response into something clean for the frontend to consume. The optional chaining throughout (?. and ??) is doing a lot of heavy lifting here; Notion properties can be null in ways the documentation doesn’t always warn you about.

    Deploying to Railway

    Initialise a git repository in your project folder and push it to GitHub. Then go to Railway, create a new project, and select “Deploy from GitHub repo”. Point it at your repo. Railway will detect the Node.js project automatically.

    Add your environment variables under the project’s “Variables” tab. Everything from your .env file needs to live there; Railway injects them at runtime. Do not commit your .env file to GitHub. Add it to .gitignore before you push anything.

    Add a start script to your package.json:

    "scripts": {
      "start": "node index.js"
    }

    Railway picks this up automatically. Your first deploy will take about 90 seconds. After that, every git push triggers a new build. Railway gives you a public URL in the format yourproject.up.railway.app. Your three API endpoints are now live at that base URL.

    Building the frontend dashboard

    I kept the frontend deliberately simple: plain HTML, a tiny bit of vanilla JS, and the excellent charting libraries that UK SaaS teams are increasingly reaching for. I used Chart.js specifically for a revenue-by-month bar chart that pulls from the invoices endpoint and groups Amount + VAT totals by the month of the due date.

    The key financial summary card calculates outstanding invoices (where paid === false) and displays total outstanding in GBP. No currency conversion, no dollar signs, just a clean £${total.toFixed(2)} string. Small thing, but it matters when you’re reporting income to HMRC.

    Serve the static frontend from the same Express app using express.static('public') and drop your HTML, CSS, and JS files into a /public folder. One deploy, one URL, everything in one place.

    A few things I learnt the hard way

    Notion’s API rate limit is 3 requests per second. If you’re querying three databases on page load, stagger them or use Promise.all carefully. I cache responses for 60 seconds using a simple in-memory object to avoid hammering the API on every browser refresh.

    Relation properties in the Notion API return page IDs, not the actual related page data. If you want the client name in your invoice response, you need a second API call to fetch that related page. I chose to keep it denormalised in the invoices database instead by adding a plain text “Client Name” field that I fill manually. Not elegant, but it halves the API calls.

    Finally, if you’re dealing with sensitive client data in these databases, think carefully about what you expose through the Railway URL. I added a simple API key check middleware that validates a header against another environment variable. Nothing fancy, but enough to stop anyone who stumbles across the URL from reading your invoice totals. And speaking of due diligence with data, I was reminded recently whilst reviewing a client’s office refurbishment docs that the same careful approach applies to physical compliance paperwork; a colleague mentioned they’d used Asbestos Compliance Solutions for site documentation before any structural work began. Proper records, properly stored. Same principle, different domain.

    This whole setup is genuinely more useful than I expected. The Notion API is well-documented, Railway removes all the ops friction, and the result is a dashboard that actually reflects how I work rather than forcing me to adapt to someone else’s product. If you want to push it further, look at adding webhook listeners to Notion page updates, or wiring in a Telegram bot that pings you when an invoice goes overdue. The foundation is there. Now go build something on a weekend.

    Frequently Asked Questions

    Is Notion's API free to use for personal freelance projects?

    Yes, the Notion API is free to use and included with all Notion plans, including the free tier. You can make up to 3 requests per second, which is plenty for a personal dashboard querying a handful of databases.

    What does Railway cost for hosting a small Node.js app like this?

    Railway’s free tier gives you $5 of credit per month (applied to resource usage), which is usually enough for a low-traffic personal app. Their Hobby plan at around £5/month removes usage caps and adds persistent deployments with no idle spin-down, which is worth it for a dashboard you check daily.

    Can I track invoices in GBP specifically through the Notion API?

    Notion stores number properties without currency formatting at the data level, so your amounts are just numbers in the API response. You apply the GBP formatting in your frontend code using JavaScript’s Intl.NumberFormat with ‘en-GB’ locale and ‘GBP’ currency, which gives you properly formatted pound sterling strings.