> Markdown version of [/videos/1210-unlocking-seamless-collaboration-design-first-apis-for-ui-components](https://www.wearedevelopers.com/videos/1210-unlocking-seamless-collaboration-design-first-apis-for-ui-components). Every page supports `.md` or `Accept: text/markdown`. Links point to the HTML versions so they work for humans too. Agent guide: [/agents.md](https://www.wearedevelopers.com/agents.md).

---

# Unlocking Seamless Collaboration: Design-First APIs for UI Components

Treat your UI elements like backend services with design-first APIs. Defining clear contracts before coding unlocks seamless team collaboration, framework-agnostic longevity, and fully automated documentation.

- **Speakers:** Lucien Immink
- **Event:** WeAreDevelopers LIVE
- **Published:** September 18, 2024
- **Duration:** 28:35
- **URL:** https://www.wearedevelopers.com/videos/1210-unlocking-seamless-collaboration-design-first-apis-for-ui-components

## Summary

The process of creating and adopting UI components often suffers from misaligned expectations between design system authors and consuming web developers. By adopting a "design-first" approach, teams can treat user interfaces like backend services—establishing a clear API contract of properties, events, slots, and CSS variables before writing implementation logic. This enables providers and consumers to collaborate efficiently without upgrade deadlocks or framework constraints, especially when utilizing standard web components.

Central to this methodology is the Custom Elements Manifest, a machine-readable JSON standard that describes a web component's API. Instead of manually maintaining documentation, developers can create "skeleton components" that define just the input and output boundaries using libraries like Lit. A code analyzer extracts these definitions into the manifest, unlocking a concept referred to as "automation as a gift."

This standardized manifest automatically powers interactive documentation, populates Storybook catalogs, enforces API validation, provides rich IDE code completion, and generates framework-specific wrappers. Ultimately, decoupling the API design from the underlying logic ensures framework-agnostic longevity, bridges team communication, and significantly accelerates the UI development lifecycle.

**Keywords:** UI component architecture, design-first API, web components, custom elements manifest, lit framework, framework-agnostic UI, design system engineering, skeleton components, storybook integration, automated component documentation, shadow DOM encapsulation, CSS custom properties, frontend API contracts, developer collaboration, JSON manifests

## Chapters

1. **Navigating workflow challenges in UI component development** (00:00) — Delays and knowledge gaps arise when web teams wait for centralized design system updates.
1. **Establishing APIs as communication contracts for components** (04:10) — Shared agreements on component interfaces prevent implementation failures and align developer expectations.
1. **Adopting a design-first and framework-agnostic component approach** (07:52) — Collaborating on component APIs before coding prevents framework lock-in and upgrade deadlocks.
1. **Leveraging web components for independent UI elements** (11:26) — Standardized shadow DOMs and slots securely encapsulate business logic and styling inside reusable web components.
1. **Standardizing API descriptions using custom elements manifests** (14:09) — Machine-readable JSON specification files provide tooling integration for frameworks and documentation displays.
1. **Building skeleton components to establish foundational API endpoints** (17:29) — Placeholder Lit components augmented with documentation blocks dynamically render interactive API playgrounds.
1. **Unlocking automation workflows for web component distribution** (23:30) — Manifest-driven automation effortlessly generates IDE completions, linting solutions, and wrapper code.
1. **Reviewing resources for web component workflow implementation** (25:38) — Essential starting points and repositories guide developers in adopting automated, design-first methodologies.

## Related Moments

- [Building a framework-agnostic design system with web components](https://www.wearedevelopers.com/videos/648-accessibility-with-web-components) (from "Accessibility with Web Components")
- [Building framework-less architectures with native custom web components](https://www.wearedevelopers.com/videos/438-making-of-paint-js-org-a-web-component-based-productivity-pwa) (from "Making of paint.js.org—a Web Component-based Productivity PWA")
- [Building and documenting UI components in isolation](https://www.wearedevelopers.com/videos/975-leveraging-storybook-for-component-driven-development-outside-of-your-classic-component-library) (from "Leveraging Storybook for Component Driven Development outside of your classic Component Library.")
- [Building isolated UI elements using standard web components](https://www.wearedevelopers.com/videos/774-why-lit-is-fire) (from "Why LIT is Fire")
- [The main promise of UI component libraries](https://www.wearedevelopers.com/videos/650-building-a-component-library-for-modern-challenges) (from "Building a component library for modern challenges")
- [Designing flexible and reusable component APIs](https://www.wearedevelopers.com/videos/975-leveraging-storybook-for-component-driven-development-outside-of-your-classic-component-library) (from "Leveraging Storybook for Component Driven Development outside of your classic Component Library.")

## Related Articles

- [Declarative Design and a fresh take on collaboration with developers](https://www.wearedevelopers.com/magazine/595-declarative-design-and-a-fresh-take-on-collaboration-with-developers)
- [Dev Digest 133 - Back to Front](https://www.wearedevelopers.com/magazine/474-dev-digest-133-back-to-front)
- [The HTML Elements That You’re Probably Over-Engineering](https://www.wearedevelopers.com/magazine/646-the-html-elements-that-you-re-probably-over-engineering)
- [How to Avoid Over-Engineering](https://www.wearedevelopers.com/magazine/546-how-to-avoid-over-engineering)

## Related Jobs

- [Senior Product UI Designer](https://www.wearedevelopers.com/jobs/ext/1998621-senior-product-ui-designer) at **Almedia**
- [Staff Frontend Engineer](https://www.wearedevelopers.com/jobs/48313-staff-frontend-engineer) at **SMG Swiss Marketplace Group**
- [Senior Web Designer, Growth](https://www.wearedevelopers.com/jobs/ext/102722-senior-web-designer-growth) at **Intercom, Inc.**
- [Staff Frontend Engineer (Expert+/Lead equivalent) - Hybrid working model, 100%, Ho Chi Minh City](https://www.wearedevelopers.com/jobs/48314-staff-frontend-engineer-expert-lead-equivalent-hybrid-working-model-100-ho-chi-minh-city) at **SMG Swiss Marketplace Group**
- [Junior Frontend Engineer](https://www.wearedevelopers.com/jobs/ext/1532351-junior-frontend-engineer) at **Almedia**
- [Software Engineer Frontend (all genders welcome) in the field of Water Line Integrity Solutions](https://www.wearedevelopers.com/jobs/ext/127888-software-engineer-frontend-all-genders-welcome-in-the-field-of-water-line-integrity-solutions) at **Rosenxt Group**