From 6813aff09260c8c447dd7cd717ef0b711589b549 Mon Sep 17 00:00:00 2001
From: Gil Balsiger <gil.balsiger@gmail.com>
Date: Sat, 27 Jan 2024 20:18:19 +0100
Subject: [PATCH] chore: update README.md

---
 README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 139e421..7aa6cbd 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,7 @@
 
 ## Table of Contents
 
+- 📖 [Introduction](#introduction)
 - 🚀 [Features](#features)
 - 📦 [Installation](#installation)
 - 💻 [Usage](#usage)
@@ -32,6 +33,19 @@
 - 💬 [Community](#community)
 - ⚖️ [License](#license)
 
+## Introduction
+
+### What is Bloum?
+
+Bloum is an open-source library of unstyled web components. The goal of this library is to provide a set of components that can be used in any web project, regardless of the framework or library used.
+It implements the most common components used in web applications that required a lot of JavaScript to work, like select, tabs, modals, etc.
+
+It is unstyled by default, meaning that it doesn't provide an opinionated design. It is up to you to style the components to fit your needs. However, it comes with a theme that you can use to get started quickly.
+
+### Why Bloum?
+
+The goal for this library is not to provide an exhaustive list of components, but rather to provider components that are usually tedious to implement and require a lot of JavaScript to work.
+
 ## Features
 
 - 🪶 **Lightweight:** Bloum is a library of *unstyled* web components. It comes with minimal CSS, so you can easily customize it to fit your needs.
@@ -40,8 +54,8 @@
 - 📱 **Responsive:** Works on all modern browsers and devices.
 - 📦 **No dependencies:** Does not depend on any other library or framework.
 - 🧪 **Tested:** End-to-end tests with Playwright.
-- 🎨 **Theming:** Easy to customize. Comes with a modern theme to quickly get started.
-- 🌈 **Modern:** Built with modern Web APIs such as Custom Elements and use the latest CSS features while maintaining compatibility with older browsers.
+- 🎨 **Theming:** Easy to customize and comes with a modern theme to quickly get started.
+- 🌈 **Modern:** Built with the [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) API.
 
 **Components:**
 
@@ -62,13 +76,76 @@
 
 ## Installation
 
+### CDN
+
+You can use the following lines in your `head` tag to load the latest version of Bloum from a CDN:
+
+```html
+<script src="https://unpkg.com/bloum" defer></script>
+
+<!-- include the default unstyled stylesheet -->
+<link href="https://unpkg.com/bloum/dist/style.min.css" rel="stylesheet">
+<!-- include the modern theme -->
+<link href="https://unpkg.com/bloum/dist/modern.min.css" rel="stylesheet">
+```
+
+### Package manager
+
+You can install Bloum using your favorite package manager:
+
+```bash
+# NPM
+npm install bloum
+
+# Yarn
+yarn add bloum
+
+# Pnpm
+pnpm add bloum
+
+# Bun
+bun add bloum
+```
+
 ## Usage
 
+Once installed, you can import the library in your JavaScript project:
+
+```js
+import "bloum"
+```
+
+This will register all the components globally.
+
+After that, you can include the default unstyled stylesheet in your JavaScript if you're using a bundler like Vite or Webpack:
+
+```js
+import "bloum/dist/style.min.css"
+```
+
+If you want to use an already styled theme, you can include it too:
+
+```js
+import "bloum/dist/modern.min.css"
+```
+
+Then, you can use the components in your HTML:
+
+```html
+<bl-select name="my-select">
+  <div data-value="1">Option 1</div>
+  <div data-value="2">Option 2</div>
+  <div data-value="3">Option 3</div>
+</bl-select>
+```
+
 ## Documentation
 
+The documentation is available at [https://www.bloum.dev](https://www.bloum.dev).
+
 ## Contributing
 
-## Community
+*TODO*
 
 ## License