@crowdstrike/ember-toucan-styles

Ember integration for CrowdStrike's design system: Toucan.

Includes:

• Base CSS and Tailwind configuration automatically integrated into the Ember build pipeline
• Color variables automatically pulled from Figma
• Color utilities at @crowdstrike/ember-toucan-styles/utils/colors
• A base ThemeManager service, for managing the current style theme from JavaScript -- not included by default, but may be extended
• Testing utilities for qunit tests that affect the current theme.

Setup

• Tailwind 3
  • App
• Tailwind 2
  • App
  • v1 Addons
  • CSS-Modules

Usage

• Scrollbar Styles
• Custom Theme Manager
• Setting the Default Theme
• Responding to Theme Changes
• Using Tailwind Plugins

Install

ember install @crowdstrike/ember-toucan-styles @crowdstrike/tailwind-toucan-base

Compatibility

• ember-source 3.24+
• ember-auto-import 2+
• typecsript 4.5+
• embroider max-compat and max-strict
• @glimmer/tracking 1.1.2+

Setup

Tailwind 3

1. Create an ember app. You don't have to start with a fresh ember app!

2. Add tailwind however you like. An easy approach is

# In your terminal
npx ember-apply tailwind

3. Install this library.

# In your terminal
pnpm add @crowdstrike/ember-toucan-styles @crowdstrike/tailwind-toucan-base

4. Add the toucan-base plugin to your tailwind config's plugin list.

// config/tailwind/tailwind.config.js
'use strict';

const path = require('path');

const appRoot = path.join(__dirname, '../../');
const appEntry = path.join(appRoot, 'app');
const relevantFilesGlob = '**/*.{html,js,ts,hbs,gjs,gts}';

module.exports = {
  content: [path.join(appEntry, relevantFilesGlob)],
  theme: {
    extend: {},
  },
  presets: [
    require('@crowdstrike/tailwind-toucan-base')
  ],
  safelist: [
    'theme-dark',
    'theme-light',
  ]
};

5. Create a button to toggle the theme.

# In your terminal
ember g component theme-toggle -gc

6. Add code to theme-toggle to toggle the theme (and to observe that the theme is toggling). Today, Toucan only supports light and dark mode, so this toggle will flip between the light theme and dark theme.

// app/components/theme-toggle.js
import Component from '@glimmer/component';
import { service } from '@ember/service';

export default class DemoComponent extends Component {
  @service themeManager;

  toggle = () => this.themeManager.toggleTheme();
}

{{! app/components/theme-toggle.hbs }}
<button
  class="
    flex whitespace-nowrap bg-surface-base type-md-tight text-titles-and-attributes
    focus:outline-none p-2 rounded"
  {{on 'click' this.toggle}}
>
  toggle
</button>

More of our colors and tailwind classes can be found here: https://tailwind-toucan-base.pages.dev/

7. Invoke <ThemeToggle> in app/templates/application.hbs.

<ThemeToggle />

8. Start both the ember dev server and the tailwind build.

# in terminal 1
pnpm start
# in terminal 2
pnpm tailwind:watch

9. A local server will boot at http://localhosts:4200 and clicking the rendered button will toggle the background color.

Note that if you're using embroider + webpack, you also have the option to follow the popular guides on setting up tailwind with webpack

Tailwind 2

To configure an Ember App, modify:

• ember-cli-build.js

const EmberApp = require('ember-cli/lib/broccoli/ember-app');

const { configureTailwind } = require('@crowdstrike/ember-toucan-styles/ember-cli');

const tailwindConfig = require('./tailwind.config');

module.exports = function (defaults) {
  let app = new EmberApp(defaults, {
    ...configureTailwind({ tailwindConfig }),
  });

  return app.toTree();
};

• app/styles/app.css

@tailwind base;
@tailwind components;
@tailwind utilities;

NOTE: if you're also using css-modules, you'll want to import the css-modules output before @tailwind base;

// ember-cli-build.js

const EmberAddon = require('ember-cli/lib/broccoli/ember-addon');

const { configureTailwind } = require('@crowdstrike/ember-toucan-styles/ember-cli');

const tailwindConfig = require('./tailwind.config');

module.exports = function (defaults) {
  let app = new EmberAddon(defaults, {
    ...configureTailwind({ tailwindConfig }),
  });

  return app.toTree();
};

/* tests/dummy/app/styles/app.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

Add ember-cli-postcss to your devDependencies

And lastly, for tests in your addon to have colors, you'll need to set either theme-light or theme-dark on the body class.

It is recommended to avoid CSS-Modules, as Tailwind is very flexible -- it may require a different approach to achieve the stylistic goal though.

Follow these steps:

• remove ember-cli-postcss from your addon

• install ember-css-modules

• change ember-cli-build.js

  -const { configureTailwind } = require('@crowdstrike/ember-toucan-styles/ember-cli');
  +const { configureCSSModules } = require('@crowdstrike/ember-toucan-styles/ember-cli');

  To use this in an addon, you'll want to apply these to the options object of the v1 addon's index.js. V2 Addons do not support app-build modifications, so the app would need to configure css-modules support.

Usage

Components may be written following the tailwind documentation. Common CSS classes provided by the Toucan preset for Tailwind can be viewed here ( Source Code here ).

Example:

<button
  class="
    flex whitespace-nowrap bg-transparent type-md-tight text-titles-and-attributes
    focus:outline-none"
  type="button"
>
  A Button!
</button>

Scrollbar Styles

To get toucan-themed scrollbars in browsers that support scrollbar customization

/* some CSS file */
@import '@crowdstrike/ember-toucan-styles/scollbar.css'

or if you have a bundling environment that supports adding CSS as part of the module graph,

// some JavaScript or TypeScript file
import '@crowdstrike/ember-toucan-styles/scrollbar.css';

Using a Custom Theme Manager

Setup

Create an {app,addon}/services/my-theme-manager.js file, and at a minimum,

import { ThemeManager } from '@crowdstrike/ember-toucan-styles';

export default class MyThemeManager extends ThemeManager {
  // your modifications here
}

NOTE: If you are developing an addon and you want your custom theme-manager to also be called theme-manager, in your package.json, you'll need to specify that your addon runs "after" @crowdstrike/ember-toucan-styles

"ember-addon": {
  "after": [
    "@crowdstrike/ember-toucan-styles"
  ]
}

Setting the Default Theme

Somewhere in the consuming app or addon, run

import { inject as service } from '@ember/service';
import { THEMES } from '@crowdstrike/ember-toucan-styles';

class MyClass {
  @service themeManager;
  // or @service('my-theme-manager') themeManager;

  setup() {
    // using a default theme (THEMES.LIGHT)
    this.themeManager.setup();

    // or with a custom default theme
    this.themeManager.setup(THEMES.DARK);
  }
}

This will first checkout the current-theme key in local storage and if that doesn't exist, the the argument passed to setup() will be used as the default.

Responding to Theme Changes

It is possible to apply certain behaviors when a theme switch occurs, for example:

import { action } from '@ember/object';
import { inject as service } from '@ember/service';

import { THEMES, ThemeManager } from '@crowdstrike/ember-toucan-styles';

import { EVENTS } from '@crowdstrike/ui/analytics/ui';

export default class MyThemeManager extends ThemeManager {
  @service externalGraphics;
  @service analytics;

  @action
  onUpdateTheme(currentTheme, wasSaved = true) {
    let key = trackingKey(currentTheme);

    if (wasSaved) {
      this.analytics.trackEvent(this, key);
    }

    this.externalGraphics.updateTheme(currentTheme);
  }
}

function trackingKey(themeName) {
  switch (themeName) {
    case THEMES.DARK:
      return EVENTS.THEME.DARK;
    case THEMES.LIGHT:
      return EVENTS.THEME.LIGHT;
    default:
      throw new Error(`Theme not recognized: ${themeName}`);
  }
}

Using your own Tailwind Plugins

Add them to your .tailwind.config.js, as normal in https://tailwindcss.com/docs/plugins