@texastribune/ds-toolbox-assets

SCSS framework and icon library

Install

yarn add @texastribune/ds-toolbox-assets

npm install @texastribune/ds-toolbox-assets

Using the CSS framework

In your scss file, you can mix and match if you only need certain helpers.

Example

@import "@texastribune/ds-toolbox-assets/scss/1-settings/all";
@import "@texastribune/ds-toolbox-assets/scss/5-typography/t-size";
@import "@texastribune/ds-toolbox-assets/scss/6-components/icon/icon";

Or you can take the whole base if you're styling a page with no outside CSS expected.

Example

@import '@texastribune/ds-toolbox-assets/scss/base-v2';

Contributing to the CSS framework

SCSS docs boilerplate

How to document a new CSS class

We use a comment parser along with some extra logic to generate our docs. To add a new section of documentation, add a boilerplate above your CSS rules like the one below:

// Title of Section (root-class-name)
//
// Description {{isWide}} {{isHelper}}
//
// root-class-name-modifier - desc
//
// Markup: 6-components/test/test.html
//
// Styleguide 6.0.1
//
.root-class-name {
  
}

{{isWide}} is used to display the demo of each modifier at full width
{{isHelper}} is used to hide main demo and only display modifiers
// Deprecated is used to signify a class to be removed. See Deprecating a CSS class for details.

Naming and organization

ITCSS

We organize our SCSS files with the inverted triangle approach in mind. We put our own spin on it by adding a typography and layouts folder, but the general idea is all the same; increased specificity as you move down the stylesheet.

BEM

We closely follow the BEM (Block Element Modifier) class naming convention in our components folder, but we break BEM rules in other places. This is a deliberate attempt to create a hybrid approach of using BEM when scoped to a component and helper classes when styling globally in a more ad hoc context.

Namespacing

Use namespacing for quick reference of the function of a CSS class. The following key can be used a guideline for naming your class:

Components

.c-component-name[__<element>|--<-modifier>] {}

Example: c-button

Typography

.t-type-util {}

Example: t-headline

Layout

.l-layout-util {}

Example: l-container

Utilities

.[is|has]-state {}

Example: has-bg-yellow

Legacy styles

This toolbox is a living system and we use it to keep a vigilant eye on how we're using CSS throughout our various products. As an outcome, there are times we will need to deprecate naming conventions, class names, and approaches within our system.

Deprecating a CSS class

We denote any class not to be used moving forward in our commenting boilerplate with the following syntax:

// Title of Section (root-class-name)
//
// Deprecated: Description of old usage and why it's being removed
//
// ...

As we phase out classes, we must be mindful of where those classes are relied upon in our various repos and ultimately our public-facing products.

Steps for removing a class:

Add the deprecation notice to the comment. // Deprecated: This class was used for x, but were phasing it out for y because...
Note where the classes appear according to the docs. (You should see a repo name and count signifying potential HTML usages in the docs interface.)
Push your changes to a branch in this repo.
Publish a new version to npm.
In the repo where this is used, yarn add @texastribune/ds-toolbox-assets@0.0.? to import your toolbox changes.
Compile the assets in the outside repo.
Preview the page using the HTML with the classes you altered. Does it break a style? Does it reference a class no longer attached to any CSS? Update the HTML accordingly.
Once everything is looking stable, merge your branch in this repo with master.