Origami Frontend Components & Services

Component Specification

Origami components are repositories containing front end code which can be used as part of a web page. Components are intended to be reusable UI patterns or functions; examples of good use-cases for components are:

Origami.json manifest

All Origami components must contain an origami.json file at the top of the repository’s directory structure. The origami.json manifest specification covers the contents of this file. In addition to the rules outlined in the manifest specification, Origami components must set the type property in the JSON to "module".

Naming conventions

Components must be named using a short descriptive term (hyphenated if necessary) and should be prefixed with o- (for Origami). The name must only contain lower-case letters and hyphens. This name must be used as the repository name, the name property in origami.json, and as a prefix for any default CSS class names.

If a component is not maintained by the Origami team, then it may be prefixed with a different letter than o-, E.g. n-button, g-audio. This practice is discouraged, it’s preferred that authors specify a support contact other than Origami in the component manifest.

Files and folder structure

Origami components must include the following files:

The rest of this section is non-normative.

A component’s folder structure may be organised as follows. The following is what the Origami team use for all of their supported components, but it’s not a requirement.

.
├── demos
│   └── src (containing Mustache files)
├── src
│   ├── js (containing JavaScript files)
│   └── scss (containing SCSS files)
├── test (containing JavaScript and Sass tests)
├── bower.json
├── README.md
├── main.js
├── main.scss
├── origami.json
└── package.json

Package management

Origami components must be installable through at least one package manager (individual package managers detailed below).

When a consumer attempts to use a component and finds that it is installable through a particular package manager, they should be able to assume that the same package manager can be used to install any Origami component.

Bower

Origami components must be installable through the Bower package manager, and should include a bower.json manifest file which configures the component. The component should not be published to the public Bower registry (through bower register or similar).

As well as following the bower.json spec, there are additional requirements to make the component’s Bower manifest conform to the Origami specification:

Bower ignored files

This section is non-normative.

The following is the list of ignored files in most component Bower configurations. This may be used as a starting point for new components:

"ignore": [
	"**/.*",
	"node_modules",
	"bower_components",
	"test",
	"build"
]

npm

Origami components may include a package.json manifest. As well as following the package.json spec, there are additional requirements to make the component’s npm manifest conform to the Origami specification:

Specifying dependencies

Components should have as few dependencies as possible. When a dependency is not required for use in production, it should be listed as a development dependency in whichever package manager you use.

Dependencies used in a component must be added explicitly to the package manager config. Components must not rely on code from sub-dependencies (see example).

When listing dependencies in your bower.json manifest, the SemVer range that you specify:

(See the example for clarification).

When an Origami component is a dependency of many other Origami components, it must verify and assert the widest version compatibility possible, including maintaining compatibility with earlier versions of a dependency unless to do so would be impractical. E.g. specifying a broad version range like "o-colors": ">=3.0.0 <5"

Source control

Origami component code must reside in a Git repository which has the same name as the component (see naming conventions). This repository must be stored remotely under one of the following GitHub organisations:

Component repositories should be public by default, however they may be private if there is a compelling reason, e.g. to comply with a font license in the case of o-fonts-assets.

Commit messages should describe the change that they introduce to a component.

Code

Markup

See the Origami Markup Specification.

Styles

Origami component styles are authored in Sass, specifically the SCSS syntax.

See the Origami Sass Specification.

Behaviour

See the Origami javascript specification.

Subresources

Origami components may load additional files (fonts, JSON data, images etc) from their own source. To do so safely, components must resolve file paths using the Origami assets module:

Without any explicit configuration, o-assets will assume, as we do for sub-resources in Sass, that the components are installed publicly at a URL path of /bower_components on the current host, and will form URLs on that basis. Product developers are advised to reconfigure o-assets to accommodate their own server-side URL routing architecture.

Where external resources are not within Origami components, a protocol-relative URL must be used (see issue 173.

Testing

Automated tests

Components should include automated tests which at least verify that the component can be built using Origami Build Tools.

A component author may additionally test their component however they like, providing that all test-related files should be in the test directory, and also ignored as outlined in Bower ignored files. A component may use Origami Build tools to run the tests for consistency:

npx origami-build-tools test

Linting

Component JavaScript and Sass source code should be linted. A component author may use Origami Build Tools to do this:

npx origami-build-tools verify

Continuous integration

Components should implement CI. If a component does so then it should verify that the component can be built using Origami Build Tools, as mentioned in Automated tests.

Browser/manual testing

All components must be tested with all the browsers listed in the FT browser support policy. If a component includes JavaScript, it must be error free in all the browsers that fall above the recommended minimum boundary for enhanced experience in that policy.

The versions tested should be listed in the component’s documentation, so that when boundary recommendations are changed, it is still possible to determine the support that was designed into an older component.

Documentation

Github Repo

If the repository is hosted on GitHub, the Github “Website” URL should be configured to be the component’s page in the Origami registry (e.g. “http://registry.origami.ft.com/components/o-grid”).

README

A component should include a README.md in the root of the component’s codebase. The README should:

The README should not include generic information (e.g. installation steps that apply equally to all components in general), but a link to such documentation may be included.

Migration

When a new major version of a component is released a migration guide should be written to help users upgrade from the previous release. The migration guide should be added to a MIGRATION.md file in the root of the component’s codebase, and should be linked to from the component’s README.md. See o-table’s migration guide as an example.

Codedocs

Component JavaScript should be documented using JSDoc and component Sass should be documented with SassDoc. This allows users to view and search the component’s public interface in the registry. For example, see o-grid’s SassDocs.

Browser support

All components must be tested with all the browsers listed in the FT browser support policy. If a component includes JavaScript, it must be error free in all the browsers which fall under the “enhanced experience” in that policy.

Demos

Component authors should provide component demos, which must be defined in origami.json and built with Origami Build Tools.

When deciding what demos to create, demos:

When building demos, they:

Where styles need to be added specifically for a demo (e.g. to make the content of o-grid containers visible), they must be attached to classes with a demo- prefix, for example:

.demo-cell {
  background-color: red;
}

Build Step

All components must be buildable by the Origami Build Service.

Component Lifecycle

Component Release

The first released version of a component must be v1.0.0. Versions lower than 1 are subject to different semver parsing logic, which is a nuance best avoided.

To ensure subsequent releases don’t affect the current users of a component:

Component Release Notice

When new versions of components are released, updates may be needed to other components and products that consume the component. The following notification rules apply:

Component Feature Deprecation

Component Deprecation

In the event of deprecating an Origami component, the following steps must be followed:

  1. Modify origami.json to change the supportStatus to deprecated.
  2. Change the README.md to have a paragraph at the top outlining the deprecation status. If it has been replaced, it must point to the new replacement component from the deprecated component.
  3. Disable the Issues functionality from the deprecated component’s repository, if the component is hosted on Github.
  4. Update the repository’s description to “deprecated - please use instead" if it has been replaced and change the URL to point towards the replacement's repository on GitHub.