FEATURE: Add Readme

FEATURE: Add Readme

diff --git a/README.md b/README.md
index a312c9d..3a4e907 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,18 @@
 # discourse-docs-card-filter
+This theme component is to be used with the [Discourse Docs Plugin](https://github.com/discourse/discourse-docs).
+
+It will allow you to place "Cards" that act as a clickable filter for quicker filter results upon entering the `/docs` page by your users. 
+
+![docs card filter preview](./readme-assets/preview.png)
+
+These cards are rendered based on your selections in the settings of the `Docs` plugin.
+
+The above would be rendered if in your docs plugin settings you have the following chosen:
+![docs settings](./readme-assets/docs-settings.png)
+
+## Component Settings
+You can select custom icons for each category or tag card filter. You can also allow category descriptions to be rendered in the category card filters.
+
+![card filter settings](./readme-assets/settings.png)
+
+
diff --git a/readme-assets/docs-settings.png b/readme-assets/docs-settings.png
new file mode 100644
index 0000000..2159b68
Binary files /dev/null and b/readme-assets/docs-settings.png differ
diff --git a/readme-assets/preview.png b/readme-assets/preview.png
new file mode 100644
index 0000000..ba29d98
Binary files /dev/null and b/readme-assets/preview.png differ
diff --git a/readme-assets/settings.png b/readme-assets/settings.png
new file mode 100644
index 0000000..bc15e7a
Binary files /dev/null and b/readme-assets/settings.png differ

GitHub sha: b7002feea48638b09344590c2407a925d2c1c3a3