Create swatches for Svelte components.

A swatch is a live, and ideally editable, example of an element of the service. They serve as:

* Documentation: what is this element, how do you use it, what does it do?
* Demonstration: what does this element look like?
* Manual test scaffolding: when I change this element like _so_, what happens?

Swatches are collectively available under `/.swatch/` on a running instance. They do not require setup or login for simplicity's sake and because they don't _do_ anything that requires either of those things.

Swatches are manually curated. First, we lack the technical infrastructure needed to do this based on static analysis, and second, manual curation lets us include affordances like "interesting values," that would be tricky to express as part of the type or schema for the component. The tradeoff, however, is that they will fall out of step with the components if not reviewed regularly.

Swatches are _possible_ because we've gone to efforts to avoid global data access or direct side effects (including API requests) in our components, delegating that upwards to `+page`s and `+layout`s. However, the isolation is imperfect. For example, the swatch for `Conversation`, which renders the conversation sidebar entries, causes actual attempts to boot the app as browsers pre-fetch the links on mouseover, and clicking them will take the user to the "real" application because they really are links.

Merges swatch into main.

2 files changed, 30 insertions, 0 deletions

diff --git a/docs/developer/SUMMARY.md b/docs/developer/SUMMARY.md
index 6b0ce6a..71f85d1 100644
--- a/docs/developer/SUMMARY.md
+++ b/docs/developer/SUMMARY.md
@@ -14,6 +14,10 @@
 - [Running Pilcrow locally](server/running.md)
 - [Debian packaging](server/debian-packaging.md)
 
+# The client
+
+- [Swatches](client/swatches.md)
+
 # Development tools
 
 - [Formatting](tools/formatting.md)
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.