Page MenuHomePhabricator
Files F13206146

D8720.diff
No OneTemporary
Actions

D8720.diff
View Options

diff --git a/src/docs/contributor/adding_new_css_and_js.diviner b/src/docs/contributor/adding_new_css_and_js.diviner
--- a/src/docs/contributor/adding_new_css_and_js.diviner
+++ b/src/docs/contributor/adding_new_css_and_js.diviner
@@ -9,10 +9,13 @@
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 @@
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 @@
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}.
diff --git a/src/docs/contributor/css_coding_standards.diviner b/src/docs/contributor/css_coding_standards.diviner
new file mode 100644
--- /dev/null
+++ b/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.

File Metadata

Mime Type
text/plain
Expires
May 16 2024, 5:31 AM (5 w, 6 h ago)
Storage Engine
blob
Storage Format
Encrypted (AES-256-CBC)
Storage Handle
6287556
Default Alt Text
D8720.diff (4 KB)

Event Timeline

Phabricator · Built by Phacility