Custom CSS

July 31, 2019 · View on GitHub

Custom CSS

Introduction
Styling components with variables
- Function addStyle
Choosing CSS-in-JS or CSS files
Examples
- Mithril example
- React JSX example
Global styling by overriding Polythene defaults
List of all variables

Introduction

Polythene components are styled with variables that specify the sizes and colors for that component. The variables are used to create a component style, to be written by JavaScript or to a CSS file.

Component style variables are located in each component's CSS vars.js file (see the complete list of all variables below).

For example, the variables file for Icon is:

// polythene-css-icon/src/vars.js
import { vars } from "polythene-theme"

export default {
  size_small:   vars.unit_icon_size_small,
  size_regular: vars.unit_icon_size,
  size_medium:  vars.unit_icon_size_medium,
  size_large:   vars.unit_icon_size_large,
  color_light:  "currentcolor",
  color_dark:   "currentcolor"
}

"Global" variables such as unit_icon_size_small are imported from polythene-theme (which gets them from package polythene-style). To override these base variables, see Global theme file.

Styling components with variables

Component variables are passed on to CSS creation modules (usually "layout" and "colors") that take variables and return a style object. The style object is converted to a style sheet by j2c.

Each component's CSS functions can be accessed with the naming pattern {ComponentName}CSS:

import { IconCSS } from "polythene-css"

You may also choose to import directly from the component's CSS package:

import { addStyle } from "polythene-css-icon"

Call addStyle to create a style:

IconCSS.addStyle(selector, {
  // CSS style key value pairs
})

For example, to change the size and color of an icon:

IconCSS.addStyle(".my-icon", {
  size_regular: 44,
  color_light:  "purple"
})

Then use that style for a specific component instance:

m(Icon, { className: "my-icon" })

or using React with JSX:

<Icon className="my-icon" />

Function `addStyle`

addStyle(selector, vars, options)

Option	Required	Type	Description
selector	required	String	CSS selector; using a class selector is the most convenient because of the reuse in component option `className`
vars	required	Object	The component's theme variables, or a subset thereof

// app.js
import { Icon } from "polythene-mithril"
import { IconCSS } from "polythene-css"

const unitSize = 20

IconCSS.addStyle(".app-icon", {
  size_large: 4 * unitSize
  // Note that we only need to list the variables that differ
})

// Show the large icon
m(Icon, {
  className: "app-icon",
  size: "large" // results in 4 * unitSize
})

To create a blue button on a dark background:

// app.js
import { Button } from "polythene-mithril"
import { ButtonCSS } from "polythene-css"

ButtonCSS.addStyle(".blue-on-dark-button", {
  color_dark_text: "#1976D2"
})

// Show the blue button on a dark background
m(".pe-dark-tone", 
  m(Button, {
    className: "blue-on-dark-button",
    label: "Blue Button"
  })
)

React JSX example

If we want to create large icons:

// app.js
import { Icon } from "polythene-react"
import { IconCSS } from "polythene-css"

const unitSize = 20

IconCSS.addStyle(".app-icon", {
  size_large: 4 * unitSize
  // Note that we only need to list the variables that differ
})

// Show the large icon
<Icon className="app-icon" size="large" />

To create a blue button on a dark background:

// app.js
import { Button } from "polythene-react"
import { ButtonCSS } from "polythene-css"

ButtonCSS.addStyle(".blue-on-dark-button", {
  color_dark_text: "#1976D2"
})

// Show the blue button on a dark background
<div className="pe-dark-tone">
  <Button
    className="blue-on-dark-button"
    label="Blue Button"
  />
</div>

Global styling by overriding Polythene defaults

Using the same method it is possible to override the default styling, just by using Polythene classnames:

IconCSS.addStyle(".pe-icon", {
  color_light:  "purple"
})

To override global variables such as the app's primary action color, see Global theme file.

List of all variables

Global variables:

polythene-style

Component variables: