Merge pull request #50 from jedgar1mx/issue.49

Issue.49

.storybook/CODTheme.js

@@ -0,0 +1,40 @@
+import { create } from '@storybook/theming';
+
+export default create({
+    base: 'light',
+
+    colorPrimary: 'white',
+    colorSecondary: '#004445',
+
+    // UI
+    appBg: 'white',
+    appContentBg: '#e6e6e6',
+    appBorderColor: '#004445',
+    appBorderRadius: 6,
+
+    // Typography
+    fontBase: '"Montserrat", sans-serif',
+    fontCode: '"Montserrat", monospace',
+
+    // Text colors
+    textColor: 'black',
+    textInverseColor: 'white',
+    textMutedColor: '#666666',
+
+    // Toolbar default and active colors
+    barTextColor: 'white',
+    barSelectedColor: '#9FD5B3',
+    barBg: '#004445',
+
+    // Form colors
+    inputBg: 'white',
+    inputBorder: '#004445',
+    inputTextColor: 'black',
+    inputBorderRadius: 4,
+
+    // Brand assets
+    brandTitle: 'City of Detroit',
+    brandUrl: 'https://detroitmi.gov',
+    brandImage: './city-of-detroit-logo-1.png',
+    brandTarget: '_self',
+});

.storybook/main.js

@@ -17,4 +17,5 @@ module.exports = {
   features: {
     interactionsDebugger: true,
   },
+  staticDirs: ['../public'],
 }

.storybook/manager-head.html

@@ -0,0 +1,4 @@
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Montserrat:wght@400;800&display=swap" rel="stylesheet">
+<link rel="shortcut icon" href="favicon.ico">

.storybook/manager.js

@@ -0,0 +1,6 @@
+import CODTheme from './CODTheme';
+import { addons } from '@storybook/addons';
+
+addons.setConfig({
+  theme: CODTheme,
+});

package.json

@@ -50,12 +50,14 @@
     "@storybook/addon-essentials": "^6.5.16",
     "@storybook/addon-interactions": "^6.5.16",
     "@storybook/addon-links": "^6.5.16",
+    "@storybook/addons": "^7.0.11",
     "@storybook/builder-webpack5": "^6.5.16",
     "@storybook/jest": "^0.0.10",
     "@storybook/manager-webpack5": "^6.5.16",
     "@storybook/storybook-deployer": "^2.8.16",
     "@storybook/test-runner": "^0.9.4",
     "@storybook/testing-library": "^0.0.13",
+    "@storybook/theming": "^7.0.11",
     "@storybook/web-components": "^6.5.16",
     "@svgr/webpack": "^5.5.0",
     "auto": "^10.43.0",

src/stories/Introduction.stories.mdx

@@ -8,7 +8,7 @@ import Plugin from './assets/plugin.svg';
 import Repo from './assets/repo.svg';
 import StackAlt from './assets/stackalt.svg';
 
-<Meta title="COD/Introduction" />
+<Meta title="COD UXDS/Introduction" />
 
 <style>
   {`
@@ -114,14 +114,24 @@ import StackAlt from './assets/stackalt.svg';
   `}
 </style>
 
-# Welcome to the City of Detroit Storybook
+<h1 class="text-center">City of Detroit Design System</h1>
 
-Storybook helps you build UI components in isolation from your app's business logic, data, and context.
-That makes it easy to develop hard-to-reach states. Save these UI states as **stories** to revisit during development, testing, or QA.
+This is the COD UXDS Storybook, a sandbox for demonstrating and developing components and patterns built for the City of Detroit UX Design System ("COD UXDS"). This demonstration is built using the open source tool Storybook using JavaScript and Node.js. All COD components are built using **ONLY JAVASCRIPT** to deliver standards-compliant web components. COD web components are platform-agnostic and can be used in any JavaScript framework of your choice or directly in the browser using static HTML.
 
-Browse example stories now by navigating to them in the sidebar.
-View their code in the `stories` directory to learn how they work.
-We recommend building UIs with a [**component-driven**](https://componentdriven.org) process starting with atomic components and ending with pages.
+**Why no framework?**
+* Frameworks can increase the learning curve due to specific syntax or particular methodologies dictated by the creators.
+* Support and maintenance are heavily influence by the developer community which can change often.
+
+In the Sidebar to the left, you can browse the components and patterns within COD. Each example will be demonstrated in what is called a "story" within the Canvas (the area of the window you're reading now). Across the top of the Canvas area, you will see a Docs tab, zoom controls, a color blindness simulator, and a light/dark theme toggle.
+
+* **Docs tab** - includes all of the developer documentation for each component, including guidelines and usage, the full API, any variants, and instructions for cherry picking.
+
+While viewing a component, to the right of the Canvas there is a tabbed Panel which displays Controls, any Action outputs associated with that demonstration, and an Accessibility audit:
+
+* **Control** - options allow you to change content in the demonstration area by altering the data given to the component via its properties.
+* **Actions** - provides console output where user actions like clicking or selecting should produce event target information.
+* **Accessibilty** - displays a11y violations of WCAG 2.0 Levels A and AA, WCAG 2.1 Level AA, Section 508, and other best practices through the aXe accessibilty engine.
+Display options and keyboard shortcuts are available via the Ellipsis Menu Icon next to the COD UXDS logo at the top of the sidebar.
 
 <div className="subheading">Configure</div>
 
@@ -189,7 +199,7 @@ We recommend building UIs with a [**component-driven**](https://componentdriven.
       Best practices from leading teams
     </span>
   </a>
-  <a className="link-item" href="https://github.com/storybookjs/storybook" target="_blank">
+  <a className="link-item" href="https://github.com/jedgar1mx/COD-Design-System" target="_blank">
     <img src={Code} alt="code" />
     <span>
       <strong>GitHub project</strong>

src/stories/Setup.stories.mdx

@@ -0,0 +1,58 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="COD UXDS/Setup" />
+
+<h1 class="text-center">Setup</h1>
+
+## Installation
+
+COD Web Components make use of Stencil's automatic lazy loader which only loads components that are actually used on the page.
+
+### CDN
+
+Add the following inside your head tag
+
+```html
+<script src="https://www.unpkg.com/browse/[email protected]/build/assets/js/main.js"></script>
+<script src="https://www.unpkg.com/browse/[email protected]/build/assets/js/runtime.js"></script>
+<script src="https://www.unpkg.com/browse/[email protected]/build/assets/js/vendors.babel.js"></script>
+<script src="https://www.unpkg.com/browse/[email protected]/build/assets/js/vendors.bootstrap-icons.js"></script>
+```
+
+### NPM
+
+`npm i @cityofdetroit/cod-design-system`
+
+### Yarn
+
+`yarn add @cityofdetroit/cod-design-system`
+
+```js
+  import 'cod-design-system/src/components/atoms/Loader/cod-loader';
+  import 'cod-design-system/src/components/atoms/Button/cod-button';
+```
+
+## Setting Props
+
+### Basic Data
+
+For basic primitive types like `string`, `boolean`, `number`, set the attribute on the element:
+
+```js
+<cod-loader data-color="color-1"></cod-loader>
+```
+
+## Using Slots
+
+Slots give you full control over the contents of a component. Some components may have multiple slots.
+
+> Web Component Concept:
+> Slotted content lives outside of the shadow DOM and as a result, you are free to style them however you want.
+
+
+```html
+<cod-breadcrumb>
+<li class="breadcrumb-item"><a href="#">Home</a></li>
+<li class="breadcrumb-item active" aria-current="page">Library</li>
+</cod-breadcrumb>
+```

src/stories/Styles.stories.mdx

@@ -0,0 +1,46 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title="COD UXDS/Customization" />
+
+# Customization
+
+If you're new to using Web Components, you'll quickly notice that the traditional way of styling elements with CSS doesn't work with COD components.
+
+For example, this won't work:
+```html
+<cod-button style="background:red;">button</cod-button>
+```
+
+This is a feature of the Shadow DOM--outside styles cannot be applied to content inside the Shadow DOM. Shadow DOM gives us a clean, native way
+of encapsulating styles and protects your applications from breaking changes. Luckily, the Shadow DOM API provides two solutions
+to this problem: CSS Custom Properties and CSS Shadow Parts.
+
+
+## Using CSS Custom Properties
+
+Each component API has a set of CSS Custom Properties defined. These are variables that you can set externally that will reflect inside the Shadow DOM.
+CSS Custom Properties are a lot like SASS variables, with one significant difference--they can be swapped at run time and do not require any build process.
+These CSS Custom Properties will usually be mapped to some CSS property (color, font-size, border-radius, etc).
+
+If you wanted to change the Button background, you could use the `--button-background-color` custom property like so:
+```css
+cod-button {
+  --button-background-color: red;
+}
+```
+
+## Using CSS Shadow Parts
+
+Because defining CSS Custom Properties for every possible CSS property is incredibly verbose and cumbersome, the recommended way for styling components is
+to make use of [CSS Shadow Parts](https://css-tricks.com/styling-in-the-shadow-dom-with-css-shadow-parts/). CSS Shadow Parts give you full control over
+the styling of a component's underlying Shadow DOM parts.
+
+If a component has any available Shadow Parts, they will be documented under their API section.
+
+To style a Shadow Part, use the [::part` pseudo-element](https://developer.mozilla.org/en-US/docs/Web/CSS/::part).
+For example, if you wanted to add some margin on the form label, you could style the `label` Shadow Part:
+```css
+cod-form-label::part(label) {
+  margin-right: 1rem;
+}
+```

src/stories/accordion.stories.js

@@ -5,7 +5,7 @@ import '../components/atoms/AccordionItem/cod-accordion-item';
 import '../components/molecules/Accordion/cod-accordion';
 
 export default {
-  title: 'COD/Molecules/Accordion',
+  title: 'Components/Molecules/Accordion',
 };
 
 export const Basic = () => html`

src/stories/alert.stories.js

@@ -1,7 +1,7 @@
 import '../components/atoms/Alert/cod-alert';
 
 export default {
-  title: 'COD/Atoms/Alert',
+  title: 'Components/Atoms/Alert',
   argTypes: {
     icon: {
         control: { type: 'select' },

src/stories/badge.stories.js

@@ -2,7 +2,7 @@ import { html } from 'lit-html';
 import '../components/atoms/Badge/cod-badge';
 
 export default {
-  title: 'COD/Atoms/Badge',
+  title: 'Components/Atoms/Badge',
   argTypes: {
     tag: {
         control: { type: 'select' },

src/stories/breadcrumb.stories.js

@@ -2,7 +2,7 @@ import { html } from 'lit-html';
 import '../components/atoms/Breadcrumb/cod-breadcrumb';
 
 export default {
-  title: 'COD/Atoms/Breadcrumb',
+  title: 'Components/Atoms/Breadcrumb',
 };
 
 export const Basic = () => html`

src/stories/button.stories.js

@@ -3,7 +3,7 @@ import { expect } from '@storybook/jest';
 import '../components/atoms/Button/cod-button';
 
 export default {
-  title: 'COD/Atoms/Button',
+  title: 'Components/Atoms/Button',
   argTypes: {
     primary: {
       control: { type: 'boolean'},

src/stories/buttongroup.stories.js

@@ -2,7 +2,7 @@ import { html } from 'lit-html';
 import '../components/molecules/ButtonGroup/cod-button-group';
 
 export default {
-  title: 'COD/Molecules/Forms/ButtonGroup',
+  title: 'Components/Molecules/ButtonGroup',
 };
 
 export const Basic = () => html`

src/stories/card.stories.js

@@ -6,7 +6,7 @@ import '../components/atoms/CardOverlay/cod-card-overlay';
 import '../components/organisms/Card/cod-card';
 
 export default {
-  title: 'COD/Organisms/Card',
+  title: 'Components/Organisms/Card',
 };
 
 export const Basic = () => html`

src/stories/carousel.stories.js

@@ -4,7 +4,7 @@ import '../components/atoms/CarouselCaption/cod-carousel-caption';
 import '../components/organisms/Carousel/cod-carousel';
 
 export default {
-  title: 'COD/Organisms/Carousel',
+  title: 'Components/Organisms/Carousel',
 };
 
 export const Basic = () => html`

src/stories/container.stories.js

@@ -1,7 +1,7 @@
 import '../components/atoms/Container/cod-container';
 
 export default {
-  title: 'COD/Atoms/Container',
+  title: 'Components/Atoms/Container',
   argTypes: {
     type: {
         control: { type: 'select' },

src/stories/dropdown.stories.js

@@ -3,7 +3,7 @@ import '../components/molecules/Dropdown/cod-dropdown';
 import '../components/atoms/DropdownMenu/cod-dropdown-menu';
 
 export default {
-  title: 'COD/Molecules/Dropdown',
+  title: 'Components/Molecules/Dropdown',
 };
 
 export const Basic = () => html`

src/stories/form.stories.js

@@ -1,7 +1,7 @@
 import '../components/organisms/Form/cod-form';
 
 export default {
-  title: 'COD/Organisms/FormValidation',
+  title: 'Forms/FormValidation',
   argTypes: {
     backgroundColor: { 
         control: { type: 'select' },

src/stories/formcheck.stories.js

@@ -1,7 +1,7 @@
 import '../components/atoms/FormCheck/cod-formcheck';
 
 export default {
-  title: 'COD/Atoms/Forms/FormCheck',
+  title: 'Forms/FormCheck',
   argTypes: {
     backgroundColor: { 
         control: { type: 'select' },

src/stories/formcheckgroup.stories.js

@@ -2,7 +2,7 @@ import { html } from 'lit-html';
 import '../components/molecules/FormCheckGroup/cod-form-check-group';
 
 export default {
-  title: 'COD/Molecules/Forms/FormCheckGroup',
+  title: 'Forms/FormCheckGroup',
 };
 
 export const RadioGroup = () => html`

src/stories/formcontrol.stories.js

@@ -1,7 +1,7 @@
 import '../components/atoms/FormControl/cod-formcontrol';
 
 export default {
-  title: 'COD/Atoms/Forms/FormControl',
+  title: 'Forms/FormControl',
   argTypes: {
     tag: {
         control: { type: 'select' },

src/stories/formlabel.stories.js

@@ -1,7 +1,7 @@
 import '../components/atoms/FormLabel/cod-formlabel';
 
 export default {
-  title: 'COD/Atoms/Forms/FormLabel',
+  title: 'Forms/FormLabel',
   argTypes: {
     required: { 
         control: { type: 'select' },

src/stories/formselect.stories.js

@@ -1,7 +1,7 @@
 import '../components/atoms/FormSelect/cod-formselect';
 
 export default {
-  title: 'COD/Atoms/Forms/FormSelect',
+  title: 'Forms/FormSelect',
   argTypes: {
     size: {
       control: { type: 'select' },

src/stories/geocoder.stories.js

@@ -2,7 +2,7 @@ import { html } from 'lit-html';
 import '../components/organisms/Geocoder/cod-geocoder';
 
 export default {
-    title: 'COD/Organisms/geocoder',
+    title: 'Components/Organisms/geocoder',
 };
 
 export const loaded = () => html`<cod-geocoder></cod-geocoder>`;