CSS Guide

Overview

Stylesheets written in CSS (.css) files, can be used to control the appearance (color, size, font and position) of the elements within the Fitbit application user interface.

.label {
  fill: black;
  x: 0;
  y: 45%;
  width: 100%;
}

Adding a Stylesheet

In order to use a stylesheet, it must included within an SVG file.

<svg>
  <defs>
    <link rel="stylesheet" href="styles.css" />
  </defs>
</svg>

Selectors

The Fitbit rendering engine supports basic selectors in order to apply styling to an element.

The following simple selectors can be used:

Type selector:

text { font-family: System-Regular; fill: black; }

Applies to all elements of the specified type. e.g. <text>

Note: Using this selector may affect system components which use these elements.

Class selector:

.labels { font-family: System-Regular; fill: red }

Applies to all elements with the specified class name. e.g. class="labels"

ID selector:

#textbox { font-family: System-Regular; fill: blue }

Applies to the element with corresponding ID. e.g. id="textbox"

<svg viewport-fill="fb-cyan">
  <svg class="horizontal-pad">
    <text>I am black text!</text>
    <text class="labels">I am red text!</text>
    <text id="textbox">I am blue text!</text>
  </svg>
</svg>

You can also use combinations of these selectors, and override previous values:

text.labels { font-family: System-Regular; fill: blue }

text#textbox { font-family: System-Regular; fill: black }

Fonts

Text elements can be styled using the system font, at any size or color. Embedding custom fonts is not supported at this time, but we recommend using a library like fitfont to generate images of each character.

font-family: "Font name";

.fancy { font-family: "System-Light"; }

System Font

System-Regular, System-Light, System-Bold

In Fitbit OS 5, the System font is called Raiju:

Dimensions and Positioning

All sizes (width, height) and coordinates (x, y) can be specified in either pixels or percentages (%).

Size

• width: 60 or width: 100%
• height: 60 or height: 100%

Coordinates

• x: 5 or x: 10%
• y: 5 or y: 10%

You can also subtract pixels from percentages, such as 50%-10.

Coordinates are always relative to the parent svg element. In the following example, the inner rectangle element will be positioned 20% from the top and left of the screen, even though its x and y coordinates are 0. This is because inner is positioned relative to its parent, container, and container's x and y are defined as 20% of its parent's size (screen).

<svg class="screen">
  <svg class="container">
    <rect class="inner" />
  </svg>
</svg>

.screen { width: 100%; height: 100%; viewport-fill: lightblue; }
.container { width: 60%; height: 60%; x: 20%; y: 20%; }
.inner { width: 100%; height: 100%; x: 0; y: 0; fill: red; }

Previous element in container ($)

There is an additional special value $, which references the previous sibling within the same container element. When $ appears in an x/y field, it takes the value of the previous sibling's position in that axis, plus the sibling's size (width or height) in the same axis. If there is no previous sibling (i.e. the element is the first child in the container), $ evalutes to 0.

In this example, the item elements use $ in their y position, stacking themselves vertically.

<svg class="screen">
  <svg class="container">
    <rect class="item" fill="fb-red" />
    <rect class="item" fill="fb-green" />
    <rect class="item" fill="fb-yellow" />
  </svg>
</svg>

.screen { width: 100%; height: 100%; viewport-fill: fb-cyan; }
.item { width: 100%; height: 27%; x: 0; y: $+5%; }

Colors

Colors can be specified in hexadecimal, or using named colors.

Hexadecimal

A 6-digit (or 3-digit shorthand), hexadecimal number that represents Red, Green, and Blue.

#RRGGBB or #RGB

text { fill: #FF9900 }
.labels { fill: #FFF }

Web Color Names

You can use any of the web standard color names within your applications.

text { fill: black; }

Fitbit Named Colors

You can use any of these Fitbit named colors to easily match your application with the colors used by system applications. Be aware that the specific color values may change in future system updates. These colors match the definitions in Fitbit OS 5.0.

text { fill: fb-indigo; }

Opacity

You can specify opacity to control the transparency of an element. Specify a value between 1.0 and 0.0. The lower the value, the more transparent it is.

text { opacity: 0.3 }

Borders

The Fitbit rendering engine does not support the CSS stroke or border properties. To achieve a similar effect you need to draw two overlapping shapes.

The larger background shape should be filled with the desired border color, and the smaller foreground shape should be filled with the desired foreground color.

For example, here is a gray circle with a black border. Notice that the background circle has a larger radius r.

<svg viewport-fill="fb-gray">
  <circle cx="50%" cy="50%" r="80" fill="fb-black"/>
  <circle cx="50%" cy="50%" r="78" fill="fb-gray"/>
</svg>

Image Grayscale Magic!

Grayscale images can be colored dynamically with the fill property. The black area of an image will be fully transparent (0) and the white will be fully opaque (255). All the mid-gray areas will inherit opacity according to their depth of color (0 - 255).

Note: The image must be 8-bit PNG format.

In the example below, the second hand on the clock has been filled with a color, but is actually just a grayscale image of a white hand on a black background.

Let's take a look how it's made.

Here's the black and white clock hand image:

The svg contains an image tag, which uses the black and white clock hand image.

<svg>
  <image width="100%" height="100%" href="hand.png" class="seconds" />
</svg>

Then we apply the chosen fill color, and opacity within our CSS stylesheet.

.seconds { fill: #3fc0fc; opacity: 1; }

Aside from making UI more adjustable to color changes, the use of grayscale images reduces the size memory usage by a factor of 4.

You can generate images in the correct format by using the following ImageMagick command:

convert original.png -colorspace gray final.png

Or, in Adobe Photoshop set Image Mode > Grayscale, 8 Bits/Channel.

Horizontal Text Alignment

text-anchor: start | middle | end

text { x: 50%; text-anchor: middle; }

Used to align a string of text horizontally relative to the x-coordinate specified by the x attribute.

• start: the start of the text is at the x-coordinate.
• middle: the middle of the text is at the x-coordinate.
• end: the end of the text is at the x-coordinate.

Monospace Numbers

The firmware doesn't include any monospace fonts (fixed width), but we have included monospace numbers within some of the existing fonts. These can be accessed using the character codes 0x10-0x19 (where 0x10 is zero).

The following example takes a string of numbers, and converts them to their monospace equivalent.

//app/index.js

function updateClock() {
  var today = new Date();
  var hours = util.monoDigits(today.getHours());
  var mins = util.monoDigits(util.zeroPad(today.getMinutes()));

  myLabel.text = hours + ":" + mins;
}

//common/util.js

// Convert a number to a special monospace number
export function monoDigits(num, pad = true) {
  let monoNum = '';
  if (typeof num === 'number') {
    num |= 0;
    if (pad && num < 10) {
      monoNum = c0 + monoDigit(num);
    } else {
      while (num > 0) {
        monoNum = monoDigit(num % 10) + monoNum;
        num = (num / 10) | 0;
      }
    }
  } else {
    let text = num.toString();
    let textLen = text.length;
    for (let i = 0; i < textLen; i++) {
      monoNum += monoDigit(text.charAt(i));
    }
  }
  return monoNum;
}

const c0 = String.fromCharCode(0x10);
const c1 = String.fromCharCode(0x11);
const c2 = String.fromCharCode(0x12);
const c3 = String.fromCharCode(0x13);
const c4 = String.fromCharCode(0x14);
const c5 = String.fromCharCode(0x15);
const c6 = String.fromCharCode(0x16);
const c7 = String.fromCharCode(0x17);
const c8 = String.fromCharCode(0x18);
const c9 = String.fromCharCode(0x19);

function monoDigit(digit) {
  switch (digit) {
    case 0: return c0;
    case 1: return c1;
    case 2: return c2;
    case 3: return c3;
    case 4: return c4;
    case 5: return c5;
    case 6: return c6;
    case 7: return c7;
    case 8: return c8;
    case 9: return c9;
    case '0': return c0;
    case '1': return c1;
    case '2': return c2;
    case '3': return c3;
    case '4': return c4;
    case '5': return c5;
    case '6': return c6;
    case '7': return c7;
    case '8': return c8;
    case '9': return c9;
    default: return digit;
  }
}

Standard Definitions

There are a handful of CSS classes that your application should define in order to assist with the default styling of system elements. These classes mean you only have to define these colors once and the text, buttons, etc will use them.

.application-fill           { fill: fb-cyan; }
.app-gradient-background    { fill: fb-blue; }
.foreground-fill            { fill: fb-white; }
.background-fill            { fill: fb-black; }

For example, to generate the background gradient:

<svg>
  <use href="#app-gradient-background" class="app-gradient-background application-fill" apply-style="at-use">
    <svg><!-- content --></svg>
  </use>
</svg>

Helper Classes

By importing the system widget definitions into your project, you can utilize some system CSS classes that ease the development process.

The definitions are as follows:

/* Typography sizes */
.h1  { font-size: 80; line-increment: 100; font-weight: bold;}
.h2  { font-size: 50; line-increment: 60;  font-weight: bold;}
.h3  { font-size: 34; line-increment: 42;  font-weight: bold; font-step-size: 4; min-font-size: 24; }
.h4  { font-size: 28; line-increment: 34;  font-weight: bold; font-step-size: 4; min-font-size: 24; }
.h5  { font-size: 22; line-increment: 26;  font-weight: bold;}

.p1  { font-size: 34; line-increment: 42; font-step-size: 4; min-font-size: 24; }
.p2  { font-size: 28; line-increment: 34; font-step-size: 4; min-font-size: 24; }
.p3  { font-size: 22; line-increment: 26; }

/* Helpers */
.stack-gap                       { y: $+6; }
.center-text                     { text-anchor: middle; display-align: center; }
.horizontal-pad                  { x: 18; width: 100%-36; }
.horizontal-pad-header           { x: 30; width: 100%-60; }
.touch-area                      { width: 100%; height: 100%; opacity: 0;}
.uppercase                       { text-transform: uppercase; }
.full-size                       { x: 0; y: 0; width: 100%; height: 100%; }

To use these helper classes in your project, you need to import the system_widget.defs in your widget.defs file:

<svg>
  <defs>
    <link rel="import" href="/mnt/sysassets/system_widget.defs" />
    <link rel="stylesheet" href="styles.css" />
  </defs>
</svg>

Then just use the classes within your markup:

<svg>
  <svg class="horizontal-pad">
    <text class="h1 center-text application-fill" x="50%">Heading1</text>
  </svg>
</svg>

Web CSS Differences

There are a number of differences between Fitbit CSS and traditional web CSS:

• Don't specify units for: font-size, letter-spacing. e.g. font-size: 120 not font-size: 120px.
• Advanced selectors such as child, descendant or attribute selectors are not currently supported.

SVG Guide

Javascript Guide