tailwindcss-golden-ratio
Version:
A Tailwind CSS plugin to add spacing utility classes based on the Golden Ratio
207 lines (162 loc) • 6.24 kB
Markdown
[](https://goldenratio.app) — built to help devs create better designs by _*[TRUE FRONTIER](https://truefrontierapps.com)*_
This Tailwind plugin introduces a set of utilities based on the Golden Ratio, a mathematical constant that occurs frequently in nature and is believed to be aesthetically pleasing. The plugin aims to simplify and beautify spacing conventions in Tailwind CSS by providing a consistent and visually appealing set of spacing values.
- [Spacing Cheatsheet](https://goldenratio.app/#/spacing)
- [The Golden Grid](https://goldenratio.app/#/grid) for creating grid layouts with the Golden Ratio
- [The Gold Calculator](https://goldenratio.app/#/calculator) for finding what combination of values will be equivalent to another set of values
```
npm i -D tailwindcss-golden-ratio
```
*tailwind.config.js*
```js
module.exports = {
// ...
theme: {
// ...
goldenRatio: {
// Custom configuration @see: https://github.com/truefrontier/tailwindcss-golden-ratio/tree/master#how-to-customize
},
},
plugins: [
require('tailwindcss-golden-ratio'),
],
}
```
The plugin generates utility classes for the following Tailwind properties:
- spacing (includes margin, padding, and various other spacing-related properties)
- aspectRatio
- backgroundSize
- borderRadius
- borderWidth
- divideWidth
- fontSize
- gap
- height
- inset
- lineHeight
- maxHeight
- maxWidth
- minHeight
- minWidth
- outlineOffset
- outlineWidth
- ringOffsetWidth
- ringWidth
- scale
- scrollMargin
- scrollPadding
- space
- strokeWidth
- translate
- textIndent
- textUnderlineOffset
- width
Each property has utility classes for the 11 main Golden Ratio values, as well as their halves and doubles. Because there are 11 values, this puts 6 in the middle, so 6 is the base unit. By default this base unit is `1.5rem`;
`mt-gr-6` => `margin-top: var(--golden-ratio-6)` => `margin-top: 1.5rem`
Any number lower will lessen this base unit by a factor of 1.61803398875 (the Golden Ratio). Numbers 7-11 increase this base unit by a factor of 1.618...
`mt-gr-5` => `margin-top: var(--golden-ratio-5)` => `margin-top: 0.927051rem` (1.5 / 1.61803)
`mt-gr-4` => `margin-top: var(--golden-ratio-4)` => `margin-top: 0.572949rem` (1.5 / 1.61803 / 1.61803)
...
`mt-gr-7` => `margin-top: var(--golden-ratio-7)` => `margin-top: 2.42705rem` (1.5 * 1.61803)
`mt-gr-8` => `margin-top: var(--golden-ratio-8)` => `margin-top: 3.92705rem` (1.5 * 1.61803 * 1.61803)
...
Sometimes you may need the fixed equivalents for the golden ratios. It comes in handy when making sure resized SVGs don't get cut off and font-sizes don't change if the system accessibility settings try to adjust it.
You can use fixed units when you use the `grf` prefix. By default there are 16px for each spacer unit.
`mt-grf-6` => `margin-top: var(--golden-ratio-fixed-6)` => `margin-top: 24px` (1.5 * 16)
By default the px value will be rounded, but you can change that under [customization](
For aspect ratio we set `aspect-gr-6` as the base. So it has `1 / 1` (or a square) `aspect-ratio` value.
Anything under 6 will become portrait (smaller width):
`aspect-gr-5` => `aspect-ratio: 0.618034 / 1`
Anything over 6 will become landscape (larger width):
`aspect-gr-7` => `aspect-ratio: 1.618034 / 1`
This plugin is highly configurable, allowing you to customize the prefix, unit, rounding behavior, and more.
*tailwind.config.js*
```js
module.exports = {
// ...
theme: {
// ...
goldenRatio: {
/**
* Use a prefix instead of overwriting existing spacing utilities
* @type {Boolean|String}
* default: true|'gr-'
* example: 'golden-ratio-' would generate classes like mt-golden-ratio-2);
*/
prefix: true,
/**
* The spacing unit
* @type {String}
* default: 'rem'
*/
spacerUnit: 'rem',
/**
* The starting point for spacing
* @type {Number}
* default: 1.5
*
* There are 11 spacing values in this system.
* That puts the 6 value in the middle, so it is the base.
* Setting the spacerBase to `1.5` will make `m-gr-6` => `margin: 1.5rem`
*
* Values 5-1 get exponentially smaller by the golden-ratio factor.
* eg. `m-gr-5` => `margin: 0.927051rem` // value comes from (1.5 / 1.61803)
* eg. `m-gr-4` => `margin: 0.572949rem` // value comes from (1.5 / 1.61803 / 1.61803)
*
* Values 7-11 get expontially larger by the golden-ratio factor.
* eg. `m-gr-7` => `margin: 2.42705rem` // value comes from (1.5 * 1.61803)
* eg. `m-gr-8` => `margin: 3.92705rem` // value comes from (1.5 * 1.61803 * 1.61803)
*
*/
spacerBase: 1.5,
/**
* The unit for fixed spacing
* @type {String}
* default: 'px'
*
* This duplicates the golden ratio spacing but fixed.
* This gives you more control when working with things like:
* - system font-size settings for accessiblility
*/
fixedSpacerUnit: 'px',
/**
* How many fixed units are in 1 spacer base unit
* @type {Number}
* default: 16
*
* example: `m-grf-6` => `24px` // value comes from (16 * 1.5) where 1.5 is the spacer unit
*/
fixedUnitsPerSpacerUnit: 16,
/**
* Round to the nearest pixel
* @type {Boolean}
* default: true
*
* If you want to use the fixed values, you probably don't want partial pixels.
* This gives you more control when working with things like:
* - not cutting off svgs on certain devices
*/
roundFixedValues: true,
/**
* Use css variables for generated values
* @type {Boolean}
*
* This is useful if you ever want to use custom calc()
* eg. -translate-y-[calc(100%+var(--golden-ratio-6))]
*/
useCssVars: true
},
// ...
},
plugins: [
require('tailwindcss-golden-ratio'),
],
// ...
}
```