[WIP] Reduce base link specificity #1054

maureenlholland · 2025-04-16T10:28:25Z

Description

This is more a thought experiment than anything at this stage. The idea is to reduce base element link specificity so it is easily overridden by a single class

Base element specificity: 0 0 1
not visited

visited

Class specificity: 0 1 0

NOTE: the danger of custom properties is that they inherit all the way down the tree, so could be going further than desired if "donut scope" was intended

I have documented this change in the design system.
I have recorded this change in CHANGELOG.md.

Issue

Add a link to a related GitHub issue if applicable.

Testing

Enter helpful notes for whoever code reviews this change.

This keeps all base element styles at a single element level of specificity and ensures any class will overrule the styles

maureenlholland · 2025-04-16T11:07:46Z

Hoping this direction is in line with transition to CSS variables

maureenlholland · 2025-04-16T11:29:51Z

assets/sass/protocol/base/elements/_links.scss

-:link {
-    color: $link-color;
+a {
+    color: var(--link-color);


This was interesting. I thought I could redeclare the --link-color var within the :visited selector scope, but it didn't seem to take effect as computed style (tested with and without the :where() selector). Dev tools seems to show both the correct variable and the wrong computed style 🤷‍♀️

:root { --link-color: default-color; --link-color-visited: visited-color; } a { color: var(--link-color); } a:where(:visited) { --link-color: var(--link-color-visited); }

pseudo-class variable correctly identified
computed value still default color

root inheritance correctly overruled

^unrelated, looks like we have a mixed up value declaration on :root, visited hover color should be #952bb9

I'm worried about using :where since the support for it is less wide spread than support for dynamic properties. Can you help me understand what would happen if a visitor had variable support but not where support? Links are visible they just don't get hover/focus? Or something more dire?

I looked into CSS layers as a possible solution (I am so excited for these!) but the support for them is about the same as support for :where()

When custom properties are supported but :where() is not, browsers will ignore any :where() selectors, so you get default user agent styles for hover/focus etc.

vs. supported and applying the :where() rules

So on a background set to black with a CSS variable they will get blue/purple links?

Will check tomorrow. I think they will get the --link-coloror --link-color-visited value. If we use mzp-t-dark for dark background, the links will still have good contrast (those variables will respond to the dark theme), but their color will not change on hover/focus.

Ok, so older browser links would always get the --link-color regardless of state or :visited status (all those rules are ignored). The correct link color will apply according to light/dark theme.

maureenlholland · 2025-04-16T11:36:25Z

assets/sass/protocol/base/elements/_links.scss


+// any descendant link will inherit dark theming (replace light-links mixin)
+// this might belong in root file? site-wide dark theme class
 .mzp-t-dark {


inherited values

maureenlholland · 2025-04-16T11:38:14Z

assets/sass/protocol/base/elements/_links.scss

+
+// any descendant link will inherit white theming (replace white-links mixin)
+// link-specific theme class
+.mzp-t-white-links {


Inherited values

I love the move the variables here! We need to be careful we also move to variables for the background colours at the same time so we don't get in a circumstance where the background is defined as dark using a hex colour but the component depends on variables for the links.

Perhaps the prudent thing to do is to bundle the CSS variable changes into one big point release version that we test on un-supporting browsers.

maureenlholland · 2025-04-16T11:39:37Z

assets/sass/protocol/base/elements/_links.scss

-        &:active {
-            color: var(--link-color-visited-hover);
-        }
+    &:where(:hover, :focus, :active) {


wiping out specificity of stateful pseudo-classes with :where()

Another thing we could do to make styling links easier would be to drop the separate styles for visited links on hover/focus/active and rely on source order for the override.

Link

Visited

Hover

Active

Focus

I've always found the a:link:visited:hover edge case to be confusing.

Will add a commit with source order for comparison

The only potential conflict here is that a stateful pseudo-class + element selector will beat a component class selector (if it doesn't also explicitly override the state). This is most likely to happen with button component and link-specific visited state.

We could unnest the link states so they are only 0,1,0 specificity and rely on source order to override (basic element styles are overruled by component styles)

Or we could also include the :visited state selector on any components that could also be links under the hood 0,2,0 beats 0,1,1

janbrasna

This makes sense, looks elegant, and is easy to follow/understand. (Redefining the vars for states as shown above resulting in the rendering woes looks cool at first, but this take looks more reliable.)

The tricky part might be following the themes to the actual components, to make sure it either still works as intended, or what tweaks could be useful there… as it's usually the components being consumed and redefined downstream causing the specificity issues, e.g. the Modal: (#758)

protocol/assets/sass/protocol/components/_modal.scss

Lines 104 to 106 in d34e087

    
           .mzp-c-modal-overlay-contents { 
        
               @include text-body-lg; 
        
               @include light-links;

janbrasna · 2025-04-16T22:51:17Z

assets/sass/protocol/base/elements/_links.scss

+// this might belong in a different CTA file?
+// it's not meant to apply to `a` elements unless they have the class added directly
+// the other classes in this file are theme containers that select `a` elements inside them
 .mzp-c-cta-link {
-    font-family: $button-font-family;
+    font-family: var(--button-font-family);
    font-weight: bold;


"this might belong in a different CTA file?"

IIUC the organization of files match the grouping of component pages, so this chubby "CTA link" styling seems to belong with these, as it's one of the variants or states of the Links styles:

https://protocol.mozilla.org/components/detail/links--call-to-action

(It feels like it's listed as a flavor of a base element, not treated as a component per se — to be used mostly in other components…)

assets/sass/protocol/base/elements/_links.scss

…me classes

janbrasna

These should also no longer complain:

janbrasna · 2025-04-28T14:57:18Z

assets/sass/protocol/components/_button.scss


-.mzp-c-button, /* stylelint-disable-line no-duplicate-selectors */
-a.mzp-c-button {
+.mzp-c-button /* stylelint-disable-line no-duplicate-selectors */ {


Suggested change

.mzp-c-button /* stylelint-disable-line no-duplicate-selectors */ {

.mzp-c-button {

janbrasna · 2025-04-28T14:57:29Z

assets/sass/protocol/components/_button.scss

 // * -------------------------------------------------------------------------- */
 // Primary

 /* stylelint-disable-next-line no-duplicate-selectors */


Suggested change

/* stylelint-disable-next-line no-duplicate-selectors */

We do still have a duplicate selector here (there's no mzp-t-primary theme class to distinguish this selector from the other default button styles), but this is the only place we need the disable comment now

stephaniehobson · 2025-05-12T22:47:06Z

assets/sass/protocol/components/_button.scss

-        background-color: transparent;
-        border-color: $color-black;
-        color: $color-black;
+.mzp-c-button.mzp-t-secondary {


This is so much nicer, I want this to work 😭

stephaniehobson · 2025-05-12T22:48:16Z

assets/sass/protocol/includes/themes/_firefox.scss

    --link-color-inverse: #{tokens.$color-blue-10};
    --link-color-visited-hover-inverse: #{tokens.$color-violet-05};
-    --link-color-visited-hover: #{tokens.$color-link-hover};
+    --link-color-visited-hover: #{tokens.$color-link-visited-hover};


Another place that would be simplified by having the same hover state for both visited and unvisited links.

maureenlholland · 2025-05-13T11:14:33Z

assets/sass/protocol/base/elements/_links.scss

+
+    &:hover, &:active, &:focus {
+        /* stylelint-disable-next-line color-function-notation */
+        color: var(--link-color-with-state, hsl(from var(--link-color) h s calc(l - 10)));


Demo of functional hover color approach:

By default, we automatically darken the lightness of the color by 10%

We can override this default with another function (i.e. dark theme automatically lightens color) or another set value (i.e. white theme uses white)

relative colors with light & dark hover

We could also do this with sass color.scale for better support but we have to use a sass variable as the input argument (CSS custom properties are not available as values at build time)

This would allow us to drop support for hover tokens and (hopefully) simplify maintenance

maureenlholland · 2025-07-09T15:27:59Z

After internal discussion, we want to drop support for :hover:visited style and rely on order of appearance to ensure :hover style always applied on hover state (whether link is visited or not)

Do Not Merge until Icon release is published

stephaniehobson · 2025-08-11T19:33:18Z

Closing in favour of #1077

maureenlholland added 2 commits April 16, 2025 11:24

Reduce base link specificity

45aa3a8

Remove stateful pseudo-class specificity with :where

78812ed

This keeps all base element styles at a single element level of specificity and ensures any class will overrule the styles

maureenlholland force-pushed the reduce-base-link-style-specificity branch from 4de77cb to 8931907 Compare April 16, 2025 10:57

maureenlholland added the Discussion 🚲 Something we need to discuss label Apr 16, 2025

Add comments

1dd40e8

maureenlholland force-pushed the reduce-base-link-style-specificity branch from 8931907 to 1dd40e8 Compare April 16, 2025 11:17

maureenlholland added 2 commits April 16, 2025 12:20

Fix syntax

459e73d

Move visited outside base selector, explicitly set rules

eacd7da

maureenlholland commented Apr 16, 2025

View reviewed changes

janbrasna reviewed Apr 24, 2025

View reviewed changes

maureenlholland added 4 commits April 28, 2025 14:38

Fix visited hover token name

003c1a6

Remove extra button selector for links styled as buttons

aacae3b

Unnest button theme selectors

763299c

Update mixins to use custom property approach, add note to prefer the…

9de9e96

…me classes

janbrasna reviewed Apr 28, 2025

View reviewed changes

maureenlholland force-pushed the reduce-base-link-style-specificity branch from dee5f6e to 9de9e96 Compare April 28, 2025 15:37

Clean comments and fix spacing

631f613

stephaniehobson reviewed May 12, 2025

View reviewed changes

Use source order for stateful link styles

97cc65c

maureenlholland force-pushed the reduce-base-link-style-specificity branch from bce794b to 97cc65c Compare May 13, 2025 10:54

Demo only: use CSS color function for hover styles

17b6cf4

maureenlholland commented May 13, 2025

View reviewed changes

maureenlholland added Do Not Merge ⚠️ Do Not Merge and removed Discussion 🚲 Something we need to discuss labels Jul 9, 2025

stephaniehobson mentioned this pull request Jul 28, 2025

Remove :hover:visited styles and decrease base link specificity (Fix #1071) #1077

Merged

2 tasks

stephaniehobson closed this Aug 11, 2025

	.mzp-c-modal-overlay-contents {
	@include text-body-lg;
	@include light-links;

	.mzp-c-button /* stylelint-disable-line no-duplicate-selectors */ {
	.mzp-c-button {

[WIP] Reduce base link specificity #1054

[WIP] Reduce base link specificity #1054

Uh oh!

Conversation

maureenlholland commented Apr 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issue

Testing

Uh oh!

maureenlholland commented Apr 16, 2025

Uh oh!

maureenlholland Apr 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maureenlholland Apr 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephaniehobson May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephaniehobson May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maureenlholland May 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janbrasna left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

janbrasna 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!

maureenlholland May 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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

maureenlholland commented Apr 16, 2025 •

edited

Loading

maureenlholland Apr 16, 2025 •

edited

Loading

maureenlholland Apr 16, 2025 •

edited

Loading

stephaniehobson May 12, 2025 •

edited

Loading

stephaniehobson May 12, 2025 •

edited

Loading

maureenlholland May 13, 2025 •

edited

Loading

maureenlholland May 13, 2025 •

edited

Loading