Creating Themes

A Practical Example

Perhaps you find it useful while working on your site to have icons aliases in your local language Spanish to make them easier to remember. You might include a set of aliases in your site's icon overrides in src/site/elements/icon.overrides.

These files already exist for your project, but are left blank by default. You can simply update the file with your aliases and save it and gulp watch will automatically recreate the original definition with your changes.

Creating Packaged Themes

After finishing up work on your project, you might find that all of your icon aliases would be useful to other Spanish developers working with Semantic. You can then create a packaged theme for distribution that other people can download and use on their site

To do this create a new folder under themes with your theme name, for example src/themes/spanish/ and add your variables and overrides file. Keep in mind all themes must include both an override and variable file, if no variables are changed you can include a blank .variables file.

You can test your packaged theme locally by adjusting your theme.config to use the specified theme:

Variables in Semantic

Variables are not just one-to-one matches with css properties, but let you work with higher-order concepts in an element's design, that may adjust several properties at once.

Abstracting Concepts to Remove Tedium

Sometimes variables are used to deal with latent issues in CSS. For example @lineHeight might seem like a simple value. Setting a line-height greater than 1 on an input is necessary to make sure descenders like "p" or "q" aren't cut off in your form. Some browsers even implicitly add this line-height to inputs even if you specify a value to low.

Having a different line height on input elements increases its vertical padding to a larger value than what is set in @verticalPadding. This implicit change in actual vertical-padding on an input, would mean the element would not line up with other UI elements that use the same @verticalPadding. Semantic deals with this on a framework level, by using derived values for padding specifically on inputs.

Using a @lineHeightOffset is also useful for other unexpected css quirks.

For example floated elements do not receive the same top padding as other sibling content:

Or headers might appear overly spaced because they have additional vertical padding from large line heights.

Abstracting Concepts to Facilitate Theming

Sometimes there is a disconnect between the name of a css property, and the function it performs visually, or a single property might house multiple concepts. For example a button may have a @shadow to make it appear raised, but it might also use require an inset box shadow to give the button a border that can use the shade of an element's background color. That single box-shadow definition might actually houses several separate concepts.

Semantic does its best to abstract out each concept separately when possible.

This may seem like way too much abstraction, but its important to note that themes do not need to redefine all these derived variables. For example, the "raised" theme, just redefines a single variable, which modifies the four or five other derived variables that the theme maker does not even need to know exist.