Material Motion Exploring solutions that will empower creators with the tools needed to describe and implement rich, interactive motion on any platform. Edit this page · History

Writing specs

Engineering specifications are the means by which we discuss and ratify what we’d like to build across all of our supported platforms. All specs have a consistent shape and are expected to evolve over time.

General guidelines

Purpose: To provide a checklist for an engineer to validate their implementation against.

Shape: Specs start with an overview of the topic and then a broken-down minimum-viable product (MVP) specification. Each part of the MVP specification should be as small as possible, and no smaller.

Order of information: The spec should be readable in a top-down fashion.

Audience: The audience is expected to be highly technical, with a strong understanding of types, object oriented programming, and functional programming.

Build it first: If you are writing a spec you ideally already have a working implementation in your language of choice. Do not paste this implementation into the spec verbatim. Your role as spec writer is to break the implementation apart into a checklist. Another engineer - potentially thinking in a language different from your own - can then follow this checklist.

Language-agnostic: Avoid use of language-specific features where possible. If a language-specific feature is necessary, explain why. Examples of language-specific features include:

  • Function short-hand (() => () in JavaScript, $0 notation in swift).
  • Named arguments (Objective-C and swift).
  • Protocol extensions (swift).

Features we expect to be available in all of our supported languages:

  • Compile-time type enforcement.
  • Generics.
  • Objects.

Conformance: Specs do not need to be 100% byte-for-byte accurate. The goal is to communicate the intent and shape of the topic, not its literal implementation.

Features: Identify non-MVP features and break them apart into separate feature specifications. A feature specification can build off of an MVP in a parallel fashion. Feature specifications live in a separate file from their MVP. E.g. for topic.md, a feature might live in topic-feature.md. Feature specs have similar shapes to MVP specs.

Shape of a spec

Presented below is the outline of an engineering specification. We discuss each section in more detail further below.

---
key: value
key: value
...
---

# <topic> specification

This is the engineering specification for the `<topic>`.

## Overview

A high-level overview of the topic. Discuss new concepts where relevant.

## Examples

An optional set of examples showing use of the topic.

## MVP

### Specific thing to build

And how to build it.

YAML preamble

All specs start with a yaml preamble. This preamble includes relevant metadata.

Layout

layout: page

Status

Indicates the current status of the page.

Date must be long-form Month day, year format.

Status can be any of Draft, Experimental, or Stable.

status:
  date: December 13, 2016
  is: Draft

Knowledge level

Defines the expected end-user knowledge level for this topic.

There are four knowledge levels: L1-L4.

knowledgelevel: L2

Library

The library this API should live within.

All library names are lower-cased and hyphenated.

library: streams

Dependencies

A list of absolute paths to other starmap files.

A dependency is a spec that must be built before this spec can be built.

depends_on:
  - /starmap/specifications/primitives/gesture_recognizers/GestureRecognizer
  - /starmap/specifications/streams/operators/foundation/$._map

Stream type

Operators should define their expected input and output types.

streamtype:
  in: GestureRecognizer
  out: Point

Availability

Link to the platform’s source and tests, when available.

We use the following platform names: Android, iOS, and JavaScript.

availability:
  - platform:
    name: <platform name>
    url: <source url>
    tests_url: <tests url>
  - platform:
    name: <platform name>
    url: <source url>
    tests_url: <tests url>