feat: the four cs documentation

src/docs/canvas/index.webc

@@ -0,0 +1,36 @@
+---
+layout: docs.webc
+title: Canvas
+description: A canvas represents a part of the page that content and controls sit within, they can provide padding and backgrounds for their content area.
+tags: ['docs', 'Four Cs']
+icon: canvas
+previous: /docs/controls/
+next: /docs/composition/
+---
+
+<template webc:type="11ty" 11ty:type="md">
+
+Canvases generally sit within a composition element to give them a layout context or they will flow outwards to fill the space.
+
+Canvases can provide padding for their content area, but should not generally dictate any other layout constraints.
+
+Typical examples of canvas components are: 
+
+- Card - a box, often presented with an image, title, text and a call to action
+- Navbar - a floating element at the top of the page, containing the logo and main navigation
+- Hero - the first element in the main content of the page, containing the title and intro
+
+<img
+  webc:is="eleventy-image"
+  src="./src/docs/canvas/canvas.webp"
+  alt="An example of UI with the canvas highlighted"
+/>
+
+<p class="codepen" data-height="300" data-theme-id="dark" data-default-tab="html,result" data-slug-hash="vYjypKv" data-pen-title="Canvas" data-preview="true" data-user="gavmck" style="height: 300px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;">
+  <span>See the Pen <a href="https://codepen.io/gavmck/pen/vYjypKv">
+  Canvas</a> by gavmck (<a href="https://codepen.io/gavmck">@gavmck</a>)
+  on <a href="https://codepen.io">CodePen</a>.</span>
+</p>
+<script async src="https://cpwebassets.codepen.io/assets/embed/ei.js" webc:keep></script>
+
+</template>

src/docs/composition/index.webc

@@ -0,0 +1,34 @@
+---
+layout: docs.webc
+title: Composition
+description: Compositions are an invisible element of the page that provides layout.
+tags: ['docs', 'Four Cs']
+icon: composition
+previous: /docs/canvas/
+next: /docs/the-realities/
+---
+
+<template webc:type="11ty" 11ty:type="md">
+
+Compositions are solely concerned with creating structure and spacing.
+
+Typical examples of a composition component are:
+
+- Grid - creates a layout with grid cells arranged in columns and rows
+- Spacing - creates spacing between components or areas of the page
+- Container - sets a max width for a page, block of content or components
+
+<img
+  webc:is="eleventy-image"
+  src="./src/docs/composition/composition.webp"
+  alt="An example of UI with the composition elements highlighted"
+/>
+
+<p class="codepen" data-height="300" data-theme-id="dark" data-default-tab="html,result" data-slug-hash="ExLNbbg" data-pen-title="Composition" data-preview="true" data-user="gavmck" style="height: 300px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;">
+  <span>See the Pen <a href="https://codepen.io/gavmck/pen/ExLNbbg">
+  Composition</a> by gavmck (<a href="https://codepen.io/gavmck">@gavmck</a>)
+  on <a href="https://codepen.io">CodePen</a>.</span>
+</p>
+<script async src="https://cpwebassets.codepen.io/assets/embed/ei.js" webc:keep></script>
+
+</template>

src/docs/content/index.webc

@@ -0,0 +1,35 @@
+---
+layout: docs.webc
+title: Content
+description: Content components look after the general styles for text and images, but can extend to data-specific patterns such as user profiles or product information.
+tags: ['docs', 'Four Cs']
+icon: content
+previous: /docs/the-solution/
+next: /docs/controls/
+---
+
+<template webc:type="11ty" 11ty:type="md">
+
+Content components are focused around text and images and the base level, but can extend into more specialised areas such as a person or a product. Content components are where the UI library can become more specialised towards the industry or product that the library is serving.
+
+Typical examples of content components are:
+
+- Heading - title elements, represented in HTML as h1-5
+- Text - a piece of typographic content
+- Icon - a glyph representing something in the app ecosystem
+- Person, ProductSummary, PaymentDetails - product/industry-specific content
+
+<img
+  webc:is="eleventy-image"
+  src="./src/docs/content/content.webp"
+  alt="An example of UI with content highlighted"
+/>
+
+<p class="codepen" data-height="300" data-theme-id="dark" data-default-tab="html,result" data-slug-hash="bGMBLgR" data-pen-title="Content" data-preview="true" data-user="gavmck" style="height: 300px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;">
+  <span>See the Pen <a href="https://codepen.io/gavmck/pen/bGMBLgR">
+  Content</a> by gavmck (<a href="https://codepen.io/gavmck">@gavmck</a>)
+  on <a href="https://codepen.io">CodePen</a>.</span>
+</p>
+<script async src="https://cpwebassets.codepen.io/assets/embed/ei.js" webc:keep></script>
+
+</template>

src/docs/controls/index.webc

@@ -0,0 +1,34 @@
+---
+layout: docs.webc
+title: Controls
+description: Controls are interactive elements of the page.
+tags: ['docs', 'Four Cs']
+icon: controls
+previous: /docs/content/
+next: /docs/canvas/
+---
+
+<template webc:type="11ty" 11ty:type="md">
+
+Anything that can be clicked, dragged, typed into or accessed in some way with the mouse, keyboard or touch is a control.
+
+Typical examples of controls are:
+
+- Button - a clickable component that triggers an action, such as submitting a form
+- Link - a hypertext link that takes the user to another page or section of the app
+- Input - a form input that allows users to enter information
+
+<img
+  webc:is="eleventy-image"
+  src="./src/docs/controls/controls.webp"
+  alt="An example of UI with controls highlighted"
+/>
+
+<p class="codepen" data-height="300" data-theme-id="dark" data-default-tab="html,result" data-slug-hash="NWMbyaw" data-pen-title="Controls" data-preview="true" data-user="gavmck" style="height: 300px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;">
+  <span>See the Pen <a href="https://codepen.io/gavmck/pen/NWMbyaw">
+  Controls</a> by gavmck (<a href="https://codepen.io/gavmck">@gavmck</a>)
+  on <a href="https://codepen.io">CodePen</a>.</span>
+</p>
+<script async src="https://cpwebassets.codepen.io/assets/embed/ei.js" webc:keep></script>
+
+</template>

src/docs/the-problem/index.webc

@@ -46,17 +46,17 @@ A little while later a new request comes in for a slightly different hero &ndash
   alt="The page hero with a yellow background"
 />
 
-Easy, you add a prop to the hero to control the background colour and another one to pass the new button variant to the CTA.
+Easy, you add a prop to the hero to control the background colour and another one to pass the new button variant to the button.
 
 It’s a couple more props, but it’s not too bad.
 
 ```html
 <page-hero
   title="Page title"
   intro="Lorem ipsum dolor [...etc]"
-  cta="Main action"
-  url="/page-slug"
-  cta-style="secondary"
+  button-text="Main action"
+  button-url="/page-slug"
+  button-style="secondary"
   theme="yellow"
 />
 ```
@@ -67,8 +67,8 @@ Over the months, more requirements come in and more props get added. Different t
 
 - Eyebrow text is added above the page title.
 - A second smaller paragraph gets added below the intro (this one has links in it too).
-- The Marketing team wanted a way to feature multiple CTAs of different types (sometimes they are buttons, sometimes links).
-- The SEO team decide the eyebrow needs to be the `h1` and the “page title” text actually needs to be a `p` for maximum search power.
+- The marketing team wanted a way to feature multiple buttons of different types (sometimes they are buttons, sometimes links).
+- The <abbr title="Search Engine Optimisation">SEO</abbr> team decide the eyebrow needs to be the `h1` and the “page title” text actually needs to be a `p` for maximum search power.
 
 <img
   webc:is="eleventy-image"
@@ -80,19 +80,19 @@ Over the months, more requirements come in and more props get added. Different t
 <page-hero
   title="Page title"
   intro="Lorem ipsum dolor [...etc]"
-  cta="Main action"
-  url="https://another.site/page-slug"
-  cta-target="_blank"
-  cta-rel="noopener noreferrer"
-  cta-style="secondary"
+  button-text="Main action"
+  button-url="https://another.site/page-slug"
+  button-target="_blank"
+  button-rel="noopener noreferrer"
+  button-style="secondary"
   theme="grey"
   eyebrow="Eyebrow text"
   eyebrow-tag="h1"
   title-tag="p"
-  secondary-cta="Secondary action"
-  secondary-cta-type="button"
-  secondary-cta-style="secondary"
-  on-secondary-cta-click="handleCtaClick()"
+  secondary-button="Secondary action"
+  secondary-button-type="button"
+  secondary-button-style="secondary"
+  on-secondary-button-click="handleButtonClick()"
 >
 	<p slot="secondary-text">
 		Suspendisse sed dictum dolor, at hendrerit nibh. Curabitur euismod 
@@ -103,7 +103,7 @@ Over the months, more requirements come in and more props get added. Different t
 
 This component is getting out of hand.
 
-It’s riddled with conditional statements and testing the different combinations of props gets increasingly awkward. We would have done better just writing this out with HTML!
+It’s riddled with conditional statements and testing the different combinations of props gets increasingly awkward. We would have done better just writing this out with <abbr>HTML</abbr>!
 
 There must be a better way!
 

src/layouts/docs.webc

@@ -37,7 +37,7 @@ layout: default.webc
 
       <d-separator class="diamond-spacing-bottom-xl"></d-separator>
 
-      <div @raw="content" class="diamond-spacing-bottom-xl"></div>
+      <div @raw="content" class="longform diamond-spacing-bottom-xl"></div>
 
       <diamond-grid>
         <diamond-grid-item small-mobile="6" webc:for="direction of ['previous', 'next']">

src/styles/util.css

@@ -25,4 +25,16 @@
 
 .text-title-case {
   text-transform: capitalize;
+}
+
+.longform {
+  img, pre[class*=language-], .cp_embed_wrapper {
+    margin-block: var(--diamond-spacing-lg);
+  }
+
+  img {
+    display: block;
+    width: 100%;
+    height: auto;
+  }
 }