Skip to content

Instantly share code, notes, and snippets.

@adamlogic

adamlogic/compass_and_css_sprites.md

Created September 1, 2012 15:26
Show Gist options
  • Save adamlogic/3577147 to your computer and use it in GitHub Desktop.
Save adamlogic/3577147 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. adamlogic revised this gist Sep 5, 2012. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion compass_and_css_sprites.md
    View file
    Original file line number Diff line number Diff line change
    @@ -68,7 +68,7 @@ In my recent project, I took this a bit further by defining my own mixin.
    $spritemap-spacing: 50px
    @import "spritemap/*.png"
    @mixin background-sprite($name, $repeat: no-repeat, $offset-x: 0, $offset-y: 0)
    =background-sprite($name, $repeat: no-repeat, $offset-x: 0, $offset-y: 0)
    background-image: $spritemap-sprites
    background-repeat: $repeat
    +sprite-background-position($spritemap-sprites, $name, $offset-x, $offset-y)
  2. adamlogic revised this gist Sep 5, 2012. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion compass_and_css_sprites.md
    View file
    Original file line number Diff line number Diff line change
    @@ -12,7 +12,7 @@ want so badly to use this feature and why it's been painful each time. The why
    is easy: CSS sprites significantly reduce HTTP requests, and manually building
    sprite maps and calculating sprite positions is a pain in the ass. If I'm going
    to use sprites, it has to be done in an automated fashion. Since I'm already
    using Compass, and Compass has CSS spriting built-in, it seems a no-brainer.
    using Compass, and Compass has CSS spriting built-in, it seems a no-brainer.
    This is a feature I need to be using.

    Unfortunately, [the docs](http://compass-style.org/help/tutorials/spriting/)
  3. adamlogic revised this gist Sep 5, 2012. 1 changed file with 2 additions and 4 deletions.
    6 changes: 2 additions & 4 deletions compass_and_css_sprites.md
    View file
    Original file line number Diff line number Diff line change
    @@ -11,10 +11,8 @@ Before I go into the nitty-gritty, let's take a step back and talk about why I
    want so badly to use this feature and why it's been painful each time. The why
    is easy: CSS sprites significantly reduce HTTP requests, and manually building
    sprite maps and calculating sprite positions is a pain in the ass. If I'm going
    to use sprites, it has to be done in an automated fashion. We pride ourselves
    on building software with minimal cost of change, and the cost of change when
    you're manually building your sprite maps is way too high. Since I'm already
    using Compass, and Compass has CSS spriting built-in, it seems a no-brainer.
    to use sprites, it has to be done in an automated fashion. Since I'm already
    using Compass, and Compass has CSS spriting built-in, it seems a no-brainer.
    This is a feature I need to be using.

    Unfortunately, [the docs](http://compass-style.org/help/tutorials/spriting/)
  4. adamlogic revised this gist Sep 5, 2012. 1 changed file with 5 additions and 5 deletions.
    10 changes: 5 additions & 5 deletions compass_and_css_sprites.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,11 +1,11 @@
    # Compass and CSS Sprites, Explained

    Yesterday was the second or third time I've attempted to use the [CSS sprites
    Last week I attempted to use the [CSS sprites
    feature](http://compass-style.org/reference/compass/helpers/sprites/) of
    Compass. It's been painful each time – with the documentation leaving me with
    more questions than answers – but the power and potential is there, so I keep
    coming back. This time was a bit different, though, because I finally decided
    to stop relying on the docs and dive straight into the code.
    Compass for the second or third time. It's been a struggle each time, but the
    power and potential is there, so I keep coming back. This time was a bit
    different, though, because I finally decided to stop relying on the docs and
    dive into the code.

    Before I go into the nitty-gritty, let's take a step back and talk about why I
    want so badly to use this feature and why it's been painful each time. The why
  5. adamlogic revised this gist Sep 5, 2012. 1 changed file with 27 additions and 5 deletions.
    32 changes: 27 additions & 5 deletions compass_and_css_sprites.md
    View file
    Original file line number Diff line number Diff line change
    @@ -54,7 +54,7 @@ mixins. We can do the exact same thing with this:
    @import "spritemap/*.png"
    h3
    background: $spritemap-sprites no-repeat;
    background: $spritemap-sprites no-repeat
    +sprite($spritemap-sprites, ribbonfull)
    ```

    @@ -75,7 +75,7 @@ $spritemap-spacing: 50px
    background-repeat: $repeat
    +sprite-background-position($spritemap-sprites, $name, $offset-x, $offset-y)
    // if no offets given, set the dimensions of the element to match the image
    // if no offsets given, set the dimensions of the element to match the image
    @if $offset-x == 0 and $offset-y == 0
    +sprite-dimensions($spritemap-sprites, $name)
    ```
    @@ -98,6 +98,27 @@ h2
    +background-sprite(doubleline, repeat-x, 0, 45px)
    ```

    The generated CSS looks this:

    ```css
    h3 {
    background-image: url('/images/spritemap-sb826ca2aba.png');
    background-repeat: no-repeat;
    background-position: 0 -405px;
    height: 29px;
    width: 295px; }

    h2 {
    background-image: url('/images/spritemap-sb826ca2aba.png');
    background-repeat: no-repeat;
    background-position: 3px -296px; }

    #positions {
    background-image: url('/images/spritemap-sb826ca2aba.png');
    background-repeat: repeat-x;
    background-position: 0 -751px; }
    ```

    There are a few gotchas worth mentioning whenever you're using sprites. First,
    unless every background image is oriented at the top left and fills the full
    element, you're going to want some spacing between the sprites so adjacent
    @@ -111,6 +132,7 @@ you want to repeat is the fill width of the generated sprite map. Images that
    repeat on both axes (such as background textures) are not possible with
    sprites.

    I'm pretty happy with how this has ended up, and I'll be using this feature of
    Compass in most future projects. CSS Sprites are a powerful way to increase
    browser performance, and now there's less friction than ever to give it a try.
    I'm pretty happy with how this has ended up. I'll definitely be using this
    feature of Compass in most future projects. CSS Sprites are a powerful way to
    increase browser performance, and now there's less friction than ever to give
    it a try.
  6. adamlogic revised this gist Sep 5, 2012. 1 changed file with 6 additions and 6 deletions.
    12 changes: 6 additions & 6 deletions compass_and_css_sprites.md
    View file
    Original file line number Diff line number Diff line change
    @@ -19,19 +19,19 @@ This is a feature I need to be using.

    Unfortunately, [the docs](http://compass-style.org/help/tutorials/spriting/)
    leave much to be desired. You might read those docs and be convinced that the
    "right" way to apply CSS Sprites is with magically-generated CSS classes
    applied to your markup. Not so. There is a better way to use sprites that is
    more straightforward, easy to understand, and with less assumed knowledge about
    how it all works.
    "right" way to use CSS Sprites is with magically-generated CSS classes applied
    to your markup. Not so. There is a better way to use sprites that is more
    straightforward, easy to understand, and without future developers having to
    understand magically generated mixins and classes.

    To get there, let's dive into the code that makes the "magic" classes work.
    [This
    template](https://github.com/chriseppstein/compass/blob/stable/lib/compass/sprite_importer/content.erb)
    is where all of those magic mixins are defined when you import your sprites
    with something like `@import "my-icons/*.png"`. You can see that these
    generated mixins are straighforward and in most cases are just delegating to a
    mixin defined
    [here](https://github.com/chriseppstein/compass/blob/stable/frameworks/compass/stylesheets/compass/utilities/sprites/_base.scss).
    regular mixin defined
    [here](https://github.com/chriseppstein/compass/blob/stable/frameworks/compass/stylesheets/compass/utilities/sprites/_base.scss).
    While not documented, there is no reason we can't use those mixins ourselves.

    Let's say you want to apply a background image called "ribbonfull.png" to your
  7. adamlogic revised this gist Sep 5, 2012. 1 changed file with 60 additions and 46 deletions.
    106 changes: 60 additions & 46 deletions compass_and_css_sprites.md
    View file
    Original file line number Diff line number Diff line change
    @@ -17,41 +17,54 @@ you're manually building your sprite maps is way too high. Since I'm already
    using Compass, and Compass has CSS spriting built-in, it seems a no-brainer.
    This is a feature I need to be using.

    Unfortunately, the docs leave much to be desired. I'm not trying to be a hater
    here. I love Compass, I use it all the time, and most of the docs are great.
    This is just an area where they fall short. The docs on sprites are badly
    organized, confusing to read, and encourage (IMHO) poor usage.

    What do I mean by poor usage? Well, let's take a look at the [Spriting With
    Compass tutorial](http://compass-style.org/help/tutorials/spriting/) where they
    state "The simplest way to use these icon sprites is to let compass give you a
    class for each sprite". This means you have to go to your markup and add
    specific "magic" classes to every element that uses a sprite background image.
    No, thank you. Separation of concerns aside, this is inconvenient, inflexible,
    and dangerous. It assumes that any future developer will understand how Compass
    sprites work and just know that these special classes cannot be changed or
    removed.

    The tutorial does go on to show an alterative method that is not dependent on
    classes: "In this example, this is done by using the magic my-icons-sprite
    mixin. Note that the mixin's name is dependent on the name of the folder in
    which you've placed your icons." This is certainly a little better, but it's
    still going to be very confusing for any developer who isn't familiar with the
    magic that's going on here. Good luck trying to find documentation on how the
    my-icons-sprite mixin works and what options are available.

    What I want is a way to use sprites that requires little effort but is more
    straightforward, easy to understand, and with less assumed knowledge about how
    it all works. It turns out that this isn't difficult at all. It's just not
    documented. Let's take [this
    Unfortunately, [the docs](http://compass-style.org/help/tutorials/spriting/)
    leave much to be desired. You might read those docs and be convinced that the
    "right" way to apply CSS Sprites is with magically-generated CSS classes
    applied to your markup. Not so. There is a better way to use sprites that is
    more straightforward, easy to understand, and with less assumed knowledge about
    how it all works.

    To get there, let's dive into the code that makes the "magic" classes work.
    [This
    template](https://github.com/chriseppstein/compass/blob/stable/lib/compass/sprite_importer/content.erb)
    as a starting point. This is where all of those magic mixins are defined when
    you import your sprites with something like `@import "my-icons/*.png"`. You can
    see that these generated mixins are straighforward and in most cases are just
    delegating to a mixin defined
    [here](https://github.com/chriseppstein/compass/blob/stable/frameworks/compass/stylesheets/compass/utilities/sprites/_base.scss).
    is where all of those magic mixins are defined when you import your sprites
    with something like `@import "my-icons/*.png"`. You can see that these
    generated mixins are straighforward and in most cases are just delegating to a
    mixin defined
    [here](https://github.com/chriseppstein/compass/blob/stable/frameworks/compass/stylesheets/compass/utilities/sprites/_base.scss).
    While not documented, there is no reason we can't use those mixins ourselves.
    In fact, that's exactly what I did.

    Let's say you want to apply a background image called "ribbonfull.png" to your
    `h3` tags. Following the docs, your code might look like this:

    ```sass
    @import "spritemap/*.png"
    +all-spritemap-sprites
    ```

    ```html
    <h3 class="spritemap-ribbonfull">Test</h3>
    ```

    Let's turn that into something more maintainable and customizable. Under the
    covers, the "spritemap-ribbonfull" class is really just applying a couple
    mixins. We can do the exact same thing with this:

    ```sass
    @import "spritemap/*.png"
    h3
    background: $spritemap-sprites no-repeat;
    +sprite($spritemap-sprites, ribbonfull)
    ```

    The only bit of magic left is the generated `$spritemap-sprites` variable. I
    can live with that. We no longer have to change our markup, and we can
    customize how the background image is applied by supplying additional arguments
    to the [sprite
    mixin](https://github.com/chriseppstein/compass/blob/stable/frameworks/compass/stylesheets/compass/utilities/sprites/_base.scss#L27).

    In my recent project, I took this a bit further by defining my own mixin.

    ```sass
    $spritemap-spacing: 50px
    @@ -61,18 +74,15 @@ $spritemap-spacing: 50px
    background-image: $spritemap-sprites
    background-repeat: $repeat
    +sprite-background-position($spritemap-sprites, $name, $offset-x, $offset-y)
    // if no offets given, set the dimensions of the element to match the image
    @if $offset-x == 0 and $offset-y == 0
    +sprite-dimensions($spritemap-sprites, $name)
    ```

    By writing my own mixin instead of using a magic mixin, I not only have more
    control over how the sprites are used, but future developers can read this
    mixin and understand exactly what is happening. The only bit of magic here is
    the `$spritemap-sprites` variable which is created automatically when the
    sprites are imported. Beyond that I'm using regular built-in mixins whose names
    are self-descriptive.

    Here is how I'm using this mixin:
    By writing my own mixin, I not only have more control over how the sprites are
    used, but future developers can read this mixin and understand what is
    happening. Here is how I'm using it:

    ```sass
    // simplest case; sets the background image and dimensions of the element
    @@ -88,15 +98,19 @@ h2
    +background-sprite(doubleline, repeat-x, 0, 45px)
    ```

    I'm pretty happy with how this has ended up. There are still a few gotchas
    worth mentioning. First, unless every background image is oriented at the top
    left and fills the full element, you're going to want some spacing between the
    sprites so adjacent images don't sneak in. Play with the `$<map>-spacing`
    configuration variable to see what works for you. I ended up at 50px.
    There are a few gotchas worth mentioning whenever you're using sprites. First,
    unless every background image is oriented at the top left and fills the full
    element, you're going to want some spacing between the sprites so adjacent
    images don't sneak in. Play with the `$<map>-spacing` configuration variable to
    see what works for you. I ended up at 50px.

    The other gotcha is with repeating backgrounds. By default, Compass will stack
    the images veritically in the sprite map. This means you can still have
    repeating backgrounds on the x-axis, but you'll need to ensure that any image
    you want to repeat is the fill width of the generated sprite map. Images that
    repeat on both axes (such as background textures) are not possible with
    sprites.

    I'm pretty happy with how this has ended up, and I'll be using this feature of
    Compass in most future projects. CSS Sprites are a powerful way to increase
    browser performance, and now there's less friction than ever to give it a try.
  8. adamlogic renamed this gist Sep 1, 2012. 1 changed file with 0 additions and 0 deletions.
    0 gistfile1 → compass_and_css_sprites.md
    View file
    File renamed without changes.
  9. adamlogic revised this gist Sep 1, 2012. No changes.
  10. adamlogic renamed this gist Sep 1, 2012. 1 changed file with 3 additions and 3 deletions.
    6 changes: 3 additions & 3 deletions gistfile1.md → gistfile1
    View file
    Original file line number Diff line number Diff line change
    @@ -97,6 +97,6 @@ configuration variable to see what works for you. I ended up at 50px.
    The other gotcha is with repeating backgrounds. By default, Compass will stack
    the images veritically in the sprite map. This means you can still have
    repeating backgrounds on the x-axis, but you'll need to ensure that any image
    you want to repeat is the widest image in the sprite. Images that repeat on
    both axes (such as background textures) are not possible with sprites.

    you want to repeat is the fill width of the generated sprite map. Images that
    repeat on both axes (such as background textures) are not possible with
    sprites.
  11. adamlogic revised this gist Sep 1, 2012. 1 changed file with 5 additions and 4 deletions.
    9 changes: 5 additions & 4 deletions gistfile1.md
    View file
    Original file line number Diff line number Diff line change
    @@ -26,7 +26,7 @@ What do I mean by poor usage? Well, let's take a look at the [Spriting With
    Compass tutorial](http://compass-style.org/help/tutorials/spriting/) where they
    state "The simplest way to use these icon sprites is to let compass give you a
    class for each sprite". This means you have to go to your markup and add
    specific "magic" classes to every element that uses a sprite background image.
    specific "magic" classes to every element that uses a sprite background image.
    No, thank you. Separation of concerns aside, this is inconvenient, inflexible,
    and dangerous. It assumes that any future developer will understand how Compass
    sprites work and just know that these special classes cannot be changed or
    @@ -49,8 +49,8 @@ as a starting point. This is where all of those magic mixins are defined when
    you import your sprites with something like `@import "my-icons/*.png"`. You can
    see that these generated mixins are straighforward and in most cases are just
    delegating to a mixin defined
    [here](https://github.com/chriseppstein/compass/blob/stable/frameworks/compass/stylesheets/compass/utilities/sprites/_base.scss).
    While not documented, there is no reason we can't use those mixins ourselves.
    [here](https://github.com/chriseppstein/compass/blob/stable/frameworks/compass/stylesheets/compass/utilities/sprites/_base.scss).
    While not documented, there is no reason we can't use those mixins ourselves.
    In fact, that's exactly what I did.

    ```sass
    @@ -98,4 +98,5 @@ The other gotcha is with repeating backgrounds. By default, Compass will stack
    the images veritically in the sprite map. This means you can still have
    repeating backgrounds on the x-axis, but you'll need to ensure that any image
    you want to repeat is the widest image in the sprite. Images that repeat on
    both axes (such as background textures) are not possible with sprites.
    both axes (such as background textures) are not possible with sprites.

  12. adamlogic revised this gist Sep 1, 2012. 1 changed file with 16 additions and 15 deletions.
    31 changes: 16 additions & 15 deletions gistfile1.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,10 +1,11 @@
    # Compass and CSS Sprites, Explained

    Yesterday was the second or third time I've attempted to use the CSS sprites
    feature of Compass. It's been painful each time – with the documentation
    leaving me with more questions than answers – but the power and potential is
    there, so I keep coming back. This time was a bit different, though, because I
    finally decided to stop relying on the docs and dive straight into the code.
    Yesterday was the second or third time I've attempted to use the [CSS sprites
    feature](http://compass-style.org/reference/compass/helpers/sprites/) of
    Compass. It's been painful each time – with the documentation leaving me with
    more questions than answers – but the power and potential is there, so I keep
    coming back. This time was a bit different, though, because I finally decided
    to stop relying on the docs and dive straight into the code.

    Before I go into the nitty-gritty, let's take a step back and talk about why I
    want so badly to use this feature and why it's been painful each time. The why
    @@ -21,14 +22,15 @@ here. I love Compass, I use it all the time, and most of the docs are great.
    This is just an area where they fall short. The docs on sprites are badly
    organized, confusing to read, and encourage (IMHO) poor usage.

    What do I mean by poor usage? Well, let's take a look at the Spriting With
    Compass tutorial where they state "The simplest way to use these icon sprites
    is to let compass give you a class for each sprite". This means you have to go
    to your markup and add specific "magic" classes to every element that uses a
    sprite background image. No, thank you. Separation of concerns aside, this is
    inconvenient, inflexible, and dangerous. It assumes that any future developer
    will understand how Compass sprites work and just know that these special
    classes cannot be changed or removed.
    What do I mean by poor usage? Well, let's take a look at the [Spriting With
    Compass tutorial](http://compass-style.org/help/tutorials/spriting/) where they
    state "The simplest way to use these icon sprites is to let compass give you a
    class for each sprite". This means you have to go to your markup and add
    specific "magic" classes to every element that uses a sprite background image.
    No, thank you. Separation of concerns aside, this is inconvenient, inflexible,
    and dangerous. It assumes that any future developer will understand how Compass
    sprites work and just know that these special classes cannot be changed or
    removed.

    The tutorial does go on to show an alterative method that is not dependent on
    classes: "In this example, this is done by using the magic my-icons-sprite
    @@ -96,5 +98,4 @@ The other gotcha is with repeating backgrounds. By default, Compass will stack
    the images veritically in the sprite map. This means you can still have
    repeating backgrounds on the x-axis, but you'll need to ensure that any image
    you want to repeat is the widest image in the sprite. Images that repeat on
    both axes (such as background textures) are not possible with sprites.

    both axes (such as background textures) are not possible with sprites.
  13. adamlogic revised this gist Sep 1, 2012. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion gistfile1.md
    View file
    Original file line number Diff line number Diff line change
    @@ -48,7 +48,7 @@ you import your sprites with something like `@import "my-icons/*.png"`. You can
    see that these generated mixins are straighforward and in most cases are just
    delegating to a mixin defined
    [here](https://github.com/chriseppstein/compass/blob/stable/frameworks/compass/stylesheets/compass/utilities/sprites/_base.scss).
    While not documented, there is no reason we can't use those mixins ourselves.
    While not documented, there is no reason we can't use those mixins ourselves.
    In fact, that's exactly what I did.

    ```sass
  14. adamlogic revised this gist Sep 1, 2012. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions gistfile1.md
    View file
    Original file line number Diff line number Diff line change
    @@ -13,11 +13,11 @@ sprite maps and calculating sprite positions is a pain in the ass. If I'm going
    to use sprites, it has to be done in an automated fashion. We pride ourselves
    on building software with minimal cost of change, and the cost of change when
    you're manually building your sprite maps is way too high. Since I'm already
    using Compass, and Compass has CSS spriting built-in, it seems a no-brainer.
    using Compass, and Compass has CSS spriting built-in, it seems a no-brainer.
    This is a feature I need to be using.

    Unfortunately, the docs leave much to be desired. I'm not trying to be a hater
    here. I love Compass, I use it all the time, and most of the docs are great.
    here. I love Compass, I use it all the time, and most of the docs are great.
    This is just an area where they fall short. The docs on sprites are badly
    organized, confusing to read, and encourage (IMHO) poor usage.

  15. adamlogic created this gist Sep 1, 2012.
    100 changes: 100 additions & 0 deletions gistfile1.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,100 @@
    # Compass and CSS Sprites, Explained

    Yesterday was the second or third time I've attempted to use the CSS sprites
    feature of Compass. It's been painful each time – with the documentation
    leaving me with more questions than answers – but the power and potential is
    there, so I keep coming back. This time was a bit different, though, because I
    finally decided to stop relying on the docs and dive straight into the code.

    Before I go into the nitty-gritty, let's take a step back and talk about why I
    want so badly to use this feature and why it's been painful each time. The why
    is easy: CSS sprites significantly reduce HTTP requests, and manually building
    sprite maps and calculating sprite positions is a pain in the ass. If I'm going
    to use sprites, it has to be done in an automated fashion. We pride ourselves
    on building software with minimal cost of change, and the cost of change when
    you're manually building your sprite maps is way too high. Since I'm already
    using Compass, and Compass has CSS spriting built-in, it seems a no-brainer.
    This is a feature I need to be using.

    Unfortunately, the docs leave much to be desired. I'm not trying to be a hater
    here. I love Compass, I use it all the time, and most of the docs are great.
    This is just an area where they fall short. The docs on sprites are badly
    organized, confusing to read, and encourage (IMHO) poor usage.

    What do I mean by poor usage? Well, let's take a look at the Spriting With
    Compass tutorial where they state "The simplest way to use these icon sprites
    is to let compass give you a class for each sprite". This means you have to go
    to your markup and add specific "magic" classes to every element that uses a
    sprite background image. No, thank you. Separation of concerns aside, this is
    inconvenient, inflexible, and dangerous. It assumes that any future developer
    will understand how Compass sprites work and just know that these special
    classes cannot be changed or removed.

    The tutorial does go on to show an alterative method that is not dependent on
    classes: "In this example, this is done by using the magic my-icons-sprite
    mixin. Note that the mixin's name is dependent on the name of the folder in
    which you've placed your icons." This is certainly a little better, but it's
    still going to be very confusing for any developer who isn't familiar with the
    magic that's going on here. Good luck trying to find documentation on how the
    my-icons-sprite mixin works and what options are available.

    What I want is a way to use sprites that requires little effort but is more
    straightforward, easy to understand, and with less assumed knowledge about how
    it all works. It turns out that this isn't difficult at all. It's just not
    documented. Let's take [this
    template](https://github.com/chriseppstein/compass/blob/stable/lib/compass/sprite_importer/content.erb)
    as a starting point. This is where all of those magic mixins are defined when
    you import your sprites with something like `@import "my-icons/*.png"`. You can
    see that these generated mixins are straighforward and in most cases are just
    delegating to a mixin defined
    [here](https://github.com/chriseppstein/compass/blob/stable/frameworks/compass/stylesheets/compass/utilities/sprites/_base.scss).
    While not documented, there is no reason we can't use those mixins ourselves.
    In fact, that's exactly what I did.

    ```sass
    $spritemap-spacing: 50px
    @import "spritemap/*.png"
    @mixin background-sprite($name, $repeat: no-repeat, $offset-x: 0, $offset-y: 0)
    background-image: $spritemap-sprites
    background-repeat: $repeat
    +sprite-background-position($spritemap-sprites, $name, $offset-x, $offset-y)
    @if $offset-x == 0 and $offset-y == 0
    +sprite-dimensions($spritemap-sprites, $name)
    ```

    By writing my own mixin instead of using a magic mixin, I not only have more
    control over how the sprites are used, but future developers can read this
    mixin and understand exactly what is happening. The only bit of magic here is
    the `$spritemap-sprites` variable which is created automatically when the
    sprites are imported. Beyond that I'm using regular built-in mixins whose names
    are self-descriptive.

    Here is how I'm using this mixin:

    ```sass
    // simplest case; sets the background image and dimensions of the element
    h3
    +background-sprite(ribbonfull)
    // custom offset; does not set the dimensions of the element
    h2
    +background-sprite(ribbonend, no-repeat, 3px, 22px)
    // repeating backgrounds are possible, too
    #positions
    +background-sprite(doubleline, repeat-x, 0, 45px)
    ```

    I'm pretty happy with how this has ended up. There are still a few gotchas
    worth mentioning. First, unless every background image is oriented at the top
    left and fills the full element, you're going to want some spacing between the
    sprites so adjacent images don't sneak in. Play with the `$<map>-spacing`
    configuration variable to see what works for you. I ended up at 50px.

    The other gotcha is with repeating backgrounds. By default, Compass will stack
    the images veritically in the sprite map. This means you can still have
    repeating backgrounds on the x-axis, but you'll need to ensure that any image
    you want to repeat is the widest image in the sprite. Images that repeat on
    both axes (such as background textures) are not possible with sprites.