We were displaying documents in five places, and in five different ways.
Sometimes with the metadata in parenthesis after the title, sometimes
with the metadata below the title, sometimes without metadata, sometimes
with an icon in front of the document, and sometimes with a separate
link to download the file.
So we're now displaying the same thing everywhere. Not sure whether this
is the best solution, but at least it's consistent.
We aren't unifying the way we display a list of documents, though, since
different sections look pretty different and I'm not sure whether the
same style would look well everywhere.
Note that we're renaming the `document` HTML class in the documents
table to `document-row` so the styles for the `document` class don't
apply here.
This way it'll be easier to change them.
Note that there were two `.document-link` elements which aren't part of
a `.documents` element. We're renaming the HTML class of the link in
investments because it didn't contain links to download documents and
are slightly duplicating the CSS in the poll answer documents in order
to keep the `word-wrap` property.
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/
The outline was invisible when we had the link containing block
elements, and I didn't manage to fix it, so the easiest solution is to
use an inline link and style the card with CSS.
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 is consistent with the usage of `$body-background`. This way
Foundation elements using `$body-font-color`, like the `<body>` tag,
will be changed when changing this variable, which wouldn't happen when
using `$text`.
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.
This way we can simplify the code a bit since Foundation automatically
chooses the text color of the caption so there's enough contrast with
the background color defined in `$orbit-caption-background`.
This way it's easier to customize colors, particularly when links use
the same colors as the text surrounding them.
Note that the `markdown-editor-header` isn't displayed since commit
76b7f66fb, which was probably an unintended side-effect. So we're
modifying the colors here as well instead of removing the element; we
might display it again in the future.
Also note the change in `.supported` only affects the proposals section;
budget investments use a different color for the `.supported` sucess
message. Not sure whether this was originally intended or done by
accident.
These elements were already using these colors because they inherited
them from their parent elements or Foundation already defined them.
Note that the only contents of `.comment-info` are: `.user-name` and
`.is-author`, `.is-association`, `.level-1`, ... and the link to the
comment. All of these elements were overwriting the `$text-medium`
color, so there's no need to set it. That means we can use the default
text color for `.user-name` without specifically setting it.
We were overwriting the color of the links, but not the color of the
links on hover.
Note we're removing the `!important` rule from the author link; after
testing it, it looks like it wasn't necessary.
This mixin was being called twice for the `.budget-investment-show`
selector; once in the CSS including this code for all the "Show
participation" pages, and once in the CSS for budget investments.
By using the Rails `button_to` helper (which generates a form), and adapting the
response to `html` and `js` formats, the feature works with or without javascript
enabled.
While reviewing commit 7702b551e, I forgot to test whether selecting
text in the budget header or clicking its link worked properly.
The negative index (-5) meant it was impossible to select its text or
click on its link.
The good news is the pseudoelement with a negative index (-1) is
considered a child of the .budget-header element, so having a negative
index will cause the pseudoelement to be render behind the content of
the .budget-header element but in front of the background of the
.budget-header element.
This is exactly what we want.
Originally, we didn't have a z-index in the .budget-header element,
meaning the pseudoelement was rendered behind the background of the
.budget-header element, meaning both backgrounds were visible. This was
OK when the background was a plain color, but it wasn't when the
background was an image.
To stress the fact that the budget header is only affected when we use
an image, I'm also moving the code inside the `.with-background-image`
selector, although it would be interesting to check whether it's a good
idea to add `z-index: 0` to the `full-width-background` mixin.
We were using very similar code for proposals, debates and investments,
so we might as well share the code between them.
Note we're using the `proposals.index.search_results` key even for
debates and investments. This will still work because the translations
shared the same text, but IMHO we should rename the key to something
like `shared.search_results_summary`. We aren't doing so because we'd
lose all the existing translations.
Defining a behavior on hover means making it different for people using
a keyboard or a touchscreen (most of the population, nowadays).
In this case, we had an accessibility issue where the message wouldn't
disappear once it appeared. That meant that, after tabbing through all
the links and buttons in, for instance, the debates index, the page
would be filled with "participation not allowed" messages, and in order
to see the information about how many people have voted, reloading the
page was required.
For touchscreen users the behavior was similar to what we get on hover,
although we've found some inconsistencies when trying to support several
elements on the same page.
We think in proposals it makes sense to hide the "support" button when
users click on it, and the same applies to the buttonsto support and
vote investment projects. However, we aren't hiding the buttons to
agree/disagree with a debate in order to keep the information about the
current number of people agreeing and disagreeing visible.
Note we're removing some support spec methods because after these
changes the duplication isn't as obvious as it was in the past.
Hovering over the votes showed a "participation not allowed" message
which was annoying when scrolling with the browser or simply moving the
mouse around the page. Furthermore, it hid the information about the
number of votes, links to show/collapse replies, ...
We're planning to change the behavior of all the "participation not
allowed" messages in order to show them on click instead of showing them
on hover (just like it's done on touchscreens). In the case of comments,
supports, however, there's very limited space in the part showing the
number of supports for comments, so adding this message without breaking
the layout is challenging.
So, for now, we're simply redirecting unauthenticated users to the login
page. If find an easy way to implement a better user interface in the
future to display the "participation not allowed" message, we might
change this behaviour.
This message is only shown in the `show` action, so it's shown at most
once in the whole page, so it doesn't take up too much space and it
isn't as overwhelming as if we were showing it on the index page, once
per debate.
We're only showing it when there are closed options, though, since
there's already a message to sign in to comment when the question
accepts open answers.
We were using the same code to render links to agree and disagree, so we
can extract a new component for this code.
We're also adding component tests to make it easier to test whether
we're breaking anything while refactoring, although the code is probably
already covered by system tests.
Since the votes mixin was only used in one place, we're removing it and
moving most of its code to a new CSS file for the shared component.
The action and the views were almost identical, with the supports
progress and the HTML classes of the success message element being the
only exceptions; we can use CSS for the styles instead.
We were using a focus outline on links, but weren't doing the same for
buttons. Since sometimes browsers use a default outline which is barely
visible, this was very disorienting when browsing using the keyboard; we
were navigating through links that clearly indicated where the keyboard
focus was, and when reaching a button suddenly we had this almost
imperceptible feedback. Even if I'm used to it, my first reaction is
always "where did the focus go?" until I realize it's now on a button.
This is even more confusing because we've got buttons looking like links
and links looking like buttons.
Note that in the rules for the `:focus` styles we're including buttons
and the `[type="button"]` attribute. This seems redundant since those
styles are already covered by the `button` selector. However, Foundation
adds styles to buttons with the `[type]` attribute. Since the attribute
selector has precedence over the tag selector, we need to use the
attribute selector as well in order to override Foundation's styles.
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.
We've deprecated the "icons" font since we started using Font Awesome
two years ago and using it caused some screen readers to announce an "l"
before the content of every list item.
The `icon-budget` hasn't been used in this context for a long time;
maybe since commit d0b8fef6b.
The `document-form` class was removed in commit 6c1d828a6.
Finally, the `topic-new` and `topic-form` were removed in commit
c887cb736.
So they follow the same convention used in proposals.
Note the styles are for elements which appear in the "new" view but not
in the "edit" view, so we only have to include them in one place.
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.
