Guide

Getting Started

The two essential files for any Ditto application to use the Pattern-library are those two:

The stylesheet should always comes first in the document <head> to ensure correct display of loadings but the script (for icons support) should ideally be loaded at the very bottom of the <body> to not impede parsing of the page or execution of any other script.

Dark theme

Any customer dahsboard app should also include our dark-theme for RLS customers just after the main stylesheet:

This theme is triggered by customer-dashboard-header web-component which will add the relevant body class upon reading the customer's JWT token.

Other available stylesheets

Those are available on their own, should they be of any use for any project that does not require the full framework:

NOTE: Those are already included in the main framework

As per this new update, the variables stylesheet is no longer required on the page as all variables are now included in the main stylesheet. See How to Integrate to make them available at build.

How to Integrate Variables

Standard CSS vars

Most CSS vars (colours and fonts) will just work straight out of the box just by adding the above stylesheets to your page.

Even if using a pre-processor like Sass, using CSS vars over Sass variables will offer some advantages.
To overwrite a rule from the main stylesheet in another stylesheet/app for a specific case scenario, we can simply re-define the variable under a specific selector, without having to re-write the entire rule.

This is particularly useful for our dark-theme where we don't have to re-define all the states of a component just to update its basic state for example: 

/* dittomusic-framework.scss */
:root {
  --brand-primary: purple;
  --primary-button-background: var(--brand-primary);
}
a {
  color: var(--brand-primary);
}
button {
  background: var(--primary-button-background);

  &:hover { /* overwrite background */ } 
  &:focus { /* overwrite background */ } 
  &:disabled { /* overwrite background */ } 
}

/* dittomusic-dark-theme.scss */
.dark-theme {
  --brand-primary: light-purple;
  // no need to re-define button rule and all others inheriting primary colour
}

/* MyApp.js */
.specific-case-scenario {
  --primary-button-background: red;
  // no need to re-define button rule and all its states
}

Custom Media Queries vars

CSS vars are not supported for media queries in the official CSS specifications.
They're a courtesy of the PostCSS Custom Media NPM package

Now because PostCSS is a pre-processor and won't run on the end browser, those variables need to be injected at build. A simple CSS import won't work because it will still be output as `@import ...` in the compiled file. We need to use another package, PostCSS Import Url, to inline the variables prior to processing them with the Custom Media plugin.

1. First install both packages as dev dependencies: 

yarn add -D postcss-import-url postcss-custom-media

2. Then configure PostCSS (comes as default with most Vue.js stacks): 

/* postcss.config.cjs */
module.exports = {
  plugins: {
    'postcss-import-url': {},
    'postcss-custom-media': {},
  },
}

Now at this stage you could probably get away with just: 

/* Should work but not ideal */
@import 'https://cdn.dittomusic.com/css/dittomusic-variables.css';
body {
  @media (--max-small) { ... }
  @media (--min-small) { ... }
}
However that's not very flexible to take into account environment based CDN urls, so the next trick...

3. Inject environment based stylesheet as Sass additional data:

In your Vite, Vue or Webpack config: 

/* vite.config.ts */
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd())
  return {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@import url('${env.VITE_CDN_URL}/css/dittomusic-variables.css');`,
        },
      },
    },
  },
})

/* vue.config.js */
module.exports = {
  css: {
    loaderOptions: {
      sass: {
        additionalData: `@import '${process.env.VUE_APP_CDN_URL}/css/dittomusic-variables.css';`,
      },
    },
  },
})

/* webpack.config.js */
module.exports = {
  module: {
    rules: [
      {
        use: [
          'css-loader',
          'postcss-loader',
          {
            loader: 'sass-loader',
            options: {
              implementation: sass,
              additionalData: `@import '${process.env.CDN_URL}/css/dittomusic-variables.css';`,
            },
          },
        },
      ],
    },
  },
}

4. Finally, to support use of a CDN running on a local Docker instance and mounted as volume in our app public folder, we must change @import by @use: 

/* vite/vue/webpack.config.js */
additionalData: CDN_URL.includes('http')
  ? `@import url('${CDN_URL}/css/dittomusic-variables.css');`
  : `@use '${path.resolve(__dirname, './public/', `./${CDN_URL}`)}/css/dittomusic-variables.css';`,

Sass variables

There are still some very rare cases where having access to the Sass variables can be useful, for example for using in a Sass mixin/function where we need the actual hex code...

It is for this reason that they are still in use in our pattern-library codebase, ideally you'll leverage the Sass power directly in the source to produce some re-usable classes.

But... should you need them in another project for example for the Sass configuration of an old plugin, you might find this other package useful: