diff --git a/COMMITLINT.md b/COMMITLINT.md
new file mode 100644
index 0000000..b593ea0
--- /dev/null
+++ b/COMMITLINT.md
@@ -0,0 +1,76 @@
+# Commit Messages Format
+
+This project uses the (conventional commit specification)[https://www.conventionalcommits.org/en/v1.0.0/#specification] for consistent commit messages.
+
+All commit messages should have the following form:
+
+```
+<type>: <description>
+```
+
+## Fix
+
+A fix (PATCH in semantic versioning) looks like this:
+
+```
+fix: correct minor typos in code
+```
+
+## Feature
+
+A new feature (MINOR in semantic versioning) looks like this:
+
+```
+feat: add catalan language
+```
+
+## Breaking Change
+
+Breaking changes can be indicated by either appending a "!" to the type:
+
+```
+refactor!: drop support for Node 6
+```
+
+Or adding "BREAKING CHANGE" to the commit message body text:
+
+```
+refactor!: drop support for Node 6
+
+BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.
+```
+
+## Available Types
+
+In addition to "fix" and "feat" the following types are allowed:
+build:, chore:, ci:, docs:, style:, refactor:, perf:, test:
+
+Install commitlint:
+
+```
+npm install --save-dev @commitlint/{config-conventional,cli}
+```
+
+or via yarn:
+
+```
+yarn add @commitlint/{config-conventional,cli}
+```
+
+Create a commitlint.config.js file:
+
+```
+echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
+```
+
+Add husky to package.json:
+
+```
+{
+  "husky": {
+    "hooks": {
+      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+    }
+  }
+}
+```
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..40dfdb3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+# Walk-up alarm
+
+![GitHub pages deploy](https://github.com/nzambello/walk-up-alarm/workflows/Test%20and%20deploy/badge.svg?branch=main)
+
+Alarm clock ringing until you walk out of the bed.
+
+<p>
+  See it in action:
+  <a href="https://nzambello.github.io/walk-up-alarm/" target="_blank" rel="noopener noreferrer">
+    nzambello.github.io/walk-up-alarm
+  </a>
+</p>
+<p>It's a <a href="https://en.wikipedia.org/wiki/Progressive_web_application" target="_blank" rel="noopener noreferrer">PWA</a>. Install it on your device!</p>
+<br />
+<a href="https://nzambello.github.io/walk-up-alarm/" target="_blank" rel="noopener noreferrer">
+  <img src="./public/walk-up-alarm.svg" width="200" alt="Walk-up logo" style="margin: 2rem 0" />
+</a>
+
+## Screenshots
+
+<img src="./screenshots/start.png" alt="Start page" width="33%"/>
+<img src="./screenshots/clock-alarm-set.png" alt="Start page" width="33%"/>
+<img src="./screenshots/alarm-playing.png" alt="Start page" width="33%"/>
+<br />
+<br />
+
+## Development
+
+```bash
+yarn install
+```
+
+### Run the app
+
+```bash
+yarn dev
+```
+
+### Build the app
+
+```bash
+yarn build
+yarn preview
+```
+
+### Run tests
+
+```bash
+yarn test
+```
+
+## Contributions
+
+Please follow our [convention](COMMITLINT.md) on commits format.
diff --git a/screenshots/alarm-playing.png b/screenshots/alarm-playing.png
new file mode 100644
index 0000000..9f3b6c2
Binary files /dev/null and b/screenshots/alarm-playing.png differ
diff --git a/screenshots/clock-alarm-set.png b/screenshots/clock-alarm-set.png
new file mode 100644
index 0000000..68c3cf2
Binary files /dev/null and b/screenshots/clock-alarm-set.png differ
diff --git a/screenshots/start.png b/screenshots/start.png
new file mode 100644
index 0000000..7ab40b9
Binary files /dev/null and b/screenshots/start.png differ