[modular] Module Facet documentation
Describes how to write a module facet.
Testing=None
Change-Id: Ibcbde66a7660e85c8779a38f8ebe331449089e1f
diff --git a/docs/modular/module_facet.md b/docs/modular/module_facet.md
new file mode 100644
index 0000000..527b855
--- /dev/null
+++ b/docs/modular/module_facet.md
@@ -0,0 +1,116 @@
+# Module Facet
+
+Modules declare their run-time capabilities (e.g. which Intent actions they
+handle) in the module facet of their [component
+manifest][component-manifest] (i.e. their `.cmx` file).
+
+## What is a facet?
+
+Component facets are sections in the component manifest which aren't consumed
+directly by the component manager, but are left to be defined and consumed by
+other parts of Fuchsia. The Modular framework defines a `fuchsia.module` facet
+which module authors use to define module specific properties.
+
+This document describes how to declare a module facet in your component manifest.
+
+## Example
+
+The following is an excerpt of a component manifest that defines a module facet.
+
+```
+{
+ "facets": {
+ "fuchsia.module": {
+ "@version": 2,
+ "suggestion_headline": "See details about person",
+ "intent_filters": [
+ {
+ "action": "com.google.fuchsia.preview.v1",
+ "parameters": [
+ {
+ "name": "entityToPreview",
+ "type": "https://fuchsia.com/types/Friend"
+ }
+ ]
+ }
+ ],
+ "composition_pattern": "ticker"
+ }
+ }
+}
+```
+
+
+This module can be launched using an Intent with the action
+`com.google.fuchsia.preview.v1` action, and a `entityToPreview` parameter of
+type `https://fuchsia.com/types/Friend`.
+
+## Module Facet fields
+
+The module facet is defined under the `fuchsia.module` facet in a component
+manifest. See [example](#example).
+
+* `@version` **unsigned integer** *(required)*
+ - Describes the version of the module facet. The fields below indicate which
+ minimum `@version` they require.
+ - **example**: `2`
+* `composition_pattern`: **string** *(optional)*
+ - **minimum `@version`**: 1
+ - **possible values:**
+ * `ticker`: Show the module at the bottom of the screen underneath another
+ module.
+ * `comments-right`: show the module to the right of other modules.
+ - **example**: `"ticker"`
+ - Specifies the compositional pattern that will be used by the story shell to
+ display this module along-side other modules in the story. For example, the
+ ticker pattern gives a signal to the story shell that the module should be
+ placed below another module that it may share a link with.
+* `suggestion_headline`: **string** *(optional)*
+ - **minimum `@version`**: 2
+ - **possible values**: UTF-8 string
+ - **example**: `"See details about this person"`
+ - A human-readable string that may be used when suggesting this Module.
+* `placeholder_color`: **string** *(optional)*
+ - **minimum `@version`**: 2
+ - **possible values**: hex color code, leading with a hashtag (`#`)
+ - **example**: `"#ff00ff"`
+ - Defines the color of the placeholder widget used while the module loads.
+* `intent_filters`: **IntentFilter[]** *(optional)*
+ - **minimum `@version`**: 2
+ - **possible values**: JSON list of [IntentFilter](#IntentFilter)
+ - **example**: See [example](#example).
+ - A list of different Intent types this Module is able to handle. An action
+ dictates a semantic function this Module implements, as well as the role of
+ each of its parameters. When resolving an intent to a module, the intent
+ resolver uses an index of these intent filter lists to determine which
+ modules can handle an intent.
+
+### IntentFilter
+`IntentFilter` is a JSON object used to describe an intent type that a module is
+able to handle. The following describes the fields of the IntentFilter JSON
+object:
+
+* `action`: **string** *(required)*
+ - **minimum `@version`**: 2
+ - **possible values**: ASCII string
+ - The action this module is able to handle.
+* `parameters`: **ParameterConstraint[]** *(required)*
+ - **minimum `@version`**: 2
+ - **possible values**: JSON List of
+ [ParameterConstraint](#ParameterConstraint)
+ - Describes the names and types of the parameters required to execute the
+ specified action. Parameters are typically passed in as Entities.
+
+### ParameterConstraint
+`ParameterConstraint` describes a particular intent parameter's name, and it's
+acceptable type.
+
+* `name`: **string** *(required)*
+ - **minimum `@version`**: 2
+* `type`: **string** *(required)*
+ - **minimum `@version`**: 2
+ - Type that is valid for this parameter.
+
+See [example](#example).
+
+[component-manifest]: https://fuchsia.googlesource.com/docs/+/master/the-book/package_metadata.md#Component-manifest
