Getting Started with Honeycomb

Honeycomb is the SchoolStatus design system and drop-in CSS/Javascript package, built on top of Tailwind CSS, Flowbite, and the Tailwind ecosystem. Add it to your application and use as much or as little as you need.

Installing Honeycomb

Honeycomb is now published as a GitHub package in their npm registry. Because the project is internal, however, the package has a restricted scope and there are few extra steps to installing it.

1. Generate a personal access token in GitHub

The first extra step is generating a personal access token in any GitHub account that can access Honeycomb. Most likely this will be your SchoolStatus SSO account, which will have org-level access by default.

Go to GitHub > Settings > Developer Settings > Personal access tokens and click “Generate new token.” Classic tokens are currently the only token that can access a package so you’ll need to use that for now.

When you create the token, ensure that the read:packages scope is selected. This is the only scope this token needs. Give it a name and a desired expiration date, then click “Generate token.” On the confirmation screen, copy the token to a secure place as this is your only chance to save this.

If you’re using an organization SSO account, you’ll also need to authorize this token via SSO. On the tokens screen for the token you just created, click “Configure SSO” and work through the authentication flow. Once the token is authorized it will be ready to use.

You’ll now use this token to install Honeycomb in your given package manager.

2a. Installing via npm/pnpm

Create or update your project’s .npmrc file

In order to tell npm to look at the GitHub registry for this package you need to first create or add the following lines to your project’s .npmrc file.

@schoolstatus:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken={PERSONAL_ACCESS_TOKEN}
always-auth=true

Make sure to include the personal access token you just generated.

Add Honeycomb to your package.json file

Now add the Honeycomb package to your package.json file, either manually or via command line:

$> npm install @schoolstatus/honeycomb@latest --save-dev

You can add the version number to target a specific version now or install without that. This will add the following line to package.json and pull the package into ./node_modules:

"@schoolstatus/honeycomb": "^0.4.2"

2b. Installing via Yarn

The installation steps for Yarn v1 are the same as above for npm/pnpm.

If you’re using Yarn v2, you need to create or edit a .yarnrc.yml file in your project root instead of an .npmrc file. Add the following to the npmScopes section:

npmScopes:
  "schoolstatus":
    npmAlwaysAuth: true
    npmAuthToken: {PERSONAL_ACCESS_TOKEN}
    npmRegistryServer: "https://npm.pkg.github.com"

Then install the Honeycomb package via command line as follows:

$> yarn add @schoolstatus/honeycomb

Importing Honeycomb into your project

Once installed, we provide a few different ways to get Honeycomb into your application. You can simply import one of the compiled CSS files and accompanying font files from ./dist depending on how much of the library you want. Alternatively, if you’re already running Tailwind, you can pull in Honeycomb’s Tailwind configuration and components as part of your asset preprocessing/compilation.

Method 1: Importing Honeycomb’s assets manually

If you don’t want to add Tailwind to your project or only want to import the minimum CSS and JS, you can simply import the distributed files of your choice.

CSS

We currently distribute two different versions of Honeycomb’s CSS files:

• honeycomb.base.css (and a minifed version, honeycomb.base.min.css): only contains our custom classes and components, excluding all utility classes and our theme color classes.

• honeycomb.css (and minified version, honeycomb.min.css): contains all components as well as the core Tailwind utility and theme classes, like margin and background color, etc.

Depending on your frontend build process, you can import one of these files to add its CSS:

@import "./node_modules/@schoolstatus/honeycomb/dist/honeycomb.min.css";

/* the rest of your CSS includes or classes \*/
@import "./layout.css";
@import "./something-else.css";

Fonts

Make sure that the Civil web font files in ./dist/font/ are also copied to a /font directory in the same location as the CSS file(s) you copied to /css. The distributed CSS files will look up a directory in ../font/.

JavaSript

Honeycomb has very minimal JS for light interactions that can’t be done via CSS transitions and animations. These JS files are split out as individual modules and bundled into one honeycomb.js file for production.

Import this JS file depending on your build process:

<script src="js/honeycomb.js" type="module"></script>

Method 2 (preferred): Compiling Honeycomb and Tailwind

If you’re already using Tailwind or would like to add Tailwind to your application, you can compile Honeycomb with it as part of your asset preprocessing/compilation process. This installation doc assumes you’re using npm and PostCSS, but any package manager and preprocessor will work.

Add and configure Tailwind and Honeycomb

First add Tailwind (as well as Honeycomb) to your package.json file. Here’s a sample package.json that has both and assumes you followed the Honeycomb installation steps above:

{
  "name": "Demo",
  "version": "1.0.0",
  "main": "index.html",
  "devDependencies": {
    "@schoolstatus/honeycomb": "^0.4.2" ,
    "tailwindcss": "^3.3.3"
  }
}

Then run npm install to install it and all dependencies.

Create your Tailwind configuration file as tailwind.config.js in your project root. Pull in Honeycomb’s presets into your Tailwind config so that when you build Tailwind, it uses our theme and options:

module.exports = {
  presets: [
    require('./node_modules/@schoolstatus/honeycomb/honeycomb.config.js')
  ],
  content: [],
  safelist: [],
  extend: [],
}

You can also add any additional customizations here and extend Tailwind as you normally would. Our preset file will overwrite some of Tailwind’s defaults (like the color palette), but anything in extend will only add on to those attributes.

Configure PostCSS

Next, create your PostCSS configuration file as postcss.config.js in the project root and ensure that this file has the appropriate plugins necessary. Here’s a sample file:

require('dotenv').config();

module.exports = {
  parser: 'postcss-scss',
  plugins: {
    'postcss-import': {},
    'tailwindcss/nesting': {},
    tailwindcss: {},
    autoprefixer: {},
    ...(process.env.ENVIRONMENT === 'production'
      ? { cssnano: {} }
      : {}
    )
  }
}

Import CSS assets

Import Tailwind and Honeycomb in your main CSS file that PostCSS will process:

@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";
@import "./node_modules/@schoolstatus/honeycomb/src/base.css";

This will add any of the Tailwind utility classes as well as Honeycomb component classes that you use in your project’s HTML and JS.

Import JS and font assets

Finally, ensure that you’re also building or compiling the JavaScript and static font assets as well.

By default, the Honeycomb Sass/CSS files look in ../font/ for the Civil webfont files. This will soon be a customization option but if you change this location now you’ll need to change that in the CSS file as well.

There is one distributed JS file, honeycomb.js, that must be imported as a module as well.

Configuration

Honeycomb uses dotenv to manage local environment variables that affect the build.

You can override the defaults by copying .env.template from Honeycomb’s root to your project directory and renaming it .env or honeycomb.env or honeycomb.prod.env or whatever works for your environment. If you’re already using dotenv you could also just copy these values into your existing file.

Each of the Tailwind flags can be set to true to force all of that category of CSS classes to be built into your resulting CSS file, regardless of any tree-shaking or whether they appear in your content path.

Publishing new versions

@todo

$> npm publish --access restricted