| name | lit-ui-designer |
| description | Design, build, review, or polish world-class Lit/LitElement web component UIs. Use for Lit components, custom elements, Web Components, shadow DOM styling, design systems/tokens, professional UI polish, accessibility/WCAG reviews, keyboard interactions, ARIA patterns, responsive states, and production-quality TypeScript/CSS implementations. |
Lit UI Designer
Use this skill to create or improve Lit web component interfaces that feel professional, accessible, robust, and production-ready.
Workflow
- Inspect before inventing. Read the existing component, styles, tokens, tests/stories, screenshots, and surrounding UX. Preserve repo conventions unless they are clearly broken.
- Define the UX contract. Identify primary user goal, component states, keyboard/mouse/touch behavior, responsive behavior, empty/loading/error/disabled states, and integration boundaries.
- Choose native semantics first. Prefer real HTML controls (
button, a, input, dialog, headings, lists, tables) before ARIA. Add ARIA only when native semantics cannot express the pattern.
- Implement Lit idiomatically. Keep public properties as external API, private
@state for internals, declarative render(), classMap/styleMap when helpful, and custom events for user-driven state changes.
- Design with craft. Use clear hierarchy, spacing rhythm, restrained color, meaningful motion, strong focus states, and polished empty/error states. Avoid generic “AI dashboard” slop.
- Verify. Run the smallest meaningful gates: typecheck/test/build, accessibility checks if present, and browser/screenshot review for meaningful visual work.
Lit implementation standards
- Use TypeScript and decorators when the repo already uses them; otherwise follow local Lit style.
- Keep reactive public props as inputs. Do not silently mutate owner-controlled props except for user-driven control patterns; emit a composed/bubbling event to announce changes.
- Use
@state() or state: true for private reactive state.
- Keep expensive derived values outside hot render paths or memoize when needed.
- Use stable keys/repeat directives for lists that reorder or update often.
- Use
static styles = css\...`` for component styles. Prefer CSS custom properties for theming and per-instance variation.
- Avoid dynamic
<style> blocks and unsafeCSS; use them only when the value is fully trusted and there is no safer design-token/custom-property option.
- Use
:host, :host([attr]), ::slotted, and CSS parts intentionally. Document exported parts and CSS custom properties when creating reusable components.
- Dispatch events with
bubbles: true and composed: true when parents outside the shadow root must handle them.
Accessibility bar
Target WCAG 2.2 AA unless the repo specifies stricter requirements.
- Keyboard: every interactive path works without a mouse; focus order is logical; Escape/Enter/Space/Arrow behavior matches the widget pattern.
- Focus: visible, high-contrast focus indicators; never remove outlines without replacement.
- Names: every icon-only control has an accessible name; form inputs have labels; status regions are announced when appropriate.
- Contrast: meet AA for text and meaningful UI indicators; do not encode meaning by color alone.
- Motion: respect
prefers-reduced-motion; keep transitions purposeful and short.
- Shadow DOM: remember labels, focus delegation, slots, composed events, and ARIA relationships can behave differently across shadow boundaries. Test actual behavior.
- ARIA: if implementing a complex widget, follow WAI-ARIA APG keyboard and role guidance exactly; do not sprinkle roles as decoration.
Professional UI checklist
- Layout has a clear information hierarchy: title, primary action, secondary actions, metadata, content.
- Spacing follows a consistent scale; alignment is deliberate; density matches the product surface.
- Loading, empty, error, offline, disabled, hover, active, selected, and focus states are designed.
- Copy is specific and calm; labels use verbs for actions and nouns for destinations.
- Components are responsive by design, not patched after the fact.
- Visual effects support comprehension; avoid gratuitous blur/glow/gradient noise.
- Dark mode and high-contrast modes are considered when the product supports them.
Review protocol
When reviewing or polishing Lit UI, report findings in this order:
- Blocking accessibility or correctness issues
- Lit/web-component architecture issues
- Visual craft and UX polish
- Nice-to-have improvements
For implementation work, prefer a small, shippable slice over a sprawling redesign. If a full redesign is needed, create a plan and one representative component first.
References
Read only as needed:
references/lit-patterns.md — Lit architecture, properties, events, styles, and component APIs.references/accessibility-checklist.md — accessibility checks for shadow DOM, custom controls, keyboard UX, and ARIA.references/design-quality.md — professional visual/UI quality standards and anti-slop guidance.
