docs: add comprehensive web component creation guidelines #10594
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add WEB_COMPONENT_GUIDELINES.md, a complete reference guide for creating new Vaadin web components. This document provides step-by-step instructions for component development following current repository patterns and best practices. The guidelines cover: Component Architecture: - Pure Lit pattern implementation (no legacy PolylitMixin) - Proper mixin chain ordering and usage - Component lifecycle management with Lit - Property definitions, event firing, and controllers Theming System: - Lumo theme implementation (business-focused design) - Aura theme implementation (modern CSS with oklch, light-dark, relative colors) - Theme comparison and design token documentation - CSS custom properties and state attributes Development Workflow: - Complete file structure for components - Package configuration and dependencies - TypeScript definitions for components and mixins - License headers and documentation requirements Testing Requirements: - Unit tests for functionality, properties, events, and accessibility - DOM snapshot tests - Visual regression tests for Lumo, Aura, and base themes - TypeScript type tests - Keyboard interaction testing Accessibility: - ARIA requirements and roles - Keyboard support patterns - Focus management - State attribute synchronization Documentation: - JSDoc comment patterns - README structure - API documentation requirements Common Patterns: - Interactive components (button-like) - Field components (input-like) - Overlay components (popup/dialog) - List/data components This guide uses modern Lit patterns and supports both Vaadin themes (Lumo and Aura), ensuring consistency across the component library.
web-padawan
reviewed
Dec 8, 2025
- Remove unused changedProperties parameter from firstUpdated() - Replace TooltipController examples with more common role attribute pattern - Update field component examples to use InputControlMixin instead of TextFieldMixin/InputFieldMixin - Remove legacy @type JSDoc annotations from property definitions - Add type specifications to @attr annotations (e.g., @attr {boolean} disabled) - Replace state: true with attribute: false for internal properties - Remove shouldUpdate() lifecycle method (not commonly used) - Remove DataProviderController from general controllers list - Remove LumoInjection CSS properties to align with pure Lit pattern
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Add WEB_COMPONENT_GUIDELINES.md, a complete reference guide for creating new Vaadin web components. This document provides step-by-step instructions for component development following current repository patterns and best practices.
The guidelines cover:
Component Architecture:
Theming System:
Development Workflow:
Testing Requirements:
Accessibility:
Documentation:
Common Patterns:
This guide uses modern Lit patterns and supports both Vaadin themes (Lumo and Aura), ensuring consistency across the component library.