3ae8d7b863
For accessibility reasons[1], it's recommended not to use "here"/"click here"/"more" as the title for a link. When screen reader users are tabbing through all links on the page, they'll miss the context of "read more about X" preceding the "here". Thankfully, the sentences in the are largely good to go, so the "here" can be dropped in favour of the last part of the sentence to give the link title more meaning. Some of these text changes may seem trivial, but when considering the link text outwith its context sentences, the text has some more meaning for those reading them through screen readers. (e.g. "API documentation" -> "`number_to_currency` API documentation") [1]: https://www.gov.uk/guidance/content-design/links#writing-link-text |
||
---|---|---|
.. | ||
assets | ||
bug_report_templates | ||
rails_guides | ||
source | ||
.document | ||
.rubocop.yml | ||
CHANGELOG.md | ||
rails_guides.rb | ||
Rakefile | ||
README.md | ||
w3c_validator.rb |
Rails Guides Redesign 2024
About the Project
The Rails Guides Visual Refresh occurred in Q1 2024, and was intended to bring the visual style of the guides inline with the rubyonrails.org site.
Editing Dependencies
The editing files for the Guides rebuild reside in stylesrc
and use SCSS to improve developer experience. The code base relies on include_media
(https://eduardoboucas.github.io/include-media/) to enable inline media-queries adjustments. We've also relied on the standard normalize.css
(https://necolas.github.io/normalize.css/) to help bring all browsers together.
Building the Guides in Development
To generate new guides into static files, type rake guides:generate
from inside the guides
folder. If you make changes to the HTML or ERB, you'll need to remove the "output" directory before running this command. The master SCSS files (style.scss, highlight.scss) will compile as part of this process.
FAQ
Why are you not using CSS variables?
Per the MDN documentation on CSS custom properties (https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties), they are not supported in media or container queries at this point (Feb 2024). They may in future releases, and we should pivot to that when they are more wholistically supported. SCSS variables, because they are interpolated at build, serve a similar purpose and allow us the flexibility to support much older browsers.
Why do we include LTR and RTL?
LTR/RTL (Left to right/right to left) is a layout change based on the nature of the language the site is being displayed in. Arabic and Farsi are two well known "RTL" languages. If the site is automatically translated, then the layout will adjust (mirror horizontally) to be more in line with the text.
Why is Dark Mode in a separate file
IncludeMedia does not handle prefers-color-scheme
at this time, so it was extracted.