1 files changed, 26 insertions, 0 deletions
diff --git a/docs/developer/client/swatches.md b/docs/developer/client/swatches.md
new file mode 100644
index 0000000..ad11381
--- /dev/null
+++ b/docs/developer/client/swatches.md
@@ -0,0 +1,26 @@
+# Swatches
+
+To make it easier to experiment with the client's component framework, the client exposes "swatches" - pages demonstrating individual components in isolation.
+
+Swatches are available from a running client at the `/.swatch/` URL. This URL is not linked in the client; you Just Need To Know.
+
+## Writing Swatches
+
+Swatches are manually curated. When adding a component, add a swatch if you can.
+
+Things to consider:
+
+- For complex values, use a parser, so that the user reading your swatch can edit the structure as text.
+- For freeform values whose meaning is significant, provide buttons to let the user rapidly enter and experiment with interesting values.
+- Be thorough. Let the user experiment with values, even if you think those values may be nonsensical.
+- Try to show the component _without_ supporting markup, as far as is possible. However, if a component generates markup that requires context - a table row component needs a table, for example, or a list element needs a list - then include that markup in the swatch.
+
+## Swatches and XSS
+
+⚠ Swatches **should not** accept arbitrary HTML as user input and render it. Use something less expressive, instead.
+
+Swatches are an interface _intended for_ developers, but _available to_ everyone - including users who may not be familiar with the Web platform or the level of access a page might have to their credentials or data. Putting HTML inputs on a swatch invites the risk that a user may be mislead into running code in that swatch that then has access to the Pilcrow API, or to their locally-stored data.
+
+If a component takes HTML as an argument, then the best compromise we've found between allowing a swatch user to experiment with that HTML and protecting that user from these risks is to provide some kind of structured input. For example, a swatch for a message might instead allow test data to be entered using the same Markdown dialect real messages are entered with.
+
+For components where there isn't an easy way to do that, providing one or more predetermined test bodies is also a workable alternative.