commit 20cc569f5961d4e896cb2f4651fd2049066bd47c
Author: Adam Barth <abarth@chromium.org>
Date:   Thu Oct 23 11:05:40 2014 -0700

    Add a README.md for Sky
    
    R=jamesr@chromium.org
    
    Review URL: https://codereview.chromium.org/672963002

diff --git a/README.md b/README.md
new file mode 100644
index 00000000000..b750fc08dc5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,152 @@
+Sky
+===
+
+Sky is an experiment in building a UI framework for Mojo.  The approach we're
+exploring is to create a layered framework based around a retained hierarchy of
+semantic elements.  We're experimenting with different ideas and exploring
+various approaches, many of which won't work and will need to be discarded, but,
+if we're lucky, some of which might turn out to be useful.
+
+Sky has three layers, each of which also adds progressively more opinion.  At
+the lowest layer, Sky contains a rendering engine that parses markup, executes
+script, and applies styling information.  Layered above the engine is a
+collection of components that define the interactive behavior of a suite of
+widgets, such as input fields, buttons, and menus.  Above the widget layer is a
+theme layer that gives each widget a concrete visual and interactive design.
+
+Elements
+--------
+
+The Sky engine contains a handful of primitive elements and the tools with which
+to create custom elements.  The following elements are built into the engine:
+
+ - ``script``: Executes script
+ - ``style``: Defines style rules
+ - ``import``: Loads a module
+ - ``iframe``: Embeds another Mojo application
+ - ``template``: Captures descendants for use as a template
+ - ``content``: Visually projects descendents of the shadow host
+ - ``shadow``: Visually projects older shadow roots of the shadow host
+ - ``image``: Displays an image
+ - ``a``: Links to another Mojo application
+ - ``title``: Briefly describes the current application state to the user
+
+### Additional Elements ###
+
+In addition to the built-in elements, frameworks and applications can define
+custom elements.  The Sky framework contains a number of general-purpose
+elements, including ``input``, ``button``, ``menu``, ``toolbar``, ``video``, and
+``dialog``.  However, developers are free to implement their own input fields,
+buttons, menus, toolbars, videos, or dialogs with access to all the same engine
+features as the frame because the framework does not occupy a privileged
+position in Sky.
+
+### Custom Layout ###
+
+TODO: Describe the approach for customizing layout.
+
+### Custom Painting ###
+
+TODO: Describe the approach for customizing painting.
+
+Modules
+-------
+
+Sky applications consist of a collection of modules.  Each module can describe
+its dependencies, register custom elements, and export objects for use in other
+modules.
+
+Below is a sketch of a typical module.  The first ``import`` element imports the
+Sky framework, which defines the ``sky-element`` element.  This module then uses
+``sky-element`` to define another element, ``my-element``. The second ``import``
+element imports another module and gives it the name ``foo`` within this module.
+For example, the ``AnnualReport`` constructor uses the ``BalanceSheet`` class
+exported by that module.
+
+```html
+<import href=”/sky/framework” />
+<import href=”/another/module.sky” as=”foo” />
+<sky-element name=”my-element”>
+  [ ... custom element definition ... ]
+</sky-element>
+<script>
+class AnnualReport {
+  constructor(bar) {
+    this.sheet = new foo.BalanceSheet(bar);
+  }
+  frobinate() {
+    this.sheet.balance();
+  }
+}
+
+function mult(x, y) {
+  return x * y;
+}
+
+function multiplyByTwo(x) {
+  return mult(x, 2);
+}
+
+module.exports = {
+  AnnualReport: AnnualReport,
+  multiplyByTwo: multiplyByTwo,
+};
+</script>
+```
+
+The script definitions are local to each module and cannot be referenced by
+other modules unless exported.  For example, the ``mult`` function is private to
+this module whereas the ``multiplyByTwo`` function can be used by other modules
+because it is exported.  Similarly, this module exports the ``AnnualReport``
+class.
+
+Services
+--------
+
+Sky applications can access Mojo services and can provide services to other Mojo
+applications.  For example, Sky applications can access the network using Mojo's
+``network_service``.  Typically, however, Sky applications access services via
+frameworks that provide idiomatic interfaces to the underlying Mojo services.
+These idiomatic interfaces are layered on top of the underlying Mojo service,
+and developers are free to use the underlying service directly.
+
+As an example, the following is a sketch of a module that wraps Mojo's
+``network_service`` in a simpler functional interface:
+
+```html
+<import href=”mojo://shell” as=”shell” />
+<import href="/mojo/network/network_service.mojom.sky" as="net" />
+<import href="/mojo/network/url_loader.mojom.sky" as="loader" />
+<script>
+module.exports = function fetch(url) {
+  return new Promise(function(resolve, reject) {
+    var networkService = shell.connectToService(
+        "mojo://network_service", net.NetworkService);
+    var request = new loader.URLRequest({
+        url: url, method: "GET", auto_follow_redirects: true});
+    var urlLoader = networkService.createURLLoader();
+    urlLoader.start(request).then(function(response) {
+      if (response.status_code == 200)
+        resolve(response.body);
+      else
+        reject(response);
+    });
+  };
+};
+</script>
+```
+
+Notice that the ``shell`` module is built-in and provides access to the
+underlying Mojo fabric but the ``net`` and ``loader`` modules run inside Sky and
+encode and decode messages sent over Mojo pipes.
+
+Specifications
+--------------
+
+TODO: Link to the specs.
+
+Contributing
+------------
+
+TODO: Link to HACKING.md, which contains the instructions for hacking on Sky.
+TODO: Link to mailing list and IRC channel.