Added core/css/properties/README.md.

third_party/WebKit/Source/core/css/properties/README.md

Index: third_party/WebKit/Source/core/css/properties/README.md
diff --git a/third_party/WebKit/Source/core/css/properties/README.md b/third_party/WebKit/Source/core/css/properties/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..35fad856ea0b803c76358d7c984586a98c104297
--- /dev/null
+++ b/third_party/WebKit/Source/core/css/properties/README.md
@@ -0,0 +1,52 @@
+# Property APIs
+
+This directory contains implementations for CSS property APIs, as well as Utils
+files containing functions commonly used by the property APIs.
+
+A CSS property API represents a single CSS property or a group of CSS
+properties, and defines the logic for that property or group of properties.
+
+Examples:
+
+*   A single property API: the `CSSPropertyAPILineHeight` class is used only by
+    the `line-height` property
+*   A group of properties that share logic: the `CSSPropertyAPIImage` class
+    is shared by the `border-image-source` and `list-style-image` properties.
+
+Status (March 16 2017): Eventually, all logic pertaining to a single property
+should be found only within its CSS property API. Currently, the code base is in
+a transitional state and property specific logic is still scattered around the
+code base. See Project Ribbon
+[tracking bug](https://bugs.chromium.org/p/chromium/issues/detail?id=545324) and
+[design doc](https://docs.google.com/document/d/1ywjUTmnxF5FXlpUTuLpint0w4TdSsjJzdWJqmhNzlss/edit#heading=h.1ckibme4i78b)
+for details of progress.
+
+## How to add a new property API
+
+1.  Add a .cpp file to this directory named
+    `CSSPropertyAPI<Property/GroupName>.cpp`
+2.  Implement the property API in the .cpp file
+    1.  Add `#include "core/css/properties/CSSPropertyAPI<Property/GroupName>.h"`
+        (this will be a generated file)
+    2.  Implement the required methods on the API, e.g. `parseSingleValue`
+3.  If logic is required by multiple property APIs you may need to create a new
+    Utils file.
+4.  Add the new property to `core/css/CSSProperties.json5`. Ensure that you
+    include the 'api_class' flag and the 'api_methods' flag so that the API
+    files are generated correctly (see
+    [CSSProperties.json5](https://cs.chromium.org/chromium/src/third_party/WebKit/Source/core/css/CSSProperties.json5)
+    for more details)
+5.  Add new files to BUILD files
+    1.  Add the new .cpp file to
+        [core/css/BUILD.gn](https://codesearch.chromium.org/chromium/src/third_party/WebKit/Source/core/css/BUILD.gn)
+        in the `blink_core_sources` target's `sources` parameter
+    2.  Add the generated .h file to
+        [core/BUILD.gn](https://codesearch.chromium.org/chromium/src/third_party/WebKit/Source/core/BUILD.gn)
+        in the `css_properties` target's `outputs` parameter
+
+See [this example CL](https://codereview.chromium.org/2735093005), which
+converts the existing line-height property to use the CSSPropertyAPI design.
+This new line-height property API only implements the parseSingleValue method,
+using
+[CSSPropertyFontUtils.cpp](https://cs.chromium.org/chromium/src/third_party/WebKit/Source/core/css/properties/CSSPropertyFontUtils.h)
+to access shared font logic.