Coding Styleguide for LUCI Contributors

Coding Style

SCSS Guidelines

  • Use hyphenated BEM style for all CSS selectors.
  • Namespace all CSS slectors with n-, examples: n-data-table, n-tabs, n-page-header
  • Use scss-lint to keep scss files clean, consistent, and readable. Refer to the library's .scss-lint.yml file for a complete list of the active rules.
  • Do not include browser-prefixed rules in scss files. Autoprefixer takes care of those automatically.

Variation Classes

For component with a large number of visual variations (Page Header or Tabs for example) additional variation classes are added to the root element of the component, i.e. n-tabs--default, n-tabs--large, etc.

Responsive Support

Test and confirm that component functionality and visual appearance work fluidly across viewports ranging from 320px to 1600px.

Semantic Versioning

The library follows SemVer guidelines for versioning, using three numbers separated by dots to denote the version:

MAJOR.MINOR.PATCH, examples: 1.0.2, 4.12.8

Use the following as a guide to determine the correct version number for each release:

Major
When you make incompatible changes to existing HTML within the library. If a library consumer needs to update their markup in order to be compatible with CSS changes in the library, this is a major version.

Minor
When new components are added, but existing components are untouched, this is minor version.

Patch
When backwards-compatible (CSS Only) bug fixes are made to the library, this is a patch version.

Browser Requirements

Test and confirm functional behaviors in the following browsers:

  • Internet Explorer 9
  • Internet Explorer 10
  • Internet Explorer 11
  • The two most recent versions of:
    • Safari
    • Chrome
    • Firefox
    • Mobile Safari
    • Mobile Android Browser

Accessibility Requirements

Alt Text

  • Provide an alt attribute for all images
  • If the image contains text, that text should be the value of the alt attribute
  • If no text is present in the image, provide a concise description of the image

SVGs

  • Provide a <title> tag within all SVGs
  • Include the aria-labelledby="title" attribute on the outer <svg> element to point to the title tag

Heading Structure

  • Provide logical, semantic headers as an outline of the document
  • Consider viewing the page with CSS disabled to understand what the document outline will look like
  • Headings should be an effective description of the content that follows
  • Use meaningful text for links that describes the event that will occur when the link is clicked
  • Do not use "Click Here" as link text
  • Ensure all text links have an underline in the hover state
  • Use the library's preset link and link:hover colors
  • Links should be focusable by tabbing and utilize the library's preset :focus state
  • Include a "Skip to main content" link as the first child of the <body> tag on each page.
  • Ensure this link allows skipping over any page shell navigation/header content
  • This link should be visually hidden, but accessible via screen readers

Forms

  • Place field-level help text before the form field to allow correct screen reader playback order
  • When help text is placed after an input, use the "aria-describedby" attribute on the input to link the adjacent help text
  • Ensure form controls have descriptive labels and instructions
  • Ensure all form controls are keyboard-navigable, including checkboxes, radios, select, etc.
  • Do not use a placeholder attribute as a substitute for a form label. Use it to provide an example of what input is being requested, not as a label for the field.

Media

  • Provide audio descriptions and transcripts of video content
  • Make playback controls keyboard navigable

Tables

  • Provide descriptive table headers, <th> to allow parsing by screen readers.

ARIA Roles

  • Use ARIA landmarks to provide navigation from one element to another
  • Use ARIA to notate functional elements on the page (e.g. role="search" for a search form)

Javascript

  • Use Javascript to progressively enhance and ensure components still function without Javascript enabled

CSS

  • Ensure a page loaded without CSS is still navigable and usable

Text Size

  • Ensure text can be resized without breaking the design (within reason, typically two browser "Zoom In" levels)

Contrast

Hiding Elements

  • Do not use display: none; to hide elements on the page
  • If using sass, utilize the %visually-hidden extension to hide elemtns while keeping them accessible for screen readers
  • If not using sass, use the utility class .n-visually-hidden to accessibly hide elements