Getting Started

Codebase is a modern website component library. You can use it as a basis for your website design projects. You can just use Codebase CSS and JS as-is, or you can reconfigure the SCSS variables and include only the parts you need.

On this page:

Simple Setup

Add codebase.css and codebase.js to your project.

Create your first HTML page – e.g. using the starter example below.

<!doctype html>
<html lang="en">
 <head>
   <meta charset="utf-8">
   <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>Your Webpage Title</title>
   <link rel="stylesheet" href="path/to/codebase/css/codebase.css">
   <link rel="stylesheet" href="path/to/your-theme/css/your-styles.css">
 </head>
 <body>

   <h1>Get to work</h1>

   <script src="path/to/codebase/js/codebase.js"></script>
   <script src="path/to/your-theme/js/your-scripts.js"></script>
 </body>
</html>

Build your HTML web page prototype(s) following the examples in these docs.
Personalize with your own stylesheet, scripts and graphics.

Alternatively, the Codebase SCSS files and JS can be added to any website development project.

The Codebase documentation is an example of Codebase in use.

Styles

The Codebase stylesheet codebase.css has been composed using SCSS. Its styles were built first as mixins and then these have been included in the Codebase classes.

Codebase styles can therefore be used as-is, simply by using the Codebase classes in your website HTML (or a templating language such as Nunjucks or Pug). Alternatively, you can include Codebase mixins into your own SCSS.

JavaScript

A few components in Codebase also use a simple, tiny JavaScript codebase.js to make them work – such as dropdowns, modals, tabs and responsive tables.

Since version 2.0, Codebase scripts have been re-factored so as not to need a dependency (e.g. jQuery is not required).

The Codebase SCSS Library

Codebase is, primarily, a highly versatile Sass (SCSS syntax) library, built using variables and mixins.

You can import the Codebase SCSS master file directly into your project SCSS master file, and then all the Codebase variables and mixins will be available for you to use.

@import "path/to/codebase.scss"

Using and Overriding Codebase Default Variables

All Codebase variables have the !default flag. To override any of these, you must first declare your own overrides using the same Codebase variable names (but with your preferred values), and then import Codebase.

Example:

// (1.) Override Codebase `!default` variables
$color-primary: #000099;

// (2.) Import Codebase
@import "path/to/codebase/scss/codebase.scss";

// (3.) Set your project styles after importing Codebase
body {
  // This will now get your override for $color-primary,
  // not the `!default` blue in Codebase
  background: $color-primary;
}

/* (4.) Your intended output */
body {
  background: #000099;
}

Tip: You can copy the entire Codebase default variables file codebase/scss/00_default-variables/_default-variables.scss into your theme, then remove all the !default flags in your version, and set your chosen variable values there.

Using Codebase Mixins

In Codebase most* of the styles have been built first as mixins. And then these have been included in the Codebase CSS classes.

(* i.e. all styles that use CSS classes plus some of the basic styles that apply to HTML tags.)

At the end of the Codebase variables file, you will find a set of $include-css-* variables. These refer to the Codebase CSS class builder mixins.

// Basics
$include-css-color-dark-theme:       false !default;
$include-css-color-ui:               true !default;
$include-css-big-typography:         true !default;

// Layout
$include-css-container:              true !default;
$include-css-flexbox:                true !default;
$include-css-grid:                   true !default;
$include-css-layout-utilities:       true !default;

// Components
$include-css-buttons:                true !default;
$include-css-badges:                 true !default;
$include-css-labels:                 true !default;
$include-css-cards:                  true !default;
$include-css-dropdowns:              true !default;
$include-css-menus:                  true !default;
$include-css-megamenu:               true !default;
$include-css-offcanvas:              true !default;
$include-css-modals:                 true !default;
$include-css-showhide:               true !default;
$include-css-tables:                 true !default;

// Utilities
$include-css-utilities:              true !default;

Example of a Codebase CSS class builder:

@if $include-css-cards == true {
  @include component-card;
}

You can:

Choose whether or not to dis-include all these classes by toggling their true/false $include- variables (i.e. by overriding them within your own variables with the value false). You will generate a smaller CSS output if you use these toggles to remove whatever you’ll never use.
Include individual Codebase mixins in your own classes (applying them to your own choice of class names). This may be useful if you are combining various frameworks and you need to have components etc. differently namespaced to avoid clashes.
Introduce another media query breakpoint, and then @include Codebase mixins therein.

Media-Query Breakpoint Widths

In Codebase the media query breakpoint width variables are:

// (Small is up to 767px)

// Medium
$mq-md: 768px !default;

// Large
$mq-lg: 1024px !default;

Also note: the largest container class has max-width: 1280px.

These media query widths are intended to cover a wide range of screen devices, approximating as follows:

Small Viewports		Medium Viewports (md)		Large Viewports (lg)
0	767px	768px	1023px	1024px	max. 1280px
phones (portrait)		phones (landscape) tablets (portrait)		tablets (landscape) & up

The media query breakpoint variables been utilized in a set of SCSS mixins as follows:

@mixin break-min($mq-min-width) {
  @media(min-width: $mq-min-width) {
    @content;
  }
}

@mixin break-max($mq-max-width) {
  @media(max-width: $mq-max-width - 1px) {
    @content;
  }
}

@mixin break-minmax($mq-min-width, $mq-max-width) {
  @media(min-width: $mq-min-width) and (max-width: $mq-max-width - 1px) {
    @content;
  }
}

These mixins are then called as in the following examples:

// For styling only intended for small viewports
@include break-max($mq-md) {
  ...
}

// For styling only intended for medium viewports
@include break-minmax($mq-md, $mq-ld) {
  ...
}

// For styling only intended for large viewports
@include break-min($mq-lg) {
  ...
}

Default Colors

Codebase’s default variable file codebase/scss/01_basics/__default-variables.scss contains ten color swatches are that are used for the five Codebase UI colors (i.e. primary, secondary, success, warning, and danger) – so that each gets a two colors, for light mode and dark mode.

$color-primary:              #2680eb !default;
$color-primary-dark:         darken($color-primary, 5%) !default;

$color-secondary:            #33cdf7 !default;
$color-secondary-dark:       darken($color-secondary, 5%) !default;

$color-success:              #6bd130 !default;
$color-success-dark:         darken($color-success, 5%) !default;

$color-warning:              #f7c736 !default;
$color-warning-dark:         darken($color-warning, 5%) !default;

$color-danger:               #ff4f23 !default;
$color-danger-dark:          darken($color-danger, 5%) !default;

primary

secondary

success

warning

danger

The primary color is also used for the default hyperlink color.

These Codebase UI colors have been chosen so that with these set as background colors (for buttons, badges, labels etc.), text on these elements can can be colored white and it will be readable – in both light and dark modes.

In addition, several shades of gray have been set as default variables for Codebase typography, line details for components and form elements, and as a default color for buttons, badges and labels. These grays cover both light and dark themes.

theme-1

theme-2

theme-3

theme-4

theme-5

For dark mode, default Codebase UI colors are slightly darker, whereas theme colors (grayscale) are inverted in order.

Codebase default theme colors have been deployed as follows:

Theme Color	Color Usage (default)
`theme-1`	`<body>` background; text on badges, buttons and labels
`theme-2`	Fine lines (e.g. horizontal rules, table cell borders)
`theme-3`	Background color of badges, buttons and labels
`theme-4`	Most text
`theme-5`	Headings

Color CSS Classes

Codebase UI colors can be deployed by CSS classes of the same name: .primary, .secondary, .success, .warning and .danger. Use these classes to color your badges, buttons, labels, etc.

Codebase also has utility classes for using these same colors for any element’s background, border, and/or text. The five theme colors (grayscale) also have utility classes for background, border, and text.

See color utilities for more information.

Overriding Codebase Default Colors

(1.) Overriding Global Default Color Variables

All Codebase default color variables can be overridden globally – the Codebase SCSS library explains how.

(2.) Overriding Local Color Mixins

Every time a color (for text, background or border) has been assigned within Codebase, this has been implemented using one of the SCSS mixins in codebase/scss/01_basics/__color-mixins:

// Text
@mixin t-color($light, $dark) {
  color: $light;

  @if $include-css-color-dark-theme == true {
    .dark & {
      color: $dark;
    }
  }
}

// Background
@mixin bg-color($light, $dark) {
  background: $light;

  @if $include-css-color-dark-theme == true {
    .dark & {
      background: $dark;
    }
  }
}

// Border
@mixin b-color($light, $dark) {
  border-color: $light;

  @if $include-css-color-dark-theme == true {
    .dark & {
      border-color: $dark;
    }
  }
}

After your @import of codebase.scss, you can use these same mixins in your project. You can use these mixins on your own CSS classes for any element, including overriding Codebase’s own use of these color mixins.

For example, consider changing the default button .btn color. You can reuse the @include for one or other of these mixins, swapping in your chosen color. The output of your use of this mixin will end up in your outputted CSS instead of that from Codebase – so, no CSS bloat.

// After you @import Codebase, set your own button colors
// for light mode and dark mode as below:

.btn {
  @include bg-color(magenta, darkmagenta);
}

(You can use color names, hex codes, RGB codes, or variables.)

See the Codebase SCSS library.

Light and Dark Themes

Since version 3.0, Codebase has simple built in light and dark CSS themes – to get you started.

While it is true that light and dark themes can be implemented entirely in CSS using a media query, as in this example...

/* Default light theme */
...

/* Dark theme override */
@media (prefers-color-scheme: dark) {
  ...
}

...Codebase has a small JavaScript that enables both the operating system and/or the the user to control light and dark modes.

The Codebase Dark Mode Support JavaScript

The Codebase dark mode support script in codebase.js operates as follows:

(1.) Automatic Operation

The CSS media query prefers-color-scheme is used in the JS to determine the preferences in the operating system (via the browser).

If it’s set to dark mode, then two things happen:
(a.) a sessionStorage data item is given the value dark, and
(b.) the CSS class .dark is added to the webpage <body> tag. Now the codebase.css can apply .dark styles.
If it’s set to light mode, then two things happen:
(a.) the sessionStorage data item is given the value light, and
(b.) the CSS class .dark is added to the webpage <body> tag.

Note: codebase.css actually has no .light classes – the light theme is the default theme (so, older browsers get the light theme by default). But the .light class has been provided so that you can use it in your design if you have a need for it.

(2.) Optional Toggle Operation

The JS light/dark mode controller also has a toggler function that responds to clicks on any element with id="theme-toggle". Every time this element is clicked, the controller toggles between light and dark (in both the sessionStorage and in the <body> tag).

A Simple Example of a Theme Toggler

If you wish to add this toggler to your HTML and CSS, then here is the simplest example of what you need:

<!-- HTML -->

<a id="theme-toggle">Theme</a>

/* CSS */

#theme-toggle::before {
  content: 'Dark ';
}

body.dark #theme-toggle::before {
  content: 'Light ';
}

This simple example above is what is used in the Codebase docs. You’ve probably clicked the docs light/dark mode toggler a few times already.

Don’t want dark mode?

Simply override this one variable to false:

$include-css-color-dark-theme: true !default;

See also Using and Overriding Codebase Default Variables for more information.

RTL Languages Support

Codebase aims to support RTL languages without the requirement for special RTL classes to be applied to elements or containers of elements. Codebase does this by using the CSS3 dir="rtl" selector.

Codebase was originally built by an LTR language speaker (English), and so the SCSS has been styled from a “LTR first” perspective, with RTL overrides built into its mixins:

@mixin something {
  // LTR supported by default
  padding-left: 100px;
  // RTL supported by override
  [dir="rtl"] & {
    padding-left: inherit;
    padding-right: 100px;
  }
}
.something {
  @include something;
}

Add dir="rtl" to a wrapper – usually the <html> tag itself. This sets the direction of the text flow from right to left – and it implements Codebase RTL support on those components that need it.

If you add dir="rtl" to the <html> tag or any wrapper, then you get Codebase’s RTL support within that wrapper.

The Codebase Static Website Generator

The Codebase CSS and JS has been built using its own Gulp-based static website generator (SWG).

You can simply use codebase.css and codebase.js in your project. Or you can pick up the whole set of folders for codebase/ and include them in your own project, for preprocessing the SCSS and concatenating the JS on whatever build system you like to use.

Or you could use the Codebase SWG – a set of Node modules (powered by Gulp) that handles all this and more:

Preprosessing of SCSS files into codebase.css
Concatenation of component JS files into codebase.js
Peprocessing of Markdown files into HTML
Building the docs from the HTML (above) and some Nunjucks templates
Passing of all these outputted files and a few more assets from to the build folder (here named docs/)
Setting up a virtual server for serving the docs to your internet browser;
Monitoring for the running Gulp tasks and then reloading your browser.

Using the Codebase SWG

You will first need to have NodeJS installed on your computer. Get the latest stable release.
Download or clone the entire Codebase repository from GitHub to your computer.
In your computer’s command line interface, change directory (cd) into your local Codebase project.
Do npm install --save-dev to install all the node module dependencies (you should only need to do this the first time).
Finally, run gulp.

First time use:

$ cd [your Codebase project name]
$ npm install --save-dev
$ gulp

Ongoing use:

$ cd [your Codebase project name]
$ gulp

Basics