Add a basic CSS doc

Summary: Fixes T3426. This describes all the weird stuff we've got, at least. We can expand this as we get more contributors or after writing CSS lint.

Test Plan: Read document.

Reviewers: btrahan, chad

Reviewed By: chad

Subscribers: epriestley

Maniphest Tasks: T3426

Differential Revision: https://secure.phabricator.com/D8720

src/docs/contributor/adding_new_css_and_js.diviner

@@ -9,10 +9,13 @@ Phabricator uses a system called **Celerity** to manage static resources. If you
 are a current or former Facebook employee, Celerity is based on the Haste system
 used at Facebook and generally behaves similarly.
 
+This document is intended for Phabricator developers and contributors. This
+process will not work correctly for third-party code, plugins, or extensions.
+
 = Adding a New File =
 
 To add a new CSS or JS file, create it in an appropriate location in
-##webroot/rsrc/css/## or ##webroot/rsrc/js/## inside your ##phabricator/##
+`webroot/rsrc/css/` or `webroot/rsrc/js/` inside your `phabricator/`
 directory.
 
 Each file must ##@provides## itself as a component, declared in a header
@@ -30,7 +33,7 @@ comment:
 Note that this comment must be a Javadoc-style comment, not just any comment.
 
 If your component depends on other components (which is common in JS but
-rare and inadvisable in CSS), declare then with ##@requires##:
+rare and inadvisable in CSS), declare then with `@requires`:
 
   LANG=js
   /**
@@ -83,3 +86,12 @@ as possible, i.e. **not** at the top of your Controller. The idea is that you
 should @{function:require_celerity_resource} a resource only if you are actually
 using it on a specific rendering of the page, not just because some views of the
 page might require it.
+
+= Next Steps =
+
+Continue by:
+
+  - reading about Javascript-specific guidelines in @{article:Javascript Coding
+    Standards}; or
+  - reading about CSS-specific guidelines and features in @{article:CSS Coding
+    Standards}.

src/docs/contributor/css_coding_standards.diviner

@@ -0,0 +1,89 @@
+@title CSS Coding Standards
+@group standards
+
+This document describes CSS features and coding standards for Phabricator.
+
+= Overview =
+
+This document describes technical and style guidelines for writing CSS in
+Phabricator.
+
+Phabricator has a limited CSS preprocessor. This document describes the features
+it makes available.
+
+= Z-Indexes =
+
+You should put all `z-index` rules in `z-index.css`, and keep them sorted. The
+goal is to make indexes relatively manageable and reduce the escalation of the
+Great Z-Index War where all indexes grow without bound in an endless arms race.
+
+= Color Variables =
+
+Phabricator's preprocessor provides some standard color variables. You can
+reference these with `{$color}`. For example:
+
+  span.critical {
+    color: {$red};
+  }
+
+You can find a list of all available colors in the **UIExamples** application.
+
+= Printable Rules =
+
+If you preface a rule with `!print`, it will be transformed into a print rule
+and activated when the user is printing the page or viewing a printable version
+of the page:
+
+  lang=css
+  !print div.menu {
+    display: none;
+  }
+
+Specifically, this directive causes two copies of the rule to be written out.
+The output will look something like this:
+
+  lang=css
+  .printable div.menu {
+    display: none;
+  }
+
+  @media print {
+    div.menu {
+      display: none;
+    }
+  }
+
+The former will activate when users look at the printable versions of pages,
+by adding `__print__` to the URI. The latter will be activated in print contexts
+by the media query.
+
+= Device Rules =
+
+Phabricator's environment defines several device classes which can be used
+to adjust behavior responsively. In particular:
+
+  lang=css
+  .device-phone {
+    /* Smallest breakpoint, usually for phones. */
+  }
+
+  .device-tablet {
+    /* Middle breakpoint, usually for tablets. */
+  }
+
+  .device-desktop {
+    /* Largest breakpoint, usually for desktops. */
+  }
+
+Since many rules are specific to handheld devices, the `.device` class selects
+either tablets or phones:
+
+  .device {
+    /* Phone or tablet (not desktop). */
+  }
+
+= Image Inlining =
+
+Phabricator's CSS preprocessor automatically inlines images which are less than
+32KB using `data:` URIs. This is primarily useful for gradients or textures
+which are small and difficult to sprite.