Writing a library

Classy-UI allows you to create a powerful library where the consuming project will only produce the CSS required based on what it imports. In addition if you want to allow extending styling the consumer can only extend within the limitations of the design system you have created.

A demo library

The following repository is a demo library that shows how you can set up a library that allows you to consume CSS with or without UI frameworks, where all of them derives from the same set of composed tokens. It also shows how you would configure your application to consume the library.

Consuming the library

The big benefit of consuming a Classy-UI library is that the application will optimally produce the styles necessary for whatever it consumes. In addition you can restrict the consumers to the design system set up by exposing preset configurations of the design system to build different types of applications. You can also restrict what can be extended and extend only with tokens from the design system.

Classy-UI requires the library to be part of the build of the application itself. That means you will need to configure the build system to include the library as part of the bundling. Read the readme.md of the demo library above to see how that works.

If the library exposes its own configuration you can simply create a classy-ui.config.js file and require the config from the library:

module.exports = {
...require('some-classy-ui-library/config'),
// Add any custom stuff
}

Creating the library

There are many ways to expose a library with Classy-UI.

Tokens

This type of library just overrides the default tokens of Classy-UI, meaning you can create a more a different identity of the design. You can broaden it, or narrow it. Maybe you want to expose a set of tokens which fits with Material Design?

module.exports = {
colors: {
RED_50: 'red'
}
}

In this config of the app:

classy-ui.config.js
module.exports = {
tokens: require('some-classy-ui-tokens-lib')
}

Configuration tool

This type of library is a function where you narrow a custom set of options that will produce the tokens for the app.

const defaultTokens = require('classy-ui/tokens')
module.exports = (colors) => ({
...defaultTokens,
colors
})

In this config of the app:

classy-ui.config.js
const config = require('some-classy-ui-config-lib')
module.exports = config({
RED_50: 'red'
})

Composed tokens

This type of library is a set of predefined token compositions. This makes you agnostic to frameworks, but can still give a notion of components. You can add type documentation to these to enrich the experience along the same lines of Classy-UI itself. That means you can add images or links to where the composition can be explored further.

import { compose, tokens } from 'classy-ui'
/**
* A button component to be used with:
* - <button />
* ![button](https://my-lib.io/examples/button.png)
*/
export const button = compose(
tokens.backgroundColor.GRAY_20,
tokens.borderRadius.RADIUS_20
)
/**
* An avatar component to be used with:
* - <div />
* ![button](https://my-lib.io/examples/button.png)
*/
export const avatar = compose(tokens.borderRadius.FULL)

Components

This is where you get specific to a framework, for example React. This lets you also define what elements the classnames are used with. Again you can use type documentation, either images or links to for example Storybook, where the component can be explored further.

import { compose, tokens } from 'classy-ui'
import React from 'react'
/**
* A Button component to be used with
* ![button](https://my-lib.io/examples/button.png)
*/
export const Button = ({ children ) => {
const className = compose(
tokens.backgroundColor.GRAY_20,
tokens.borderRadius.RADIUS_20
)
return <button className={className}>{children}</button>
}

Multi framework components

The demo library on this repo exposes components for React, Vue and Angular. We are going to use Storybook to write our library. It is a complex project, but it shows you how far you can go with Classy-UI to build a library.