1. Developing Applications with Oracle JET
  2. Theming Applications
  3. Best Practices for Using CSS and Themes

Best Practices for Using CSS and Themes

Use the recommended styling standards for creating CSS and themes in your web or hybrid mobile application.

Standard Details Example

Use mobile-first design

Applications should be mobile first, meaning that they should work on a phone and tablet. This means they must be touch friendly, including sizing tap targets appropriately. There is no hover in mobile, so the design should not rely on the use of hover.

 

Follow naming conventions

Use the .namespace-block-element naming convention for your CSS file.

For example, if you are writing a branding bar that contains a header element for your company acme, then choose acme as the namespace, branding as the block, and header as the element. So, the selector name will be .acme-branding-header. Oracle JET uses dashes in their selector names, but you may use other naming conventions such as Block, Element, Modifier (BEM).

Including a namespace is important in order to minimize the chances of your customer's CSS on the page affecting your CSS and vice-versa. For example, if you and your customer both have a class named branding-header as seen below, your branding header text color will be red.

Customer CSS:
.branding-header{color: red}

Your CSS:
.branding-header{background-color: blue}

Using .acme-branding-header rather than just .branding-header will greatly reduce the chance that your customer will use a class with the same name.

.acme-branding-header

Use only Oracle JET public classes

Use only the public classes documented in the Oracle® JavaScript Extension Toolkit (JET) Styling Reference. All other Oracle JET classes are considered private and subject to change without notice.

 

Do not override Oracle JET classes

Do not override any Oracle JET class containing the oj- prefix, whether public or private. In some cases the Cookbook may contain mixins to customize component styling, for example, Button Styling.

Error Icon Do not override Oracle JET classes like this: 

.acme-branding-header .oj-button{
  color: white;
  background: blue;
}

Don’t set the font family in the CSS

The application should set the font family for text once on the root of the page which allows the application to change the font family as needed. In order to blend in with the font family chosen by the application, do not set the font family in the CSS.

Error Icon Do not set the font family like this: 

.acme-branding-header {
  font-family: arial;
}

Consider using REM for font sizes

Consider Using REM for font sizes in order to blend in with the base font size the application has chosen. 

.acme-branding-header {
  font-size: 1.2rem;
}

Add bi-directional (BIDI) styling support

Oracle JET applications are expected to set dir="rtl" for right-to-left (RTL) languages as described in Setting Text Direction. You can use this setting to support both left-to-right (LTR) and RTL languages in your CSS. 

html:not([dir="rtl"]) .acme-branding-header {
  right: 0; }

html[dir="rtl"] .acme-branding-header {
  left: 0; }

Use oj-hicontrast for high contrast styling

When Oracle JET detects high contrast mode, it places the oj-hicontrast selector on the body element which you can use to change the CSS as needed. See Configuring High Contrast Mode. 

.acme-branding-header {
  border: 1px;
}

.oj-hicontrast .acme-branding-header {
  border: 2px;
}

Avoid !important

Avoid the use of !important in your CSS as it makes it problematic to override the value. Where possible, use higher specificity instead. See the Mozilla specificity page for more information.

Warning Icon Avoid using !important. 

.acme-branding-header {
  font-size: 1.2rem !important;
}

Optimize image use

All image systems have advantages and disadvantages. See Working with Images to decide if icon fonts are right for you.

Always consider performance when using images. For tips, see Adding Performance Optimization to an Oracle JET Application