Developer Guide
Documentation for developers extending LCARdS — building custom cards, editors, and packs.
How-to Guides
| Page | Description |
|---|---|
| Building a Custom Card | Extend LCARdSCard, wire lifecycle hooks, register in lcards.js |
| Building an Editor | Add a visual editor to your card using LCARdSBaseEditor |
| Building a Pack | Bundle style presets, components, themes, audio, and more into a distributable pack |
API Reference
| Page | Description |
|---|---|
| Animation API | window.lcards.anim.* — anime.js v4 access, helpers, presets, scopes |
| Assets & SVG API | Font loading, SVG cache, SVG/anchor helpers, text measure cache |
| Color Resolution | Correct patterns for resolving CSS vars, computed expressions (darken, lighten, alpha, etc.) in all contexts |
| Debug API | Console introspection: log level, core singletons, MSD cards, data sources |
| Helpers API | WebSocket-based HA helper management — create, read, update, delete |
Internals
| Page | Description |
|---|---|
| Codebase Review | Architecture findings, duplication hotspots, and prioritized follow-up PR slices |
Repository validation commands
These run in CI and are safe to run locally before opening a PR:
| Command | What it does |
|---|---|
npm run validate:css-vars | Audits every --lcars-*, --lcards-*, and theme: reference against the allowlists in scripts/ha-lcars-theme-vars.js and src/lcards-vars.js. Gates npm run build. |
npm run validate:doc-examples | Parses every fenced yaml/yml block in doc/**.md, checks that any type: custom:lcards-* value matches a registered element, and validates parsed card configs against the real JSON Schemas from src/cards/schemas/ (7 card types covered; lcards-msd-card excluded). Add --strict to promote schema and parse warnings to errors. Two fence meta hints: ```yaml alternatives skips YAML parsing but still checks type refs; ```yaml no-validate skips the block entirely. |
npm run typecheck | Runs tsc against the JSDoc-typed sources. |
npm run docs:build | Builds the VitePress site. |