try to write down the various naming & architectural conventions that the SDK adheres to...

README.md

@@ -39,3 +39,86 @@ react from your app) you must be sure to:
 2. If you `npm link` matrix-react-sdk, manually remove the 'react' directory
    from matrix-react-sdk's `node_modules` folder, otherwise browserify will
    pull in both copies of react which causes the app to break.
+
+How to customise the SDK
+========================
+
+The matrix-react-sdk has been built to be heavily customisable - letting
+developers both create new skins by extending/overriding the CSS and View
+classes provided in the base skin, as well as entirely replacing components as
+required.
+
+The SDK uses the 'atomic' design pattern as seen at http://patternlab.io to
+encourage a very modular and reusable architecture, making it as easy to
+customise and use UI widgets independently of the rest of the SDK and your app.
+In practice this means:
+
+ * The UI of the app is strictly split up into a hierarchy of components.
+ 
+ * Each component has its own:
+   * View object defined as a React javascript class containing embedded
+     HTML expressed in React's JSX notation.
+   * CSS file, which defines the styling specific to that component.
+ 
+ * Components are loosely grouped into the 5 levels outlined by atomic design:
+   * atoms: fundamental building blocks (e.g. a timestamp tag)
+   * molecules: "group of atoms which functions together as a unit"
+     (e.g. a message in a chat timeline)
+   * organisms: "groups of molecules (and atoms) which form a distinct section
+     of a UI" (e.g. a view of a chat room)
+   * templates: "a reusable configuration of organisms" - used to combine and
+     style organisms into a well-defined global look and feel
+   * pages: specific instances of templates.
+
+ Good separation between the components is maintained by adopting various best
+ practices that anyone working with the SDK needs to be be aware of and uphold:
+
+  * Views are named with upper camel case (e.g. molecules/MessageTile.js)
+
+  * The view's CSS file MUST have the same name (e.g. molecules/MessageTile.css)
+
+  * Per-view CSS is optional - it could choose to inherit all its styling from
+    the context of the rest of the app, although this is unusual for any but 
+    the simplest atoms and molecules.
+
+  * The view MUST *only* refer to the CSS rules defined in its own CSS file.
+    'Stealing' styling information from other components (including parents)
+    is not cool, as it breaks the independence of the components.
+
+  * CSS classes are named with an app-specific namespacing prefix to try to avoid
+    CSS collisions.  The base skin shipped by Matrix.org with the matrix-react-sdk
+    uses the naming prefix "mx_".  A company called Yoyodyne Inc might use a
+    prefix like "yy_" for its app-specific classes.
+
+  * CSS classes use upper camel case when they describe React components - e.g.
+    .mx_MessageTile is the selector for the CSS applied to a MessageTile view.
+
+  * CSS classes for DOM elements within a view which aren't components are named
+    by appending a lower camel case identifier to the view's class name - e.g.
+    .mx_MessageTile_randomDiv is how you'd name the class of an arbitrary div
+    within the MessageTile view.
+
+  * We deliberately use vanilla CSS 3.0 to avoid adding any more magic
+    dependencies into the mix than we already have.  App developers are welcome
+    to use whatever floats their boat however.
+
+  * The CSS for a component can however override the rules for child components.
+    For instance, .mx_RoomList .mx_RoomTile {} would be the selector to override
+    styles of RoomTiles when viewed in the context of a RoomList view.
+    Overrides *must* be scoped to the View's CSS class - i.e. don't just define
+    .mx_RoomTile {} in RoomList.css - only RoomTile.css is allowed to define its
+    own CSS.  Instead, say .mx_RoomList .mx_RoomTile {} to scope the override
+    only to the context of RoomList views.  N.B. overrides should be relatively
+    rare as in general CSS inheritence should be enough.
+
+  * Components should render only within the bounding box of their outermost DOM
+    element. Page-absolute positioning and negative CSS margins and similar are
+    generally not cool and stop the component from being reused easily in
+    different places.
+
+  * We don't use the atomify library itself, as React already provides most
+    of the modularity requirements it brings to the table.
+
+With all this in mind, here's how you go about skinning the react SDK UI
+components to embed a Matrix client into your app:  TODO. For now, check out
+the examples and work it out for yourself...