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 |
| Backend WS API | lcards/* WebSocket commands: storage, HA service targeting, degraded mode |
| 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 |
CSS & Theming
| Page | Description |
|---|---|
| HA CSS Variable Reference | Every HA 2026.6+ CSS variable, its default value, and current LCARdS usage |
Internals
| Page | Description |
|---|
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 and view configs against the real JSON Schemas listed in scripts/lib/card-schemas.js (every card including MSD, plus the layout view). 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 validate:schema-descriptions | Fails when a schema property is added without a description (descriptions are published in lcards-schema.json). The existing backlog is listed in scripts/schema-description-baseline.txt; after filling some, run npm run validate:schema-descriptions:update. Gates npm run build. |
npm run typecheck | Runs tsc against the JSDoc-typed sources. |
npm run docs:build | Builds the VitePress site. |
npm run generate:llm-schema | Writes the published JSON Schemas: lcards-schema.json (everything) and schema/ (an index, one file per card, view and strategy, and shared/ for the big subsystems), into doc/public/ (gitignored). Runs inside docs:build and docs:serve. |