1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2024-12-24 06:20:56 +01:00

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
This commit is contained in:
epriestley 2014-04-08 08:05:05 -07:00
parent 740fbba961
commit 88dc1cf3f6
2 changed files with 103 additions and 2 deletions

View file

@ -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}.

View file

@ -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.