[Summary view] [Print] [Text view]

   1  @title CSS Coding Standards
   2  @group standards
   3  
   4  This document describes CSS features and coding standards for Phabricator.
   5  
   6  = Overview =
   7  
   8  This document describes technical and style guidelines for writing CSS in
   9  Phabricator.
  10  
  11  Phabricator has a limited CSS preprocessor. This document describes the features
  12  it makes available.
  13  
  14  = Z-Indexes =
  15  
  16  You should put all `z-index` rules in `z-index.css`, and keep them sorted. The
  17  goal is to make indexes relatively manageable and reduce the escalation of the
  18  Great Z-Index War where all indexes grow without bound in an endless arms race.
  19  
  20  = Color Variables =
  21  
  22  Phabricator's preprocessor provides some standard color variables. You can
  23  reference these with `{$color}`. For example:
  24  
  25    span.critical {
  26      color: {$red};
  27    }
  28  
  29  You can find a list of all available colors in the **UIExamples** application.
  30  
  31  = Printable Rules =
  32  
  33  If you preface a rule with `!print`, it will be transformed into a print rule
  34  and activated when the user is printing the page or viewing a printable version
  35  of the page:
  36  
  37    lang=css
  38    !print div.menu {
  39      display: none;
  40    }
  41  
  42  Specifically, this directive causes two copies of the rule to be written out.
  43  The output will look something like this:
  44  
  45    lang=css
  46    .printable div.menu {
  47      display: none;
  48    }
  49  
  50    @media print {
  51      div.menu {
  52        display: none;
  53      }
  54    }
  55  
  56  The former will activate when users look at the printable versions of pages, by
  57  adding `__print__` to the URI. The latter will be activated in print contexts
  58  by the media query.
  59  
  60  = Device Rules =
  61  
  62  Phabricator's environment defines several device classes which can be used to
  63  adjust behavior responsively. In particular:
  64  
  65    lang=css
  66    .device-phone {
  67      /* Smallest breakpoint, usually for phones. */
  68    }
  69  
  70    .device-tablet {
  71      /* Middle breakpoint, usually for tablets. */
  72    }
  73  
  74    .device-desktop {
  75      /* Largest breakpoint, usually for desktops. */
  76    }
  77  
  78  Since many rules are specific to handheld devices, the `.device` class selects
  79  either tablets or phones:
  80  
  81    .device {
  82      /* Phone or tablet (not desktop). */
  83    }
  84  
  85  = Image Inlining =
  86  
  87  Phabricator's CSS preprocessor automatically inlines images which are less than
  88  32KB using `data:` URIs. This is primarily useful for gradients or textures
  89  which are small and difficult to sprite.