[PNP-9605] Allow every component's CSS files to render on a component's preview page #5055

AshGDS · 2025-10-01T11:47:13Z

What

Adds the following query parameter options to the /preview route on a component
- all_components=true e.g. https://components-gem-pr-5055.herokuapp.com/component-guide/button/preview?all_components=true - this will render the component alongside every other component's CSS file
- render_component_first=true e.g. https://components-gem-pr-5055.herokuapp.com/component-guide/button/preview?all_components=true&render_component_first=true this will load the component first before all the other CSS files
- percy=true e.g. https://components-gem-pr-5055.herokuapp.com/component-guide/button/preview?percy=true - this just refactors some existing functionality that shortened the page title for Percy tests. The previous code used a regex string replace, which was a lot less flexible.

Why

We noticed that we do not test component isolation in the component guide - in other words, we aren't sure if one components CSS can override another's. This PR was meant to result in us having new Percy screenshots to automatically surface this for us, but we are not doing that due to the screenshot limit on our plan. Therefore these new routes exist, and documentation has been updated to guide devs on how to ensure they can use the routes to check CSS specificity.
- Note that this PR isn't ideal to resolve the underlying problem at the moment...for example, even with these new routes, someone can still modify the accordion and only test the accordion previews, but their change could have accidentally broken warning_text. That wouldn't be surfaced by our existing automatic testing, and therefore it would be on the dev to have checked if warning_text styles are now influenced by accordion styles. We can't expect devs to go and check every single component preview when they modify one component's styles, so it would be good if we can incorporate the automatic Percy tests in the future. We can manually trigger a Percy visual diff though (as outlined here), so maybe that's something to run every so often just to check things are OK.
Related to GOVUK Frontend styles are overriding some styles that were previously overridden #5035

Potential things to add

Some things I have left out that may be worth adding:

Adding a link/menu bar of some sort on the /preview pages so that devs can easily access the specificity test pages
Some of the logic in the view could maybe be put somewhere else - I did try having one data structure for all the component docs and handling render_component_first by making the component the first item in the data structure, but it seems that ComponentDoc objects aren't correctly setting a source, so at render time I couldn't determine whether it was an app component or a gem component. Still, it's probably possible to do this if you think it's worth it but I may have to refactor the ComponentDoc model.

Visual Changes

This PR won't result in any visual changes, but the visual changes that have been surfaced by this work are in the following PRs: #5056 and #5061

It has an empty, unused stylesheet, so we can delete it.

KludgeKML

LGTM!

andysellick · 2025-10-13T09:55:24Z

spec/components/all_components_spec.rb

      end

-      it "has a correctly named SCSS file", not_applicable: component_name.in?(%w[contextual_breadcrumbs contextual_footer contextual_sidebar google_tag_manager_script list machine_readable_metadata meta_tags]) do
+      it "has a correctly named SCSS file", not_applicable: component_name.in?(%w[contextual_breadcrumbs contextual_footer contextual_sidebar copy_to_clipboard google_tag_manager_script list machine_readable_metadata meta_tags]) do


I'm surprised we didn't do this earlier, which always makes me nervous that there's some reason we haven't thought of 😁 You might also want to remove these lines, which reference this stylesheet: https://github.com/alphagov/govuk_publishing_components/blob/main/lib/govuk_publishing_components/config.rb#L40-L41

andysellick · 2025-10-13T10:03:45Z

app/controllers/govuk_publishing_components/component_guide_controller.rb

It doesn't look like there's a test for this file. That might be a Rails convention (I'm not sure) but there's a lot of things happening in here. Would it be worth raising an issue that we should add a test?

andysellick · 2025-10-13T10:06:35Z

app/views/govuk_publishing_components/component_guide/preview.html.erb

-<% content_for :application_stylesheet do %>
+<% content_for :application_stylesheet do
+  if @all_components
+    if @render_component_first


Just trying to get my head around this... if we don't render the component stylesheet first, is it loaded by the component? Only if we do render the component stylesheet first, does that mean it gets loaded a second time by the component further down?

andysellick · 2025-10-13T10:10:06Z

spec/component_guide/component_preview_spec.rb

+    visit "/component-guide/warning_text/preview"
+    expect(page).to have_css("link[rel=stylesheet]", visible: :hidden, count: 2)
+    expect(page).to have_css("link[rel='stylesheet'][href*='/assets/component_guide/application-']", visible: :hidden)
+    expect(page).to have_css("link[rel='stylesheet'][href*='/assets/govuk_publishing_components/components/_warning-text-']", visible: :hidden)


Probably don't need to also check that the two specific stylesheets are hidden, given that this has already been checked on line 47 (same comment for the following tests).

andysellick · 2025-10-13T10:13:07Z

docs/testing-components.md


 [1]: https://github.com/alphagov/govuk_publishing_components/blob/e455358c8a031403c6b5b0670f891c922919a3ca/.github/workflows/visual-regression-tests.yml
+
+## CSS Specificty testing


Nitpick: I think it's specificity.

andysellick · 2025-10-13T10:14:36Z

docs/testing-components.md

+
+## CSS Specificty testing
+
+It's possible that changes you make to a component can influence other components if component isolation breaks. To help prevent this, you can test a component alongside every other components CSS file to ensure there are no unexpected changes.


Suggestion: I think the sentence is clear enough as just It's possible that changes you make to a component can influence other components.

andysellick · 2025-10-13T10:19:20Z

docs/testing-components.md

+
+It's possible that changes you make to a component can influence other components if component isolation breaks. To help prevent this, you can test a component alongside every other components CSS file to ensure there are no unexpected changes.
+
+You can test your component alongside every other component's CSS by adding `?all_components=true` to the `/preview` route for that component. For example, visiting `component-guide/button/preview?all_components=true` will show you the button component on a page that also contains every other component's CSS file. By default, the component you're testing's CSS will load at the end of the list, and therefore you should also test how the component looks when its CSS is loaded first. This can be achieved by adding `&render_component_first=true` onto the query string, for example `component-guide/button/preview?all_components=true&render_component_first=true`.


Suggestion:

Change the component guide preview page URL as follows to test a component with other component CSS. - `?all_components=true` e.g. https://components.publishing.service.gov.uk/component-guide/button/preview?all_components=true - `?all_components=true&render_component_first=true` will load the current component CSS after other component CSS (defaults to loading the current component CSS last) e.g. https://components.publishing.service.gov.uk/component-guide/button/preview?all_components=true&render_component_first=true

andysellick · 2025-10-13T10:19:37Z

docs/testing-components.md

+
+You can test your component alongside every other component's CSS by adding `?all_components=true` to the `/preview` route for that component. For example, visiting `component-guide/button/preview?all_components=true` will show you the button component on a page that also contains every other component's CSS file. By default, the component you're testing's CSS will load at the end of the list, and therefore you should also test how the component looks when its CSS is loaded first. This can be achieved by adding `&render_component_first=true` onto the query string, for example `component-guide/button/preview?all_components=true&render_component_first=true`.
+
+We are not using these versions of the component preview on Percy in order to stay within our monthly screenshot usage limits. However you can use Percy in your PR to automatically detect any visual changes when all component's CSS are rendered at once, however the code change to achieve this should not be merged.


Suggestion: You can use Percy in your PR to automatically detect any visual changes when all component's CSS are rendered at once, however the code change to achieve this should not be merged.

andysellick · 2025-10-13T10:21:47Z

docs/testing-components.md

+
+We are not using these versions of the component preview on Percy in order to stay within our monthly screenshot usage limits. However you can use Percy in your PR to automatically detect any visual changes when all component's CSS are rendered at once, however the code change to achieve this should not be merged.
+
+To do this, navigate to `spec/visual_regression_tests/all_components_spec.rb` and replace `URI("#{link[:href]}/preview?percy=true")` with the all components query params: either ` URI("#{link[:href]}/preview?percy=true&all_components=true")` or `URI("#{link[:href]}/preview?percy=true&all_components=true&render_component_first=true")`. This will set Percy to use this new page for screenshots.


This seems quite complicated - I worry that people won't do this. Maybe not for this PR, but maybe there's a way of configuring this state more easily - perhaps by running ./startup.sh with a different parameter, or some other on/off switch.

govuk-ci temporarily deployed to components-gem-pr-5055 October 1, 2025 11:47 Inactive

AshGDS force-pushed the all-components-test branch from bc7d5c0 to c2bd428 Compare October 1, 2025 12:01

govuk-ci temporarily deployed to components-gem-pr-5055 October 1, 2025 12:01 Inactive

govuk-ci temporarily deployed to components-gem-pr-5055 October 3, 2025 10:03 Inactive

AshGDS force-pushed the all-components-test branch from baec3ea to 274e5e3 Compare October 3, 2025 10:08

govuk-ci temporarily deployed to components-gem-pr-5055 October 3, 2025 10:09 Inactive

AshGDS force-pushed the all-components-test branch from 274e5e3 to 00ced7c Compare October 3, 2025 10:11

govuk-ci temporarily deployed to components-gem-pr-5055 October 3, 2025 10:12 Inactive

govuk-ci temporarily deployed to components-gem-pr-5055 October 3, 2025 10:20 Inactive

govuk-ci temporarily deployed to components-gem-pr-5055 October 3, 2025 10:22 Inactive

govuk-ci temporarily deployed to components-gem-pr-5055 October 3, 2025 10:27 Inactive

AshGDS force-pushed the all-components-test branch from 223e9ac to 3181771 Compare October 3, 2025 10:54

govuk-ci temporarily deployed to components-gem-pr-5055 October 3, 2025 10:54 Inactive

govuk-ci temporarily deployed to components-gem-pr-5055 October 6, 2025 14:57 Inactive

AshGDS force-pushed the all-components-test branch from c6428b3 to 9154f7a Compare October 6, 2025 15:44

govuk-ci temporarily deployed to components-gem-pr-5055 October 6, 2025 15:44 Inactive

AshGDS changed the title ~~Render every component's CSS on a component preview page~~ Render component examples with every component's CSS in Percy snapshots Oct 6, 2025

AshGDS force-pushed the all-components-test branch from 9154f7a to 0c7e5bb Compare October 7, 2025 10:16

govuk-ci temporarily deployed to components-gem-pr-5055 October 7, 2025 10:17 Inactive

AshGDS force-pushed the all-components-test branch from 0c7e5bb to cd825b2 Compare October 7, 2025 11:58

govuk-ci temporarily deployed to components-gem-pr-5055 October 7, 2025 11:58 Inactive

AshGDS changed the title ~~Render component examples with every component's CSS in Percy snapshots~~ Allow every component's CSS files to render on a component's preview page Oct 7, 2025

Delete copy_to_clipboard SASS file

94dc408

It has an empty, unused stylesheet, so we can delete it.

AshGDS force-pushed the all-components-test branch from cd825b2 to c239101 Compare October 9, 2025 15:31

AshGDS changed the title ~~Allow every component's CSS files to render on a component's preview page~~ [PNP-9605] Allow every component's CSS files to render on a component's preview page Oct 9, 2025

govuk-ci temporarily deployed to components-gem-pr-5055 October 9, 2025 16:07 Inactive

AshGDS force-pushed the all-components-test branch from c239101 to dd1307d Compare October 10, 2025 11:24

govuk-ci temporarily deployed to components-gem-pr-5055 October 10, 2025 11:24 Inactive

AshGDS force-pushed the all-components-test branch from dd1307d to 1f6d957 Compare October 10, 2025 12:05

govuk-ci temporarily deployed to components-gem-pr-5055 October 10, 2025 12:06 Inactive

AshGDS added 7 commits October 10, 2025 14:35

Add 'all components' functionality to controller'

75f2d16

Add 'all component CSS' functionality to preview view

c47fdee

Generate page preview title in controller

fe258dd

Add tests for all component CSS rendering

e8175d6

Add specificty testing guidance to docs

ad83ea1

Update CHANGELOG.md

2a93d18

Add comment to PR template

b5eea1b

AshGDS force-pushed the all-components-test branch from 1f6d957 to b5eea1b Compare October 10, 2025 13:39

govuk-ci deployed to components-gem-pr-5055 October 10, 2025 13:39 View deployment

AshGDS marked this pull request as ready for review October 10, 2025 13:54

AshGDS requested review from KludgeKML and andysellick October 10, 2025 13:54

KludgeKML approved these changes Oct 13, 2025

View reviewed changes

andysellick reviewed Oct 13, 2025

View reviewed changes

AshGDS mentioned this pull request Oct 13, 2025

Fix CSS specificity issues when all components are rendered on the same page #5073

Open

21 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[PNP-9605] Allow every component's CSS files to render on a component's preview page #5055

[PNP-9605] Allow every component's CSS files to render on a component's preview page #5055

Uh oh!

AshGDS commented Oct 1, 2025 •

edited

Loading

Uh oh!

KludgeKML left a comment

Uh oh!

andysellick Oct 13, 2025

Uh oh!

andysellick Oct 13, 2025

Uh oh!

andysellick Oct 13, 2025

Uh oh!

andysellick Oct 13, 2025

Uh oh!

andysellick Oct 13, 2025

Uh oh!

andysellick Oct 13, 2025

Uh oh!

andysellick Oct 13, 2025

Uh oh!

andysellick Oct 13, 2025

Uh oh!

andysellick Oct 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		[1]: https://github.com/alphagov/govuk_publishing_components/blob/e455358c8a031403c6b5b0670f891c922919a3ca/.github/workflows/visual-regression-tests.yml

		## CSS Specificty testing


		## CSS Specificty testing

		It's possible that changes you make to a component can influence other components if component isolation breaks. To help prevent this, you can test a component alongside every other components CSS file to ensure there are no unexpected changes.


		It's possible that changes you make to a component can influence other components if component isolation breaks. To help prevent this, you can test a component alongside every other components CSS file to ensure there are no unexpected changes.

		You can test your component alongside every other component's CSS by adding `?all_components=true` to the `/preview` route for that component. For example, visiting `component-guide/button/preview?all_components=true` will show you the button component on a page that also contains every other component's CSS file. By default, the component you're testing's CSS will load at the end of the list, and therefore you should also test how the component looks when its CSS is loaded first. This can be achieved by adding `&render_component_first=true` onto the query string, for example `component-guide/button/preview?all_components=true&render_component_first=true`.


		You can test your component alongside every other component's CSS by adding `?all_components=true` to the `/preview` route for that component. For example, visiting `component-guide/button/preview?all_components=true` will show you the button component on a page that also contains every other component's CSS file. By default, the component you're testing's CSS will load at the end of the list, and therefore you should also test how the component looks when its CSS is loaded first. This can be achieved by adding `&render_component_first=true` onto the query string, for example `component-guide/button/preview?all_components=true&render_component_first=true`.

		We are not using these versions of the component preview on Percy in order to stay within our monthly screenshot usage limits. However you can use Percy in your PR to automatically detect any visual changes when all component's CSS are rendered at once, however the code change to achieve this should not be merged.


		We are not using these versions of the component preview on Percy in order to stay within our monthly screenshot usage limits. However you can use Percy in your PR to automatically detect any visual changes when all component's CSS are rendered at once, however the code change to achieve this should not be merged.

		To do this, navigate to `spec/visual_regression_tests/all_components_spec.rb` and replace `URI("#{link[:href]}/preview?percy=true")` with the all components query params: either ` URI("#{link[:href]}/preview?percy=true&all_components=true")` or `URI("#{link[:href]}/preview?percy=true&all_components=true&render_component_first=true")`. This will set Percy to use this new page for screenshots.

[PNP-9605] Allow every component's CSS files to render on a component's preview page #5055

Are you sure you want to change the base?

[PNP-9605] Allow every component's CSS files to render on a component's preview page #5055

Uh oh!

Conversation

AshGDS commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Potential things to add

Visual Changes

Uh oh!

KludgeKML left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AshGDS commented Oct 1, 2025 •

edited

Loading