Add guidance for how to pass HTML to components

To see what led to this decision see:

- [an incident involving multiple components](#305)
- [a potential vulnerability with the govspeak component](#356).

docs/component_conventions.md

@@ -201,3 +201,73 @@ Code can be called and referred to in the template as follows:
 
 <%= card_helper.heading_tag %>
 ```
+
+## Passing HTML to a component
+We try avoid the risk of Cross Site Scripting (XSS) attacks, we can make sure to only sanitise HTML when the component is used, rather than doing so on the application's behalf.
+
+This means avoiding use of 'raw' or 'html_safe' within a component's view.
+
+There are a few methods to achieve this:
+
+### Single slots for nested children
+
+Similar to HTML, there may be a clear slot where nested children should appear in a component.
+
+For a panel component, you may expect anything nested within it to appear
+at the bottom of the component.
+
+Do not:
+
+```erb
+<%= render 'panel', content: "Your reference number<br><strong>HDJ2123F</strong>" %>
+```
+
+Do:
+
+```erb
+<%= render 'panel' do %>
+  Your reference number
+  <br>
+  <strong>HDJ2123F</strong>
+<% end %>
+```
+
+### Multiple slots
+
+If you have multiple slots where HTML may go, you could consider passing them as arguments.
+
+Note: If you can avoid a requirement for HTML this may be better. In the following example you may consider
+title: { level: 1, text: 'Application complete' }.
+
+Do not:
+
+```erb
+<%= render 'panel', { title: '<h1>Application complete</h1>' } do %>
+  Your reference number
+  <br>
+  <strong>HDJ2123F</strong>
+<% end %>
+```
+
+Do:
+
+```erb
+<% panelTitle = capture do %>
+  <h1>Application complete</h1>
+<% end %>
+<%= render 'panel', { title: panelTitle } do %>
+  Your reference number
+  <br>
+  <strong>HDJ2123F</strong>
+<% end %>
+```
+
+or (if the data is passed from a presenter / controller)
+
+```erb
+<%= render 'panel', { title: presentedPanelTitle.html_safe } do %>
+  Your reference number
+  <br>
+  <strong>HDJ2123F</strong>
+<% end %>
+```