Strawman web ui style guide.

Change-Id: I6d6ee09bb42f79adad8789e6b9cfb5a9f59dc1f2

website/content/docs/index.html

@@ -32,4 +32,5 @@ HTML, though:</p>
 <li><a href="/docs/prior-art">Prior Art</a>: other projects doing similar stuff</li>
 <li><a href="/download">Release History</a>: previous releases and notable features of each</li>
 <li><a href="/docs/contributing">Contributing</a>: how to help</li>
+<li><a href="/docs/web-ui-styleguide">The style to use when working on the Web UI</a></li>
 </ul>

website/content/docs/web-ui-styleguide

@@ -0,0 +1,60 @@
+<h1>Web UI Styleguide</h1>
+
+<p><em><strong>Note:</strong> The following statements represent how we think
+things should be, not how they are. The Web UI is just getting started and
+doesn't adhere to all of these goals yet. New code should, though.</em>
+
+<h2>Architecture</h2>
+
+<p>The Camlistore Web UI is an "<a
+href="http://en.wikipedia.org/wiki/Ajax_(programming)">AJAX</a>"-style web
+application that interacts with Camlistore servers just as any other client
+would. It speaks the same HTTP APIs as the Android and iOS clients, for example.
+We avoid creating APIs that are specific to one client, instead preferring to
+generalize functionality such that all current clients and even unknown future
+clients can make use of it.
+
+<p>The Web UI is written almost entirely in JavaScript. We make no effort to
+"<a href="http://www.w3.org/wiki/Graceful_degredation_versus_progressive_enhancement">degrade
+gracefully</a>" in the absence of JavaScript or CSS support. We try to minimize
+usage of literal HTML markup in the source, as it tends to lead to poor
+modularity. We instead prefer to construct DOM trees programmatically.
+
+<h2>Paradigm</h2>
+
+<p>Though we are architected mostly as a "<a
+href="http://en.wikipedia.org/wiki/Single-page_application">single-page
+application</a>", we make extensive use of URLs via
+<a href="https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history">pushState()</a>.
+In general every unique view in the application has a URL that can be used to
+revisit that view.
+
+<p>In the same vein, although we are an interactive application, we make
+appropriate use of web platform primitives where they exist. We use &lt;a&gt;
+tags for clickable things that navigate, so that browser tools like "Open in new
+tab" and "Copy link" work as users would expect. Similarly, when we want to
+display text, we use HTML text rather than  &lt;canvas&gt; or &lt;img&gt; tags
+so that selection and find-in-page work.
+
+<h2>Stack</h2>
+
+<p>We use <a href="https://developers.google.com/closure/">Google Closure</a>,
+mainly for its excellent dead-code removal and decent standard library. We
+use some Closure UI widgets, but are also happy to bypass the Closure UI layer
+and implement our own UI directly on the DOM when that's easier.
+
+<h2>Style</h2>
+
+<p>We follow the <a
+href="http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml"
+>Google JavaScript Styleguide</a> and the <a
+href="https://developers.google.com/closure/compiler/docs/js-for-compiler"
+>Closure JSDoc Rules</a> for formatting and so-on. Those of us that use Emacs
+install <a href="https://code.google.com/p/js2-mode/">Js2Mode</a>.
+
+<h2>Compatibility</h2>
+
+<p>We target the last two stable versions of Desktop Chrome, Firefox, Safari,
+IE. We also target the last two stable versions of Safari and Chrome on Android
+and iOS tablets. We don't currently target the phone form factor at all, though
+it probably sort of works with a lot of zooming and panning.