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.5"

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.css (and a minifed version, honeycomb.min.css): only contains our custom classes and components, excluding all Tailwind utility classes and resets.

• honeycomb.base.css (and minified version, honeycomb.base.min.css): contains all components as well as the core Tailwind resets and defaults.

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

@import "./node_modules/@schoolstatus/honeycomb/dist/css/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: 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.5" ,
    "tailwindcss": "^3.3.3"
  }
}

Then run npm install to install it and all dependencies. Honeycomb has quite a few PostCSS and related dependencies specifically for compiling it so you may see a lot of those in your .node_modules. These are not required at all if you’re just including our precompiled CSS files, for reference.

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: ['./src/docs/**/*.{html,md,js}'],
  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': {},
    'postcss-each': {},
    tailwindcss: {},
    autoprefixer: {},
    ...(process.env.PREFIX === 'true'
      ? { 
        'postcss-advanced-variables': { 
          variables: { 
            'hc-prefix': 'hc-',
            'hc-version': process.env.npm_package_version,
          },
          unresolved: 'ignore'
        } 
      } : { 
        'postcss-advanced-variables': {
          variables: { 
            'hc-prefix': '',
            'hc-version': process.env.npm_package_version,
          },
          unresolved: 'ignore' 
        } 
      }
    ),
    ...(process.env.ENVIRONMENT === 'production'
      ? { cssnano: {} }
      : {}
    )
  }
}

This file assumes all of our PostCSS dependencies have been installed. It accounts for any prefixing and other environement settings.

Import CSS assets

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

To only include the core set of Honeycomb components with no Tailwind resets/defaults or utility classes, use core.css. Use base.css to add in the resets and defaults, and use full.css to include a bunch of relevant utility classes as well.

@import "./node_modules/@schoolstatus/honeycomb/src/publish/core.css";

Importantly, you should also modify the content: [], value in your tailwind.config.js file to ensure that PostCSS will look at all of the relevant places that have Honeycomb classes and components for tree-shaking purposes.

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.example 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.

There are two Honeycomb environment variables in here: PREFIX and PREFIX_VALUE. The default that we ship is to use a prefix and for that prefix to be .hc-, which is what all of our components are prefixed with in the distributed CSS files and as referenced in the documentation.

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

Patch releases

For patch releases, we have a new bash script at /bin/release.sh that will handle everything.

Ensure that CHANGELOG.md has a new section for the version that you’re creating. This will be one above the current version, and should be in the following format:

## [0.4.5] - YYYY-MM-DD

### Added

* Brief explanation of what was added

### Changed
### Fixed
### Removed

Only include the headings/sections if you’re adding, changing, fixing, or removing something, as applicable.

Next simply run ./bin/release.sh "{Release title}" and it will increment the version number, compile all distributed assets, tag the commit to the new version number, push this commit and the tag to GitHub, publish these assets as a new release in the registry, and then create a new GitHub release.

Major and Minor releases

Major and minor releases need to be done manually still and should be infrequent. Documentation forthcoming on all of the steps, with the final NPM registry command:

$> npm publish --access restricted