@etymos/ui

Project

• Name: Etymos UI — a lightweight web component Design System.
• Purpose: Provide opinionated, highly-customizable, accessible UI components built with Lit that work with any web framework.

Installation

• npm: npm install @etymos/ui
• yarn: yarn add @etymos/ui
• Local development: git clone this repo and run npm install.

Quick Start

• Import: Register the components in your app (see src/components/* for examples).
  • Example (module import): import '@etymos/ui/button';
• Use: Add components to HTML:
  • <et-button>Click me</et-button>
  • Components use slots for semantic content and props/attributes for configuration.

Core Principles

• Compatibility: Built as standard web components (Custom Elements, Shadow DOM, HTML slots) to integrate with any framework.
• Accessibility: Accessibility-first design; runtime checks and console guidance help enforce correct usage (for example, components warn when an accessible name is missing).
• SEO Awareness: Use slots for semantic content so authors control markup visible to search engines and assistive tech.
• Declarative DX: Favor composition, slots, and custom events over imperative APIs for a simpler developer experience.
• Opinionated + Customizable: Components provide sensible defaults while allowing style and behavior overrides through Design Tokens and CSS variables.

Accessibility Notes

• Accessible names: Components validate common accessibility issues at runtime and log helpful messages to guide fixes.
• Slots for semantics: Put readable and semantic content (text, anchors, headings) inside slots so assistive technology can consume it.
• Testing tip: In tests, wait for slot distribution (slotchange) before asserting slot-dependent behavior or console warnings.

Theming & Design Tokens

Three token levels

• Primitive tokens: Base values (colors, spacing, fonts).
• Semantic tokens: Meaningful abstractions (brand, background, surface).
• Component tokens: Component-specific variables derived from semantic tokens.

Customize

Override CSS variables on :root or a theme wrapper: :root { --et-color-primary: #0b5fff; --et-spacing-1: 8px; }

Scope themes

Apply a class to a root container to switch theme variables (for example .et-theme-dark { ... }).

Where tokens live

Tokens and styles are under their own package @etymos/tokens and component styles under src/components/*/*.styles.ts.

Usage Patterns & Best Practices

Slots for content

Provide semantic content through slots rather than props when that content should be visible to users or search engines.

Props for behaviour

Use attributes/props to control size, variant and interactivity (e.g., size="small", usage="link").

Custom events

Listen to component events (for example etClose, etToggle) dispatched by components for framework-agnostic interactivity.

Development

• Install dependencies: npm install
• Start dev server: npm run dev (or vite if configured)
• Build: npm run build
• Component locations: See src/components/* — each component includes implementation, styles, stories and tests.

Testing

• Run tests: npm run test (this project uses vitest).
• Test tips:
  • Spy on console methods before rendering to capture runtime warnings.
  • Await component updateComplete, then await slotchange (or use a MutationObserver) for slot-dependent logic.
  • Mount elements programmatically if you need to attach listeners before distribution.

Contributing

• Guidelines: Open PRs against main/release/* branches; follow existing code style.
• Add components: Keep components small, accessible-first, with clear token usage. Add stories and tests.
• Lint & format: Run npm run lint and npm run format if configured.

Examples & API

• Props & events: See component *.types.ts and *.stories.ts files for props, events and examples.
• Live preview: Use stories (src/components/*/*.stories.ts) for interactive examples when Storybook or a preview is configured.

License

• See LICENSE in the repository root.

Contact & Support

• For issues or feature requests, open an issue in this repository. PRs and suggested improvements are welcome.