# Tailwind Compositor
Compositor is a system of constraints designed to produce aesthetically pleasing, typographic compositions, based on objective, constant dimensions of space.
A baseline-grid typography system for [tailwindcss](https://tailwindcss.com/).
Algorithm Demo: [Styled Baseline](https://styled-baseline.netlify.app/)
---
## Installation
You will need fontkit, postcss and tailwindcss installed along with the plugin
```
npm install postcss fontkit tailwindcss tailwind-compositor
```
#### - postcss.config.js
In your `postcss.config.js` you will need to import your standard `tailwind.config.js`, but also your `compositor.config.js`.
The `{ compositor }` will receive both, merge with your tailwind config, and return a standard tailwind configuration.
```
const tailwindcss = require('tailwindcss');]
const { compositor } = require('tailwind-compositor');
// import both configurations
const compositorConfig = require('./compositor.config.js');
const tailwindConfig = require('./tailwind.config.js');
// compose config
const tailwindConfigComposed = compositor(compositorConfig)(tailwindConfig);
// use with tailwind
module.exports = {
plugins: [
tailwindcss(tailwindConfigComposed),
],
};
```
---
## Configuration
#### - compositor.config.js
```
const compositorConfig = {
// root unit
root: 16,
// baseline grid height in px units
baseline: 8,
// maximum leading
leading: 4,
// matrix max columns
matrix: 4,
// type scale in px units
type: [16, 18, 20, 22, 24, 28, 30, 32, 40, 48, 56, 60, 72],
// spacing scale in baseline units
rhythm: [0, 1, 2, 3, 4, 5, 6, 8, 10, 12],
// line width in ch units
measure: [10, 15, 20, 30, 35, 50, 55, 60, 65],
// webfonts and vertical metrics
fonts: [
{
key: "sans-400",
familyName: "Inter",
fallback: "sans-serif",
weight: 400,
italic: false,
upm: 2816,
xHeight: 1536,
capHeight: 2048,
ascent: 2728,
descent: -680
}
{
key: 'sans-600',
familyName: "Inter",
fallback: 'sans-serif',
file: path.resolve('./fonts/inter/Inter-Semibold.woff2'),
},
],
// compositor options
options: {
useRem: true,
snap: true,
type: true,
rhythm: true,
measure: true,
matrix: true,
xray: true,
},
}
```
---
#### 1/9 - root: integer
The root font size, in `px` units.
---
#### 2/9 - baseline: integer
The baseline grid row height, in `px` units.
---
#### 3/9 - leading: integer
The maximum leading value in baseline units.
---
#### 4/9 - matrix: integer
The maximum columns on the matrix utility
---
#### 5/9 - type : array[integer]
```
type: [16, 18, 20, 22, 24, 28, 30, 32, 40, 48, 56, 60, 72]
```
The system's typographic scale, in `px` units.
---
#### 6/9 - rhythm : array[integer]
```
rhythm: [0, 1, 2, 3, 4, 5, 6, 8, 10, 12]
```
The system's size and spacing scale, in `baseline` units, used for `rhythm`, `margin`, `padding`, `width/min/max`, `height/min/max` and `grid-gap` utilities
---
#### 7/9 - measure : array[integer]
```
measure: [10, 15, 20, 30, 35, 50, 55, 60, 65]
```
Separate scale used for `measure` (line-width) utilities, configured in `ch` units.
---
#### 8/9 - fonts : array[opentype]
The font scale provides all the information needed to render text styles. Each entry describes a font/weight/style set, and only those that are part of the system will be enabled.
The `file` property, is used to extract the vertical metrics dynamically from the font-file. If you want to configure the metrics manually, you can omit the `file` prop.
The `key` property is used to name the utility classes. The configuration bellow will produce four font styles. The recommended convention is `${family}-${weight}${style}`.
1. `font-sans-400` : Inter Regular
2. `font-sans-400i` : Inter Regular Italic
3. `font-sans-600i` : Inter Semibold
4. `font-sans-600i` : Inter Semibold Italic
```
{
key: "sans-400",
familyName: "Inter",
fallback: "sans-serif",
weight: 400,
italic: false,
upm: 2816,
xHeight: 1536,
capHeight: 2048,
lineGap: 0,
ascent: 2728,
descent: -680
}
{
key: 'sans-400i',
familyName: "Inter",
fallback: 'sans-serif',
file: path.resolve('./fonts/inter/Inter-Italic.woff2'),
},
{
key: 'sans-600',
familyName: "Inter",
fallback: 'sans-serif',
file: path.resolve('./fonts/inter/Inter-Semibold.woff2'),
},
{
key: 'sans-600i',
familyName: "Inter",
fallback: 'sans-serif',
file: path.resolve('./fonts/inter/Inter-SemiboldItalic.woff2'),
},
```
---
#### 9/9 - Options : object
Options properties, are used to enable/disable individual compositor utilities.
If `useRem` is set to true, compositor will use the root unit value, to transform all spacing and font-size utilities, to relative units. Line-height will be transformed to unitless ratios.
If `snap` is true, compositor will align each line text to the nearest baseline grid row, otherwise will trim the line-height above the capHeight and below the baseline, and apply a constant lineGap between lines of text.
- `useRem: boolean` transform to relative units
- `snap: boolean` Align text styles to a baseline grid
`type: boolean` Enable typographic utilities
- `rhythm: boolean` Enable rhythm utilities
- `measure: boolean` Enable measure utilities
- `matrix: boolean` Enable matrix utilities
- `xray: boolean` Enable debug utilities
```
options: {
useRem: true,
snap: true,
type: true,
rhythm: true,
measure: true,
matrix: true,
xray: true,
}
```
---
## Tailwind Utility Classes
#### 1/7 - Typography
##### Font & Font Style
- font: `font-{font-key}`
```
// fonts: [
// { key: "sans-400", ... },
// { key: 'sans-400i', ... },
// { key: 'sans-600', ... },
// { key: 'sans-600i', ... },
// ],
// sans semibold italic
// sans regular
// sans regular italic
```
##### Text Style
- Text Style : `text-{type_scale_index}/{leading_baseline_units}`
```
// type: [16, 18, 20, 22, 24, 28, 30, 32, 40, 48, 56]
// sans semibold italic - 56px / leading 3
// sans regular - 20px / leading 3
// sans regular italic - 18px / leading 2
```
---
#### 2/7 - Line Width
- `measure-{measure_scale_index}`
```
// measure: [10, 15, 20, 30, 35, 50, 55, 60, 65]
// 10ch
Ad proident quis enim duis commodo.
// 15ch
Ad proident quis enim duis commodo.
// 20ch
Ad proident quis enim duis commodo.
// 30ch
Ad proident quis enim duis commodo.
```
---
#### 3/7 - Spacing
When the tailwind theme is composed, the rhythm scale is transformed to tailwindcss spacing scale and can be used for all spacing utilities, margin, padding and grid-gap.
- Margin: `m-{rhythm_scale_index}`
- Margin Left: `ml-{rhythm_scale_index}`
- Padding: `p-{rhythm_scale_index}`
- ...etc
```
// rhythm: [0, 1, 2, 3, 4, 5, 6, 8, 10, 12]
```
---
#### 4/7 - Size
Compositor also applies the spacing scale to tailwind sizing scales, width, min/max width and also height min/max.
- Height: `h-{rhythm_scale_index}`
- Min Height: `min-h-{rhythm_scale_index}`
- Max Height: `max-h-{rhythm_scale_index}`
- ...etc
-
```
```
---
#### 5/7 - Lobotomized Owls
- Vertical rhythm (alias): `rhythm-{rhythm_scale_index}`
- Vertical rhythm: `rhythm-y-{rhythm_scale_index}`
- Horizontal Rhythm: `rhythm-x-{rhythm_scale_index}`
```
// render horizontally
```
---
#### 6/7 - Matrix Utils
##### Matrix
- Matrix: `matrix-{columns_length}`
- Matrix Gap: `matrix-gap-{rhythm_scale_index}`
- Matrix Gap X: `matrix-gap-x-{rhythm_scale_index}`
- Matrix Gap Y: `matrix-gap-y-{rhythm_scale_index}`
##### Cells
By default every child of the matrix, will be placed in the next available column and will span for 1 column. In many cases you might not need any cell utilities or only the `cell-span-x` utility.
- Cell Start X: `cell-start-x-{columns_index}`
- Cell Span X: `cell-span-x-{columns_index}`
---
#### 7/7 - Dev Utils
- Background grid lines: `bg-baseline`
```
```