Feature/documentation

README.md

@@ -3,87 +3,37 @@
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/af892fe4afc048c4860462c5fc736675)](https://www.codacy.com/gh/adoxography/tailwind-scrollbar/dashboard?utm_source=github.com&utm_medium=referral&utm_content=adoxography/tailwind-scrollbar&utm_campaign=Badge_Grade)
 ![npm](https://img.shields.io/npm/dt/tailwind-scrollbar)
 
-Adds styling utilities for scrollbars in Firefox and webkit-based browsers.
+`tailwind-scrollbar` is a plugin for [Tailwind CSS](https://tailwindcss.com) that adds styling utilities for scrollbars with cross-browser support.
+
+## Motivation
+There are currently two competing standards for styling scrollbars amongst browsers: the [scrollbar-width](https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-width) and [scrollbar-color](https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-color) properties used by Firefox and the [::-webkit-scrollbar](https://developer.mozilla.org/en-US/docs/Web/CSS/::-webkit-scrollbar) family of pseudoelements used by everything else\*. This plugin defines a single API for configuring both standards at once from within Tailwind.
 
 ## Installation
 
+1. Add the package to your project
 ```bash
-yarn add -D tailwind-scrollbar
-```
-or
-```bash
+# npm
 npm install --save-dev tailwind-scrollbar
+# yarn
+yarn add -D tailwind-scrollbar
+# pnpm
+pnpm add -D tailwind-scrollbar
 ```
 
-Add it to the plugins array of your Tailwind config.
+2. Add it to the plugins array of your Tailwind config
 
-```js
-plugins: [
+```javascript
+module.exports = {
     // ...
-    require('tailwind-scrollbar'),
-],
+    plugins: [
+        // ...
+        require('tailwind-scrollbar'),
+    ],
+};
 ```
 
 ## Usage
-
-**NB:** This plugin *styles* scrollbars; it does not force them to appear. Use typical CSS techniques to force content to overflow and trigger a scrollbar.
-
-For every element that you want to style, add either the `scrollbar` or `scrollbar-thin` class. You may then add any `scrollbar-track-{color}`, `scrollbar-thumb-{color}` or `hover:scrollbar-thumb-{color}` classes you like. (Note that `hover:scrollbar-thumb-{color}` classes only have effects in webkit-based browsers.)
-
-If you're using both vertical and horizontal scrollbars, you may notice a white square show up. You can change its colour with the `scrollbar-corner-{color}` utility.
-
-Here's a minimal example (keeping in mind that the `h-32` and `h-64` classes are just there to force the scrollbar to appear):
-
-```html
-<div class="h-32 scrollbar scrollbar-thumb-gray-900 scrollbar-track-gray-100">
-    <div class="h-64"></div>
-</div>
-```
-
-A live version of this demo [can be found here](https://tailwind-scrollbar-example.adoxography.repl.co/).
-
-## Configuration
-
-This plugin is capable of adding utilties for creating rounded scrollbars by referencing your configured [border radius](https://tailwindcss.com/docs/border-radius#customizing) settings. However, as they are only supported in chromium-based browsers, their usage is inadvisable in cross-browser applications. To enable rounded scrollbar utilities, pass `nocompatible: true` to the plugin during its declaration; e.g.:
-
-```js
-plugins: [
-    // ...
-    require('tailwind-scrollbar')({ nocompatible: true }),
-],
-```
-
-This will add utilities such as `scrollbar-thumb-rounded` or `scrollbar-thumb-rounded-md`.
-
-## Complete list of utilities
-All utilities are compatible with variants, unless otherwise specified.
-
-### Width utilities
-These utilities initialize scrollbar styling. You always need one of them, even if you're using custom widths. (See below.)
-
-| Utility     | Effect | Notes |
-|-------------|--------|-------|
-| `scrollbar` | Enables custom scrollbar styling, using the default width | On Firefox, this is `scrollbar-width: auto`, which is `16px`. Chrome is hard coded to `16px` for consistency. |
-| `scrollbar-thin` | Enables custom scrollbar styling, using the thin width | On Firefox, this is `scrollbar-width: thin`, which is `8px`. Chrome is hard coded to `8px` for consistency. |
-| `scrollbar-none` | Hides the scrollbar completely | Because of browser quirks, this cannot be used to hide an existing styled scrollbar - i.e. `scrollbar hover:scrollbar-none` will not work. |
-
-### Colour utilities
-All of the asterisks can be replaced [with any tailwind colour](https://tailwindcss.com/docs/customizing-colors#using-custom-colors), including [arbitrary values](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values) and [opacity modifiers](https://tailwindcss.com/docs/background-color#changing-the-opacity). With the exception of the width utilities, all utilities are inherited by child elements.
-
-| Utility     | Effect | Notes |
-|-------------|--------|-------|
-| `scrollbar-thumb-*` | Sets the colour of the scrollbar thumb | |
-| `scrollbar-track-*` | Sets the colour of the scrollbar track | |
-| `scrollbar-corner-*` | Sets the colour of the scrollbar corner | The corner will only appear if you have both vertical and horizontal scrollbars. |
-
-### Nocompatible utilities
-These styles are only available in `nocompatible` mode. They won't have any effect in Firefox.
-
-| Utility     | Effect | Notes |
-|-------------|--------|-------|
-| `scrollbar-w-*` | Sets the width of vertical scrollbars | The asterisk can be replaced with any Tailwind [width setting](https://tailwindcss.com/docs/width), including arbitrary values. Only applies to scrollbars styled with `scrollbar` (not `scrollbar-thin`). |
-| `scrollbar-h-*` | Sets the height of horizontal scrollbars | The asterisk can be replaced with any Tailwind [height setting](https://tailwindcss.com/docs/height), including arbitrary values. Only applies to scrollbars styled with `scrollbar` (not `scrollbar-thin`). |
-| `scrollbar-rounded-*` | Rounds a scrollbar thumb's corners | The asterisk can be replaced with any Tailwind [rounded setting](https://tailwindcss.com/docs/border-radius#using-custom-values), including arbitrary values. |
+See the [documentation](https://adoxography.github.io/tailwind-scrollbar/examples).
 
 ## License
 

website/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')]
+};

website/docs/examples.md

@@ -0,0 +1,131 @@
+---
+sidebar_position: 3
+---
+
+# Examples
+
+## Minimal example
+
+It's a good idea to start with an element that already has a scrollbar. Begin custom styling by adding either the `scrollbar` or `scrollbar-thin` utilities, then add a `scrollbar-thumb-*` and (optionally) a `scrollbar-track-*` utility to define your scrollbar colours.
+
+<div className="scrollbar scrollbar-thumb-sky-700 scrollbar-track-sky-300 h-32 overflow-y-scroll hover:scrollbar-thumb-sky-700 active:scrollbar-thumb-sky-700">
+    <div className="h-64 bg-slate-400"></div>
+</div>
+
+```html
+<div class="scrollbar scrollbar-thumb-sky-700 scrollbar-track-sky-300 h-32 overflow-y-scroll">
+    <div class="h-64 bg-slate-400"></div>
+</div>
+```
+
+## Global scrollbar colours
+
+The scollbar colour utilities are inherited, so if you want to use the same colours on every custom scrollbar, you can define them at a high-level element (e.g. `html`) and then simply add `scrollbar` or `scrollbar-thin` to each scrollbar you'd like to apply custom styling to.
+
+<div className="scrollbar-thumb-sky-700 scrollbar-track-sky-300 hover:scrollbar-thumb-sky-700 active:scrollbar-thumb-sky-700">
+    <div className="scrollbar-thin h-32 overflow-y-scroll">
+        <div className="h-64 bg-slate-400"></div>
+    </div>
+</div>
+
+```html
+<html className="scrollbar-thumb-sky-700 scrollbar-track-sky-300">
+    <!-- ... -->
+    <div className="scrollbar-thin h-32 overflow-y-scroll">
+        <div className="h-64 bg-slate-400"></div>
+    </div>
+    <!-- ... -->
+</html>
+```
+
+## Variants
+
+`hover:` and `active:` variants will be honoured in most browsers, but be aware that Firefox applies its own hover and active styling instead.
+
+All browsers are compatible with `dark:` variants.
+
+<div className="hover:scrollbar-thumb-sky-500 active:scrollbar-thumb-sky-400 h-32 scrollbar scrollbar-thumb-slate-700 scrollbar-track-slate-300 overflow-y-scroll">
+    <div className="h-64 bg-slate-400"></div>
+</div>
+
+```html
+<div class="hover:scrollbar-thumb-sky-500 active:scrollbar-thumb-sky-400 h-32 scrollbar scrollbar-thumb-slate-700 scrollbar-track-slate-300 overflow-y-scroll">
+    <div class="h-64 bg-slate-400"></div>
+</div>
+```
+
+## Custom colours
+
+The colour utilities can accept colours in any format Tailwind's native colour utilities like `bg-*` can, including [custom colours](https://tailwindcss.com/docs/customizing-colors#adding-additional-colors) and [arbitrary values](https://tailwindcss.com/docs/customizing-colors#arbitrary-values).
+
+<div className="scrollbar-thumb-custom scrollbar-track-custom-light hover:scrollbar-thumb-[#059669] active:scrollbar-thumb-emerald-500/50 scrollbar h-32 overflow-y-scroll">
+    <div className="h-64 bg-slate-400"></div>
+</div>
+
+```html
+<div class="scrollbar-thumb-custom scrollbar-track-custom-light hover:scrollbar-thumb-[#059669] active:scrollbar-thumb-emerald-500/50 scrollbar h-32 overflow-y-scroll">
+    <div class="h-64 bg-slate-400"></div>
+</div>
+```
+
+```javascript title="tailwind.config.js"
+module.exports = {
+    // ...
+    theme: {
+        extend: {
+            colors: {
+                custom: {
+                    DEFAULT: '#10B981',
+                    light: '#D1FAE5',
+                },
+            },
+        },
+    },
+};
+```
+
+## Corners
+
+When you have both a vertical and horizontal scrollbar, you'll end up with an empty box in the bottom right corner. You can use the `scrollbar-corner-*` utilities to colour this region as you would `scrollbar-thumb-*`.
+
+<div className="scrollbar-corner-sky-500 scrollbar scrollbar-thumb-slate-700 scrollbar-track-slate-300 h-32 overflow-scroll hover:scrollbar-thumb-slate-700 active:scrollbar-thumb-slate-700">
+    <div className="h-64 w-[100vw] bg-slate-400"></div>
+</div>
+
+```html
+<div class="scrollbar-corner-sky-500 scrollbar scrollbar-thumb-slate-700 scrollbar-track-slate-300 h-32 overflow-scroll">
+    <div class="h-64 w-[100vw] bg-slate-400"></div>
+</div>
+```
+
+## Rounded bars
+
+*These utilities only work in `nocompatible` mode, and have no effect in Firefox. See [configuration](/getting-started#configuration).*
+
+The `scrollbar-*-rounded-*` family of utilities can be applied to the `thumb`, `track`, or `corner` components, and work in the same was as Tailwind's native `rounded-*` utilities. Custom values and arbitrary values are permitted.
+
+<div className="scrollbar-thumb-rounded-full scrollbar-track-rounded-full scrollbar scrollbar-thumb-slate-700 scrollbar-track-slate-300 h-32 overflow-y-scroll hover:scrollbar-thumb-slate-700 active:scrollbar-thumb-slate-700">
+    <div className="h-64 bg-slate-400"></div>
+</div>
+
+```html
+<div class="scrollbar-thumb-rounded-full scrollbar-track-rounded-full scrollbar scrollbar-thumb-slate-700 scrollbar-track-slate-300 h-32 overflow-y-scroll">
+    <div class="h-64 bg-slate-400"></div>
+</div>
+```
+
+## Custom sizes
+
+*These utilities only work in `nocompatible` mode, and have no effect in Firefox. See [configuration](/getting-started#configuration).*
+
+The `scrollbar-w-*` and `scrollbar-h-*` utilities can be used to fine-tine the width and height of scrollbars. Note that these only have effects on vertical and horizontal scrollbars, respectively, and can only be used with the `scrollbar` utility (not `scrollbar-thin`).
+
+<div className="scrollbar-w-8 scrollbar scrollbar-thumb-slate-700 scrollbar-track-slate-300 h-32 overflow-y-scroll hover:scrollbar-thumb-slate-700 active:scrollbar-thumb-slate-700">
+    <div className="h-64 bg-slate-400"></div>
+</div>
+
+```html
+<div class="scrollbar-w-8 scrollbar scrollbar-thumb-slate-700 scrollbar-track-slate-300 h-32 overflow-y-scroll">
+    <div class="h-64 bg-slate-400"></div>
+</div>
+```

website/docs/getting-started.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 2
+---
+
+# Getting Started
+
+## Installation
+
+1. Add the package to your project
+```bash
+# npm
+npm install --save-dev tailwind-scrollbar
+# yarn
+yarn add -D tailwind-scrollbar
+# pnpm
+pnpm add -D tailwind-scrollbar
+```
+
+2. Add it to the plugins array of your Tailwind config
+
+```javascript
+module.exports = {
+    // ...
+    plugins: [
+        // ...
+        require('tailwind-scrollbar'),
+    ],
+};
+```
+
+## Configuration
+
+By default, only utilities that can have expressions across browsers are available. In order to access additional utilities that may not exist in all browsers, like [rounding](/examples#rounded-bars) and [custom sizes](/examples#custom-sizes), you can add the `nocompatible` flag to the configuration.
+
+```javascript
+module.exports = {
+    // ...
+    plugins: [
+        // ...
+        require('tailwind-scrollbar')({ nocompatible: true }),
+    ],
+};
+```
+
+## Usage
+
+[See the examples](/examples)

website/docs/intro.md

@@ -0,0 +1,32 @@
+---
+slug: /
+sidebar_position: 1
+---
+
+# Introduction
+
+`tailwind-scrollbar` is a plugin for [Tailwind CSS](https://tailwindcss.com) that adds styling utilities for scrollbars with cross-browser support.
+
+## Motivation
+
+There are currently two competing standards for styling scrollbars amongst browsers: the [scrollbar-width](https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-width) and [scrollbar-color](https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-color) properties used by Firefox and the [::-webkit-scrollbar](https://developer.mozilla.org/en-US/docs/Web/CSS/::-webkit-scrollbar) family of pseudoelements used by everything else\*. This plugin defines a single API for configuring both standards at once from within Tailwind.
+
+_\* As of Chrome v118, `scrollbar-width` and `scrollbar-color` are now supported with the `#enable-experimental-web-platform-features` flag._
+
+### What this plugin isn't
+
+#### A scrollbar triggering tool
+
+This plugin _styles_ scrollbars; it does not force them to appear. Use typical CSS techniques to get the scrollbar in place (e.g. the `overflow-*` family of utilities), and then use the utilities in this plugin to style it from there.
+
+#### A fully custom scrollbar
+
+This plugin is intented to unify existing browser APIs; it's not meant to create fully custom scrollbar elements. As such, it is limited to some extent in terms of what kinds of scrollbars it can create.
+
+#### Perfect cross-browser replication
+
+Scrollbars in different browsers and operating systems look different and have different degrees of customizability. This plugin won't make them look exactly the same; it will just help you ensure that they don't clash with your site's theme.
+
+## License
+
+This project is licensed under the [MIT License](https://github.com/adoxography/tailwind-scrollbar/blob/main/LICENSE).