Origami

Documentation site
Components

Origami manifests

All origami components, whether imagesets, modules or web services, should be discoverable by the Origami registry and provide information on how the component is supported. To do this, the component must contain an origami.json file in the root of its repository.

Format

origami.json is a JSON format file, with the following properties:

Property Type Description
{
  description string* A short (< 5 words, ideally) description of the purpose of the component
  origamiType string* The value 'imageset' where the component conforms to the imageset spec, 'module' where the component conforms to the module spec, or "service" where it conforms to the web service spec.
  origamiVersion integer* Version of Origami to which the component conforms. Currently must be set to 1.
  keywords string* Keywords related to the component to help discovery in the Registry. These should be stored as a comma separate string, i.e. "colours, palette, pink" for o-colors.
  origamiCategory string* The organisational category the module belongs to. Must be set to one of the following: "components", "primitives", "utilities", "layouts".
  support string*

Where a product developer can go for support on this component, normally the URL of the component's bug or issue tracker (e.g. a GitHub issues URL, or other issue tracker such as Redmine).

It's valid to use an email address in place of an issue tracker URL, but this is deprecated: use supportContact.email instead.
  supportStatus string*

Current support status of the component's major version. Set to one of:

  • 'active' (feature development ongoing, bug reports will be gratefully received and acted upon promptly)
  • 'maintained' (not actively developed but reproducible bugs will be fixed promptly and work done where necessary to maintain compatibility with browsers and other components)
  • 'deprecated' (not actively developed, not recommended for new projects, only the most disabling bugs will be addressed and only when time allows, but existing implementations may still work)
  • 'dead' (known to be broken, no plans to fix)
  • 'experimental' (the component is not ready for production use. This was previously called 'not implemented')
  supportContact { object

Contact details which a product developer can use to find support for this component. The owner(s) identified commit to the following obligations:

  • review code prior to a release
  • sign off deployments
  • publish and keep up to date release notes and documentation
  • move to decommission the component when appropriate
  • provide help and support to users of the component
    email string An email address that users can request support from. This email must group or role based, not a named individual.
    slack string A slack channel that users can go to for support. This must be in the format: organisation/channel-name. E.g. financialtimes/ft-origami
  },
  ci { object (optional) A set of one or more URLs where build validity information can be found
    circle string A CircleCI build status URL (https://circleci.com/api/v1/project/owner/repo)
    travis string A Travis CI build status URL (normally https://api.travis-ci.org/repos/owner/repo/builds.json)
    jenkins string A Jenkins build status URL
  },
  browserFeatures { object (optional) For modules only, a grouping object for browser features required or used by this module
    required array A list of features, as defined by Polyfill Service features (or, if the feature required is not there, which is most often the case for CSS features, as Modernizr tests), which the module will assume to exist, and may choose to rely on in its JavaScript code. If these features do not exist, the module may error.
    optional array A list of features, as defined by Polyfill Service features (or, if the feature required is not there, which is most often the case for CSS features, as Modernizr tests), which the module will use if they are available in the browser. The absense of the feature may result in the module offering different or reduced functionality, but it will be handled elegantly.
  }
  serviceUrl string (optional) For web services only, the URL on which the service is provided. Required for web services.
  demosDefaults: { object (optional) Default options to be applied to all demos.
      template string* The mustache template to render.
      sass string (optional) The Sass file to compile.
      js string (optional) The JS file to build with Browserify.
      data string (optional) Data to pass to the mustache template.
      documentClasses string (optional) CSS classes to set on the html tag.
      dependencies array (optional) List of strings of other modules that are only needed for one or more demos and will be loaded via the build service. They follow the same structure as how the build service works. (e.g.: "o-ft-icons@^2.3.1" or "o-ft-icons").
  }
  demos: [ array (optional) Array of individual demos.
    { object A config object to be applied for each demo (repeatable). Please check out the options in the modules component spec
      name string* Demo name which will be used as the name of the outputted html file.
      title string* A title for the demo which will appear when listed in the Registry.
      description string* Explanation of the purpose of the demo.
      hidden boolean (optional) Whether the demo should be hidden in the Registry.
      display_html boolean (optional) Whether the demo should have a HTML tab in the Registry (defaults to true).
      template string* The mustache template to render.
      sass string (optional) The Sass file to compile.
      js string (optional) The JS file to build with Browserify.
      data string (optional) Data to pass to the mustache template.
      documentClasses string (optional) CSS classes to set on the html tag.
      dependencies array (optional) List of strings of other modules that are needed for this demo and will be loaded via the build service.
    }
  ]
}

* Required property

Example

{
  "description": "Tables module",
  "origamiType": "module",
  "origamiVersion": 1,
  "keywords": "data, information, numbers",
  "origamiCategory": "component",
  "support": "developer@example.com",
  "supportStatus": "active",
  "browserFeatures": {
    "required": [
      "postmessage",
      "localstorage"
    ],
    "optional": [
      "webaudio"
    ]
  },
  "demosDefaults": {
  	"sass": "demos/src/demo.scss",
  	"js": "demos/src/demo.js"
  },
  "demos": [
  	{
		"name": "demo1",
		"description": "Basic module implementation",
		"template": "demos/src/demo1.mustache"
	},
  	{
		"name": "pa11y",
		"description": "Hidden test for pa11y",
		"hidden": true,
		"template": "demos/src/demo-pa11y.mustache"
  	}
  ],
  "ci": {
    "circle": "https://circleci.com/api/v1/project/Financial-Times/o-table"
  }
}