diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0b45cc6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,50 @@
+WSElement
+---------
+A demo for a `WebSocket` based `WebComponent` custom `Element`.
+
+Motivation
+----------
+As I've embraced WebComponent increasingly I find myself writing less and less JavaScript.
+One place it doesn't seems to have decreased is around WebSockets, so why not try to pass
+some of this complexity off to an extensible WebComponent?
+
+In a prior project I had experimented with this and it look feasible, but my one off code
+didn't feel generic enough for general use. This code represents a cleaner more trimmed down
+version I feel accomplishes this goal better. 
+
+Code and Usage
+--------------
+This codebase provides a trimmed down base Element, `WSElement`, who's default behavior is
+simply to update it's own `innerText`. This could be simply used on it's own, embedded in
+other HTML or extended to provide more complex behavior with in a custom WebComponent.
+
+In addition two subclass Elements are provided to examples of extending the base class.
+
+`WSTime` provides a slightly more complex example, adding several child elements and perform
+a partial update.
+
+`WSTable` increases the complexity by parsing incoming `JSON` data and dynamically building
+a `Table`. It also demonstrates using attributes to control behavior.
+
+### Demo Server
+To see this in action a demo server has been provided based on `Flask`. To run it....
+
+```
+python -m venv .
+pip install -r requirements.txt
+. bin/activate
+flask run --debug #optional
+```
+
+(Lack of) Licensing
+-------------------
+This isn't really meant to be a consumable module but more of a how-to, feel free to use as
+you wish under no formal license, with no guarantees.
+
+If/As I developer this further, this may change, please feel free to make suggestions, though
+again, with no guarantees.
+
+Future
+------
+I do hope to develop this further, specifically I'm mulling how this would look when also
+sending data over the socket, something I haven't needed as much yet.