The Web Content Accessibility Guidelines version 2.1 added a success
criterion called Non-text Contrast [1], which mentions that the focus
indicator must contrast with the background, and version 2.2 introduced
a specific one regarding focus appearance [2]. According to that
criterion, the focus indicator:
* is at least as large as the area of a 2 CSS pixel thick perimeter of
the unfocused component or sub-component
* has a contrast ratio of at least 3:1 between the same pixels in the
focused and unfocused states.
Our current solution for highlighting elements on focus has a couple of
issues:
* It doesn't offer enough contrast against the default white background
(1.6:1)
* It offers even less contrast against other backgrounds, like the
homepage banner or the featured proposals/debates
Making the color of the outline darker would increase the contrast
against these backgrounds, but it would reduce the contrast against
other backgrounds like our default brand color.
For this reason, most modern browsers use a special double outline with
two different colors [3], and we're choosing to combine an outline and a
box shadow to emulate it, using the brand color as the second color.
However, this double-colored outline doesn't work so well when focusing
on dark buttons surrounded by a light background, so instead we're using
a triple outline, which works well on any color combination [4]. Since I
feel that making the third outline 2px wide makes the overall outline
too wide, I'm making the inner outline just 1px wide since that's enough
to prevent edge cases.
Note that Foundation adds a transition for the `box-shadow` property on
`select` controls, which gets in the way of the focus we use on the
language selector. So we're removing the transition.
Also note that the box-shadow style didn't work properly with the
box-shadow we added on the `:hover` status on cards, so we're changing
the code in order to cover this case.
Finally, note that the box-shadow isn't displayed properly on multiline
links (in Chrome, not even with `box-decoration-break: clone`), like the
ones in debates/proposals/polls/investments/processes titles, so we're
changing the style of these links to `inline-block`.
[1] https://www.w3.org/TR/WCAG21/#non-text-contrast
[2] https://www.w3.org/TR/WCAG22/#focus-appearance
[3] https://www.sarasoueidan.com/blog/focus-indicators/#examining-(current)-browser-focus-indicators-against-wcag-requirements
[4] https://www.erikkroes.nl/blog/the-universal-focus-state/
This way it's going to be easier to style the link on focus, since
styles like `box-shadow` weren't working properly when we had an inline
link with block elements inside, and adding the `display: inline-block`
element to the link didn't play well with the layout we were using for
the recommendations.
We're also fixing the focus outline on recommendations, which didn't
look properly because of the border added with:
```
.recommended-index {
// (...)
@include full-width-border(top, 1px solid #fafafa);
}
```
The border was on top of the outline, breaking it. Increasing the
`z-index` of the element containing the outline solves the issue.
In a similar way, we're making sure the button to hide recommendations
stays visible so it's easier to click it.
The `inverted-selection` rules defined in the `%brand-background`
selector weren't being applied because we were using this selector in
`::before` and `::after` pseudoelements. Not sure about the reason, but
it looks like the saturation of `::after::selection` pseudoelements
resulted in invalid selectors and so the inverted selection rules were
ignored for every selection using `%brand-background`, like
`%budget-header`.
Using `@include brand-background` instead of `@extend %brand-background`
in pseudoelements solves the issue. The inverted selection might not
work in these pseudoelements, but we don't need it there since these
pseudoelements don't have content.
This is the only part of the sidebar that needs to be re-rendered after
an AJAX request adding or removing investments to a ballot, so having a
separate view just for it will make it easier to simplify the code.
Until now, overwriting the styles for a certain tenant was a very
tedious task. For example, if we wanted to use a different brand color
for a tenant, we had to manually overwrite the styles for every element
using that color.
It isn't possible to use different SCSS variables per tenant unless we
generate a different stylesheet per tenant. However, doing so would make
the CSS compilation take way too long on installations with more than a
couple of tenants, and it wouldn't allow to get the colors dynamically
from the database, which we intend to support in the future.
So we're using CSS variables instead. These variables are supported by
97% of the browsers (as of October 2022), and for the other 3% of the
browsers we're using the default colors (SCSS variables) instead.
CSS variables have some limitations: for instance, it isn't possible to
use functions like `lighten`, `darken` or `scale-color` with CSS
variables, so the application might behave in a strange way when we use
these functions.
It also isn't possible to automatically get whether black or white text
makes a better contrast with a certain background color. To overcome
this limitation, we're providing variables ending with `-contrast`. For
instance, since the default `$brand` color is a dark one, when assigning
a light color to `--brand`, we probably want to assign
`--brand-contrast: #{$black}` as well, so the text is still readable.
We were using each one half the time, while they both had the same value
by default. It was impossible to know when me meant "use a dark color
here" or "use the secondary brand color" here.
So now we're only using one variable, so it's easy it'll be easy to add
CSS custom properties to overwrite this variable. We're choosing
`brand-secondary` because its name makes it less problematic to use a
light color.
This way we simplify the code a bit.
Note we're only using this function when variables for background colors
are already defined, since that means customizing the variable using the
background color will automatically change the color of the text.
Customization isn't easier when using raw colors.
We were defining (for instance) white text against the `$brand`
background. That meant that, if somebody customized the `$brand` color
so it used a light color, they had to customize the text color as well
in order to guarantee proper contrast between text and background
colors.
So we're using `color-pick-contrast` instead, which means we don't have
to manually calculate whether white or black will be the color which
makes the text more readable.
As mentioned in commit bc0f04075, a <select> field which submits its
form on change causes many accessibility and usability issues. In this
case there was also an incompatibility with the advanced search filter
which caused a bug solved in commit 541a5fa89.
So the question is where to position the filters and how to display
them. One factor to take into the account is how relevant these filters
are, particularly compared to the links to select the prefered order,
since we don't usually give users the choice of both filters and orders.
Our filters don't really make sense until the valuation phase starts,
since before that phase investments aren't selected nor their
feasibility is decided.
After that phase, the only phase where citizens are really involved
is the final voting; the rest of the phases are done by valuators and
administrators. In the final voting, citizens can only vote on selected
projects, and that's the default filter during that phase.
So these filters are mainly there for information purposes, and not to
help citizens in the phases where they're actually involved (accepting
projects, selecting projects and balloting).
Orders, on the other hand, play a crucial role during the final voting
phase. Since citizens might have already voted for a few projects and
have, let's say, 100,000€ left, ordering by price allows them to find
which projects are within their remaining budget.
In conclusion, orders are more important than filters, and so they
should have a more prominent place.
For consistency with the proposals section, where we've got some links
in the sidebar (bottom part of the page on small screens) providing a
similar funcionality, like accessing selected proposals or archived or
retired proposals, we're moving the investments filters to the sidebar
(bottom part of the page on small screens) as well.
Before, users needed to navigate to the list of groups in order to
add, edit or delete a group.
Also, they need to navigate to the list of groups first, and then to
the list of headings for that group in order to add, edit or delete a
heading.
Now, it's possible to do all these actions for any group or heading
from the participatory budget view to bring simplicity and to reduce
the number of clicks from a user perspective.
Co-Authored-By: Javi Martín <javim@elretirao.net>
This way we remove duplication and it'll be easier to add better support
for RTL languages.
In a few years this might not be necessary since support for the `gap`
property in a flexbox layout will improve. At the time of writing,
however, only 86.5% of the browsers support it [1].
[1] https://caniuse.com/flexbox-gap
When render the investment list component with the link "see all
investments", now we redirect to groups index page when a budget has
multiple headings.
The budget header was supposed to be huge, but only in the participatory
budgets index or show actions. It was still huge, with plenty of empty
space, when there was no budget, or in the "submit my ballot" and
"select a heading" pages.
Since we're going to reuse this pattern in other forms, we shouldn't
rely on the header having just one element. There could be a subtitle.
So we're changing the CSS to be less dependent on a very specific HTML
structure.
Regarding the subtitle, the original idea was to have both an <h1> and
an <h2> element inside the header. However, the W3C advices against it
[1]:
> h1–h6 elements must not be used to markup subheadings, subtitles,
> alternative titles and taglines unless intended to be the heading for
> a new section or subsection.
So we ended up including the subtitle inside he <h1>. We could also add
it in a separate <p> tag. However, in this case I think it's better to
include it in the <h1> (and in the <title> tag) because it helps to
uniquely identify the current page from other pages.
Due to some rounding issues in Firefox, we're manually moving the polygon
6px so there isn't a blank space between it and the icon on the right.
And due to rounding issues in Chrome, we're adding one extra pixel to
the bottom of the polygon defining the clip-path.
[1] https://www.w3.org/TR/html52/common-idioms-without-dedicated-elements.html#common-idioms-without-dedicated-elements
So we don't add the same lines to pretty much every stylesheet we
create.
Eventually we'll remove this code and add a padding to every <main>
element, or (even better) to the <body> element itself.
In commit 49b406199 we added an extra `<span>` element just so we could
add an icon to the right while maintaining both the title and subtitle
on the left.
We can do the same thing without the extra `<span>` element, absolutely
positioning the element and leaving enough padding.
We had an additional `<div>` just to add a background color, when we can
do it by applying the background color to the whole `<main>` element and
then the body background color to the optional fields.
However, I've decided not to do so. The main purpose of changing the
background color is to highlight the required fields. The benefits of
changing the background color of the header as well are unclear. When in
doubt, we're using the solution which requires less code.
Now the padding is only applied in two places (administration forms) so
we can apply it just there instead of applying it everywhere and then
removing it in most places. We're using the `column` class here because
it's what's used in the rest of the fields of these forms and because we
haven't defined (yet) general margin/padding rules for the
administration views.
We don't need any row classes anymore because the <body> already has a
maximum width. As for columns, we only have one column in this form, so
we don't need them either. Besides, the form's parent element already
has a padding.
Although most CONSUL installation don't enable the translation
interface, we're adding some code to take this case into account.
We were using these rules in order to set the maximum width of an
element to `$global-width`. However, since we now do so in the <body>
element, there's no need to apply these rules to "rows".
Note we're adding `overflow: hidden` to the budget subheader. That's
because it only contains `float` element inside, and we're now missing
the `.row::before` and `.row::after` rules which make sure float
elements are rendered properly.
We weren't using a global maximum width for the <body> element because
we wanted the background of some elements to cover the whole screen. If
the body didn't cover the whole screen, then we would have to find a way
to extend the background beyond the limits of the body.
Elements can take the whole screen width using a width of 100 viewport
width (vw) units, which weren't as widely supported when CONSUL
development started as they are today.
However, there's a gotcha will vw units; they don't take into account
the vertical scrollbars browsers add when scroll is needed. That means
that an element with a width of 100vw would cause a *horizontal*
scrollbar when the vertical scrollbar appears on the screen. So
approaches like this one wouldn't work:
```
body {
margin-left: auto;
margin-right: auto;
max-width: $global-width;
}
@mixin full-background-width {
&::before {
margin-left: calc(50% - 50vw);
margin-right: calc(50% - 50vw);
}
}
```
We could add `overflow-x: hidden` to the body to avoid the horizontal
scrollbar. However, on certain screens sizes that could cause some
content to disappear if there isn't enough horizontal space for all the
elements.
If we tried some other solution based on using `max-width` with `margin:
auto` on the <body> element, it would result in a body having a fixed
width and a variable margin (depending on whether there's a scrollbar).
So it wouldn't be possible to set a negative margin on child elements
based on the margin of the body, because that margin would be different
depending on the existence of a scrollbar.
So, instead, we're adding a fixed margin to the body, which depends on
the viewport width and the font size of the <html> element. With this
approach, when a vertical scrollbar appears, the margin of the <body> is
still the same; what changes is its width. That means we can set a
negative margin on child elements based on the margin of the <body>. No
horizontal scrollbar will appear.
Note we're slightly duplicating the code by using two variables
(`$body-margin` and `$full-width-margin`) to do the same thing. We could
simply use `$body-margin` and then use `calc(-1 * #{$body-margin})` in
our `full-width-background` mixin. We aren't doing so because some old
versions of the Android browser and Internet Explorer can't handle this
operation. Since our whole layout is based on these properties, in this
case supporting old browsers is quite important.
For similar reasons we're using a breakpoint instead of using the
`max()` function like: `Max(0px, calc(50vw - #{$global-width / 2}))`. At
the time of writing, `max()` is only supported in about 91% of the
browsers.
With this change, we no longer need to add `row` elements to make sure
we don't exceed the maximum width; the <body> element takes care of
that.
Also note banners sometimes have a full background and sometimes they
don't, depending on which page they appear. We're adding specific rules
for them.
Finally, the code for full width borders is a bit brittle; sometimes we
want the border to cover an element, and sometimes we don't. For
example, we had to slightly change the way the border of the "tabs" in
legislation processes is rendered. Without these changes, the borders
wouldn't overlap as we intended. We also had to add a `z-index` to
navigation links so their bottom outline is visible when they're
focused. The recommendations have a border with the same color as the
background so it's painted on top of the border of the `help-header`
section.
We're using `background: #fff` and `background: $white` in many places.
Sometimes we mean "use the same background as the body", which means if
we change the body background so it's, let's say, dark, we'll also have
to change all these places.
So now we're using `$body-background` in more places, so changing the
general background color is easier.
There are still some places where we use `#fff` or `$white`. Sometimes
it's hard to tell whether the intention is "use a white background here"
or "use the same background as the body here". When in doubt, I've left
it the way it was.
Just for testing purposes, I've tested locally how things would look
like if we added this code to `_consul_custom_overrides.scss`:
```
$body-background: #fea;
$card-background: $body-background;
$tab-background: $body-background;
$tab-content-background: $body-background;
$table-background: $body-background;
```
Or:
```
$body-background: #333;
$text: #fcfcfc;
$body-font-color: $text;
$card-background: $body-background;
$tab-background: $body-background;
$tab-content-background: $body-background;
$table-background: $body-background;
```
Testing shows we've still got a long way to go to make it easy to add
custom color themes, since there are many custom colors in the code.
Hopefully these changes bring us one step closer.
As mentioned in commit 5214d89c8, there are several issues with
submitting a form when a `<select>` tag changes. In particular, keyboard
users might accidentally fire the event while browsing the options, and
screen reader users will find a form with no obvious way to submit it.
In this case, there's an extra problem: in commit be8a0dbe8 we added a
second `<select>` field to this form, which also submitted on change.
Sometimes users changed one of the values and wanted to change the other
value as well before submitting the form. However, it wasn't possible,
because we would submit it before they had a chance to change the second
value.
So now we don't submit the form on change and add a submit button. This
is similar to what we do in the "Advanced filters" we use in several
places.
Using `inherit` is IMHO more expressive since it means "use the color of
the parent element".
This is particularly useful for CONSUL installations using custom
styles. Consider the following code:
```
h2 {
color: $white;
a {
color: $white;
}
}
```
If we'd like to customize the way headings look, we'd have to override
two colors:
```
h2 {
color: $red;
a {
color: $red;
}
}
```
Consider the scenario where we use `inherit`:
```
h2 {
color: $white;
a {
color: inherit;
}
}
```
Now we only need to override one color to change the styles:
```
h2 {
color: $red;
}
```
The color we used offered a contrast of 3.94 against the background. The
minimum requirement for AA level is a contrast of 4.5, and we usually
aim for a contrast of 5 at least.
So we're making the text slightly darker so it's easier to read.
Note one of the tests dealing with random results is a bit flaky; since
it's a permutation selecting 7 objects out of 12, it will fail about
once every 4 million times. We think this is acceptable.
Co-Authored-By: Julian Nicolas Herrero <microweb10@gmail.com>
Note we're using an extra `<span>` element but we could use a CSS grid
layout instead. We're not using it because browser compatibility is only
94.56% at the time of writing.
Note we're absolutely positioning the link instead of the icon; that way
keyboard users will be able to focus on the icon. Until now, users would
focus on an empty link.
For the same reason, we couldn't use `click_link` with Capybara, since
it would fail to click an empty link. Now we can.
Co-authored-by: Javi Martín <javim@elretirao.net>
Setting the color to `$white` or `#fff` while setting the background to
`$brand` is a pattern we were using in many places. Since we're going to
edit it in order to fix the `::selection` behavior, we're defining the
pattern in one place.
