diff --git a/packages/rmf-dashboard-framework/README.md b/packages/rmf-dashboard-framework/README.md
index faf8ff62a..9df1146c7 100644
--- a/packages/rmf-dashboard-framework/README.md
+++ b/packages/rmf-dashboard-framework/README.md
@@ -1,48 +1,16 @@
-# rmf-dashboard
+# rmf-dashboard-framework
-`rmf-dashboard` is a web application that provides overall visualization and control over the RMF system.
+`rmf-dashboard-framework` is a library that makes it easy to build a web application that provides visualization and control over the RMF system.
-# Setup
+## Getting Started
-Follow the build instructions [here](../../README.md/#launching).
+See the [Getting Started](./docs/getting-started.md) docs.
-## Configuration
+## MicroApps
-Before building the dashboard, you must configure it according to the deployment. All the configurations is on `app-config.json`, the default configuration is for running the api-server and dashboard locally. You may check [src/app-config.ts](src/app-config.ts) for more details on the config file schema.
+MicroApps are react components that can be used to build a page. The dashboard comes with many different micro-apps, each serving a different purpose when interacting with an Open-RMF deployment. The dashboard uses events to pipe information between micro-apps, for example clicking onto a task row in the Task app, will center the map onto the robot that the task was assigned to.
-### (Optional) Add external resources.
-
-The `resources` option in the app config allows configuring various assets used by the dashboard. At the moment, it mainly allows configuring the header logo and robot icons, they should point to either the full url or absolute url, for example
-
-```json
- "resources": {
- "default": {
- "fleets": {
- "tinyRobot": {
- "default": {
- "icon": "https://raw.githubusercontent.com/open-rmf/rmf_demos/rmf-web-dashboard-resources/rmf_demos_dashboard_resources/office/icons/tinyRobot.png",
- "scale": 0.00123
- }
- }
- },
- "logos": {
- "header": "/resources/defaultLogo.png"
- }
- }
- },
-```
-
-In the above config, the header logo will be on absolute url `/resources/defaultLogo.png`, if the resources are hosted on a different domain (e.g. you are using a cdn), then it should include the full url, e.g. `https://storage.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]`.
-
-For testing, it is convenient to put the resources in the `public` folder and they will be served by the vite dev server.
-
-For dashboard resources for `rmf_demos` simulation worlds, check out the [rmf-web-dashboard-resources](https://github.com/open-rmf/rmf_demos/tree/rmf-web-dashboard-resources) branch of `rmf_demos`.
-
-### Micro-apps
-
-The dashboard comes with many different micro-apps, each serving a different purpose when interacting with an Open-RMF deployment. The dashboard uses events to pipe information between micro-apps, for example clicking onto a task row in the Task app, will center the map onto the robot that the task was assigned to.
-
-Here are the available apps,
+Some of the built in MicroApps are:
* Robots
* Map
* Doors
@@ -54,39 +22,37 @@ Here are the available apps,
* Task Details
* Task Logs
-### Workspace (tab) layouts
+It is also possible to create new MicroApps, see [Creating a MicroApp](./docs/micro-apps.md#creating-a-microapp) for some examples.
-Each workspace (tab) allows users to define how the layout of micro-apps should be. By modifying the `WorkspaceState` of the workspace, micro-apps can be resized, moved, added or removed.
+## Workspaces
-Here is an example workspace state,
+A `Workspace` is a react component that render MicroApps based on a given layout, it makes it very easy to build a page in `rmf-dashboard-framework` by combining multiple MicroApps. Here is an example of a workspace
-```typescript
-export const robotsWorkspace: WorkspaceState = {
- layout: [
- { i: 'robots', x: 0, y: 0, w: 7, h: 3 },
- { i: 'map', x: 8, y: 0, w: 5, h: 9 },
- { i: 'doors', x: 0, y: 0, w: 7, h: 3 },
- { i: 'lifts', x: 0, y: 0, w: 7, h: 3 },
- { i: 'beacons', x: 0, y: 0, w: 7, h: 3 },
- { i: 'mutexGroups', x: 8, y: 0, w: 5, h: 3 },
- ],
- windows: [
- { key: 'robots', appName: 'Robots' },
- { key: 'map', appName: 'Map' },
- { key: 'doors', appName: 'Doors' },
- { key: 'lifts', appName: 'Lifts' },
- { key: 'beacons', appName: 'Beacons' },
- { key: 'mutexGroups', appName: 'Mutex Groups' },
- ],
-};
+```tsx
+
```
-### Custom tab(s)
-
-With the dashboard configuration parameter `customTabs: true`, 2 custom tabs would be available on the App bar. These custom tabs allow users to create a custom layout of desired micro-apps, if a custom workflow is desired.
-
-These custom layouts will be cached locally on the browser's machine, where it can be brought up again.
+The above workspace renders a "Tasks" and "Map" MicroApp with a fixed layout, but it supports a `designMode` that allows free customizable of the layout by the user at runtime
+
+```tsx
+
+```
-To edit a custom tab, click onto the wand icon on the right end of the App bar, and proceed to add, resize, move or remove micro-apps from the layout.
+## Examples
-
+See [examples](./examples/)