Guidelines:CSS

From Zelda Wiki, the Zelda encyclopedia
Jump to navigation Jump to search

Cascading Style Sheets (CSS) is the language used to define Zelda Wiki's appearance. It is used to customize MediaWiki's default interface and its various skins. It is also used to define the presentation of templates.

If you have questions about Zelda Wiki's CSS, we invite you to ask them in #wiki-tech on Discord.

If you would like to help improve the wiki's CSS, Category:Templates needing CSS improvements lists templates which do not follow the best practices outlined below.

Learning CSS

If you are new to CSS, check out the following resources:

CSS at Zelda Wiki

Zelda Wiki uses Extension:TemplateStyles to apply CSS to templates. See Category:Template Styles for a list of the wiki's template-specific CSS files.

CSS for the general site interface is found on the following staff-restricted pages:

  1. MediaWiki:Gadget-Site.css and MediaWiki:Gadget-Variables.css, for CSS common to desktop and mobile views
  2. MediaWiki:Common.css and MediaWiki:Mobile.css, for CSS specific to the desktop view or mobile view, respectively
  3. MediaWiki:Vector.css and MediaWiki:Timeless.css, the default desktop and mobile skins, respectively
  4. Various Category:Gadget Styles

Non-default skins are maintained unofficially by the community. See Category:Community-Maintained Skins.

Best Practices

When writing CSS for Zelda Wiki, try your best to adhere to these best practices. If you see a template that does not follow these practices, please add it to Category:Templates needing CSS improvements.

Design Tokens

When choosing CSS values such as colors or spacing units, try as much as possible to use the values in MediaWiki:Gadget-Variables.css. These variables constitute Zelda Wiki's design tokens. Using them ensures a consistent design across the wiki. In particular, using variables instead of hard-coded colors will allow us to support multiple color themes on the wiki.

Unfortunately, CSS variables won't work in template styles until we upgrade to MediaWiki 1.39. For now, we can copy the values of these variables into template styles. Once we upgrade we can do a site-wide text replacement to swap in variable references.

Inline Styles

Generally, if a template contains anything but the smallest amount of styling, it should be placed in a separate CSS file to simplify maintenance. This enables the use of more advanced styling such as media queries for responsive design (see below).

Avoid using inline styles in articles, especially when styles may be copied to other pages. The duplication makes the styles difficult to maintain if they ever need to be changed.

TFH Red Link desperate.png
Don't
TFH Green Link ok.png
Do

Don't use inline styles in templates.

<div style="display: flex; border-radius: 8px; border: 1px solid #426787; background-color: #1d578b;"><span style="font-weight: bold; font-size: 2rem">...</span></div>

Do use TemplateStyles.

<templatestyles src="Template:TemplateName/Styles.css"/><div class="class-name-here"><span class="other-class-name">...</span></div>
.class-name-here {
  display: flex;
  background-color: #1d578b;
  border: 1px solid #426787;
  border-radius: 0.5rem;
}

.other-class-name {
  font-weight: bold;
  font-size: 2rem;
}

Responsive Design

Templates should be responsive—they should not appear broken when viewed on mobile devices.

To achieve this, you may need to use media queries.

Media Queries

Note how Template:Main Page Categories/Styles.css, for example, starts with CSS that works on small screens then uses media queries to have the template make use of the additional space:

.main-page-categories {
	margin-top: 2.5rem;
}

.main-page-category-item {
	position: relative;
	height: 75px;

	margin-top: 1rem;
	max-width: 20rem;
}

/* ... */

@media (min-width: 53.125rem) {
	.main-page-categories {
		display: flex;
		flex-wrap: wrap;
		justify-content: center;
	}
	.main-page-category-item {
		width: 12.5rem;
		margin-right: 1.25rem;
		margin-top: 0;
	}
}

Targeting Screen Sizes

This approach is advisable only when responsiveness cannot be achieved by using the same HTML on all screen sizes, as shown above.

In some cases you may need to show different content on smaller screens versus larger ones. Module:Data Table does this for the Upgrading page, for example.

Zelda Wiki has classes for targeting specific screen sizes.

Resize your window to see the content change
Input Output
<div class="size-small-down">Content on screens size <code>small</code> and down</div>
<div class="size-medium-up">Content on screens size <code>medium</code> and up</div>
Content on screens size small and down
Content on screens size medium and up

MediaWiki:Gadget-Site.css defines the following sizes:

  • small: under 53.125rem (850px)
  • medium: 53.125rem (850px)
  • large: 68.75rem (1100px)
  • xlarge: 90rem (1440px) and over

A nomobile class also exists which hides content on screens smaller than 850px when using the mobile skin (Timeless). However, completely hiding content on mobile is generally not recommended as all readers of the wiki should have access to the same information. Exceptions include non-essential navigation elements, particularly imagemaps such as Template:Great Plateau which are only fully usable with a mouse.

rem units

Zelda Wiki uses rem units for most size-related design tokens. On most browsers, 1rem equals 16px by default. Using rem units ensures that all users have a consistent experience regardless of their font settings.

There is some debate among web developers as to whether rem units should be used to this extent. We do not claim to be experts in this field and defer to the judgement of the makers of design systems such as Lightning, Material, and Polaris, who use rem values in their design tokens for web.

Selectors and Class Naming

Assign unique class names such that elements (even sub-elements) can be targeted with a single class selector. Avoid using IDs and tags in CSS selectors. Here's why.

The BEM Methodology is recommended for this purpose.

TFH Red Link desperate.png
Don't
TFH Green Link ok.png
Do

Don't use generic class names that require the use of descendant combinators in selectors.

<div class="knight-challenge">
  <div class="card">
    <div class="header">
    <div class="content">
  </div>
</div>
.knight-challenge .card .header {
  font-weight: bold;
}

Do use highly specific class names such as BEM naming.

<div class="knight-challenge">
  <div class="knight-challenge__card">
    <div class="knight-challenge__card-header">
    <div class="knight-challenge__card-content">
  </div>
</div>
.knight-challenge__card-header {
  font-weight: bold;
}

Avoid using IDs and tags in selectors.

<div id="knight-challenges">
  <p class="knight-challenges__description"></p>
</div>
#knight-challenges {
  margin: 1rem;
}

p.knight-challenges__description {
  font-weight: bold;
}

Use class selectors only.

<div class="knight-challenges">
  <p class="knight-challenges__description"></p>
</div>
.knight-challenges {
  margin: 1rem;
}

.knight-challenges__description {
  font-weight: bold;
}