src/docs/contributor/css_coding_standards.diviner

   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   lang=css
  26   span.critical {
  27     color: {$red};
  28   }
  29
  30 You can find a list of all available colors in the **UIExamples** application.
  31
  32 = Printable Rules =
  33
  34 If you preface a rule with `!print`, it will be transformed into a print rule
  35 and activated when the user is printing the page or viewing a printable version
  36 of the page:
  37
  38   lang=css
  39   !print div.menu {
  40     display: none;
  41   }
  42
  43 Specifically, this directive causes two copies of the rule to be written out.
  44 The output will look something like this:
  45
  46   lang=css
  47   .printable div.menu {
  48     display: none;
  49   }
  50
  51   @media print {
  52     div.menu {
  53       display: none;
  54     }
  55   }
  56
  57 The former will activate when users look at the printable versions of pages, by
  58 adding `__print__` to the URI. The latter will be activated in print contexts
  59 by the media query.
  60
  61 = Device Rules =
  62
  63 Phabricator's environment defines several device classes which can be used to
  64 adjust behavior responsively. In particular:
  65
  66   lang=css
  67   .device-phone {
  68     /* Smallest breakpoint, usually for phones. */
  69   }
  70
  71   .device-tablet {
  72     /* Middle breakpoint, usually for tablets. */
  73   }
  74
  75   .device-desktop {
  76     /* Largest breakpoint, usually for desktops. */
  77   }
  78
  79 Since many rules are specific to handheld devices, the `.device` class selects
  80 either tablets or phones:
  81
  82   lang=css
  83   .device {
  84     /* Phone or tablet (not desktop). */
  85   }
  86
  87 = Image Inlining =
  88
  89 Phabricator's CSS preprocessor automatically inlines images which are less than
  90 32KB using `data:` URIs. This is primarily useful for gradients or textures
  91 which are small and difficult to sprite.