From bdc7587de597c6b1d43124d54e578492c1143193 Mon Sep 17 00:00:00 2001 From: Adam Wathan Date: Mon, 30 Oct 2017 12:57:34 -0400 Subject: [PATCH 1/5] Add more details to installation docs --- docs/source/_assets/less/markdown.less | 9 +++ docs/source/installation.blade.md | 103 +++++++++++++++++++------ 2 files changed, 89 insertions(+), 23 deletions(-) diff --git a/docs/source/_assets/less/markdown.less b/docs/source/_assets/less/markdown.less index 35884deb2..e6f5a64ce 100644 --- a/docs/source/_assets/less/markdown.less +++ b/docs/source/_assets/less/markdown.less @@ -79,6 +79,15 @@ @apply .text-lg; } + > h4, h4& { + @apply .mt-8; + @apply .mb-0; + @apply .text-slate-darker; + @apply .leading-none; + @apply .font-semibold; + @apply .text-base; + } + > p, p&, > blockquote > p { @apply .text-slate-dark; @apply .mt-4; diff --git a/docs/source/installation.blade.md b/docs/source/installation.blade.md index 42edab79f..07e53c2bb 100644 --- a/docs/source/installation.blade.md +++ b/docs/source/installation.blade.md @@ -9,15 +9,15 @@ title: "Installation" Quick start guide for installing and configuring Tailwind. -## 1. Install the dependency +## 1. Install Tailwind via npm Tailwind is [available on npm](https://www.npmjs.com/package/tailwindcss) and can be installed using npm or Yarn.
# Using npm
-
npm install tailwindcss
+
npm install tailwindcss --save-dev
# Using Yarn
-
yarn install tailwindcss
+
yarn add tailwindcss --dev
## 2. Create a Tailwind config file @@ -32,7 +32,9 @@ Alternatively, you can simply copy the default config file [from here](https://g ## 3. Add Tailwind to your CSS -Next, you need to add Tailwind to your main stylesheet. This can be plain CSS, Less, Sass, Stylus, or something else. There order here is important, so please follow this structure: +Use the `@@tailwind` directive to inject Tailwind's `reset` and `utilities` styles into your CSS. + +To avoid specificity issues, we highly recommend structuring your main stylesheet like this: ```less /** @@ -42,48 +44,103 @@ Next, you need to add Tailwind to your main stylesheet. This can be plain CSS, L * You can see the styles here: * https://github.com/nothingworksinc/tailwindcss/blob/master/css/preflight.css */ -@tailwind reset; +@@tailwind reset; /** * Here you would import any custom component classes; stuff that you'd * want loaded *before* the utilities so that the utilities can still * override them. */ -@import "my-components/foo"; -@import "my-components/bar"; +// @@import "my-components/foo"; +// @@import "my-components/bar"; /** * This injects all of Tailwind's utility classes, generated based on your * config file. */ -@tailwind utilities; +@@tailwind utilities; /** * Here you would add any custom utilities you need that don't come out of the box with Tailwind. */ -.bg-hero-image { - background-image: url('/some/image/file.png'); +// .bg-hero-image { +// background-image: url('/some/image/file.png'); +// } +``` + +## 4. Process your CSS with Tailwind + +### Using Tailwind CLI + +For simple projects or just giving Tailwind a spin, you can use the Tailwind CLI tool to process your CSS: + +
+
./node_modules/.bin/tailwind styles.css [-c ./your-tailwind-config.js] [-o ./output.css]
+
+ +### Using Tailwind with PostCSS + +For most projects, you'll want to add Tailwind as a PostCSS plugin in your build chain. + +We've included the Tailwind-specific instructions for a few popular tools below, but for instructions on getting started with PostCSS in general, see the [PostCSS documentation](https://github.com/postcss/postcss#usage). + +#### Webpack + +Add `tailwindcss` as a plugin in your `postcss.config.js` file, passing the path to your config file: + +```js +var tailwindcss = require('tailwindcss'); +module.exports = { + plugins: [ + // ... + tailwindcss('./path/to/your/tailwind-config.js'), + // ... + ] } ``` -## 4. Add Tailwind to your build process +### Gulp -Finally, you'll need to add Tailwind to your build process. Fair warning: this can be the trickiest step. For simple projects you can use the Tailwind CLI tool to generate your CSS: - -
-
./node_modules/.bin/tailwind styles.css [-c ./custom-config.js] [-o ./output.css]
-
- -For most projects, you'll want to add Tailwind as a PostCSS plugin in your build chain, passing your config object as a parameter. Here's an example using [Laravel Mix](https://laravel.com/docs/5.5/mix): +Add `tailwindcss` to the list of plugins you pass to [gulp-postcss](https://github.com/postcss/gulp-postcss), passing the path to your config file: ```js -const mix = require('laravel-mix'); -const tailwind = require('tailwindcss'); +gulp.task('css', function () { + var postcss = require('gulp-postcss'); + var tailwindcss = require('tailwindcss'); -mix.less('resources/assets/less/app.less', 'public/css') + return gulp.src('src/styles.css') + // ... + .pipe(postcss([ + // ... + tailwindcss('./path/to/your/tailwind-config.js'), + // ... + ])) + // ... + .pipe(gulp.dest('build/')); +}); +``` + +#### Laravel Mix + +If you're writing your project in plain CSS, use Mix's `postCss` method to process your CSS. Include `tailwindcss` as a plugin and pass the path to your config file: + +```js +var tailwindcss = require('tailwindcss'); + +mix.postCss('resources/assets/css/main.css', 'public/css', [ + tailwindcss('./path/to/your/tailwind-config.js'), +]); +``` + +If you're using a preprocessor, use the `options` method to add `tailwindcss` as a PostCSS plugin: + +```js +var tailwindcss = require('tailwindcss'); + +mix.less('source/_assets/less/main.less', 'source/css') .options({ postCss: [ - tailwind(require('./path/to/your/tailwind/config.js')) + tailwindcss('./path/to/your/tailwind-config.js'), ] - }); + }) ``` From 9880e16821c1ddc1f488c1948de0b8b340e57d2a Mon Sep 17 00:00:00 2001 From: Adam Wathan Date: Mon, 30 Oct 2017 12:58:04 -0400 Subject: [PATCH 2/5] Don't double declare `font-family: inherit` on buttons --- __tests__/fixtures/tailwind.css | 1 - css/preflight.css | 1 - 2 files changed, 2 deletions(-) diff --git a/__tests__/fixtures/tailwind.css b/__tests__/fixtures/tailwind.css index b1d1e9d56..3f6b21548 100644 --- a/__tests__/fixtures/tailwind.css +++ b/__tests__/fixtures/tailwind.css @@ -555,7 +555,6 @@ input::placeholder { button, [role=button] { - font-family: inherit; cursor: pointer; } diff --git a/css/preflight.css b/css/preflight.css index 4be97e1db..8a98969ac 100644 --- a/css/preflight.css +++ b/css/preflight.css @@ -95,6 +95,5 @@ input::placeholder { } button, [role=button] { - font-family: inherit; cursor: pointer; } From a0bca677656777bed7cf50f4492243ae596bf88b Mon Sep 17 00:00:00 2001 From: Adam Wathan Date: Mon, 30 Oct 2017 13:01:07 -0400 Subject: [PATCH 3/5] Remove base styles page We can add something around this later if we want. --- docs/source/_layouts/master.blade.php | 1 - docs/source/base.blade.md | 14 -------------- 2 files changed, 15 deletions(-) delete mode 100644 docs/source/base.blade.md diff --git a/docs/source/_layouts/master.blade.php b/docs/source/_layouts/master.blade.php index e7f86d6c8..4aeb400fc 100644 --- a/docs/source/_layouts/master.blade.php +++ b/docs/source/_layouts/master.blade.php @@ -87,7 +87,6 @@

Styles

    -
  • Base
  • Backgrounds
      diff --git a/docs/source/base.blade.md b/docs/source/base.blade.md deleted file mode 100644 index e5a258ed3..000000000 --- a/docs/source/base.blade.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -extends: _layouts.markdown -title: "Base" ---- - -# Base - -
      - Usage - Responsive - Customizing -
      - -Document our base styles. From 795534c5318966aa20ecc0fb9fae04838244a37f Mon Sep 17 00:00:00 2001 From: Adam Wathan Date: Mon, 30 Oct 2017 13:13:37 -0400 Subject: [PATCH 4/5] Polish functions and directives docs --- docs/source/functions-and-directives.blade.md | 69 ++++++++++--------- 1 file changed, 35 insertions(+), 34 deletions(-) diff --git a/docs/source/functions-and-directives.blade.md b/docs/source/functions-and-directives.blade.md index 1a994542d..299effe3f 100644 --- a/docs/source/functions-and-directives.blade.md +++ b/docs/source/functions-and-directives.blade.md @@ -5,11 +5,11 @@ title: "Functions & Directives" # Functions & Directives -Tailwind exposes a few CSS functions and directives that can be used in your actual CSS files. +Tailwind exposes a few custom CSS functions and directives that can be used in your actual CSS files. -## `@tailwind` +## `@@tailwind` -Use the `@tailwind` directive to insert the Tailwind reset styles and utilities into your CSS file. Here is a full example of how you might do this: +Use the `@@tailwind` directive to insert Tailwind's `reset` and `utilities` styles into your CSS. Here is a full example of how you might do this: ```less /** @@ -19,36 +19,21 @@ Use the `@tailwind` directive to insert the Tailwind reset styles and utilities * You can see the styles here: * https://github.com/nothingworksinc/tailwindcss/blob/master/css/preflight.css */ -@tailwind reset; - -/** - * Here you would import any custom component classes; stuff that you'd - * want loaded *before* the utilities so that the utilities can still - * override them. - */ -@import "my-components/foo"; -@import "my-components/bar"; +@@tailwind reset; /** * This injects all of Tailwind's utility classes, generated based on your * config file. */ -@tailwind utilities; - -/** - * Here you would add any custom utilities you need that don't come out of the box with Tailwind. - */ -.bg-hero-image { - background-image: url('/some/image/file.png'); -} +@@tailwind utilities; ``` -## `@responsive` +## `@@responsive` -You can generate responsive versions of your own utilities by wrapping their definitions in the `@responsive` directive: +You can generate responsive versions of your own classes by wrapping their definitions in the `@responsive` directive: ```less -@responsive { +@@responsive { .bg-gradient-brand { background-image: linear-gradient(blue, green); } @@ -61,51 +46,67 @@ This will generate these classes (assuming you haven't changed the default break .bg-gradient-brand { background-image: linear-gradient(blue, green); } -@media (min-width: 576px) { + +// ... + +@@media (min-width: 576px) { .sm\:bg-gradient-brand { background-image: linear-gradient(blue, green); } + // ... } -@media (min-width: 768px) { + +@@media (min-width: 768px) { .md\:bg-gradient-brand { background-image: linear-gradient(blue, green); } + // ... } -@media (min-width: 992px) { + +@@media (min-width: 992px) { .lg\:bg-gradient-brand { background-image: linear-gradient(blue, green); } + // ... } -@media (min-width: 1200px) { + +@@media (min-width: 1200px) { .xl\:bg-gradient-brand { background-image: linear-gradient(blue, green); } + // ... } ``` -## `@screen` +The responsive versions will be added to Tailwind's existing media queries at the end of your stylesheet to make sure classes with a responsive prefix always defeat non-responsive classes that are targeting the same CSS property. -Say you have a `sm` breakpoint at `576px`, and you need to write some custom CSS that references this breakpoint. +## `@@screen` -Instead of duplicating the values like this: +The `@@screen` directive allows you to create media queries that reference your breakpoints by name instead of duplicating their values in your own CSS. + +For example, say you have a `sm` breakpoint at `576px` and you need to write some custom CSS that references this breakpoint. + +Instead of writing a raw media query that duplicates that value like this: ```less -@media (min-width: 576px) { +{{ '@media (min-width: 576px) {' }} /* ... */ } ``` -...you can use the `@screen` directive and pass the breakpoint name: +...you can use the `@@screen` directive and reference the breakpoint by name: ```less -@screen sm { +@@screen sm { /* ... */ } ``` ## `config()` -With all your variables defined in your JavaScript-based Tailwind config file, you may be wondering how you access those values in your custom CSS. This can be done using the `config()` helper function. Here is an example: +While it's recommended to use the `@@apply` directive to compose custom CSS out of existing utility classes whenever possible, some times you need direct access to your Tailwind config values. + +Use the `config()` function to access your Tailwind config values using dot notation: ```less .error { From 991c4d664f34ec47b5b15fac6f32b24dfa602f4d Mon Sep 17 00:00:00 2001 From: Adam Wathan Date: Mon, 30 Oct 2017 13:23:48 -0400 Subject: [PATCH 5/5] Document @apply helper --- docs/source/functions-and-directives.blade.md | 40 ++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/source/functions-and-directives.blade.md b/docs/source/functions-and-directives.blade.md index 299effe3f..5e22d4cb4 100644 --- a/docs/source/functions-and-directives.blade.md +++ b/docs/source/functions-and-directives.blade.md @@ -28,6 +28,44 @@ Use the `@@tailwind` directive to insert Tailwind's `reset` and `utilities` styl @@tailwind utilities; ``` +## `@@apply` + +Use `@@apply` to mixin the contents of existing classes into your custom CSS. + +This is extremely useful when you find a common utility pattern in your HTML that you'd like to extract to a new component. + +```less +.btn { + @@apply .font-bold .py-2 .px-4 .rounded; +} +.btn-blue { + @@apply .bg-blue .text-white; +} +.btn-blue:hover { + @@apply .bg-blue-dark; +} +``` + +Note that `@@apply` **will not work** for mixing in hover or responsive variants of another utility. Instead, mixin the plain version of that utility into the `:hover` pseudo-selector or a new media query: + +```less +// Won't work: +.btn { + @@apply .md:inline-block; + @@apply .hover:bg-blue; +} + +// Do this instead: +.btn { + &:hover { + @@apply .bg-blue; + } + @@screen md { + @@apply .inline-block; + } +} +``` + ## `@@responsive` You can generate responsive versions of your own classes by wrapping their definitions in the `@responsive` directive: @@ -78,7 +116,7 @@ This will generate these classes (assuming you haven't changed the default break } ``` -The responsive versions will be added to Tailwind's existing media queries at the end of your stylesheet to make sure classes with a responsive prefix always defeat non-responsive classes that are targeting the same CSS property. +The responsive versions will be added to Tailwind's existing media queries **at the end of your stylesheet.** This makes sure that classes with a responsive prefix always defeat non-responsive classes that are targeting the same CSS property. ## `@@screen`