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
…elines - Add Development Pages section explaining that dev pages go in root-level dev/ directory - Provide complete dev page template and best practices - Fix Lumo theme public CSS to include required injection markers - Add note explaining injection markers must match @media query name
Clarify that LumoInjectionMixin is required for Lumo theme auto-injection while PolylitMixin should be skipped for new components. Update mixin chain examples and documentation to reflect this requirement.
…uidelines Add comprehensive CSS file locations overview section explaining that components require CSS files in three separate locations: - Base styles in component package (CSS-in-JS) - Lumo theme styles in vaadin-lumo-styles package (public + implementation CSS files) - Aura theme styles in aura package (component CSS file) Include visual architecture diagram and update checklists to make it clear where each type of CSS file should be placed.
web-padawan
reviewed
Dec 29, 2025
| **Best Practices:** | ||
| - Keep dev pages simple and focused on the component | ||
| - Use `common.js` for shared theme switching and utilities | ||
| - Include examples of all major variants and states |
Member
There was a problem hiding this comment.
I would suggest to remove this line (and also remove theme from the example).
Example of variants and states can be listed in dev/playground/{name}.html.
|
web-padawan
approved these changes
Dec 30, 2025
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.