docs: new design system example/tutorial (microsoft#5186)

* docs: new design system example/tutorial * fixing linting error * address tree-shaking comment * update readme to use yarn * move styles to css file * adding comment * fix recipe not working * update yarn.lock * make project a workspace * remove fluent references * fix card recipe * fixing up demo w/ changes Co-authored-by: nicholasrice <nicholasrice@users.noreply.github.com> Co-authored-by: Nicholas Rice <3213292+nicholasrice@users.noreply.github.com>
albertsadday · Sep 27, 2021 · 77f4553 · 77f4553
1 parent 2d07b6a
commit 77f4553
Show file tree

Hide file tree

Showing 16 changed files with 857 additions and 64 deletions.
diff --git a/examples/design-system-tutorial/README.md b/examples/design-system-tutorial/README.md
@@ -0,0 +1,11 @@
+# Design System Tutorial
+
+A heavily-commented demo of using FAST's Adaptive UI Design System and Design Tokens.
+
+## Setup
+
+`yarn install`
+
+## Run
+
+`yarn start`
diff --git a/examples/design-system-tutorial/index.html b/examples/design-system-tutorial/index.html
@@ -0,0 +1,174 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <title>Design System Tutorial</title>
+        <link href="styles.css" rel="stylesheet" />
+    </head>
+    <body>
+        <div id="root">
+            <demo-navigation>
+                <fast-tree-view>
+                    <fast-tree-item selected>My Feed</fast-tree-item>
+                    <fast-tree-item>Microsoft</fast-tree-item>
+                    <fast-tree-item>Information Technology</fast-tree-item>
+                    <fast-tree-item>Business News</fast-tree-item>
+                    <fast-tree-item>Seattle / Tacoma</fast-tree-item>
+                    <fast-tree-item>Money</fast-tree-item>
+                    <fast-tree-item>News</fast-tree-item>
+                    <fast-tree-item>Markets</fast-tree-item>
+                </fast-tree-view>
+            </demo-navigation>
+            <div class="canvas">
+                <div class="container">
+                    <fast-demo-card>
+                        <h2 slot="heading">We're not ready for another pandemic</h2>
+                        <fast-attribution slot="attribution">
+                            The Atlantic
+                            <img
+                                src="//img-s-msn-com.akamaized.net/tenant/amp/entityid/BBY4G4r?w=16&h=16&q=100&m=6&f=png&u=t"
+                                alt="The Atlantic"
+                                slot="icon"
+                            />
+                        </fast-attribution>
+                        <img
+                            src="https://www.bing.com/th?id=ORMS.bbec3ae474a1dbbf78c519c6d136c959&pid=Wdp&w=300&h=225&qlt=60&c=1&rs=1"
+                            alt=""
+                            slot="feature-media"
+                        />
+                    </fast-demo-card>
+                    <fast-demo-card>
+                        <h2 slot="heading">
+                            'Birds Aren't Real' Followers Flock to Missouri, Claim Birds
+                            Are Government Drones
+                        </h2>
+                        <fast-attribution slot="attribution">
+                            Newsweek
+                            <img
+                                src="//img-s-msn-com.akamaized.net/tenant/amp/entityid/AA38A54?w=16&h=16&q=100&m=6&f=png&u=t"
+                                alt="Newsweek"
+                                slot="icon"
+                            />
+                        </fast-attribution>
+                        <img
+                            src="https://www.bing.com/th?id=ORMS.527ca29d9437fa2fc050df9b594e4886&pid=Wdp&w=300&h=225&qlt=60&c=1&rs=1"
+                            alt=""
+                            slot="feature-media"
+                        />
+                    </fast-demo-card>
+                    <fast-demo-card>
+                        <h2 slot="heading">
+                            How a couple built their tiny house on wheels
+                        </h2>
+                        <fast-attribution slot="attribution">
+                            Lovemoney
+                            <img
+                                src="//img-s-msn-com.akamaized.net/tenant/amp/entityid/AA3HAHV?w=16&h=16&q=100&m=6&f=png&u=t"
+                                alt="Lovemoney"
+                                slot="icon"
+                            />
+                        </fast-attribution>
+                        <img
+                            src="https://www.bing.com/th?id=ORMS.5fcd6baf40ea0d78ca6679d0596ad88e&pid=Wdp&w=300&h=225&qlt=60&c=1&rs=1"
+                            alt=""
+                            slot="feature-media"
+                        />
+                    </fast-demo-card>
+                    <fast-demo-card>
+                        <h2 slot="heading">
+                            NASA: Mystery of subsurface lakes under Mars south pole
+                            deepens
+                        </h2>
+                        <fast-attribution slot="attribution">
+                            CNET
+                            <img
+                                src="//img-s-msn-com.akamaized.net/tenant/amp/entityid/BB17VHmX?w=16&h=16&q=100&m=6&f=png&u=t"
+                                alt="CNET"
+                                slot="icon"
+                            />
+                        </fast-attribution>
+                        <img
+                            src="https://www.bing.com/th?id=ORMS.d209a08b72c080784bf8155992699eb0&pid=Wdp&w=300&h=225&qlt=60&c=1&rs=1"
+                            alt=""
+                            slot="feature-media"
+                        />
+                    </fast-demo-card>
+                </div>
+                <div class="container">
+                    <fast-demo-card>
+                        <h2 slot="heading">
+                            If You Can Walk This Far, You May Live Longer, Says Science
+                        </h2>
+                        <fast-attribution slot="attribution">
+                            ETNT Mind+Body
+                            <img
+                                src="//img-s-msn-com.akamaized.net/tenant/amp/entityid/BB1gzZE3?w=16&h=16&q=100&m=6&f=png&u=t"
+                                alt="ETNT Mind+Body"
+                                slot="icon"
+                            />
+                        </fast-attribution>
+                        <img
+                            src="https://www.bing.com/th?id=ORMS.667bd5eda32e1e56b25a714a46deec10&pid=Wdp&w=300&h=225&qlt=60&c=1&rs=1"
+                            alt=""
+                            slot="feature-media"
+                        />
+                    </fast-demo-card>
+                    <fast-demo-card>
+                        <h2 slot="heading">Pond Weed Identification: What to Know</h2>
+                        <fast-attribution slot="attribution">
+                            The Family Handyman
+                            <img
+                                src="//img-s-msn-com.akamaized.net/tenant/amp/entityid/BBtOBsY?w=16&h=16&q=100&m=6&f=png&u=t"
+                                alt="The Family Handyman"
+                                slot="icon"
+                            />
+                        </fast-attribution>
+                        <img
+                            src="https://www.bing.com/th?id=ORMS.b26a2184225d0b0237fbac43989019e9&pid=Wdp&w=300&h=225&qlt=60&c=1&rs=1"
+                            alt=""
+                            slot="feature-media"
+                        />
+                    </fast-demo-card>
+                    <fast-demo-card>
+                        <h2 slot="heading">
+                            Man arrested for stealing boat from Seattle, claimed
+                            explosives were on board
+                        </h2>
+                        <fast-attribution slot="attribution">
+                            KOMO-TV Seattle
+                            <img
+                                src="//img-s-msn-com.akamaized.net/tenant/amp/entityid/BB127ztF?w=16&h=16&q=100&m=6&f=png&u=t"
+                                alt="KOMO-TV Seattle"
+                                slot="icon"
+                            />
+                        </fast-attribution>
+                        <img
+                            src="https://www.bing.com/th?id=ORMS.885b00fba36834ed6306a17fe738e30a&pid=Wdp&w=300&h=225&qlt=60&c=1&rs=1"
+                            alt=""
+                            slot="feature-media"
+                        />
+                    </fast-demo-card>
+                    <fast-demo-card>
+                        <h2 slot="heading">
+                            Canada Goose to Stop Using Animal Fur in Products
+                        </h2>
+                        <fast-attribution slot="attribution">
+                            TheStreet
+                            <img
+                                src="//img-s-msn-com.akamaized.net/tenant/amp/entityid/AA42cl9?w=16&h=16&q=100&m=6&f=png&u=t"
+                                alt="The Street"
+                                slot="icon"
+                            />
+                        </fast-attribution>
+                        <img
+                            src="https://www.bing.com/th?id=ORMS.ad780fca80d9d18a638f0f99a87c9da8&pid=Wdp&w=300&h=225&qlt=60&c=1&rs=1"
+                            alt=""
+                            slot="feature-media"
+                        />
+                    </fast-demo-card>
+                </div>
+            </div>
+        </div>
+        <script src="dist/bundle.js"></script>
+    </body>
+</html>
diff --git a/examples/design-system-tutorial/package.json b/examples/design-system-tutorial/package.json
@@ -0,0 +1,30 @@
+{
+  "name": "fast-design-system-demo",
+  "version": "1.0.0",
+  "description": "A heavily-commented demo of using FAST's Adaptive UI Design System and Design Tokens.",
+  "main": "index.js",
+  "private": true,
+  "scripts": {
+    "build": "rimraf dist && webpack --config webpack.config.js --mode=production",
+    "start": "webpack-dev-server"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@microsoft/fast-colors": "^5.1.3",
+    "@microsoft/fast-element": "^1.5.1",
+    "@microsoft/fast-foundation": "^2.16.1",
+    "@microsoft/fast-components": "^2.11.3",
+    "lodash-es": "4.17.15",
+    "tslib": "^1.11.1"
+  },
+  "devDependencies": {
+    "http-server": "^0.12.1",
+    "rimraf": "^3.0.2",
+    "ts-loader": "^7.0.1",
+    "typescript": "^3.8.3",
+    "webpack": "^4.44.0",
+    "webpack-cli": "^3.3.11",
+    "webpack-dev-server": "^3.11.0"
+  }
+}
diff --git a/examples/design-system-tutorial/src/components/attribution.ts b/examples/design-system-tutorial/src/components/attribution.ts
@@ -0,0 +1,38 @@
+import { designUnit, neutralForegroundHint } from "@microsoft/fast-components";
+import { css, html } from "@microsoft/fast-element";
+import { display, FoundationElement } from "@microsoft/fast-foundation";
+
+/**
+ * The Fluent UI Web Components don't have an "attribution" component built-in.
+ * The code below shows how you can build your own. Basing it on FoundationElement and
+ * using the FoundationElement.compose API, you can create a brand new component that
+ * has all the features and integrates into Design System registration in the same way as
+ * our official Fluent UI components. Notice also how the styles leverage the design tokens
+ * and style helpers provided by the existing Fluent UI Web Components.
+ *
+ * Since this is a simple component, we've chosen to keep all of its source in
+ * this single file. For an example of how to organize code for a more complex component,
+ * take a look in the card folder.
+ *
+ * Additionally, because this component has no behavior of its own, but simply provides
+ * an easy to re-use block of HTML with associated styles, we do not need to create a
+ * unique class. Calling FoundationElement.compose directly will handle that for us when
+ * it defines the web component with the platform.
+ */
+
+export const fastAttribution = FoundationElement.compose({
+    baseName: "attribution",
+    template: html`
+        <slot name="icon"></slot>
+        <slot></slot>
+    `,
+    styles: css`
+        ${display("flex")} ::slotted (*) {
+            margin: 0 calc(${designUnit} * 1px);
+        }
+
+        :host {
+            color: ${neutralForegroundHint};
+        }
+    `,
+});
diff --git a/examples/design-system-tutorial/src/components/card/card.styles.ts b/examples/design-system-tutorial/src/components/card/card.styles.ts
@@ -0,0 +1,78 @@
+import {
+    controlCornerRadius,
+    designUnit,
+    fillColor,
+    neutralForegroundRest,
+    typeRampMinus1FontSize,
+    typeRampMinus1LineHeight,
+    typeRampPlus1FontSize,
+    typeRampPlus1LineHeight,
+} from "@microsoft/fast-components";
+import { css } from "@microsoft/fast-element";
+import { DesignToken, display } from "@microsoft/fast-foundation";
+
+/**
+ * Not only can we have system-wide design tokens, but we can
+ * have component-specific tokens as well. This token enables
+ * changing the corner radius of cards independently of other controls.
+ */
+export const cardPadding = DesignToken.create<number>("card-padding").withDefault(
+    (el: HTMLElement) => designUnit.getValueFor(el) * 2
+);
+
+export const demoCardStyles = css`
+    ${display("grid")} :host {
+        --elevation: 4;
+        grid-template-rows: calc(${designUnit} * 39px) 1fr auto calc(${designUnit} * 2px);
+        background-color: ${fillColor};
+        width: calc(${designUnit} * 75px);
+        height: calc(${designUnit} * 76px);
+        border-radius: calc(${controlCornerRadius} * 1px);
+        contain: content;
+        margin: calc(${designUnit} * 2px);
+        box-shadow: 0 0 calc((var(--elevation) * 0.225px) + 2px)
+                rgba(0, 0, 0, calc(0.11 * (2))),
+            0 calc(var(--elevation) * 0.4px) calc((var(--elevation) * 0.9px))
+                rgba(0, 0, 0, calc(0.13));
+    }
+
+    .feature-image {
+        overflow: hidden;
+    }
+
+    .feature-image ::slotted(img) {
+        place-self: stretch;
+        width: 100%;
+        position: relative;
+        top: 50%;
+        transform: translateY(-50%);
+    }
+
+    .content,
+    .footer {
+        padding: 0 calc(${cardPadding} * 1px);
+    }
+
+    slot[name="heading"]::slotted(*) {
+        color: ${neutralForegroundRest};
+        font-size: ${typeRampPlus1FontSize};
+        line-height: ${typeRampPlus1LineHeight};
+        font-weight: 400;
+        overflow: hidden;
+        max-height: calc(${typeRampPlus1LineHeight} * 2);
+    }
+
+    fast-button::part(control) {
+        transition: padding 0.2s ease-in-out;
+    }
+
+    fast-button:not(:hover)::part(control) {
+        padding: 0;
+    }
+
+    ::slotted(fast-attribution) {
+        margin-top: calc(${designUnit} * 2px);
+        font-size: ${typeRampMinus1FontSize};
+        line-height: ${typeRampMinus1LineHeight};
+    }
+`;
diff --git a/examples/design-system-tutorial/src/components/card/card.template.ts b/examples/design-system-tutorial/src/components/card/card.template.ts
@@ -0,0 +1,46 @@
+import { html, ViewTemplate } from "@microsoft/fast-element";
+import {
+    Button,
+    ElementDefinitionContext,
+    OverrideFoundationElementDefinition,
+} from "@microsoft/fast-foundation";
+import type { DemoCard, DemoCardDefinitionOptions } from "./card";
+
+/**
+ * When creating components with FoundationElement.compose, the component definition
+ * can provide either a template or a function that creates a template (shown below).
+ * If a function is provided then the design system will provide the template function
+ * with contextual information related to the design system, as well as the definition
+ * configuration object provided by combining the base configuration with any customization
+ * options provided by the developer. Together, these inputs enable customizing the template
+ * for the component itself.
+ *
+ * Below, the context.tagFor helper is used to enable this card to be reusable with any
+ * design system based Foundation Button. This could be fluent-button, fast-button, or
+ * any custom button configured with the design system.
+ *
+ * Additionally, the definition object is used to allow the developer to specify custom
+ * "like-button" slotted content. If supplied this will be used across all instances of this card,
+ * overriding what was originally built-in.
+ */
+export const template = (
+    context: ElementDefinitionContext,
+    definition: OverrideFoundationElementDefinition<DemoCardDefinitionOptions>
+): ViewTemplate<DemoCard> => {
+    const buttonTag = context.tagFor(Button);
+
+    return html`
+        <div class="feature-image">
+            <slot name="feature-media"></slot>
+        </div>
+        <div class="content">
+            <slot name="attribution"></slot>
+            <slot name="heading"></slot>
+        </div>
+        <div class="footer">
+            <slot name="like-button">
+                ${definition.likeButton || html`<${buttonTag}>Like</${buttonTag}>`}
+            </slot>
+        </div>
+    `;
+};