diff --git a/src/color-scale/README.md b/src/color-scale/README.md
index b4e746c3..0da93281 100644
--- a/src/color-scale/README.md
+++ b/src/color-scale/README.md
@@ -67,6 +67,98 @@ You can also create compact color scales, by simply setting `--details-style: co
Issue: How to make them focusable??
+### The `editable` attribute
+
+The `editable` attribute allows you to make the color scale editable: adding new colors and editing, reordering, or removing existing ones.
+
+Use `editable` as a boolean attribute to make the color scale editable:
+
+```html
+
+```
+
+You can specify whether the color names, color values, or both should be editable.
+
+Editing colors:
+
+```html
+
+```
+
+Editing color names:
+
+```html
+
+```
+
+Or both:
+
+```html
+
+```
+
+Add `list` to enable all list operations (add, delete, reorder) in one go:
+
+```html
+
+```
+
+For more granular control, specify operations to be enabled:
+
+```html
+
+```
+
+Keep in mind that interpolated colors are generated automatically, are not editable, and cannot be reordered or deleted:
+
+```html
+
+```
+
+The `editable` attribute is reactive and can be set programmatically:
+
+```html
+
+
+```
+
+You can also add colors programmatically with the `addColor()` method, providing the color to add and, optionally, its name:
+
+```html
+
+
+```
+
+Or don't provide any of them. In that case, the added swatch will get the color of the last one:
+
+```html
+
+
+```
+
+Don't want added swatches to get the color of the last one? No problem. You can change that, too.
+Set the `defaultColor` property of the color scale to the desired color. If the value of the property is a color object,
+you can give the color a name by adding the `name` property to it:
+
+```html
+
+
+
+
+```
+