diff --git a/doc-src/content/upgrading/css3-v2.markdown b/doc-src/content/upgrading/css3-v2.markdown
new file mode 100644
index 00000000..06aaa3ca
--- /dev/null
+++ b/doc-src/content/upgrading/css3-v2.markdown
@@ -0,0 +1,58 @@
+---
+title: Upgrading to the Compass CSS3 API Version 2
+crumb: CSS3 API Upgrade
+classnames:
+  - tutorial
+layout: tutorial
+---
+
+The Compass CSS3 API is the easiest way to take advantage of the advanced CSS3 capabilities
+offered by modern browsers. The initial version (v1) of the Compass CSS3 API is now more than
+1 year old and the specification continues to evolve. The Compass team is dedicated to keeping
+our library up-to-date so that you can continue to stay at the fore-front of modern web design.
+To this end, a new version of the CSS3 API has been created for the compass v0.11 release. The
+old version of the API still exists and works, but some aspects of the old API are now
+deprecated and will be removed v0.12. This document will guide you through the steps that
+are required to stay up to date.
+
+<a name="box-shadow"></a>
+## Box Shadow
+
+The `box-shadow` mixin API has been changed. To upgrade to the new box shadow API, you should
+`@import "compass/css3/box-shadow-v2"` or `@import "compass/css/version-2"`. Once you have
+changed your imports, it is expected that you have migrated your code to the new version,
+until then, you will receive a deprecation warning from each place in your code where you use
+deprecated mixins.
+ 
+Two new mixins are now provided:
+
+1. `single-box-shadow` - This is the old version of the box shadow mixin renamed.
+   It is optimized for creating a single box shadow with nice defaults that result
+   in approximately what you're expecting when you think of a box shadow and allow
+   for simple overriding of defaults using keyword-style arguments.
+2. `multiple-box-shadow` - This mixin allows you to specify up to 10 shadows to be
+   applied. Each argument to this mixin is a space delimited list of values specifying
+   a shadow.
+
+Additionally, the `box-shadow` mixin is now a shortcut for the `multiple-box-shadow`
+mixin because this most closely matches the CSS3 specification.
+   
+To upgrade, you have two choices:
+
+1. Change the mixin from `box-shadow` to `single-box-shadow` and keep the arguments
+   unchanged. For instance:
+   
+       @include box-shadow(darken($border_color, 40), 5px, 5px, 2px, 3px, inset)
+   
+   would now become:
+   
+       @include single-box-shadow(darken($border_color, 40), 5px, 5px, 2px, 3px, inset)
+   
+2. Keep including the `box-shadow` mixin but update the arguments to be a space delimited
+   list. For instance:
+   
+       @include box-shadow(darken($border_color, 40), 5px, 5px, 2px, 3px, inset)
+   
+   would now become:
+   
+       @include box-shadow(inset 5px 5px 2px 3px darken($border_color, 40))
diff --git a/frameworks/compass/stylesheets/compass/_css3.scss b/frameworks/compass/stylesheets/compass/_css3.scss
index c87e3d45..ecb7f3d7 100644
--- a/frameworks/compass/stylesheets/compass/_css3.scss
+++ b/frameworks/compass/stylesheets/compass/_css3.scss
@@ -1,15 +1 @@
-@import "css3/border-radius";
-@import "css3/inline-block";
-@import "css3/opacity";
-@import "css3/box-shadow";
-@import "css3/text-shadow";
-@import "css3/columns";
-@import "css3/box-sizing";
-@import "css3/box";
-@import "css3/gradient";
-@import "css3/background-clip";
-@import "css3/background-origin";
-@import "css3/background-size";
-@import "css3/font-face";
-@import "css3/transform";
-@import "css3/transition";
+@import "css3/version-1";
diff --git a/frameworks/compass/stylesheets/compass/css3/_box-shadow-v2.scss b/frameworks/compass/stylesheets/compass/css3/_box-shadow-v2.scss
new file mode 100644
index 00000000..81a7f616
--- /dev/null
+++ b/frameworks/compass/stylesheets/compass/css3/_box-shadow-v2.scss
@@ -0,0 +1,98 @@
+// @doc off
+// These defaults make the arguments optional for this mixin
+// If you like, set different defaults before importing.
+// @doc on
+
+@import "shared";
+
+// The default color for box shadows
+$default-box-shadow-color: #333333 !default;
+
+// The default horizontal offset. Positive is to the right.
+$default-box-shadow-h-offset: 1px !default;
+
+// The default vertical offset. Positive is down.
+$default-box-shadow-v-offset: 1px !default;
+
+// The default blur length.
+$default-box-shadow-blur: 5px !default;
+
+// The default spread length.
+$default-box-shadow-spread : false !default;
+
+// The default shadow instet: inset or false (for standard shadow).
+$default-box-shadow-inset : false !default;
+
+// Provides cross-browser CSS box shadows for Webkit, Gecko, and CSS3.
+// Arguments are color, horizontal offset, vertical offset, blur length, spread length, and inset.
+@mixin single-box-shadow(
+  $color  : $default-box-shadow-color,
+  $hoff   : $default-box-shadow-h-offset,
+  $voff   : $default-box-shadow-v-offset,
+  $blur   : $default-box-shadow-blur,
+  $spread : $default-box-shadow-spread,
+  $inset  : $default-box-shadow-inset
+) {
+  @if not ($inset == true or $inset == false or $inset == inset) {
+    @warn "$inset expected to be true or the inset keyword. Got #{$inset} instead. Using: inset";
+  }
+
+  @if $color == none {
+    @include multiple-box-shadows(none);
+  } @else {
+    $full   : $hoff $voff;
+    @if $blur   { $full: $full $blur;   }
+    @if $spread { $full: $full $spread; }
+    @if $color  { $full: $full $color;  }
+    @if $inset  { $full: inset $full;   }
+    @include multiple-box-shadows($full);
+  }
+}
+
+// Provides cross-browser box shadows when one or more box shadows are needed.
+@mixin multiple-box-shadows(
+  $shadow-1,
+  $shadow-2 : false,
+  $shadow-3 : false,
+  $shadow-4 : false,
+  $shadow-5 : false,
+  $shadow-6 : false,
+  $shadow-7 : false,
+  $shadow-8 : false,
+  $shadow-9 : false,
+  $shadow-10: false
+) {
+  // Ugh. Sass needs variable argument support.
+  $shadow : $shadow-1;
+  @if $shadow-2  { $shadow: $shadow, $shadow-2;  }
+  @if $shadow-3  { $shadow: $shadow, $shadow-3;  }
+  @if $shadow-4  { $shadow: $shadow, $shadow-4;  }
+  @if $shadow-5  { $shadow: $shadow, $shadow-5;  }
+  @if $shadow-6  { $shadow: $shadow, $shadow-6;  }
+  @if $shadow-7  { $shadow: $shadow, $shadow-7;  }
+  @if $shadow-8  { $shadow: $shadow, $shadow-8;  }
+  @if $shadow-9  { $shadow: $shadow, $shadow-9;  }
+  @if $shadow-10 { $shadow: $shadow, $shadow-10; }
+  @include experimental(box-shadow, $shadow,
+    -moz, -webkit, -o, not -ms, not -khtml, official
+  );
+}
+
+@mixin box-shadow(
+  $shadow-1,
+  $shadow-2 : false,
+  $shadow-3 : false,
+  $shadow-4 : false,
+  $shadow-5 : false,
+  $shadow-6 : false,
+  $shadow-7 : false,
+  $shadow-8 : false,
+  $shadow-9 : false,
+  $shadow-10: false
+) {
+  @include multiple-box-shadows(
+    $shadow-1, $shadow-2, $shadow-3,
+    $shadow-4, $shadow-5, $shadow-6,
+    $shadow-7, $shadow-8, $shadow-9, $shadow-10
+  );
+}
diff --git a/frameworks/compass/stylesheets/compass/css3/_box-shadow.scss b/frameworks/compass/stylesheets/compass/css3/_box-shadow.scss
index 59c228a6..76dd7491 100644
--- a/frameworks/compass/stylesheets/compass/css3/_box-shadow.scss
+++ b/frameworks/compass/stylesheets/compass/css3/_box-shadow.scss
@@ -1,67 +1,9 @@
-// @doc off
-// These defaults make the arguments optional for this mixin
-// If you like, set different defaults before importing.
-// @doc on
+@import "box-shadow-v2";
 
-@import "shared";
-
-$legacy-box-shadow: true !default;
-
-// The default color for box shadows
-$default-box-shadow-color: #333333 !default;
-
-// The default horizontal offset. Positive is to the right.
-$default-box-shadow-h-offset: 1px !default;
-
-// The default vertical offset. Positive is down.
-$default-box-shadow-v-offset: 1px !default;
-
-// The default blur length.
-$default-box-shadow-blur: 5px !default;
-
-// The default spread length.
-$default-box-shadow-spread : false !default;
-
-// The default shadow instet: inset or false (for standard shadow).
-$default-box-shadow-inset : false !default;
-
-@if $legacy-box-shadow {
-  @mixin box-shadow(
-    $color  : $default-box-shadow-color, 
-    $hoff   : $default-box-shadow-h-offset, 
-    $voff   : $default-box-shadow-v-offset, 
-    $blur   : $default-box-shadow-blur, 
-    $spread : $default-box-shadow-spread, 
-    $inset  : $default-box-shadow-inset
-  ) {
-    @warn "This usage of the box-shadow mixin has been deprecated. Please read: http://compass-style.org/docs/upgrading/box-shadow-api/ for details."
-    @include legacy-box-shadow($color, $hoff, $voff, $blur, $spread, $inset);
-  }
-} @else {
-  @mixin box-shadow(
-    $shadow-1,
-    $shadow-2 : false,
-    $shadow-3 : false,
-    $shadow-4 : false,
-    $shadow-5 : false,
-    $shadow-6 : false,
-    $shadow-7 : false,
-    $shadow-8 : false,
-    $shadow-9 : false,
-    $shadow-10: false
-  ) {
-    @include mult-box-shadow(
-      $shadow-1, $shadow-2, $shadow-3,
-      $shadow-4, $shadow-5, $shadow-6,
-      $shadow-7, $shadow-8, $shadow-9, $shadow-10
-    );
-  }
-}
-
-// Provides cross-browser CSS box shadows for Webkit, Gecko, and CSS3.
-// Arguments are color, horizontal offset, vertical offset, blur length, spread length, and inset.
+// This mixin is deprecated.
+// Use the box-shadow mixin from compass/css3/box-shadow-v2 instead.
 // @deprecated
-@mixin legacy-box-shadow(
+@mixin box-shadow(
   $color  : $default-box-shadow-color, 
   $hoff   : $default-box-shadow-h-offset, 
   $voff   : $default-box-shadow-v-offset, 
@@ -69,46 +11,7 @@ $default-box-shadow-inset : false !default;
   $spread : $default-box-shadow-spread, 
   $inset  : $default-box-shadow-inset
 ) {
-  @if not ($inset == true or $inset == false or $inset == inset) {
-    @warn "$inset expected to be true or the inset keyword. Got #{$inset} instead. Using: inset";
-  }
-
-  @if $color == none {
-    @include mult-box-shadow(none);
-  } @else {  
-    $full   : $hoff $voff;
-    @if $blur   { $full: $full $blur;   }
-    @if $spread { $full: $full $spread; }
-    @if $color  { $full: $full $color;  }
-    @if $inset  { $full: inset $full;   }
-    @include mult-box-shadow($full);
-  }
+  @warn "This version of the box-shadow mixin has been deprecated. Please read: http://compass-style.org/docs/upgrading/css3-v2/#box-shadow for details.";
+  @include single-box-shadow($color, $hoff, $voff, $blur, $spread, $inset);
 }
 
-// Provides cross-browser box shadows when one or more box shadows are to be used.
-@mixin mult-box-shadow(
-  $shadow-1,
-  $shadow-2 : false,
-  $shadow-3 : false,
-  $shadow-4 : false,
-  $shadow-5 : false,
-  $shadow-6 : false,
-  $shadow-7 : false,
-  $shadow-8 : false,
-  $shadow-9 : false,
-  $shadow-10: false
-) {
-  $shadow : $shadow-1;
-  @if $shadow-2  { $shadow: $shadow, $shadow-2;  }
-  @if $shadow-3  { $shadow: $shadow, $shadow-3;  }
-  @if $shadow-4  { $shadow: $shadow, $shadow-4;  }
-  @if $shadow-5  { $shadow: $shadow, $shadow-5;  }
-  @if $shadow-6  { $shadow: $shadow, $shadow-6;  }
-  @if $shadow-7  { $shadow: $shadow, $shadow-7;  }
-  @if $shadow-8  { $shadow: $shadow, $shadow-8;  }
-  @if $shadow-9  { $shadow: $shadow, $shadow-9;  }
-  @if $shadow-10 { $shadow: $shadow, $shadow-10; }
-  @include experimental(box-shadow, $shadow,
-    -moz, -webkit, -o, not -ms, not -khtml, official
-  );
-}
diff --git a/frameworks/compass/stylesheets/compass/css3/_version-1.scss b/frameworks/compass/stylesheets/compass/css3/_version-1.scss
new file mode 100644
index 00000000..cc124cc1
--- /dev/null
+++ b/frameworks/compass/stylesheets/compass/css3/_version-1.scss
@@ -0,0 +1,15 @@
+@import "border-radius";
+@import "inline-block";
+@import "opacity";
+@import "box-shadow";
+@import "text-shadow";
+@import "columns";
+@import "box-sizing";
+@import "box";
+@import "gradient";
+@import "background-clip";
+@import "background-origin";
+@import "background-size";
+@import "font-face";
+@import "transform";
+@import "transition";
diff --git a/frameworks/compass/stylesheets/compass/css3/_version-2.scss b/frameworks/compass/stylesheets/compass/css3/_version-2.scss
new file mode 100644
index 00000000..8d1d2fc0
--- /dev/null
+++ b/frameworks/compass/stylesheets/compass/css3/_version-2.scss
@@ -0,0 +1,15 @@
+@import "border-radius";
+@import "inline-block";
+@import "opacity";
+@import "box-shadow-v2";
+@import "text-shadow";
+@import "columns";
+@import "box-sizing";
+@import "box";
+@import "gradient";
+@import "background-clip";
+@import "background-origin";
+@import "background-size";
+@import "font-face";
+@import "transform";
+@import "transition";