Build World Cup fixtures/results atom

[petternitter]

Summary

In support of the World Cup coverage, we need to build a new fixtures/results atom that editorial can drop into relevant fronts and articles. This is to offer an additional entry point to the tournament and help drive traffic to our coverage.

Given the atom needs to be ready for June 1st, it should only display World Cup fixtures/results for this first version of the atom. Building out the capability for editorial to select which competition the atom displays is out of scope for now - but we should aim to build/structure the atom in a way that makes it as simple to support this capability in a future iteration where possible.

The priority is to get a World Cup version working in time for the tournament. Longer term, we want this to become something editorial can configure in tooling, but we should only do the bits now that move us in that direction without adding complexity/scope and risk to delivery.

Scope

• Build the UI for the new atom based on the following designs
• Support the three designed states for:
  • upcoming fixtures
  • live matches
  • finished matches/results
• Make it available as an atom that can be placed into a front or article
• Limit the atom to World Cup for now, but where possible structure it so competition/league selection could be made editorially configurable later
• Document the follow-up work needed to support the reusable, editorially controlled future version

Open questions

• How long should a finished result stay in the atom before it drops out and the next upcoming fixture replaces it? (Currently with Product Design)

Notes

• Ignore references to Premier League in the designs - this should be replaced with World Cup
• We should be able to get started on the UI without waiting for every UX detail to be nailed down

Out of scope

• Integrating the atom with editorial tooling in a way that allows them to choose different football competition
• Supporting competitions other than the World Cup in this first version
• Solving every future use case for this component now; the priority is a working World Cup version

Deliverable

• A working World Cup fixtures/results atom that can be used across fronts and articles
• Adaptive UI covering the designed states
• A write-up of any follow-up work needed for further configurability of atom via editorial tooling

Acceptance criteria

• Atom UI is matches the design and adapts to different states based on data available
• The atom can be placed on fronts and articles in the same way as other atoms
• Displays World Cup fixtures/results by default
• The implementation is structured so that support for league selection can be implemented without having to start from scratch
• The UX of the display logic has been resolved and implemented accordingly

Notes

• Data source: PA
• Design: Figma link

[jamesmockett]

Proposed architecture

Ultimately we'd like to build this component into the platform, but as we lack sufficient time to make the necessary tooling updates building it as an atom allows it to be dropped into fronts and articles where needed using existing tooling and workflows.

However, we can lay some of the groundwork for adding it to the platform by adopting a similar architecture to the existing football atoms collection. Rather than fetching and rendering match data themselves these atoms defer to Frontend which renders the necessary markup and exposes it via an 'embed' endpoint. eg.:

https://www.theguardian.com/football/world-cup-2026/groups/individual/embed/a

The atoms don't do anything beyond fetching the markup for the appropriate group stage or knockout table, rendering it as static HTML and publishing to S3. Styles live alongside the atoms in the interactives repo.

As this is new functionality we would built it into DCAR rather than Frontend: DCAR will be responsible for fetching match fixtures and results data from Frontend, and rendering as HTML. This will be exposed via a new endpoint that a newly built atom will fetch markup from, render and publish to S3. Like the existing football atoms the new fixtures / results atom will run on a schedule and fetch new data from the endpoint every minute so that it always displays up-to-date information. (The atoms are statically published and don't make any requests on the client — the request is from the atom build step when republished so there will only be a single request to the endpoint per minute.)

Taking this approach avoids needing to duplicate the work required to fetch and render this data in an atom when it's something we ultimately want to do in DCAR. With the ability to render this component in DCAR we can, at a later date, add any necessary enhancements (such as client side data fetching) and tooling updates to enable us to replace the atom entirely.