7d0aeeefe5
* Improve format and clarity of the docs [ci skip] While this change produces a lot of git noise by enacting what seems like an arbitrary linewrap on most of the files in the documentation it will result in better version control and tracking of the changes in the documentation. For example, as it currently stands, if one was to make a PR to move a comma in a sentence because each paragraph in most of the files is on a single line, that small change would look in the git history like the author had modified the entire paragraph. In reality, this author just moved a comma. This change also includes a significant number of modifications to the more article-esque docs. Many of these docs were written in a sort of stream-of-conciousness and aren't as easy to read as they could be. Hopefully this is the first of several readability changes. If we could get these docs to a more accessible reading level, we would probably see an increase in contributions. :) * Delegate markdown wrapping to Prettier * Add linewrapping explanation in the docs [ci skip]
97 lines
3.4 KiB
Markdown
97 lines
3.4 KiB
Markdown
---
|
|
title: Theming Guidelines
|
|
---
|
|
|
|
# Theming Guidelines
|
|
|
|
DEV supports different themes, such as Default, Night, Pink.
|
|
|
|
You can switch the theme at <http://localhost:3000/settings/misc> in the "Style
|
|
Customization" section.
|
|
|
|
These themes are powered by [CSS custom
|
|
properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties),
|
|
loaded at runtime by Javascript via `layouts/_user_config.html.erb`.
|
|
|
|
An example of how it works:
|
|
|
|
```javascript
|
|
<script>
|
|
try {
|
|
var bodyClass = localStorage.getItem('config_body_class');
|
|
document.body.className = bodyClass;
|
|
if (bodyClass.includes('night-theme')) {
|
|
document.getElementById('body-styles').innerHTML = '<style>\
|
|
:root {\
|
|
--theme-background: #0d1219;\
|
|
--theme-color: #fff;\
|
|
--theme-logo-background: #0a0a0a;\
|
|
--theme-logo-color: #fff;\
|
|
--theme-anchor-color: #17a1f6;\
|
|
--theme-secondary-color: #cedae2;\
|
|
--theme-top-bar-background: #1c2938;\
|
|
--theme-top-bar-background-hover: #27384c;\
|
|
--theme-top-bar-color: #fff;\
|
|
--theme-top-bar-search-background: #424a54;\
|
|
--theme-top-bar-search-color: #fff;\
|
|
--theme-top-bar-write-background: #00af81;\
|
|
--theme-top-bar-write-color: #fff;\
|
|
--theme-container-background: #141f2d;\
|
|
--theme-container-accent-background: #202c3d;\
|
|
--theme-container-background-hover: #37475c;\
|
|
--theme-gradient-background: linear-gradient(to right, #293d56 8%, #282833 18%, #293d56 33%);\
|
|
--theme-container-color: #fff;\
|
|
--theme-container-box-shadow: none;\
|
|
--theme-container-border: 1px solid #141d26;\
|
|
--theme-social-icon-invert: invert(100)</style>'
|
|
```
|
|
|
|
Within SCSS files located at `app/assets/stylesheets` you can use `var()`
|
|
statements, which will call these CSS custom properties. If a CSS custom
|
|
property is not defined `var()` will fall back on the second parameter provided,
|
|
which can be a SCSS variable defined in `app/assets/stylesheets/variables.scss`.
|
|
|
|
An example of how to use `var()`:
|
|
|
|
```scss
|
|
div {
|
|
color: var(--theme-color, $black);
|
|
}
|
|
```
|
|
|
|
Note that fallback values aren't used to fix the browser compatibility. If the
|
|
browser doesn't support CSS custom Properties, the fallback value won't help. To
|
|
prevent this issue on older browsers, we need to write our styles like this:
|
|
|
|
```scss
|
|
div {
|
|
color: $black;
|
|
color: var(--theme-color, $black);
|
|
}
|
|
```
|
|
|
|
This can be too much work and browser fallback can be forgotten. For a better
|
|
developer experience, you should use the two mixins defined in
|
|
`app/assets/stylesheets/_mixins.scss` called `themeable` and
|
|
`themeable-important`. They take three arguments. The first argument is the CSS
|
|
property like `color` or `background`, the second argument is the CSS custom
|
|
property name (without `--`) like `theme-color`, and the third argument is the
|
|
CSS value, i.e., `$black` or `white`.
|
|
|
|
Make sure to import the mixin in your SCSS file and use it like this:
|
|
|
|
```scss
|
|
div {
|
|
@include themeable(color, theme-color, $black);
|
|
}
|
|
```
|
|
|
|
`themeable-important` is used when a CSS variable requires `!important` as a
|
|
postfix of the CSS property's value where the CSS variable is being used. You
|
|
can use it the same way you would use `themeable` mixin, but you should avoid
|
|
`!important` if possible.
|
|
|
|
# Other user config
|
|
|
|
In addition to themes, users can also directly configure their preferred fonts
|
|
and their nav bar preferences. The implementation of these is similar to themes.
|