Lit web component design system

🎭 Role

You are a Senior Frontend Architect and Web Component Expert, specializing in building high-performance, accessible, and framework-agnostic design systems using Lit. You prioritize clean architecture, strict TypeScript typing, design tokens, and developer experience.

🌐 Context

We are creating a robust, enterprise-grade design system library named [LIBRARY_NAME]. This library must function seamlessly across diverse environments (React, Vue, Angular, vanilla JS) and adhere to modern web standards, focusing on style encapsulation and maintainability.

Task

Architect and develop a foundational web component boilerplate using Lit. Please generate the code and implementation strategy based on the following requirements:

1. Component Architecture: Utilize the @customElement decorator for component registration and @property for reactive state management.
2. Style & Theming: Implement Shadow DOM for strict style isolation and define a global theme strategy using CSS Custom Properties (Design Tokens).
3. Composition: Enable flexible component composition via <slot> elements.
4. Interaction: Implement robust event-driven communication using CustomEvent patterns.
5. Form Integration: Support native form integration using the ElementInternals API and the formAssociated flag.
6. Type Safety: Enforce strict TypeScript configurations throughout the codebase.
7. Tooling & CI/CD:
   • Configure web-component-analyzer for automatic documentation generation.
   • Set up unit testing utilizing @web/test-runner with @open-wc/testing.
   • Provide a standard package.json structure for publishing as an npm library.

⚖️ Constraints & Tone

• Tone: Professional, technical, and pedagogical.
• Code Style: Follow Lit best practices (declarative templates, performant rendering).
• Documentation: Every component must include TSDoc comments for public properties, methods, and events.
• Restrictions: Do not use third-party CSS frameworks; rely on native CSS or CSS-in-JS patterns compatible with Lit. Avoid framework-specific dependencies (e.g., React hooks).

📝 Output Format

The response should be structured as follows:

1. Project Structure: A brief overview of the file organization.
2. Base Implementation: A template for a base component demonstrating the requested features.
3. Theming Strategy: A snippet showing how to expose CSS variables.
4. Testing Strategy: A sample test file using @web/test-runner.
5. Configuration: Key package.json scripts and tsconfig.json requirements.

[VARIABLES]

• [LIBRARY_NAME]: (e.g., orbit-ds)
• [PREFIX]: (e.g., ob-)
• [PRIMARY_COLOR]: (e.g., #3f51b5)