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:
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 origamiType property in the JSON to "module".
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 ASCII 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.
Origami components must include the following files:
main.js if the component has JavaScript functionalitymain.scss if the component has stylesorigami.json as outlined in Origami.json manifest aboveThe 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
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.
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 specification, there are additional requirements to make the component’s Bower manifest conform to the Origami specification:
name property set to the repository name, e.g. o-typographymain property set to an array which must:
main.js) if it existsmain.scss) if it existsdependencies property set to an object if the component has any Origami dependencies. Each key/value pair must:
ignore property set to an array, which must:
origami.json, README.md, and files required to build demosversion property. This is not needed and risks being out of sync with the repository’s git tagsdescription property set to a short description of the componentThis 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"
]Origami components may include a package.json manifest. As well as following the package.json specification, there are additional requirements to make the component’s npm manifest conform to the Origami specification:
bin, bugs, config, cpu, dependencies (as this would indicate that the manifest is required for consumption of the component), engines, engineStrict, files, main, os, preferGlobal, publishConfigversion propertydevDependencies property set to an object if the component has any npm dependencies required for development or testingprivate property set to trueComponents 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:
MINOR and PATCH to automatically update. This is normally achieved by using the caret (^) operator1.0.01.0.0-beta(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"
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.
See the Origami Markup Specification.
Origami component styles are authored in Sass, specifically the SCSS syntax.
See the Origami Sass Specification.
See the Origami javascript specification.
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.
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 testComponents 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.
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.
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”).
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.
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.
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.
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.
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;
}
All components must be buildable by the Origami Build Service.
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:
>=1.2.3 <3). If not, a major release is necessary.origami.json), make a major release.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:
deprecated. This way, it will be much easier to work with the new code while maintaining legacy code. It will also be easier to delete when making a major release.deprecated file or directory is not pragmatic, modified code must be appended and prepended with a comment which begins @deprecated, followed by text which describes the deprecation.type: breaking must be created as a reminder to remove deprecated code upon a future major release.In the event of deprecating an Origami component, the following steps must be followed:
supportStatus to deprecated.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.