diff --git a/README.md b/README.md
index e6678b18..3ea3dff2 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
 
 ## introduction
 
-htmx allows you to access  [AJAX](https://htmx.org/docs#ajax), 
+htmx allows you to access  [AJAX](https://htmx.org/docs#ajax), [CSS Transitions](https://htmx.org/docs#css_transitions),
 [WebSockets](https://htmx.org/docs#websockets) and [Server Sent Events](https://htmx.org/docs#sse) 
 directly in HTML, using [attributes](https://htmx.org/reference#attributes), so you can build 
 [modern user interfaces](https://htmx.org/examples) with the [simplicity](https://en.wikipedia.org/wiki/HATEOAS) and 
diff --git a/www/docs.md b/www/docs.md
index 20d96546..f6ae3248 100644
--- a/www/docs.md
+++ b/www/docs.md
@@ -324,6 +324,64 @@ with any of the following values:
 | `afterend` | appends the content after the target in the targets parent element
 | `none` | does not append content from response (out of band items will still be processed)
 
+#### <a name="css_transitions"></a>[CSS Transitions](#css_transitions)
+
+htmx makes it easy to use [CSS Transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions) without javascript.  To understand how CSS transitions
+work in htmx, you must first understand the swap & settle model that htmx uses.
+
+When new content is received from a server, before the content is swapped in, the existing
+content of the page is examined for elements that match by the `id` attribute.  If a match
+is found for an element in the new content, the attributes of the old content are copied
+onto the new element before the swap occurs.  The new content is then swapped in, but with the
+*old* attribute values.  Finally, the new attribute values are swapped in, after a "settle" delay
+(100ms by default).
+
+This may seem a bit complicated, but with this mechanic for swapping content, you can write
+CSS transitions from old to new attribute values.
+
+An example will help clarify.  Consider this original content:
+
+```html
+  <div id="div1">Original Content</div>
+```
+
+And this content, which has been received by htmx after an AJAX request, to replace it:
+
+```html
+  <div id="div1" class="red">New Content</div>
+```
+
+The first thing that htmx does, before it swaps in this new content, is note that these two elements match by `id` (and tag type).  It therefore swaps the *old* attribute values onto the *new* content:
+
+```html
+  <div id="div1">New Content</div>
+```
+
+Note that the new content no longer has a `class` attribute.  This modified new content is then
+swapped into the DOM.  This is the swap step.
+
+Next, after a "settle" delay, the new div will have its attributes updated to the actual values received from the server:
+
+```html
+  <div id="div1" class="red">New Content</div>
+```
+
+Because this `div` was in the DOM with the original `div`'s attributes, this is will trigger a
+CSS transition.  So you can write, for example, this CSS:
+
+```css
+.red {
+  color: red;
+  transition: all ease-in 1s ;
+}
+```
+
+And the newly swapped content will gently transition to a red text color over one second.
+
+All of that may seem a little crazy, but it can be summarized as this: 
+
+> In htmx, all you need to do to use CSS transitions for an element is keep its `id` stable across requests
+
 #### <a name="oob_swaps"></a>[Out of Band Swaps](#oob_swaps)
 
 If you want to swap content from a response directly into the DOM by using the `id` attribute you can use the
diff --git a/www/index.md b/www/index.md
index 789e58cb..312bddd3 100644
--- a/www/index.md
+++ b/www/index.md
@@ -11,8 +11,7 @@ title: </> htmx - high power tools for html
 
 ## introduction
 
-htmx allows you to access  [AJAX](https://htmx.org/docs#ajax), 
-[WebSockets](https://htmx.org/docs#websockets) and [Server Sent Events](https://htmx.org/docs#sse) 
+htmx allows you to access  [AJAX](https://htmx.org/docs#ajax), [CSS Transitions](https://htmx.org/docs#css_transitions),  [WebSockets](https://htmx.org/docs#websockets) and [Server Sent Events](https://htmx.org/docs#sse) 
 directly in HTML, using [attributes](https://htmx.org/reference#attributes), so you can build 
 [modern user interfaces](https://htmx.org/examples) with the [simplicity](https://en.wikipedia.org/wiki/HATEOAS) and 
 [power](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) of hypertext