Home

🇨🇳 中文 | 🇺🇸 English

Skins Pro — Wiki

Welcome to the Skins Pro wiki! This guide covers features, usage, configuration, skin development, and code development.

⚠️ Layout broken? First step: clear your browser cache.
Press Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac) to hard refresh.
If that doesn't help, clear all cached data for your HA domain in browser settings.
Skins Pro caches aggressively — cache issues are the #1 cause of visual glitches.

Overview

Skins Pro is a community Lovelace card for Home Assistant that transforms your dashboard into an immersive, multi-skin experience. It ships with a modern glassmorphism skin and offers additional community skins via the built-in skin store.

Key highlights:

Multi-skin architecture — switch between skins freely
Bilingual (CN/EN) — auto-detects your HA language
Fullscreen Kiosk mode — immersive experience
Force kiosk lock for non-admin users — block right-click & dev tools
Auto icon resolution — reads icons directly from HA entities
Mobile responsive — works on phones and tablets

Features & Usage

🏠 Home Page

The main dashboard shows a welcome greeting, weather forecast, devices, rooms, scenes, energy usage, and environment sensors — all organized by area.

Views:

Home — Main dashboard with all sections
Devices — All devices grouped by type
Rooms — Rooms with snapshots and scene shortcuts
Scenes — Quick scene activation
Automations — Automation list
Security — Cameras, locks, alarm control panel
Energy — Energy consumption comparison

☀️ Weather & Greeting

The welcome section shows:

A customizable greeting (name + message)
Current weather condition with icon, temperature, and forecast
Optional: camera snapshot, time, date, and environment sensors (when camera is enabled)

Usage: Configure the greeting text in the card editor under "Info Display". Weather entity is auto-detected or configured in "Weather" settings.

📱 Device Controls

Devices are displayed by room or by type. Supported controls:

Light — brightness slider, color temperature, color picker, switch
Switch — toggle switch
Cover — position slider
Climate — temperature control (± buttons), mode display
Water Heater — temperature control
Fan — speed control, oscillation, direction
Humidifier — humidity target control
Vacuum — start, pause, dock, locate buttons
Media Player — play/pause, skip tracks, volume slider
Lock — lock/unlock toggle
Alarm Control Panel — arm/disarm with mode selection

Usage: Devices are auto-detected from HA. In the card editor, you can filter by area or device type. The "quick control" section on the home page shows the most recently used devices.

🚪 Room Snapshots

Each room displays a background image with device icons and room-specific scene chips. Click the room to see all devices.

Background images:

Use HA area pictures (set in HA: Settings → Areas → Edit → Picture)
Upload custom room images in the card editor
Skin-provided room images

🎬 Scene Buttons

One-click scene activation. Scenes are auto-detected from HA. Enable/disable specific scenes in the card editor.

🛡️ Security Page

Auto-detected security devices:

Cameras — live snapshot, click to view more info
Alarm Control Panel — auto-detected, click to arm/disarm, mode selection (away/home/night/vacation)
Locks — lock/unlock status

🎵 Media Player

Full media player card on the home page:

Album art display
Play/pause, skip previous/next
Volume slider with mute toggle
Auto-detects current media source

🌡️ Environment Sensors

Display sensor values like temperature, humidity, CO₂, PM2.5, etc. Icons are automatically resolved from Home Assistant's entity settings.

Display modes:

Sidebar — full list with icons and values
Inline — compact row layout (shown in welcome area when camera is enabled)

Floor grouping: When HA has multiple floors configured, sensors are automatically grouped by floor.

🌙 Dark Mode

Auto — switches at sunset/sunrise based on your HA location
Manual — tap the clock to toggle
Skin support — skins can provide dark-optimized assets and CSS

🔍 Global Search

Search all devices by name. Filter by type (lights, switches, climate, etc.). Fuzzy matching finds results even with partial names.

↔️ Kiosk Mode

Fullscreen mode that hides the HA sidebar and header for an immersive experience.

Admin behavior: Click the avatar to toggle kiosk on/off.

Non-admin behavior: Kiosk is forced automatically. Right-click and dev tools shortcuts (F12, Ctrl+Shift+I/J/C) are blocked. No way to exit kiosk from the UI.

📱 Mobile Responsive

The layout automatically adapts to portrait and landscape orientations on phones and tablets. Navigation switches to a bottom tab bar on mobile.

Configuration

Card Editor Settings

After adding Skins Pro to your dashboard, click the card to open the editor:

General:

Title — Custom dashboard title (bilingual CN/EN)
Language — Auto or force CN/EN

Skin:

Skin — Select from installed skins
Skin Mode — Light/Dark/Auto
Downloaded Skins — Manually list locally installed skins

Layout:

Fullscreen — Enable kiosk mode
Sidebar Hidden — Hide sidebar on startup
Filter Room — Show only specific rooms
Filter Type — Show only specific device types
Hide Unassigned — Hide devices not assigned to any room

Home Page:

Weather — Select weather entity
Info Display — Choose info entity for greeting quote
Camera — Select camera entity for homepage snapshot
Media Player — Select media player entity
Environment Sensors — Pick sensor entities to display

Energy:

Energy Entity — Energy sensor for daily comparison

Rooms:

Scenes — Enable/disable specific scenes per room
Room Background — Upload custom images

Environment Sensor Configuration

Sensors can be added in two ways:

Auto-detect — Add entity IDs to home_selection.environment, icons auto-resolve from HA
Manual config — Configure config.environment[] with explicit entity, label, unit, icon, variant fields

Full Configuration Reference

For advanced configuration, the card editor generates JSON that you can further customize. Example:

{
  "type": "custom:skins-pro-card",
  "title": "My Home",
  "title_zh": "我的家",
  "fullscreen": true,
  "resource_pack": { "skin": "modern" },
  "weather": { "entity": "weather.home" },
  "home_selection": {
    "environment": ["sensor.temperature", "sensor.humidity"]
  }
}

Skin Development

A skin is a folder under skins-pro/<skin-name>/ containing images, CSS, and metadata. npm run build auto-discovers, processes images, and generates code.

Directory Structure

skins-pro/
  your-skin-name/
    theme.css               # Styles (required)
    strings.json            # Strings + icon_map + author + version (required)
    avatar.jpg              # Avatar, recommended ≥ 300×300
    background.jpg          # Background, recommended width ≥ 2560px
    decoration.jpg          # Side decoration, recommended height ≥ 400px
    base-texture.jpg        # Base texture, recommended width ≥ 2560px
    stage-*.jpg             # Stage image, recommended width ≥ 2560px
    room-*.jpg              # Room image, recommended width ≥ 1200px
    icon-*.jpg              # Device icon, recommended longest edge ≥ 300px

Required Files

File	Purpose
`theme.css`	All styles via CSS variables on `:host`. See `src/skins/modern/theme.css`
`strings.json`	Greeting text + `icon_map`. Must include a non-empty `author` field
`avatar.*` (png/jpg)	Avatar image, recommended ≥ 300×300
`background.*` (png/jpg)	Main background, recommended width ≥ 2560px
`screenshots/<skin-name>.png`	Store preview image. Filename must match the skin folder name exactly

Dark Mode Assets (optional)

To support dark mode, place -dark variants alongside the originals — same extension, with -dark appended before the extension:

skins-pro/your-skin-name/
  background-dark.jpg      # Dark variant of background.jpg
  icon-light-dark.jpg      # Dark variant of icon-light.jpg
  room-living-dark.jpg     # Dark variant of room-living.jpg
  ...                      # One -dark file per original

Also add :host([data-sp-theme="dark"]) { ... } in theme.css to override CSS variables for dark colors. See src/skins/modern/theme.css for a reference implementation.

Image Processing on Build

Pattern	Recommended source	Notes
`room-*`	width ≥ 1200px	Maintain ratio, downscale to 1200px
`icon-*`	longest edge ≥ 300px	Maintain ratio, downscale to 300px
`avatar.*`	longest edge ≥ 300px	Maintain ratio, downscale to 300px
`decoration.*`	height ≥ 400px	Maintain ratio, downscale to height 400px
`background.`, `base-`, `stage-*`	width ≥ 2560px	Maintain ratio, downscale to 2560px
others	width ≥ 1200px	Maintain ratio, downscale to 1200px

Supports PNG / JPG / BMP / WebP input. Icons, avatars, and decorations output as PNG; everything else as JPG. Never upscales.

theme.css

All styles are customized via CSS variables on :host. Each skin has its own theme.css. The :host block defines ~120+ CSS variables covering:

Colors — text, accent, backgrounds, glass effects, device states
Spacing — uniform spacing tokens (--sp-space-3xs through --sp-space-xl)
Typography — fluid font sizes via clamp()
Layout — sidebar width, stage padding, card/room/scene min widths
Shadows — neumorphism, card, glass, device, scene shadows
Radius — border radius tokens for all element types

See src/skins/modern/theme.css for the full variable list and reference implementation.

CSS architecture:

:host — CSS variable definitions
.mc-app — main layout grid (sidebar + stage)
.stage-grid — home page grid (welcome, side, bottom)
.welcome-group — greeting + weather/environment section
.side — sidebar panel (environment, energy, media, scenes)
.bottom-stack — devices + rooms section
.device, .room, .scene — card components
.env-row — environment sensor rows
.media-actions — media player controls
@media (orientation: portrait) — responsive layout for mobile
:host([data-sp-theme="dark"]) — dark mode overrides
@container sp (max-width: ...) — container queries for responsive sizing

strings.json + icon_map + author + version

{
  "version": "1.0.0",
  "author": "your-github-username",
  "dark_mode": true,
  "title_zh": "欢迎回来！",
  "title_en": "Welcome back!",
  "icon_map": {
    "light": "light",
    "switch": "switch",
    "climate": "climate",
    "media_player": "speaker",
    "lock": "lock"
  }
}

version — Skin version string (e.g. "1.0.0"). Displayed in the store.
author — Your GitHub username (without @). Displayed in the store and linked to your profile.
dark_mode — Optional. Set to true if your skin provides dark variant assets. Defaults to false.
icon_map — Maps entity domains to icon image filenames. Unmapped domains fall back automatically.

Icon Naming Convention

Icon files match the domain of the entity they represent:

light → icon-light.jpg (for all light entities)
switch → icon-switch.jpg
climate → icon-climate.jpg
media_player → icon-speaker.jpg (configurable via icon_map)
sensor → icon-sensor.jpg

Best reference — Use visionOS/ as the starting point when creating a new skin. It has the most complete icon_map, theme.css, and icon assets.

Testing a New Skin Locally

You don't need the store to test a new skin. Just:

Create your skin folder under skins-pro/<new-skin-name>/ with the usual files (theme.css, strings.json, images)
Run npm run build -- <new-skin-name> --skins-only — processes only your skin's images, outputs to dist/<new-skin-name>/

Copy dist/<new-skin-name>/ to your HA www/ folder:

<HA config>/www/skins-pro/<new-skin-name>/
  ├── theme.css
  ├── avatar.jpg
  ├── background.jpg
  ├── room-*.jpg
  ├── icon-*.jpg
  └── ... (all files from your skin directory)

In the Skins Pro card editor, add the skin name to downloaded_skins:
```
"downloaded_skins": ["<new-skin-name>"]
```
This tells the card the skin is already installed, so it shows up in the skin dropdown right away. Select it and hard refresh.

That's it — no store, no PR needed for local testing. When you're happy with the result, open a PR to share it.

Code Development

Prerequisites

Node.js 18+
npm

Setup

git clone https://github.com/ha-china/Skins-Pro.git
cd Skins-Pro
npm install

Build Commands

npm run build                            # Build everything
npm run build -- <skin-name>             # Build only one skin + modern (faster)
npm run build -- <skin-name> --skins-only  # Process skin images only, no JS rebuild
npm run watch                            # Auto-rebuild on file changes
npm run type-check                       # Check for code errors

Build Output

dist/skins-pro.js — The main JS file (the only file you need for HA)
dist/modern/ — The built-in modern skin's images and CSS
dist/<skin-name>/ — Each additional skin's assets

Project Structure

src/
├── skins-pro-card.ts         # Main card component (LitElement)
├── types.ts                  # TypeScript interfaces
├── index.ts                  # Entry point
├── components/               # UI components
│   ├── device-card.ts        # Device control card
│   ├── media-player.ts       # Media player panel
│   ├── weather.ts            # Weather display
│   ├── environment.ts        # Environment sensors
│   ├── nav.ts                # Sidebar navigation
│   ├── alarm-control-panel.ts # Alarm panel
│   ├── climate.ts            # Climate control
│   ├── fan.ts                # Fan control
│   ├── humidifier.ts         # Humidifier control
│   ├── vacuum.ts             # Vacuum control
│   ├── water-heater.ts       # Water heater control
│   ├── light.ts              # Light control (color, brightness)
│   └── maintenance.ts        # Maintenance card
├── views/                    # Page views
│   ├── home.ts               # Home page
│   ├── devices.ts            # Devices page
│   ├── rooms.ts              # Rooms page
│   ├── scenes.ts             # Scenes page
│   ├── automations.ts        # Automations page
│   ├── security.ts           # Security page
│   ├── energy.ts             # Energy page
│   └── search.ts             # Global search overlay
├── ha/                       # HA integration layer
│   ├── kiosk.ts              # Kiosk mode CSS injection
│   └── energy.ts             # Energy data fetching
├── render/                   # Rendering utilities
│   ├── layout.ts             # Layout calculations
│   └── context.ts            # Render context
├── utils/                    # Utilities
│   └── index.ts              # Shared helpers
├── skins/                    # Bundled skins
│   ├── generated.ts          # Auto-generated skin registry
│   └── modern/               # Modern skin
│       └── theme.css         # 770+ lines of CSS
└── editor/                   # Card editor
    ├── template.ts           # Editor UI template
    ├── events.ts             # Editor event handling
    └── skin-store.ts         # Skin store management

Key Architecture Decisions

Shadow DOM: The card uses open Shadow DOM for style isolation. Each skin's theme.css is loaded via <link> inside the shadow root, preventing style leakage.

CSS Variables: All styling is driven by ~120+ CSS variables defined on :host. Skins customize these variables. The build system injects user-configured theme overrides as inline styles on the host element.

HA Native Components: The card uses HA's <ha-state-icon> for entity icons — this delegates icon resolution (including device_class defaults) to HA's own frontend logic.

Responsive: Layout uses CSS Grid with grid-template-areas, fluid clamp() font sizes, and container queries for responsive sizing.

Testing in Home Assistant

Build the project:
```
npm run build
```
Copy dist/skins-pro.js to your HA www/ folder:
```
<HA config>/www/skins-pro.js
```
Add it as a dashboard resource in Home Assistant:
Settings → Dashboards → Resources → Add Resource
- URL: /local/skins-pro.js
- Type: JavaScript Module
Hard refresh (Ctrl+Shift+R) your browser.

After that, every time you npm run build, just replace www/skins-pro.js and hard refresh to see changes.

Tip — If the built-in modern skin images or styles are not loading, also copy dist/modern/ to www/community/skins-pro/modern/:
<HA config>/www/community/skins-pro/modern/  ← copy dist/modern/ here

Contributing

Contributing a Skin

We welcome skin contributions! Simply:

Create a skin folder under skins-pro/<skin-name>/ with the required files (see Skin Development above)
Add a preview screenshot screenshots/<skin-name>.png (1920×1080 recommended)
Submit a PR using the PR template — fill in all required fields

Once merged, CI automatically builds the card and makes it available in the card editor's skin store.

⚠️ Copyright Notice — When contributing skins, please ensure your image assets do not infringe on others' copyright. We recommend using AI-generated or original images. Skins with valid copyright complaints will be removed from the store.

After submitting, a bot will automatically post a Screenshot Preview comment showing your skin's preview image.

Tips for Skin Creators

Use visionOS/ as the reference — it has the most complete icon_map and assets
Images are auto-processed on build (resize, JPG output) — no manual optimization needed
icon_map in strings.json maps entity domains to icon filenames; unmapped domains fall back automatically
Test locally before submitting a PR (see Testing a New Skin Locally)
Preview images are generated automatically by the CI bot after PR submission

Contributing Code

Bug fixes, improvements, and new features are welcome:

Fork the repository
Create a feature branch
Make your changes
Run npm run build and npm run type-check to verify
Submit a PR

Reporting Issues

Report bugs and feature requests on the GitHub Issues page.

Uh oh!

Home

Skins Pro — Wiki

Table of Contents

Overview

Features & Usage

🏠 Home Page

☀️ Weather & Greeting

📱 Device Controls

🚪 Room Snapshots

🎬 Scene Buttons

🛡️ Security Page

🎵 Media Player

🌡️ Environment Sensors

🌙 Dark Mode

🔍 Global Search

↔️ Kiosk Mode

📱 Mobile Responsive

Configuration

Card Editor Settings

Environment Sensor Configuration

Full Configuration Reference

Skin Development

Directory Structure

Required Files

Dark Mode Assets (optional)

Image Processing on Build

theme.css

strings.json + icon_map + author + version

Icon Naming Convention

Testing a New Skin Locally

Code Development

Prerequisites

Setup

Build Commands

Build Output

Project Structure

Key Architecture Decisions

Testing in Home Assistant

Contributing

Contributing a Skin

Tips for Skin Creators

Contributing Code

Reporting Issues

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally