From f1869771bc8b8e8a6c7a98385ec58e0bf0d2d98e Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Sat, 14 Dec 2013 14:18:43 -0800 Subject: [PATCH] Fixes #10505: Document more of LESS vars and mixins --- _includes/nav-css.html | 8 + css.html | 460 +++++++++++++++++++++++++++++++++++++++ docs-assets/css/docs.css | 29 +++ 3 files changed, 497 insertions(+) diff --git a/_includes/nav-css.html b/_includes/nav-css.html index 0228932dd3..b180bbf56a 100644 --- a/_includes/nav-css.html +++ b/_includes/nav-css.html @@ -105,3 +105,11 @@
  • Test cases
    • +
  • + Using LESS + +
    • diff --git a/css.html b/css.html index 9f22ec10d2..83e0a70933 100644 --- a/css.html +++ b/css.html @@ -2710,3 +2710,463 @@ For example, <section> should be wrapped as inline. + + + + +
    +
    +

    Using LESS

    +
    +

    Bootstrap's CSS is built on LESS, a preprocessor with additional functionality like variables, mixins, and functions for compiling CSS. Thosing looking to use the source LESS files instead of our compiled CSS files can make use of the numerous variables and mixins we use throughout the framework.

    + +

    Grid variables and mixins are covered within the Grid system section.

    + + +

    Variables

    +

    Variables are used throughout the entire project as a way to centralize and share commonly used values like colors, spacing, or font stacks. For a complete breakdown, please see the Customizer.

    + +

    Colors

    +

    Easily make use of two color schemes: grayscale and semantic. Grayscale colors provide quick access to commonly used shades of black while semantic include various colors assigned to meaningful contextual values.

    +
    +
    +
    +
    +
    +
    +
    +
    +
    +{% highlight css %} +@gray-darker: lighten(#000, 13.5%); // #222 +@gray-dark: lighten(#000, 20%); // #333 +@gray: lighten(#000, 33.5%); // #555 +@gray-light: lighten(#000, 60%); // #999 +@gray-lighter: lighten(#000, 93.5%); // #eee +{% endhighlight %} + +
    +
    +
    +
    +
    +
    +
    +
    +
    +{% highlight css %} +@brand-primary: #428bca; +@brand-success: #5cb85c; +@brand-warning: #f0ad4e; +@brand-danger: #d9534f; +@brand-info: #5bc0de; +{% endhighlight %} + +

    Use any of these color variables as they are or reassign them to more meaningful variables for your project.

    +{% highlight css %} +// Use as-is +.masthead { + background-color: @brand-primary; +} + +// Reassigned variables in LESS +@alert-message-background: @brand-info; +.alert { + background-color: @alert-message-background; +} +{% endhighlight %} + +

    Scaffolding

    +

    A handful of variables for quickly customizing key elements of your site's skeleton.

    +{% highlight css %} +// Scaffolding +@body-background: #fff; +@text-color: @black-50; +{% endhighlight %} + + +

    Easily style your links with the right color with only one value.

    +{% highlight css %} +// Variables +@link-color: @brand-primary; +@link-color-hover: darken(@link-color, 15%); + +// Usage +a { + color: @link-color; + text-decoration: none; + + &:hover { + color: @link-color-hover; + text-decoration: underline; + } +} +{% endhighlight %} +

    Note that the @link-color-hover uses a function, another awesome tool from LESS, to automagically create the right hover color. You can use darken, lighten, saturate, and desaturate.

    + +

    Typography

    +

    Easily set your type face, text size, leading, and more with a few quick variables. Bootstrap makes use of these as well to provide easy typographic mixins as well.

    +{% highlight css %} +@font-family-sans-serif: "Helvetica Neue", Helvetica, Arial, sans-serif; +@font-family-serif: Georgia, "Times New Roman", Times, serif; +@font-family-monospace: Menlo, Monaco, Consolas, "Courier New", monospace; +@font-family-base: @font-family-sans-serif; + +@font-size-base: 14px; +@font-size-large: ceil((@font-size-base * 1.25)); // ~18px +@font-size-small: ceil((@font-size-base * 0.85)); // ~12px + +@font-size-h1: floor((@font-size-base * 2.6)); // ~36px +@font-size-h2: floor((@font-size-base * 2.15)); // ~30px +@font-size-h3: ceil((@font-size-base * 1.7)); // ~24px +@font-size-h4: ceil((@font-size-base * 1.25)); // ~18px +@font-size-h5: @font-size-base; +@font-size-h6: ceil((@font-size-base * 0.85)); // ~12px + +@line-height-base: 1.428571429; // 20/14 +@line-height-computed: floor((@font-size-base * @line-height-base)); // ~20px + +@headings-font-family: inherit; +@headings-font-weight: 500; +@headings-line-height: 1.1; +@headings-color: inherit; +{% endhighlight %} + +

    Icons

    +

    Two quick variables for customizing the location and filename of your icons.

    +{% highlight css %} +@icon-font-path: "../fonts/"; +@icon-font-name: "glyphicons-halflings-regular"; +{% endhighlight %}} + +

    Components

    +

    Components throughout Bootstrap make use of some default variables for setting common values. Here are the most commonly used.

    +{% highlight css %} +@padding-base-vertical: 6px; +@padding-base-horizontal: 12px; + +@padding-large-vertical: 10px; +@padding-large-horizontal: 16px; + +@padding-small-vertical: 5px; +@padding-small-horizontal: 10px; + +@padding-xs-vertical: 1px; +@padding-xs-horizontal: 5px; + +@line-height-large: 1.33; +@line-height-small: 1.5; + +@border-radius-base: 4px; +@border-radius-large: 6px; +@border-radius-small: 3px; + +@component-active-color: #fff; +@component-active-bg: @brand-primary; + +@caret-width-base: 4px; +@caret-width-large: 5px; +{% endhighlight %}} + + +

    Vendor mixins

    +

    Vendor mixins are mixins to help support multiple browsers by including all relevant vendor prefixs in your compiled CSS.

    + + +

    Box-sizing

    +

    Reset your components' box model with a single mixin. For context, see this helpful article from Mozilla.

    +{% highlight css %} +.box-sizing(@box-model) { + -webkit-box-sizing: @box-model; // Safari <= 5 + -moz-box-sizing: @box-model; // Firefox <= 19 + box-sizing: @box-model; +} +{% endhighlight %} + +

    Rounded corners

    +

    Today all modern browsers support the non-prefixed border-radius property. As such, there is no .border-radius() mixin, but Preboot does include shortcuts for quickly rounding two corners on a particular side of an object.

    +{% highlight css %} +.border-top-radius(@radius) { + border-top-right-radius: @radius; + border-top-left-radius: @radius; +} +.border-right-radius(@radius) { + border-bottom-right-radius: @radius; + border-top-right-radius: @radius; +} +.border-bottom-radius(@radius) { + border-bottom-right-radius: @radius; + border-bottom-left-radius: @radius; +} +.border-left-radius(@radius) { + border-bottom-left-radius: @radius; + border-top-left-radius: @radius; +} +{% endhighlight %} + +

    Box (Drop) shadows

    +

    If your target audience is using the latest and greatest browsers and devices, be sure to just use the box-shadow property on it's own. If you need support for older Android (pre-v4) and iOS devices (pre-iOS 5), use of the mixin to pick up the required -webkit prefix.

    +

    Be sure to use rgba() colors in your box shadows so they blend as seamlessly as possible with backgrounds.

    +{% highlight css %} +.box-shadow(@shadow: 0 1px 3px rgba(0,0,0,.25)) { + -webkit-box-shadow: @shadow; // iOS <4.3 & Android <4.1 + box-shadow: @shadow; +} +{% endhighlight %} + +

    Transitions

    +

    Three mixins for flexibility. Set all transition information with one, or specify a separate delay and duration as needed.

    +{% highlight css %} +.transition(@transition) { + -webkit-transition: @transition; + transition: @transition; +} +.transition-property(@transition-property) { + -webkit-transition-property: @transition-property; + transition-property: @transition-property; +} +.transition-delay(@transition-delay) { + -webkit-transition-delay: @transition-delay; + transition-delay: @transition-delay; +} +.transition-duration(@transition-duration) { + -webkit-transition-duration: @transition-duration; + transition-duration: @transition-duration; +} +.transition-transform(@transition) { + -webkit-transition: -webkit-transform @transition; + -moz-transition: -moz-transform @transition; + -o-transition: -o-transform @transition; + transition: transform @transition; +} +{% endhighlight %} + +

    Transformations

    +

    Rorate, scale, translate (move), or skew any object.

    +{% highlight css %} +.rotate(@degrees) { + -webkit-transform: rotate(@degrees); + -ms-transform: rotate(@degrees); // IE9 only + transform: rotate(@degrees); +} +.scale(@ratio; @ratio-y...) { + -webkit-transform: scale(@ratio, @ratio-y); + -ms-transform: scale(@ratio, @ratio-y); // IE9 only + transform: scale(@ratio, @ratio-y); +} +.translate(@x; @y) { + -webkit-transform: translate(@x, @y); + -ms-transform: translate(@x, @y); // IE9 only + transform: translate(@x, @y); +} +.skew(@x; @y) { + -webkit-transform: skew(@x, @y); + -ms-transform: skewX(@x) skewY(@y); // See https://github.com/twbs/bootstrap/issues/4885; IE9+ + transform: skew(@x, @y); +} +.translate3d(@x; @y; @z) { + -webkit-transform: translate3d(@x, @y, @z); + transform: translate3d(@x, @y, @z); +} + +.rotateX(@degrees) { + -webkit-transform: rotateX(@degrees); + -ms-transform: rotateX(@degrees); // IE9 only + transform: rotateX(@degrees); +} +.rotateY(@degrees) { + -webkit-transform: rotateY(@degrees); + -ms-transform: rotateY(@degrees); // IE9 only + transform: rotateY(@degrees); +} +.perspective(@perspective) { + -webkit-perspective: @perspective; + -moz-perspective: @perspective; + perspective: @perspective; +} +.perspective-origin(@perspective) { + -webkit-perspective-origin: @perspective; + -moz-perspective-origin: @perspective; + perspective-origin: @perspective; +} +.transform-origin(@origin) { + -webkit-transform-origin: @origin; + -moz-transform-origin: @origin; + -ms-transform-origin: @origin; // IE9 only + transform-origin: @origin; +} +{% endhighlight %} + +

    Opacity

    +

    Set the opacity for all browsers and provide a filter fallback for IE8.

    +{% highlight css %} +.opacity(@opacity) { + opacity: @opacity; + // IE8 filter + @opacity-ie: (@opacity * 100); + filter: ~"alpha(opacity=@{opacity-ie})"; +} +{% endhighlight %} + +

    Placeholder text

    +

    Provide context for form controls within each field.

    +{% highlight css %} +.placeholder(@color: @input-color-placeholder) { + &:-moz-placeholder { color: @color; } // Firefox 4-18 + &::-moz-placeholder { color: @color; } // Firefox 19+ + &:-ms-input-placeholder { color: @color; } // Internet Explorer 10+ + &::-webkit-input-placeholder { color: @color; } // Safari and Chrome +} +{% endhighlight %} + +

    Columns

    +

    Generate columns via CSS within a single element.

    +{% highlight css %} +.content-columns(@width; @count; @gap) { + -webkit-column-width: @width; + -moz-column-width: @width; + column-width: @width; + -webkit-column-count: @count; + -moz-column-count: @count; + column-count: @count; + -webkit-column-gap: @gap; + -moz-column-gap: @gap; + column-gap: @gap; +} +{% endhighlight %} + +

    Gradients

    +

    Easily turn any two colors into a background gradient. Get more advanced and set a direction, use three colors, or use a radial gradient. With a single mixin you get all the prefixed syntaxes you'll need.

    +{% highlight css %} +#gradient > .vertical(#333; #000); +#gradient > .horizontal(#333; #000); +#gradient > .radial(#333; #000); +{% endhighlight %} +

    You can also specify the angle of a standard two-color, linear gradient:

    +{% highlight css %} +#gradient > .directional(#333; #000; 45deg); +{% endhighlight %} +

    If you need a barber-stripe style gradient, that's easy, too. Just specify a single color and we'll overlay a translucent white stripe.

    +{% highlight css %} +#gradient > .striped(#333; #000; 45deg); +{% endhighlight %} +

    Up the ante and use three colors instead. Set the first color, the second color, the second color's color stop (a decimal value like 0.25), and the third color with these mixins:

    +{% highlight css %} +#gradient > .vertical-three-colors(#777; #333; .25; #000); +#gradient > .horizontal-three-colors(#777; #333; .25; #000); +{% endhighlight %} +

    Heads up! Should you ever need to remove a gradient, be sure to remove any IE-specific filter you may have added. You can do that by using .reset-filter() mixin alignside background-image: none;.

    + + +

    Utility mixins

    +

    Utility mixins are mixins that combine otherwise unrelated CSS properties to achieve a specific goal or task.

    + +

    Clearfix

    +

    Forget adding class="clearfix" to any element and instead add the .clearfix() mixin where appropriate. Uses the micro clearfix from Nicolas Gallager.

    +{% highlight css %} +// Mixin +.clearfix() { + &:before, + &:after { + content: " "; + display: table; + } + &:after { + clear: both; + } +} + +// Usage +.container { + .clearfix(); +} +{% endhighlight %} + +

    Horizontal centering

    +

    Quickly center any element within its parent. Requires width or max-width to be set.

    +{% highlight css %} +// Mixin +.center-block() { + display: block; + margin-left: auto; + margin-right: auto; +} + +// Usage +.container { + width: 940px; + .center-block(); +} +{% endhighlight %} + +

    Sizing helpers

    +

    Specify the dimensions of an object more easily.

    +{% highlight css %} +// Mixins +.size(@width; @height) { + width: @width; + height: @height; +} +.square(@size) { + .size(@size; @size); +} + +// Usage +.image { .size(400px; 300px); } +.avatar { .square(48px); } +{% endhighlight %} + +

    Resizable textareas

    +

    Easily configure the resize options for any textarea, or any other element. Defaults to normal browser behavior (both).

    +{% highlight css %} +.resizable(@direction: both) { + // Options: horizontal, vertical, both + resize: @direction; + // Safari fix + overflow: auto; +} +{% endhighlight %} + +

    Truncating text

    +

    Easily truncate text with an ellipsis with a single mixin. Requires element to be block or inline-block level.

    +{% highlight css %} +// Mixin +.text-truncate() { + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +// Usage +.branch-name { + display: inline-block; + max-width: 200px; + .text-truncate(); +} +{% endhighlight %} + +

    Retina images

    +

    Specify two image paths and the @1x image dimensions, and Preboot will provide an @2x media query. If you have many images to serve, consider writing your retina image CSS manually in a single media query.

    +{% highlight css %} +.img-retina(@file-1x; @file-2x; @width-1x; @height-1x) { + background-image: url("@{file-1x}"); + + @media + only screen and (-webkit-min-device-pixel-ratio: 2), + only screen and ( min--moz-device-pixel-ratio: 2), + only screen and ( -o-min-device-pixel-ratio: 2/1), + only screen and ( min-device-pixel-ratio: 2), + only screen and ( min-resolution: 192dpi), + only screen and ( min-resolution: 2dppx) { + background-image: url("@{file-2x}"); + background-size: @width-1x @height-1x; + } +} + +// Usage +.jumbotron { + .retina-image("/img/bg-1x.png", "/img/bg-2x.png", 100px, 100px); +} +{% endhighlight %} +
    diff --git a/docs-assets/css/docs.css b/docs-assets/css/docs.css index 15b533dd96..28d93e4e9a 100644 --- a/docs-assets/css/docs.css +++ b/docs-assets/css/docs.css @@ -597,6 +597,35 @@ h1[id] { } +/* + * Color swatches + * + * Color swatches and associated values for our grayscale and brand colors. + */ + +.color-swatches { + margin: 0 -5px; + overflow: hidden; /* clearfix */ +} +.color-swatch { + float: left; + width: 100px; + height: 100px; + margin: 0 5px; + border-radius: 3px; +} +.color-swatches .gray-darker { background-color: #222; } +.color-swatches .gray-dark { background-color: #333; } +.color-swatches .gray { background-color: #555; } +.color-swatches .gray-light { background-color: #999; } +.color-swatches .gray-lighter { background-color: #eee; } +.color-swatches .brand-primary { background-color: #428bca; } +.color-swatches .brand-success { background-color: #5cb85c; } +.color-swatches .brand-warning { background-color: #f0ad4e; } +.color-swatches .brand-danger { background-color: #d9534f; } +.color-swatches .brand-info { background-color: #5bc0de; } + + /* * Team members * -- 2.47.2