docs: readme and landing page

.eslintrc.cjs

@@ -17,6 +17,8 @@ module.exports = {
           'color',
           'nowrap',
           'center',
+          'etc',
+          'flexbox',
         ],
       },
     ],

.storybook/preview.ts

@@ -1,4 +1,4 @@
 import type { Preview } from '@storybook/web-components'
 
 // Vite builder doesn't like the glob import in diamond-ui.css
 // importing the individual css files here instead.
@@ -9,6 +9,7 @@
 import '../styles/docs/docs.css';
 import './styles.css'; // Storybook style overrides
 
+import '../docs/components/Cell';
 import '../docs/components/Spacing';
 import '../docs/components/TokenTable';
 
@@ -21,11 +22,13 @@
       storySort: {
         order: [
           'Docs',
+          ['Get Started', 'Theming', 'Why no Sass?', 'Support'],
           'Showroom',
-          'Composition',
-          'Canvas',
+          'Foundations',
           'Content',
-          'Controls',
+          'Control',
+          'Canvas',
+          'Composition',
           'Recipes',
         ],
       },

README.md

@@ -1,5 +1,42 @@
 # Diamond UI
 
-[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=etchteam_diamond-ui&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=etchteam_diamond-ui)
-[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=etchteam_diamond-ui&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=etchteam_diamond-ui)
-[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=etchteam_diamond-ui&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=etchteam_diamond-ui)
+Diamond UI is a collection of design tokens, CSS, web components and [CSS web components](https://etch.co/blog/css-web-components) that can be used to scaffold out web projects.
+
+The components are built using the methodology from the [Diamond UI docs](https://diamond/etch.co). They are extremely light weight, using very little JavaScript or external dependencies. The components and CSS should be installable in any project or framework.
+
+## Install
+
+Install the package from npm.
+
+```shell
+npm i @etchteam/diamond-ui --save
+```
+
+Include the base CSS, either in JS or SCSS/CSS or HTML
+
+```scss
+@import '~@etchteam/diamond-ui/diamond-ui.css';
+```
+
+Components can be imported by importing the file, which will also give type completion.
+
+```js
+import '@etchteam/diamond-ui/composition/Grid/Grid';
+```
+
+And then used in HTML (or React, Vue, Angular, etc)
+
+```html
+<diamond-grid>
+  <diamond-grid-item>
+    Grid content
+  </diamond-grid-item>
+</diamond-grid>
+```
+
+## Configure
+
+Diamond comes with smart defaults for tokens, but these can all be overwritten by creating your own
+set of CSS tokens applied to `:root`. All the tokens are listed in the [token docs](https://diamond.etch.co/components?path=/docs/foundations-tokens-border--docs)
+
+Diamond supports custom theming, but in the interests of needing to override the least amount of base config, no production-ready themes are available out of the box. Full docs on creating themes which can be applied to components are available in the [theme docs](https://diamond.etch.co/components?path=/docs/docs-theming--docs).

components/canvas/Card/Card.stories.ts

@@ -1,4 +1,4 @@
 import { StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 
 import '../../composition/Grid/Grid';
@@ -23,7 +23,7 @@
         'sm',
         'md',
         'lg',
         'xl',
         'fluid-sm',
         'fluid',
         'fluid-lg',
@@ -31,9 +31,17 @@
       ],
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'The card component is a simple wrapper with a single slot and optional props for styling the card itself.',
+      },
+    },
+  },
 };
 
 export const Card: StoryObj = {
   render: ({ border, shadow, muted, radius, padding, theme }) => html`
     <diamond-card
       ?border="${border}"
@@ -63,7 +71,7 @@
   theme: 'light',
 };
 
 export const Interactive: StoryObj = {
   render: () => html`
     <diamond-grid wrap="wrap">
       <diamond-grid-item mobile="12" tablet="6">
@@ -101,7 +109,7 @@
   },
 };
 
 export const ImageCard: StoryObj = {
   render: () => html`
     <diamond-wrap size="sm">
       <diamond-card border radius shadow class="diamond-theme-light">

components/composition/Enter/Enter.stories.ts

@@ -1,4 +1,4 @@
 import { StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 
 import './Enter';
@@ -13,9 +13,17 @@
       options: ['fade', 'fade-in-up', 'boing'],
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'The enter component can be wrapped around content to animate it into view.',
+      },
+    },
+  },
 };
 
 export const Enter: StoryObj = {
   render: (args) => html`
     <diamond-enter
       type="${args.type}"

components/composition/FormGroup/FormGroup.stories.ts

@@ -16,6 +16,14 @@ export default {
       options: ['horizontal', 'vertical'],
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'The form group component is a wrapper for grouping form elements with a label and optional help text.',
+      },
+    },
+  },
 };
 
 export const FormGroup: StoryObj = {
@@ -74,7 +82,7 @@ export const FormGroupValidationError: StoryObj = {
   render: (args) => html`
     <diamond-form-group orientation="${args.orientation}">
       <label for="name">Form group label</label>
-      <diamond-help-text state="error">Error message</diamond-help-text>
+      <diamond-help-text state="invalid">Error message</diamond-help-text>
       <diamond-input state="invalid">
         <input id="name" type="text" />
       </diamond-input>

components/composition/Grid/Grid.stories.ts

@@ -4,6 +4,11 @@ import { html } from 'lit';
 import './Grid';
 import './GridItem';
 
+const description = `
+The grid and grid item components are used to create a grid layout by exposing
+the most commonly used flexbox properties as attributes.
+`;
+
 export default {
   component: 'diamond-grid',
   argTypes: {
@@ -45,6 +50,13 @@ export default {
       options: ['xs', 'sm', 'md', 'lg', 'xl'],
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        component: description,
+      },
+    },
+  },
 };
 
 export const Grid: StoryObj = {
@@ -67,11 +79,7 @@ export const Grid: StoryObj = {
       ${[...Array(12).keys()].map(
         (i) => html`
           <diamond-grid-item grow shrink>
-            <div
-              style="height: 100px; background-color: #eee; display: flex; align-items: center; justify-content: center;"
-            >
-              ${i + 1}
-            </div>
+            <docs-cell>${i + 1}</docs-cell>
           </diamond-grid-item>
         `,
       )}
@@ -87,3 +95,124 @@ Grid.args = {
   gap: 'md',
   inline: false,
 };
+
+export const StretchOneSide = () => `
+  <diamond-grid>
+    <diamond-grid-item grow shrink>
+      <docs-cell>Grow</docs-cell>
+    </diamond-grid-item>
+    <diamond-grid-item>
+      <docs-cell>Fixed</docs-cell>
+    </diamond-grid-item>
+  </diamond-grid>
+  <diamond-spacing bottom="sm"></diamond-spacing>
+  <diamond-grid>
+    <diamond-grid-item>
+      <docs-cell>Fixed</docs-cell>
+    </diamond-grid-item>
+    <diamond-grid-item grow shrink>
+      <docs-cell>Grow</docs-cell>
+    </diamond-grid-item>
+  </diamond-grid>
+`;
+
+export const PushApart = () => `
+  <diamond-grid justify-content="space-between">
+    <diamond-grid-item>
+      <docs-cell>Left</docs-cell>
+    </diamond-grid-item>
+    <diamond-grid-item>
+      <docs-cell>Right</docs-cell>
+    </diamond-grid-item>
+  </diamond-grid>
+`;
+
+export const Centered = () => `
+  <diamond-grid justify-content="center">
+    <diamond-grid-item>
+      <docs-cell>Centered</docs-cell>
+    </diamond-grid-item>
+    <diamond-grid-item>
+      <docs-cell>Centered</docs-cell>
+    </diamond-grid-item>
+    <diamond-grid-item>
+      <docs-cell>Centered</docs-cell>
+    </diamond-grid-item>
+  </diamond-grid>
+`;
+
+export const ResponsiveColumns = () => `
+  <diamond-grid wrap="wrap">
+    <diamond-grid-item mobile="12" tablet="6" desktop="3">
+      <docs-cell>Cell</docs-cell>
+    </diamond-grid-item>
+    <diamond-grid-item mobile="12" tablet="6" desktop="3">
+      <docs-cell>Cell</docs-cell>
+    </diamond-grid-item>
+    <diamond-grid-item mobile="12" tablet="6" desktop="3">
+      <docs-cell>Cell</docs-cell>
+    </diamond-grid-item>
+    <diamond-grid-item mobile="12" tablet="6" desktop="3">
+      <docs-cell>Cell</docs-cell>
+    </diamond-grid-item>
+  </diamond-grid>
+`;
+
+const responsiveColumnsDescription = `
+Changes from 1-4 columns through mobile-desktop
+`;
+
+ResponsiveColumns.parameters = {
+  docs: {
+    description: {
+      story: responsiveColumnsDescription,
+    },
+  },
+};
+
+export const MobileCTA = () => `
+  <diamond-wrap gutter="none" size="md">
+    <diamond-grid wrap="wrap" direction="row-reverse">
+      <diamond-grid-item mobile="12" tablet="3">
+        <diamond-button variant="primary" width="full-width">
+          <button type="button">Continue</button>
+        </diamond-button>
+      </diamond-grid-item>
+      <diamond-grid-item mobile="12" tablet="3">
+        <diamond-button width="full-width">
+          <button type="button">Cancel</button>
+        </diamond-button>
+      </diamond-grid-item>
+    </diamond-grid>
+  </diamond-wrap>
+`;
+
+const mobileCTADescription = `
+This grid uses direction and justify to put the buttons in the right
+order on mobile and desktop, with primary top on mobile and right on desktop.
+`;
+
+MobileCTA.parameters = {
+  docs: {
+    description: {
+      story: mobileCTADescription,
+    },
+  },
+};
+
+export const VerticalCenterContent = () => `
+  <diamond-wrap gutter="none" size="sm">
+    <diamond-grid align-items="center">
+      <diamond-grid-item grow shrink>
+        <p>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas
+          ut justo in velit euismod ultricies id sit amet diam. Vivamus convallis
+          molestie urna.
+        </p>
+      </diamond-grid-item>
+      <diamond-grid-item>
+        <img src="https://placehold.co/200x150" alt="Placeholder image" width="200" height="150" />
+      </diamond-grid-item>
+    </diamond-grid>
+  </diamond-wrap>
+`;

components/composition/InputButtonGroup/InputButtonGroup.stories.ts

@@ -6,8 +6,7 @@ export default {
   parameters: {
     docs: {
       description: {
-        component:
-          'This composition allows for an input control to be paired with a button, handling scaling and alignment of both elements.',
+        component: 'Groups an input and button together as one unit.',
       },
     },
   },

components/content/HelpText/HelpText.stories.ts

@@ -10,7 +10,7 @@ export default {
     docs: {
       description: {
         component:
-          'A piece of text to provide additional information or context for form inputs, including form validation messages.',
+          'A piece of text to provide additional information or context for form inputs, including [form validation messages](?path=/docs/composition-formgroup--docs).',
       },
     },
   },

components/content/Img/Img.stories.ts

@@ -3,6 +3,11 @@ import { html } from 'lit';
 
 import './Img';
 
+const description = `
+The image component wraps an img tag to provide some common image controls,
+such as making it responsive or fitting a specific aspect ratio.
+`;
+
 export default {
   component: 'diamond-img',
   argTypes: {
@@ -13,6 +18,13 @@ export default {
       options: ['fill', 'cover', 'contain'],
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        component: description,
+      },
+    },
+  },
 };
 
 export const Img: StoryObj = {

components/content/List/List.stories.ts

@@ -4,6 +4,10 @@ import { html } from 'lit';
 import '../Icon/Icon';
 import './List';
 
+const description = `
+The list component adds a bit more power to HTML lists, such as spacing control and icon support.
+`;
+
 export default {
   component: 'diamond-list',
   argTypes: {
@@ -30,6 +34,13 @@ export default {
       ],
     },
   },
+  parameters: {
+    docs: {
+      description: {
+        component: description,
+      },
+    },
+  },
 };
 
 export const List: StoryObj = {

components/content/LoadingButton/LoadingButton.stories.ts

@@ -5,6 +5,14 @@ import './LoadingButton';
 
 export default {
   component: 'diamond-loading-button',
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Used as a loading placeholder before the content is available. For a full demo, see the [loading recipe](?path=/docs/recipes-loading-skeleton--docs).',
+      },
+    },
+  },
 };
 
 export const LoadingButton: StoryObj = {

components/content/LoadingImg/LoadingImg.stories.ts

@@ -5,6 +5,14 @@ import './LoadingImg';
 
 export default {
   component: 'diamond-loading-img',
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Used as a loading placeholder before the content is available. For a full demo, see the [loading recipe](?path=/docs/recipes-loading-skeleton--docs).',
+      },
+    },
+  },
 };
 
 export const LoadingImg: StoryObj = {