Design-First APIs for UI Components
Who writes UI components?
Who has control over all UI?
Who needs to wait till a new component is developed and released?
Lucien Immink
Principal Consultant @ Team Rockstars IT
Google Developer Expert
Menu
- Communication
- Design first
- Web-components
- Custom Elements Manifest
- AaaG
Design First
All stakeholders can be involved in developing the communication layer:
- Providers (Design system team)
- Consumers (Web team)
- Roadmaps (Product Owners)
Framework agnostic
Independent of any framework
- No (peer)dependency on React/Angular/Vue/...
- No need to rewrite your code to use UI component
- No upgrade dead-locks
Web Components
Independent of any framework
- <template>, <slot>
- shadow dom
- custom-elements
- part of the web platform
<!DOCTYPE html> <html lang="en"> <body> <hello-world type="amazing"></hello-world> <script type="module" src="hello-world.js"></script> </body> </html>
<!DOCTYPE html> <html lang="en"> <body> <hello-world type="amazing"></hello-world> <script type="module" src="hello-world.js"></script> </body> </html>
index.html
Web (Components) API
- properties (input)
- events (output)
- slots (placement)
- css (variables) (styling)
Custom elements manifest (CEM)
Many tools need some machine-readable descriptions of custom elements: IDEs, documentation viewers, linters, graphical design tools, etc.
Custom elements manifest is an effort to bring together tool owners to standardize on a common specification for a description format.
Design-first or not to design-first
- Write CEM first or
- Write skeleton component to generate CEM
Custom Element Manifest
{ "kind": "javascript-module", "path": "components/hello-world.ts", "declarations": [ { "kind": "class", "description": "Hello generated world! Click for a gift or a bomb", "name": "HelloWorld", "cssProperties": [ { "description": "Controls the text colour", "name": "--text-color", "default": "black" }, { "description": "Controls the background colour", "name": "--background-color", "default": "red" } ], "members": [ { "kind": "field", "name": "type", "type": { "text": "string" }, "default": "\"wonderful\"", "description": "What type is the world today?", "attribute": "type" }, { "kind": "method", "name": "eventFunctionGift", "privacy": "private", "description": "Write function that dispatches the event Gift" }, { "kind": "method", "name": "eventFunctionBomb", "privacy": "private", "description": "Write function that dispatches the event Bomb" } ], "events": [ { "name": "Gift", "type": { "text": "Event" }, "description": "gift - I'm bearing a gift" }, { "name": "Bomb", "type": { "text": "Event" }, "description": "bomb - This was a mistake..." } ], "attributes": [ { "name": "type", "type": { "text": "string" }, "default": "wonderful", "description": "What type is the world today?", "fieldName": "type" } ], "superclass": { "name": "LitElement", "package": "lit" }, "tagName": "hello-world", "customElement": true } ], "exports": [ { "kind": "js", "name": "HelloWorld", "declaration": { "name": "HelloWorld", "module": "components/hello-world.ts" } }, { "kind": "custom-element-definition", "name": "hello-world", "declaration": { "name": "HelloWorld", "module": "components/hello-world.ts" } } ] }
{ "kind": "javascript-module", "path": "components/hello-world.ts", "declarations": [ { "kind": "class", "description": "Hello generated world! Click for a gift or a bomb", "name": "HelloWorld", "cssProperties": [ { "description": "Controls the text colour", "name": "--text-color", "default": "black" }, { "description": "Controls the background colour", "name": "--background-color", "default": "red" } ], "members": [ { "kind": "field", "name": "type", "type": { "text": "string" }, "default": "\"wonderful\"", "description": "What type is the world today?", "attribute": "type" }, { "kind": "method", "name": "eventFunctionGift", "privacy": "private", "description": "Write function that dispatches the event Gift" }, { "kind": "method", "name": "eventFunctionBomb", "privacy": "private", "description": "Write function that dispatches the event Bomb" } ], "events": [ { "name": "Gift", "type": { "text": "Event" }, "description": "gift - I'm bearing a gift" }, { "name": "Bomb", "type": { "text": "Event" }, "description": "bomb - This was a mistake..." } ], "attributes": [ { "name": "type", "type": { "text": "string" }, "default": "wonderful", "description": "What type is the world today?", "fieldName": "type" } ], "superclass": { "name": "LitElement", "package": "lit" }, "tagName": "hello-world", "customElement": true } ], "exports": [ { "kind": "js", "name": "HelloWorld", "declaration": { "name": "HelloWorld", "module": "components/hello-world.ts" } }, { "kind": "custom-element-definition", "name": "hello-world", "declaration": { "name": "HelloWorld", "module": "components/hello-world.ts" } } ] }
{ "kind": "javascript-module", "path": "components/hello-world.ts", "declarations": [ { "kind": "class", "description": "Hello generated world! Click for a gift or a bomb", "name": "HelloWorld", "cssProperties": [ { "description": "Controls the text colour", "name": "--text-color", "default": "black" }, { "description": "Controls the background colour", "name": "--background-color", "default": "red" } ], "members": [ { "kind": "field", "name": "type", "type": { "text": "string" }, "default": "\"wonderful\"", "description": "What type is the world today?", "attribute": "type" }, { "kind": "method", "name": "eventFunctionGift", "privacy": "private", "description": "Write function that dispatches the event Gift" }, { "kind": "method", "name": "eventFunctionBomb", "privacy": "private", "description": "Write function that dispatches the event Bomb" } ], "events": [ { "name": "Gift", "type": { "text": "Event" }, "description": "gift - I'm bearing a gift" }, { "name": "Bomb", "type": { "text": "Event" }, "description": "bomb - This was a mistake..." } ], "attributes": [ { "name": "type", "type": { "text": "string" }, "default": "wonderful", "description": "What type is the world today?", "fieldName": "type" } ], "superclass": { "name": "LitElement", "package": "lit" }, "tagName": "hello-world", "customElement": true } ], "exports": [ { "kind": "js", "name": "HelloWorld", "declaration": { "name": "HelloWorld", "module": "components/hello-world.ts" } }, { "kind": "custom-element-definition", "name": "hello-world", "declaration": { "name": "HelloWorld", "module": "components/hello-world.ts" } } ] }
{ "kind": "javascript-module", "path": "components/hello-world.ts", "declarations": [ { "kind": "class", "description": "Hello generated world! Click for a gift or a bomb", "name": "HelloWorld", "cssProperties": [ { "description": "Controls the text colour", "name": "--text-color", "default": "black" }, { "description": "Controls the background colour", "name": "--background-color", "default": "red" } ], "members": [ { "kind": "field", "name": "type", "type": { "text": "string" }, "default": "\"wonderful\"", "description": "What type is the world today?", "attribute": "type" }, { "kind": "method", "name": "eventFunctionGift", "privacy": "private", "description": "Write function that dispatches the event Gift" }, { "kind": "method", "name": "eventFunctionBomb", "privacy": "private", "description": "Write function that dispatches the event Bomb" } ], "events": [ { "name": "Gift", "type": { "text": "Event" }, "description": "gift - I'm bearing a gift" }, { "name": "Bomb", "type": { "text": "Event" }, "description": "bomb - This was a mistake..." } ], "attributes": [ { "name": "type", "type": { "text": "string" }, "default": "wonderful", "description": "What type is the world today?", "fieldName": "type" } ], "superclass": { "name": "LitElement", "package": "lit" }, "tagName": "hello-world", "customElement": true } ], "exports": [ { "kind": "js", "name": "HelloWorld", "declaration": { "name": "HelloWorld", "module": "components/hello-world.ts" } }, { "kind": "custom-element-definition", "name": "hello-world", "declaration": { "name": "HelloWorld", "module": "components/hello-world.ts" } } ] }
custom-elements.json
Skeleton components
- Define properties
- Define events
- Define slots
- Define CSS variables
- In short: Define your API
Create 🩻 component
import { html, css, LitElement } from "lit" import { customElement, property } from "lit/decorators.js" @customElement("hello-world") export class HelloWorld extends LitElement { static styles = css` :host { color: var(--text-color, black); background-color: var(--background-color, red); } ` @property() type = "wonderful" private eventFunctionGift() { this.dispatchEvent(new Event("Gift")) } private eventFunctionBomb() { this.dispatchEvent(new Event("Bomb")) } render() { return html` <h1>HelloWorld - <hello-world></hello-world></h1> <p>Hello generated world! Click for a gift or a bomb</p> <h2>CSS variables</h2> <ul> <li> <span style="color: var(--text-color, black)" >current text-color: --text-color default value: black</span > </li> <li> <span style="color: var(--background-color, red)" >current text-color: --background-color default value: red</span > </li> </ul> <h2>Attributes</h2> <ul> <li>type = ${this.type}</li> </ul> <h2>Events</h2> <ul> <li><button @click=${this.eventFunctionGift}>trigger Gift</button></li> <li><button @click=${this.eventFunctionBomb}>trigger Bomb</button></li> </ul> ` } }
import { html, css, LitElement } from "lit" import { customElement, property } from "lit/decorators.js" @customElement("hello-world") export class HelloWorld extends LitElement { static styles = css` :host { color: var(--text-color, black); background-color: var(--background-color, red); } ` @property() type = "wonderful" private eventFunctionGift() { this.dispatchEvent(new Event("Gift")) } private eventFunctionBomb() { this.dispatchEvent(new Event("Bomb")) } render() { return html` <h1>HelloWorld - <hello-world></hello-world></h1> <p>Hello generated world! Click for a gift or a bomb</p> <h2>CSS variables</h2> <ul> <li> <span style="color: var(--text-color, black)" >current text-color: --text-color default value: black</span > </li> <li> <span style="color: var(--background-color, red)" >current text-color: --background-color default value: red</span > </li> </ul> <h2>Attributes</h2> <ul> <li>type = ${this.type}</li> </ul> <h2>Events</h2> <ul> <li><button @click=${this.eventFunctionGift}>trigger Gift</button></li> <li><button @click=${this.eventFunctionBomb}>trigger Bomb</button></li> </ul> ` } }
import { html, css, LitElement } from "lit" import { customElement, property } from "lit/decorators.js" @customElement("hello-world") export class HelloWorld extends LitElement { static styles = css` :host { color: var(--text-color, black); background-color: var(--background-color, red); } ` @property() type = "wonderful" private eventFunctionGift() { this.dispatchEvent(new Event("Gift")) } private eventFunctionBomb() { this.dispatchEvent(new Event("Bomb")) } render() { return html` <h1>HelloWorld - <hello-world></hello-world></h1> <p>Hello generated world! Click for a gift or a bomb</p> <h2>CSS variables</h2> <ul> <li> <span style="color: var(--text-color, black)" >current text-color: --text-color default value: black</span > </li> <li> <span style="color: var(--background-color, red)" >current text-color: --background-color default value: red</span > </li> </ul> <h2>Attributes</h2> <ul> <li>type = ${this.type}</li> </ul> <h2>Events</h2> <ul> <li><button @click=${this.eventFunctionGift}>trigger Gift</button></li> <li><button @click=${this.eventFunctionBomb}>trigger Bomb</button></li> </ul> ` } }
import { html, css, LitElement } from "lit" import { customElement, property } from "lit/decorators.js" @customElement("hello-world") export class HelloWorld extends LitElement { static styles = css` :host { color: var(--text-color, black); background-color: var(--background-color, red); } ` @property() type = "wonderful" private eventFunctionGift() { this.dispatchEvent(new Event("Gift")) } private eventFunctionBomb() { this.dispatchEvent(new Event("Bomb")) } render() { return html` <h1>HelloWorld - <hello-world></hello-world></h1> <p>Hello generated world! Click for a gift or a bomb</p> <h2>CSS variables</h2> <ul> <li> <span style="color: var(--text-color, black)" >current text-color: --text-color default value: black</span > </li> <li> <span style="color: var(--background-color, red)" >current text-color: --background-color default value: red</span > </li> </ul> <h2>Attributes</h2> <ul> <li>type = ${this.type}</li> </ul> <h2>Events</h2> <ul> <li><button @click=${this.eventFunctionGift}>trigger Gift</button></li> <li><button @click=${this.eventFunctionBomb}>trigger Bomb</button></li> </ul> ` } }
hello-world.ts
Document 🩻 component
import { html, css, LitElement } from "lit" import { customElement, property } from "lit/decorators.js" /** * Hello generated world! Click for a gift or a bomb * * @cssprop [--text-color=black] - Controls the text colour * @cssprop [--background-color=red] - Controls the background colour */ @customElement("hello-world") export class HelloWorld extends LitElement { static styles = css` :host { color: var(--text-color, black); background-color: var(--background-color, red); } ` /** What type is the world today? */ @property() type = "wonderful" /** Write function that dispatches the event Gift */ private eventFunctionGift() { /** @type {Event} gift - I'm bearing a gift */ this.dispatchEvent(new Event("Gift")) } /** Write function that dispatches the event Bomb */ private eventFunctionBomb() { /** @type {Event} bomb - This was a mistake... */ this.dispatchEvent(new Event("Bomb")) } render() { return html` <h1>HelloWorld - <hello-world></hello-world></h1> <p>Hello generated world! Click for a gift or a bomb</p> <h2>CSS variables</h2> <ul> <li> <span style="color: var(--text-color, black)" >current text-color: --text-color default value: black</span > </li> <li> <span style="color: var(--background-color, red)" >current text-color: --background-color default value: red</span > </li> </ul> <h2>Attributes</h2> <ul> <li>type = ${this.type}</li> </ul> <h2>Events</h2> <ul> <li><button @click=${this.eventFunctionGift}>trigger Gift</button></li> <li><button @click=${this.eventFunctionBomb}>trigger Bomb</button></li> </ul> ` } }
import { html, css, LitElement } from "lit" import { customElement, property } from "lit/decorators.js" /** * Hello generated world! Click for a gift or a bomb * * @cssprop [--text-color=black] - Controls the text colour * @cssprop [--background-color=red] - Controls the background colour */ @customElement("hello-world") export class HelloWorld extends LitElement { static styles = css` :host { color: var(--text-color, black); background-color: var(--background-color, red); } ` /** What type is the world today? */ @property() type = "wonderful" /** Write function that dispatches the event Gift */ private eventFunctionGift() { /** @type {Event} gift - I'm bearing a gift */ this.dispatchEvent(new Event("Gift")) } /** Write function that dispatches the event Bomb */ private eventFunctionBomb() { /** @type {Event} bomb - This was a mistake... */ this.dispatchEvent(new Event("Bomb")) } render() { return html` <h1>HelloWorld - <hello-world></hello-world></h1> <p>Hello generated world! Click for a gift or a bomb</p> <h2>CSS variables</h2> <ul> <li> <span style="color: var(--text-color, black)" >current text-color: --text-color default value: black</span > </li> <li> <span style="color: var(--background-color, red)" >current text-color: --background-color default value: red</span > </li> </ul> <h2>Attributes</h2> <ul> <li>type = ${this.type}</li> </ul> <h2>Events</h2> <ul> <li><button @click=${this.eventFunctionGift}>trigger Gift</button></li> <li><button @click=${this.eventFunctionBomb}>trigger Bomb</button></li> </ul> ` } }
import { html, css, LitElement } from "lit" import { customElement, property } from "lit/decorators.js" /** * Hello generated world! Click for a gift or a bomb * * @cssprop [--text-color=black] - Controls the text colour * @cssprop [--background-color=red] - Controls the background colour */ @customElement("hello-world") export class HelloWorld extends LitElement { static styles = css` :host { color: var(--text-color, black); background-color: var(--background-color, red); } ` /** What type is the world today? */ @property() type = "wonderful" /** Write function that dispatches the event Gift */ private eventFunctionGift() { /** @type {Event} gift - I'm bearing a gift */ this.dispatchEvent(new Event("Gift")) } /** Write function that dispatches the event Bomb */ private eventFunctionBomb() { /** @type {Event} bomb - This was a mistake... */ this.dispatchEvent(new Event("Bomb")) } render() { return html` <h1>HelloWorld - <hello-world></hello-world></h1> <p>Hello generated world! Click for a gift or a bomb</p> <h2>CSS variables</h2> <ul> <li> <span style="color: var(--text-color, black)" >current text-color: --text-color default value: black</span > </li> <li> <span style="color: var(--background-color, red)" >current text-color: --background-color default value: red</span > </li> </ul> <h2>Attributes</h2> <ul> <li>type = ${this.type}</li> </ul> <h2>Events</h2> <ul> <li><button @click=${this.eventFunctionGift}>trigger Gift</button></li> <li><button @click=${this.eventFunctionBomb}>trigger Bomb</button></li> </ul> ` } }
hello-world.ts
🧙♂️ magic time ✨🌈
AaaG
Automation as a Gift
AaaG examples
- Demos
- Linting
- Testing
- Cataloging
- Generation
- Integration
- Documentation
Getting started
- lit.dev (web component library)
- custom-elements-manifest.open-wc.org (CEM)
- custom-elements-manifest.open-wc.org/analyzer/plugins/intro/ (AaaG)
- github.com/lucienimmink/skeleton-component-generator (AaaG - design first APIs)
- medium.com/team-rockstars-it/api-first-ui-components-c24fd242053d (written version)
- api-first-ui-components.netlify.app (this presentation)
📸 this is the best time to take a picture
Wrap up
- Communication
- Design first
- Web-components
- Custom Elements Manifest
- AaaG
Thank you
Contact me:
Design-First APIs for UI Components 🌐 api-first-ui-components.netlify.app