diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3fe9051..bda7923 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,7 @@
 # Squib CHANGELOG
 
 ## v0.3.0a
+* Gradients! Can now specify linear or radial gradients anywhere you specify colors. See README for more details.
 * Added new sample table for color constants in `samples/colors.rb`
 
 ## v0.2.0
diff --git a/README.md b/README.md
index ded3428..2936254 100644
--- a/README.md
+++ b/README.md
@@ -153,7 +153,7 @@ By default, Squib thinks in pixels. This decision was made so that we can have p
 
 Note: we do not support unit conversion on `save_pdf` and `Squib::Deck.new()`, [yet](https://github.com/andymeneely/squib/issues/21). We are also working on support for unit conversion within layout parsing, so using it as a part of `extends` is not yet supported.
 
-## Specifying Colors
+## Specifying Colors & Gradients
 
 Colors can be specified in a wide variety of ways, mostly in a hex-string. Take a look at the examples from `samples/colors.rb`, found [here](https://github.com/andymeneely/squib/tree/master/samples/colors.rb)
 
@@ -161,6 +161,26 @@ Colors can be specified in a wide variety of ways, mostly in a hex-string. Take
 
 Under the hood, Squib uses the `rcairo` [color parser](https://github.com/rcairo/rcairo/blob/master/lib/cairo/color.rb) to accept a variety of color specifications, along with over [300 pre-defined constants](https://github.com/rcairo/rcairo/blob/master/lib/cairo/colors.rb). The above sample will generate a table of such constants.
 
+Additionally, in most places where colors are allowed, you may also supply a string that defines a gradient. Squib supports two flavors of gradients: linear and radial. Gradients are specified by supplying some xy coordinates, which are relative to the card (not the command). Each stop must be between 0.0 and 1.0, and you can supply as many as you like. Colors can be specified as above (in any of the hex notations or built-in constant). If you add two (or more) colors at the same stop, then the gradient keeps the colors in the in order specified and treats it like sharp transition.
+
+The format for gradient strings look like this:
+
+Linear:
+```
+(x1,y1)(x2,y2) color1@stop1 color2@stop2
+```
+The xy coordinates define the angle of the gradient.
+
+Radial:
+```
+(x1,y1,radius1)(x2,y2,radius2) color1@stop1 color2@stop2
+```
+The coordinates specify an inner circle first, then an outer circle.
+
+Check out the following sample from `samples/gradients.rb`, found [here](https://github.com/andymeneely/squib/tree/master/samples/colors.rb)
+
+{include:file:samples/gradients.rb}
+
 ## Specifying Files
 
 All files opened for reading or writing (e.g. for `png` and `xlsx`) are opened relative to the current directory. Files opened for writing (e.g. for `save_png`) will be overwritten without warning.
diff --git a/lib/squib/api/background.rb b/lib/squib/api/background.rb
index fea77ba..ea76941 100644
--- a/lib/squib/api/background.rb
+++ b/lib/squib/api/background.rb
@@ -7,7 +7,7 @@ module Squib
     # Options support Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
     #
     # @option opts range [Enumerable] (:all) the range of cards over which this will be rendered. See {file:README.md#Specifying_Ranges Specifying Ranges}
-    # @option opts color [String] (:black) the color the font will render to. See {file:README.md#Specifying_Colors Specifying Colors}.
+    # @option opts color [String] (:black) the color the font will render to. See {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}.
     # @return [nil] nothing
     # @api public
     def background(opts = {})
diff --git a/lib/squib/api/shapes.rb b/lib/squib/api/shapes.rb
index 64bcc2d..4a6ab5d 100644
--- a/lib/squib/api/shapes.rb
+++ b/lib/squib/api/shapes.rb
@@ -16,8 +16,8 @@ module Squib
     # @option opts x_radius [Integer] (0) the radius of the rounded corner horiztonally. Zero is a non-rounded corner. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts y_radius [Integer] (0) the radius of the rounded corner vertically. Zero is a non-rounded corner. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts radius [Integer] (nil) when set, overrides both x_radius and y_radius. Supports Unit Conversion, see {file:README.md#Units Units}.
-    # @option opts fill_color [String] ('#0000') the color with which to fill the rectangle
-    # @option opts stroke_color [String] (:black) the color with which to stroke the outside of the rectangle
+    # @option opts fill_color [String] ('#0000') the color with which to fill the rectangle. See {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}
+    # @option opts stroke_color [String] (:black) the color with which to stroke the outside of the rectangle. {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}
     # @option opts stroke_width [Decimal] (2.0) the width of the outside stroke. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:README.md#Custom_Layouts Custom Layouts}
     # @return [nil] intended to be void
@@ -44,8 +44,8 @@ module Squib
     # @option opts x [Integer] (0) the x-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts y [Integer] (0) the y-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts radius [Integer] (100) radius of the circle. Supports Unit Conversion, see {file:README.md#Units Units}.
-    # @option opts fill_color [String] ('#0000') the color with which to fill the rectangle
-    # @option opts stroke_color [String] (:black) the color with which to stroke the outside of the rectangle
+    # @option opts fill_color [String] ('#0000') the color with which to fill the rectangle. See {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}.
+    # @option opts stroke_color [String] (:black) the color with which to stroke the outside of the rectangle. See {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}.
     # @option opts stroke_width [Decimal] (2.0) the width of the outside stroke. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @return [nil] intended to be void
     # @api public
@@ -73,8 +73,8 @@ module Squib
     # @option opts y2 [Integer] (50) the y-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts x3 [Integer] (0) the x-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts y3 [Integer] (50) the y-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
-    # @option opts fill_color [String] ('#0000') the color with which to fill the triangle
-    # @option opts stroke_color [String] (:black) the color with which to stroke the outside of the triangle
+    # @option opts fill_color [String] ('#0000') the color with which to fill the triangle. See {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}
+    # @option opts stroke_color [String] (:black) the color with which to stroke the outside of the triangle. See {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}
     # @option opts stroke_width [Decimal] (2.0) the width of the outside stroke. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @return [nil] intended to be void
     # @api public
@@ -100,7 +100,7 @@ module Squib
     # @option opts y1 [Integer] (0) the y-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts x2 [Integer] (50) the x-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts y2 [Integer] (50) the y-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
-    # @option opts stroke_color [String] (:black) the color with which to stroke the line
+    # @option opts stroke_color [String] (:black) the color with which to stroke the line. See {file:README.md#Specifying_Colors___Gradients Specifying Colors & Gradients}.
     # @option opts stroke_width [Decimal] (2.0) the width of the outside stroke. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @return [nil] intended to be void
     # @api public
diff --git a/lib/squib/api/text.rb b/lib/squib/api/text.rb
index fe9078f..e3fa8cf 100644
--- a/lib/squib/api/text.rb
+++ b/lib/squib/api/text.rb
@@ -22,7 +22,7 @@ module Squib
     # @option opts font_size [Integer] (nil) an override of font string description, for scaling the font according to the size of the string
     # @option opts x [Integer] (0) the x-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts y [Integer] (0) the y-coordinate to place. Supports Unit Conversion, see {file:README.md#Units Units}.
-    # @option opts color [String] (:black) the color the font will render to. See {file:README.md#Specifying_Colors Specifying Colors}
+    # @option opts color [String] (:black) the color the font will render to. Gradients supported. See {file:README.md#Specifying_Colors___Gradients Specifying Colors}
     # @option opts markup: [Boolean] (false) Enable markup parsing of `str` using the HTML-like Pango Markup syntax, defined [here](http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup) and [here](https://developer.gnome.org/pango/stable/PangoMarkupFormat.html).
     # @option opts width [Integer, :native] (:native) the width of the box the string will be placed in. Stretches to the content by default.. Supports Unit Conversion, see {file:README.md#Units Units}.
     # @option opts height [Integer, :native] the height of the box the string will be placed in. Stretches to the content by default. Supports Unit Conversion, see {file:README.md#Units Units}.