README

A responsive UBC CLF (Common Look and Feel) theme for Drupal using Tailwind and Bootstrap 5. Created by the UBC IT Web Services Department.

Kraken is a theme for Drupal 10+, providing UBC-branded units with the basic structure of the UBC CLF (Common Look and Feel).

IE Support

This theme does not support Internet Explorer. If older browser support is required, it must be added separately or galactus, an earlier version of the CLF, can be used.

Rationale

Why another theme? Why not extend the Galactus Drupal 10 theme?

As a web developer in Web Services, you should be able to expect that CSS and Javascript are added in a single consistent way in any project. The Galactus theme works as is, however it is intended for general-purpose use by the broader UBC community. Kraken's goal is to add proper dependency management and workflow for Web Service's theme layer in the same way we have done for the application layer. It is intentionally biased and uses specific CSS and Javascript frameworks (Tailwindcss and Bootstrap 5). Both of these are well-supported and flexible enough to work on any web project (CLF or not) and provide a consistent set of features and functionality. The benefits are improved reusability, improved ramp up time and improved optics. There should be no hidden features only understood by a single developer. Do note that the version of Bootstrap included with the theme is an updated version (currently v5), not version 2 (as used by the default CLF).

Using the theme

To make changes to the theme CSS and Javascript, you will need to use the command-line tools.

Requirements

Ensure that you have node.js installed, version 18 or higher. To confirm your version, navigate to the Kraken theme directory in your command-line and type node -v.

Installation

From the theme root, install the theme dependencies:

npm install

This will install everything required to work with the CSS and Javascript:

• the Tailwindcss utility-based CSS library
• the Bootstrap 5 library
• packages such as Webpack, Postcss, and Autoprefixer that automate building and preparing the web assets.

Running the commands

There are four node.js commands defined in in /package.json.

• npm run css

  • compiles the CSS in the /src/css directory, excluding the subdirectories, and saves the minified files in /css. Settings in /postcss.config.js

• npm run js

  • compiles the Javascript in the /src/css directory, excluding the subdirectories, and saves the unminified files in /js. Settings in /webpack.common.js and /webpack.dev.js

• npm run prod

  • compiles the CSS in the src > css directory, excluding the subdirectories, and saves the minified files in /css. Settings in /postcss.config.js
  • compiles the Javascript in the /src/css directory, excluding the subdirectories, and saves the minified files in /js with a .min.js extension. Settings in /webpack.common.js and /webpack.prod.js
  • saves an external sourcemap (.map file) to facilitate debugging. Settings in /webpack.prod.js

• npm run watch

  • watches for changes to the CSS in the /src/css directory and recompiles when a file is resaved (top level only).

Tailwindcss

The theme makes extensive use of utility classes provided by Tailwind.

All configuration for Tailwind utilities are set in /tailwind.config.js. The configuration uses UBC default colours, fonts, regular spacing, etc. More details about this file can be found in the Tailwind documentation.

Two very important places where it diverges fro the documentation:

• Separators: by default, Tailwind uses a colon to separate media query and state prefixes, whereas the config defines the prefix separator as a double dash. For example, md:text-white hover:text-black become md--text-white hover--text-black
• Colour palette: the config excludes Tailwind's default colurs and replaces them with UBC colours and a few user-defined colours.

When running the production build script (npm run prod), PurgeCSS is used to scan all Twig, Vue and Javascript files and remove any Tailwind utilities that are not in use. This allows for us to deliver a considerably smaller set of CSS classes. Note that classes not provided by Tailwind are never purged.

Additionally, all vendor prefixes for supported browsers are added automatically with Autoprefixer, so there is no need to add these (e.g. -webkit).

I highly recommend installing the Tailwind VS Code extension. It provides code completion for Tailwind utility classes as defined in the tailwind.config.js file. Another useful utility is the Headwind VS Code extension, that sorts classes in your markup based on an opinionated order.

Kraken theme settings

Once installed and set to default, you can adjust the following theme settings:

• switch between v.7 and v.8 of the CLF (note that v.7 of the CLF is not from the CDN and contains a subset of the full CLF).
• change the base font size and line heights to adjust the overall relative sizing and vertical spacing of the type.
• add a CWL login option to the login page.
• optionally load the CLF fonts or the Google Fonts service.
• add verification header tags for Google and Bing search services.
• opt into a set of svg icons that can be added to the site via the svg use tag

Planned settings (not yet feature complete)

• enable dark mode
• make the primary horizontal navigation 'sticky' when scrolling up only