[docs-app] create "Design Principles" section, mention CSS API contract

packages/docs-app/src/blueprint.md

@@ -18,7 +18,7 @@ Blueprint v3 is available now! [See what's new.](#blueprint/whats-new-3.0)
 
 ### Install
 
-**@blueprintjs/core** is the primary Blueprint package on NPM and home to over 40 components.
+**@blueprintjs/core** is the primary Blueprint package on NPM and home to over 40 components. Install it with your package manager ([Yarn](https://yarnpkg.com/) is used in this example):
 
 ```sh
 yarn add @blueprintjs/core react react-dom
@@ -36,26 +36,20 @@ import { Button } from "@blueprintjs/core";
 <Button intent="success" text="button content" onClick={incrementCounter} />
 ```
 
-Don't forget to include the **main CSS file** from each Blueprint package!
+For this button to be styled correctly in the DOM, it needs its associated CSS to be loaded on the page.
+Don't forget to include the **main CSS file** from each Blueprint package and their dependencies!
+The following example shows an `index.html` file; the same stylesheets should be loaded if you use a bundler like Webpack.
 
 ```html
-<!-- in index.html, or however you manage your CSS files -->
 <link href="path/to/node_modules/normalize.css/normalize.css" rel="stylesheet" />
 <!-- blueprint-icons.css file must be included alongside blueprint.css! -->
 <link href="path/to/node_modules/@blueprintjs/icons/lib/css/blueprint-icons.css" rel="stylesheet" />
 <link href="path/to/node_modules/@blueprintjs/core/lib/css/blueprint.css" rel="stylesheet" />
 <!-- add other blueprint-*.css files here -->
 ```
 
-@## Browser support
-
-**Blueprint supports Chrome, Firefox, Safari, IE 11, and Microsoft Edge.**
-
-You may experience degraded visuals in IE.
-IE 10 and below are unsupported due to their lack of support for CSS Flexbox Layout.
-These browsers were deprecated by Microsoft (end of support) in [January 2016](https://www.microsoft.com/en-us/WindowsForBusiness/End-of-IE-support).
-
 @page getting-started
 @page reading-the-docs
+@page principles
 @page whats-new-2.0
 @page whats-new-3.0

packages/docs-app/src/principles.md

@@ -0,0 +1,17 @@
+@# Design Principles
+
+@## Browser support
+
+**Blueprint supports Chrome, Firefox, Safari, IE 11, and Microsoft Edge.**
+
+You may experience degraded visuals in IE.
+IE 10 and below are unsupported due to their lack of support for CSS Flexbox Layout.
+These browsers were deprecated by Microsoft (end of support) in [January 2016](https://www.microsoft.com/en-us/WindowsForBusiness/End-of-IE-support).
+
+@## API Contract
+
+Blueprint strictly adheres to [semver](https://semver.org/) in its public APIs:
+
+- JS APIs exported from the root/main module of a Blueprint package
+- HTML structure of components
+- CSS styles for rendered components