The markup must be valid HTML5, except that a DOCTYPE, and opening <html> and <body> tags should be assumed (i.e. the markup should be a document body fragment which becomes a valid HTML5 document when enclosed in <html> and <body> tags).
Markup must also conform to the following XML rules:
Semantic markup must be used where native elements exist to describe the content:
<address><div class="address">The following elements must not be used:
<script><style><base><link><noscript><iframe> (except iframes may be added to the DOM by JavaScript)Elements and attributes which are deprecated in the HTML5 specification should not be used:
<applet>, <frameset>, <font>, <link rev="">, <td align="right">Elements that are normally singletons on a page must not be used in components:
<meta name="viewport" content="..." />.<meta charset="utf-8">.<title>, <html>, <head>, <body>.The following attributes must not be present on any element:
onclick, onchangeHREFs in markup must not use the javascript: protocol.
Attributes that are normally singletons on a page must not be used in components. This includes attributes defined by specifications external to the main HTML5 specification, such as Microdata and WAI-ARIA:
role="main" attribute.id attribute (except as below).The ID attribute must not be used, except where:
for attribute or is an unavoidable requirement of a third party library e.g. google ads.o-signin-username.Component authors are encouraged to provide assistive accessibility information in their component’s markup where appropriate. See WAI-ARIA Authoring Practices; keep in mind no ARIA is better than bad ARIA.
Conditional comments must not be used within components. To target styles for a specifc browser or feature set, see feature flags in the Sass specification.
“Owned DOM” is the DOM a component may act on with JavaScript or style with CSS.
A component may act on a DOM element using JavaScript if it, or any ancestor, has a data attribute containing the component’s name data-o-componentname. It must not act on other DOM, with two exceptions.
A component may style a DOM element with CSS if it, or any ancestor, has a class which starts with the name of the component o-componentname. It must not style other DOM.
As an example, the o-date component is permitted to style and apply JavaScript behaviour to the following element:
<time data-o-component="o-date" class="o-date" datetime="2000-06-14T23:00:00.000Z">June 15, 2000</time>
Component styles and behaviour may assume that any HTML markup follows the hierarchical structure specified in their documentation and demos. However, components should not make assumptions about the order of HTML elements, and should, as far as possible, cope with additional HTML elements not specified.
Markup may contain elements that do not work without accompanying JavaScript. To support a core and enhanced experience these elements must have a o--if-js class. They should be accompanied by an element with a class of o--if-no-js to offer feature fallback to users where the product developer opts not to run the JavaScript, or the user agent does not support it:
<div class="o--if-js">Submit a new comment: ... </div>
<div class="o--if-no-js">To comment on this article, you need to upgrade your web browser. <a href="...">Learn how to upgrade</a>.</div>
If the o--if-no-js element contains an image for the core experience only, a <noscript> tag should be used to avoid unnecessary HTTP requests:
<div class="o--if-no-js">
<noscript>
<img src="https://spoor-api.ft.com/px.gif?xxxxxx"/>
</noscript>
</div>
Origami components should not provide templates directly, outside of HTML within component demos and the readme. But where they do, templates must be in Mustache format. This is because product developers may choose to use any technology stack to built their application, and it’s important that they not be forced to choose a particular one in order to use Origami components.
Mustache templates may include references to other assets, whether they are data placeholders, other templates, or other components (all of which need to be resolved server-side), or static assets like images that might need to be resolved on the client. In many cases these references will need to be transformed by product developers in order to make templates useful, while other product developers may simply use templates as a guide to the markup they must write into their own code. Either way, templates must refer to external assets in a consistent way.
Partials included from the same repository must be referenced using a relative path, prefixed with a > and enclosed in double braces:
{{> ../partials/innerbox.mustache }}
Other Origami components must be referenced using the name of the component, enclosed in triple braces:
{{{ o-sign-in }}}
Static assets (such as images) included from the same repository must be referenced using a relative path:
<img src="../images/logo.png" alt="" />
Links to real URLs must be protocol-relative:
<a href="//www.google.com">Google</a>
Placeholders for the component’s data model must be referenced using a descriptive (lowercased and hyphened) keyword, prefixed with the name of the component and a dot:
{{ o-header.main-title }}
Double braces must be used for content that should have HTML entities escaped. Triple braces must be used for content which should be inserted without modification.