diff --git a/doc-src/content/examples/compass/css3/gradient.haml b/doc-src/content/examples/compass/css3/gradient.haml
index c15144bf..3417cc46 100644
--- a/doc-src/content/examples/compass/css3/gradient.haml
+++ b/doc-src/content/examples/compass/css3/gradient.haml
@@ -1,8 +1,8 @@
 ---
-title: Gradient
+title: Background Gradients
 description: css3 mixin for css gradients
 framework: compass
-stylesheet: compass/css3/_gradient.scss
+stylesheet: compass/css3/_images.scss
 example: true
 ---
 = render "partials/example"
\ No newline at end of file
diff --git a/doc-src/content/examples/compass/css3/gradient/stylesheet.sass b/doc-src/content/examples/compass/css3/gradient/stylesheet.sass
index 77aea812..d5edcdbb 100644
--- a/doc-src/content/examples/compass/css3/gradient/stylesheet.sass
+++ b/doc-src/content/examples/compass/css3/gradient/stylesheet.sass
@@ -14,30 +14,30 @@
 
 // This will yield a radial gradient with an apparent specular highlight  
 #radial-gradient
-  +radial-gradient(color-stops(#00FFFF 10px, #1E90FF 30px), 45 45)
+  +background-image(radial-gradient(45 45, #0ff 10px, #1e90ff 30px))
 
 // This yields a linear gradient spanning from the upper left corner to the lower right corner
 #linear-gradient
-  +linear-gradient(color-stops(#fff, #ddd), left top)
+  +background-image(linear-gradient(left top, #fff, #ddd))
 
 // This yields a gradient starting at the top with #fff, ending in #aaa  
 #v-gradient
-  +linear-gradient(color-stops(#fff, #aaa))
+  +background-image(linear-gradient(#fff, #aaa))
 
 // Same as above but with a #ccc at the halfway point  
 #v-gradient-2
-  +linear-gradient(color-stops(#fff, #ccc, #aaa))
+  +background-image(linear-gradient(#fff, #ccc, #aaa))
 
 // Same as the first example but with #ccc at the 30% from the top, and #bbb at 70% from the top  
 #v-gradient-3
-  +linear-gradient(color-stops(#fff, #ccc 30%, #bbb 70%, #aaa))
+  +background-image(linear-gradient(#fff, #ccc 30%, #bbb 70%, #aaa))
 
 // This yields a horizontal linear gradient spanning from left to right.
 #h-gradient
-  +linear-gradient(color-stops(#fff, #ddd), left)
+  +background-image(linear-gradient(left, #fff, #ddd))
 
 #svg-gradient
   $experimental-support-for-svg: true
-  +linear-gradient(color-stops(#2AC363, #CD8C14, #9C4CC2), left)
+  +background-image(linear-gradient(left, #2ac363, #cd8c14, #9c4cc2))
   width: 80px
   height: 80px
diff --git a/doc-src/content/reference/compass/css3/gradient.haml b/doc-src/content/reference/compass/css3/gradient.haml
index dfd70112..745e320a 100644
--- a/doc-src/content/reference/compass/css3/gradient.haml
+++ b/doc-src/content/reference/compass/css3/gradient.haml
@@ -12,13 +12,8 @@ classnames:
   - css3
 ---
 - render 'reference' do
-  %p
+  :markdown
+    **<span class="warning">IMPORTANT:</span>** This module has been deprecated. See the new
+    [images module](../images/) for the new, more flexible approach to gradients.
+    
     Provides mixins to create cross-browser CSS3 gradients.
-  %p
-    To enable SVG gradient support in Opera and IE9, set
-    <code>$experimental-support-for-svg: true</code> in your stylesheet.
-  %p
-    NOTE: At this time, Opera renders incorrectly an SVG background on a element
-    with a border, repeating the gradient towards the end. You can set
-    <code>background-repeat: no-repeat</code> to avoid this, but the gradient
-    will not fill the area completely.
diff --git a/doc-src/content/reference/compass/css3/images.haml b/doc-src/content/reference/compass/css3/images.haml
index 5436dadb..667b8238 100644
--- a/doc-src/content/reference/compass/css3/images.haml
+++ b/doc-src/content/reference/compass/css3/images.haml
@@ -12,6 +12,33 @@ classnames:
   - css3
 ---
 - render 'reference' do
-  %p
+  :markdown
     Provides mixins that work across many modern browsers with the latest
     CSS3 image rendering primitives.
+    
+    These mixins provide intelligent cross-browser access to properties that accept
+    images or image-like values (e.g. gradients). The syntax is very straightforward,
+    it is exactly like the css syntax that you would use for the corresponding CSS3
+    properties: Values are comma and space delimited, just as they would be for a property.
+    Vendor prefixes are use only when they are necessary.
+    
+    Example (more examples are available by following the links below):
+    
+    <pre><code class="source-code scss">.in-css3 {
+      background: image-url("foo.png"),
+                  linear-gradient(top left, #333, #0c0),
+                  radial-gradient(#c00, #fff 100px);
+    }
+    .with-compass {
+      @include background(image-url("foo.png"),
+                          linear-gradient(top left, #333, #0c0),
+                          radial-gradient(#c00, #fff 100px));
+    }</code></pre>
+        
+    To enable SVG gradient support in Opera and IE9, set
+    <code>$experimental-support-for-svg: true</code> in your stylesheet.
+    
+    NOTE: At this time, Opera renders incorrectly an SVG background on a element
+    with a border, repeating the gradient towards the end. You can set
+    <code>background-repeat: no-repeat</code> to avoid this, but the gradient
+    will not fill the area completely.
diff --git a/doc-src/content/stylesheets/partials/_typography.scss b/doc-src/content/stylesheets/partials/_typography.scss
index ab16fe3b..fe85f130 100644
--- a/doc-src/content/stylesheets/partials/_typography.scss
+++ b/doc-src/content/stylesheets/partials/_typography.scss
@@ -42,3 +42,5 @@ em { font-style: italic; }
 
 dl.table dt, dl.table dd { display: inline-block; }
 dg { display: block; margin-bottom: 1.5em; }
+
+.warning { color: #c00; }
\ No newline at end of file