Lit Web Components Best Practices

An Agent Plugin (spec v1.0.0) containing comprehensive best practices for building Lit web components, optimized for AI-assisted code generation, review, and refactoring.

Overview

This skill contains 34 rules across 9 categories, prioritized by impact to guide automated refactoring and code generation:

Installation

Agent Plugins-compatible clients

This repository is a conformant Agent Plugin: clone it (or point your client at it) and the client discovers skills/lit-best-practices/ from plugin.json.

Claude Code

Install as a plugin (manifest at .claude-plugin/plugin.json, skills auto-discovered from skills/), or copy the skill directly:

npx skills add artmsilva/lit-best-practices

Manual Installation

Copy skills/lit-best-practices/ into your project's skills directory, or paste its SKILL.md into a conversation.

Structure

.
├── plugin.json                    # Agent Plugins v1.0.0 manifest
├── .claude-plugin/plugin.json     # Claude Code plugin manifest
├── README.md                      # This file
└── skills/
    └── lit-best-practices/
        ├── SKILL.md              # Lightweight index + quick reference
        ├── AGENTS.md             # High-level guidance for AI agents
        └── rules/                # Individual rule files (loaded on-demand)
            ├── 1-1-use-decorators.md
            ├── 2-1-pure-render.md
            └── ...

The rules are split into individual files so agents can load only the rules relevant to the current task, saving context.

Usage

The skill automatically activates when Claude detects tasks involving:

• Lit web components
• Custom elements
• Shadow DOM
• Reactive properties
• Web component testing

Example Prompts

"Create a Lit component for a dropdown menu with keyboard navigation"
"Review this Lit component for accessibility issues"
"Refactor this component to follow Lit best practices"
"Add form association to this custom input component"

Priority Levels

Rules are categorized by impact:

Key Patterns Covered

Component Structure

• TypeScript decorators for properties
• Separating public API (@property) from internal state (@state)
• Property reflection guidelines
• Default values and type safety

Rendering

• Pure render() methods
• Using nothing for conditional content
• repeat() directive for keyed lists
• cache() directive for view switching
• Derived state in willUpdate()

Styling

• Static styles (never inline <style>)
• :host element styling patterns
• CSS custom properties for theming
• CSS parts for deep customization

Events

• Composed events for shadow DOM
• Naming conventions
• Event listener cleanup

Lifecycle

• Correct super call ordering
• firstUpdated for DOM operations
• willUpdate vs updated usage
• Async patterns with updateComplete

Accessibility

• delegatesFocus for interactive components
• ARIA roles and states
• Keyboard interaction
• Form-associated custom elements

Performance

• Custom hasChanged functions
• Property update batching
• Lazy loading
• Memoization patterns

Composition & Data

• Reactive controllers instead of mixins
• @lit/task for async data and abort handling
• @lit/context instead of prop drilling

Security

• unsafeHTML/unsafeSVG sanitization rules
• URL binding sinks

Reference Resources

• Lit Documentation
• Agent Plugins Specification
• Open Web Components
• Lion Web Components
• Shoelace
• Adobe Spectrum Web Components
• web.dev Custom Elements Best Practices

Contributing

Contributions welcome! Please ensure:

1. Rules include clear incorrect/correct examples
2. Impact level is justified
3. TypeScript examples are properly typed
4. Accessibility implications are considered

License

MIT