docs: clarify alpha status, components likely to change

Several people have asked about why the component library is in an alpha release stage, and what
components are likely to see breaking changes before the end of alpha. This attempts to clarify
those issues in the documentation.

COMPONENT_DESIGN.md

@@ -2,8 +2,13 @@
 
 Best practices for developing presentational web components that have a nice API and are easy to work with.
 
- - [Prefer structured markup](#markdown-header-prefer-structured-markup-over-complex-attributes-over-js-interfaces)
- - [Use a consistent input API](#markdown-header-use-a-consistent-api-for-components-that-accept-input)
+The general principle at work in this document is that our presentational components should have APIs that are
+consistent with native browser elements. They should feel familiar to users who are comfortable working with
+native input elements and controls.
+
+- [Prefer structured markup](#markdown-header-prefer-structured-markup-over-complex-attributes-over-js-interfaces)
+- [Use a consistent input API](#markdown-header-use-a-consistent-api-for-components-that-accept-input)
+- [Don't use reflectToAttr](#markdown-header-dont-use-reflecttoattr)
 
 ## Prefer structured markup over complex attributes or js interfaces
 
@@ -71,4 +76,19 @@ those components and for events emitted by the components. In particular compone
 - Should have a `value` attribute and property, like the various native input-related elements
   - An additional boolean attribute similar to `checked` may be appropriate for elements with boolean state.
 - Should emit the `input` event (at a minimum) with the `detail` property on the event set to the data the
-component is intended to get from the user.
+  component is intended to get from the user.
+
+## Don't use reflectToAttr
+
+Stencil properties can be set with the option `reflectToAttr`. When set, a change in an elements property will
+also change the value of the attribute in the DOM. For example, when dealing with this input element:
+
+```html
+<my-custom-input id="myInput" value="default"></my-custom-input>
+```
+
+If `reflectToAttr` was set on `value`, then calling `document.getElementById("myInput").value = "new value"` would
+mean that `document.getElementById("myInput").getAttr("value")` would now return "new value". This is _not_ how
+native browser elements behave. It also puts the internal implementation of the compnent in conflict with the surrounding
+framework used to render it about what the attribute's value should be, since it is being set twice, potentially leading
+to bugs.

README.md

@@ -17,6 +17,10 @@ You may also want to join the chat room for the Genesys Cloud [Common UI Develop
 
 ## Installing the library
 
+Currently the main line of development is done in the 1.0.0-alpha branch/release. This is because we are working on making
+changes to the APIs of some components to bring them up to our [API design standards](COMPONENT_DESIGN.md). The elements
+that are currently likely to change are documented by the `likely-breaking-changes` label [in JIRA](<https://inindca.atlassian.net/issues/?jql=project%20%3D%20%22COMUI%22%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20in%20(likely-breaking-changes)%20ORDER%20BY%20priority%20DESC>).
+
 ### Prerequisites
 
 Published artifacts are stored in our private artifactory/jfrog registry, so you will need to update your