docs: updating readme file

README.md

@@ -92,3 +92,68 @@ For the same reasons as for CodeMirror this dependencies are required for OAuth1
 <script src="node_modules/cryptojslib/rollups/hmac-sha1.js"></script>
 <script src="node_modules/jsrsasign/lib/jsrsasign-rsa-min.js"></script>
 ```
+
+## Usage
+
+Two basic use cases for API Console is:
+
+-   standalone application - enables application, full window view
+-   web component - lighter version, does not offer general layout and routing support
+
+### Standalone application
+
+To use API Console as a standalone application use `api-console-app` element provided by `api-console-app.js` file.
+The standalone application supports routing and layout elemenets (compared to API Console as an element).
+
+In this mode the console has title bar, drawer that holds navigation and enables modile view, and main element that
+holds scrolling region (the body is not a scrolling region in this case).
+
+Additionally the console application includes `xhr-simple-request`, `oauth1-authorization`, and `oauth2-authorization` components.
+
+See `demo/standalone/index.html` for an example.
+
+### Web component
+
+Offers rendering documentation view as a default view, on user request request panel, and contains an aloways hidden navigation that cannot be triggered from the elements's UI. The application that hosts the element must provide some kind of an UI for the user to trigger the navigation. Navigation cnn be opened by setting the `navigationOpened` property to `true`.
+
+Because API console as a web component has no layout element you may want to control the height of the console. It should be set as specific value to properly support navigation drawer.
+
+The API Console element does not includes `xhr-simple-request`, `oauth1-authorization`, or `oauth2-authorization` components. This components has to be added to the DOM separately, if not planning to handle authorization or sending events.
+
+See `demo/element/index.html` for an example.
+
+### Working with AMF model
+
+API console does not offer parsing API file(s) to the data model. This is done by the [AMF](https://github.com/aml-org/amf) parser provided by MuleSoft.
+
+For both standalone and web component version of API console you must set AMF generated model on `amf` property of the console. The source can be direct result of parsing API spec file by the AMF parser or a JSON+ld model stored in a file. For a performance reasons the later is preffered.
+
+```html
+<api-console></api-console>
+<script>
+{
+  const model = await generateApiModel();
+  const apic = document.querySelector('api-console');
+  apic.amf = model;
+  // reset selection
+  apic.selectedShape = 'summary';
+  apic.selectedShapeType = 'summary';
+}
+</script>
+```
+
+### Styling API Console
+
+Styles can be manipulated by creating a stylesheet with CSS veriables definition. Each component that has been used to build the console exposes own styling API.
+
+API components ecosystem does not provide detailed documentation for styling API. Because of that when styling the console use Chrome DevTools to read name of a
+variable with default value to sett it in the stylesheet.
+
+See `demo/themed/anypoint-theme.css` and `demo/themed/dark-theme.css` files for an example of styled API Console.
+
+#### Anypoint compatibility
+
+API Console offers a `compatibility` property that enables (some) components to switch theme to Anypoint. All form controls in request panel, buttons, icon buttons,
+and lists are switched to compatibility view automaticaly when `compatibility` is set.
+
+Note, that not all components support this property and therefore some styling adjustment may be needed. See `demo/themed/anypoint-theme.css` for an example of such style sheet.