Custom Styles

Ian Prest edited this page Jul 31, 2015 · 15 revisions

Using Custom Styles

You can now use custom styles to modify the appearance of keycaps in your keyboard layouts. Custom styles are just a CSS stylesheet that is applied to your layout.

Loading & Using Fonts

To use a custom font in your layout, add a @font-face tag that points to the font files. E.g., to use the Fredoka One font from Google Fonts, you would first reference the font in your Custom Styles:

@font-face {
  font-family: 'Fredoka One';
  font-style: normal;
  font-weight: 400;
  src: local('Fredoka One'), local('FredokaOne-Regular'), url( format('woff2');

Note that @import rules are normally restricted (see below), but you are specifically allowed to import fonts from Google Fonts. The following code is short-hand for the above @font-face declaration:

@import url(;

Once the font is declared, you can change all your keycaps to reference it:

* { font-family: 'Fredoka One'; }

Keycap Parts

Keycaps are made up out of a bunch of DIVs, styled so that they resemble keycaps. The exact makeup of each keycap is subject to change!

However, each keycap has up to twelve key labels that will always have the following class names available for styling:

  • keylabel0 --- Top-left key label
  • keylabel1 --- Top-center key label
  • keylabel2 --- Top-right key label
  • keylabel3 --- Middle-left key label
  • keylabel4 --- Middle-center key label
  • keylabel5 --- Middle-right key label
  • keylabel6 --- Bottom-left key label
  • keylabel7 --- Bottom-center key label
  • keylabel8 --- Bottom-right key label
  • keylabel9 --- Front-left key label
  • keylabel10 --- Front-center key label
  • keylabel11 --- Front-right key label

One potential application is to change the font on a per-legend basis. For example, to change only the front legends to use the 'Fredoka One' font from the above samples, you could write something like this:

.keylabel9, .keylabel10, .keylabel11 { font-family: 'Fredoka One'; }

Custom Glyphs

If you are going to create custom glyphs using CSS, it is recommended that you follow the same pattern used by Font Awesome.

By rigorously following this pattern, we can be sure that future enhancements to will support the glyphs. E.g., a "character picker" is a planned enhancement, and it will be able to automatically detect your custom glyphs and allow you to pick them if you follow this format. It is also hoped that simple examples of custom glyphs might also be exported to SVG one day.

A good example demonstrating the custom-glyph pattern is the Commodore VIC-20 sample layout, which defines custom glyphs for the unique Commodore PETSCII glyphs it needs:

/* class to define general glyph-set properties */
.petscii {
  font-family: 'C64ProMono';
  border: solid 1px;
/* class for each individual glyph; note the pattern of the class names */
.petscii-circle-open:after { content: "\0ee57"; }
.petscii-club:after { content: "\0ee58"; }
.petscii-heart:after { content: "\0ee53"; }
.petscii-spade:after { content: "\0ee41"; }
.petscii-diamond:after { content: "\0ee5a"; }
.petscii-cross:after { content: "\0ee5b"; }
/* etc */

Until such time as there is a character picker, you will need to manually add HTML code to your legend to access your glyphs:

<!-- Use the glyphs! -->
<i class='petscii petscii-spade'></i>
<i class='petscii petscii-diamond'></i>
<!-- etc -->

You needn't limit yourself to using glyphs from a font: custom image-based glyphs are also possible (though you will have to host the images yourself):

.custom {}
.custom-glyph-1:after { 
  /* Set the background for this glyph to your image */
  background-image: url('...'); 
  background-repeat: no-repeat;
  background-position: center;

  /* Content is required for it to appear; this is a non-breaking-space */

  /* Sizing in EMs allows the glyph to scale with the font-size */
  width: 1em; 
  height: 1em; 
  background-size: 1em; 

Styling Limitations

In order to prevent certain forms of abuse, any CSS you enter into the custom-styles window is parsed and sanitized prior to being applied.

The sanitization prevents the following CSS features from being used:

  • All at-rules except:
    • @font-face
    • @import (Google Fonts only!)
  • CSS namespaces
  • All selectors are modified so that styles will only apply to the keycaps themselves.

The CSS parser itself is fairly lenient, but none of your styles will be applied if it encounters any errors---unlike a browser which would normally just discard the specific rules it couldn't understand. Fortunately, if there are any parsing errors, you will be alerted to the error in the Custom Styles tab. (If you find a CSS parsing error that prevents a legitimate use-case, please log it!)

Note also that while you can use the custom styles to achieve some advanced effects, it is unlikely that these will ever be supported in SVG export.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.