Principles
- Front-end source of truth — Eddie is the single source of truth for UI
- Presentational only — Components have no business logic, data models, or environment dependencies
- Framework agnostic — Native web components that work everywhere
- Predictable APIs — Consistent naming conventions across all components
- Composition over inheritance — Use slots for content injection
HTML Conventions
- Prefer semantic HTML and native elements over custom implementations
- Every element inside a component must have a BEM class (no unclassed tags except in TextPassage)
- Use
tagName prop to render as different HTML elements when semantically appropriate
Repository Structure
Eddie is a monorepo with four npm workspace packages:
| Package |
Description |
eddie-web-components |
Lit-based web components (the core) |
eddie-recipes |
Product-specific compositions built on core |
eddie-design-tokens |
Design tokens via Style Dictionary |
eddie-icons |
SVG icon sprite library |
Component Structure
Each component lives in a flat directory:
components/<name>/
├── <name>.ts # Component class
├── <name>.scss # Scoped styles (BEM)
├── <name>.stories.ts # Storybook stories
└── test/
└── <name>.test.ts # Unit tests
Base Classes
EdElement — Root base class extending LitElement. Provides componentClassNames() for BEM class construction, slotEmpty() for slot detection, and dispatch() for custom events.EdFormElement — Extends EdElement for form-associated components. Implements the ElementInternals API for native form participation, validation, and reset handling.