Firmware design-system handoff (skill)
Use this skill when a user has an existing firmware repo with a
hand-rolled web UI (LittleFS / SPIFFS / similar partition, no build
step on the device) and wants the design layer rebuilt as a real,
token-driven design system that:
- ships as a drop-in package, not a refactor PR,
- backs up the existing
data/ before touching anything,
- leaves behavior untouched (no JS rewrites beyond minimum hooks),
- comes with a visual regression page hosted on the device itself,
- is applyable on Windows with a double-click.
Inputs to gather (questions_v2 first)
Always ask these before writing anything:
- Repo + screen list. Which firmware (path / repo URL), and which
pages/screens does the UI have? Need: home, settings, log/monitor,
one or more device-specific control panels, file explorer, etc.
- Existing CSS state. Are there hand-rolled stylesheets per page,
or one global CSS, and is there a dark-mode variant? Get the file
names — they show up in the apply script's plan.
- Theme toggle mechanism.
body.dark class? [data-theme] attr?
localStorage key? Match the existing convention so the toggle keeps
working.
- Chart library. ECharts? Chart.js? None? CDN or self-host? If
CDN: which version is pinned. The skill emits a chart-theme
helper that reads CSS vars regardless of library.
- Fonts. Self-hosted WOFF2 (preferred for offline devices) or
system stack? File-size budget if relevant — embedded partitions
are usually 1-2 MB.
- Variations to expose as Tweaks. Optional — usually no, this is
production output, not a design exploration.
- Scope. Just the design layer, or also a list of bugs/issues
that need to be fixed alongside (e.g. "the X panel is broken").
- Branding constraints. Which colors are "the brand"? What can
be changed and what is sacred?
- Iconography. Self-host PNG/SVG, icon font, or no icons?
- Apply target. Windows / macOS / Linux for the script. Default
to Windows since most firmware-flashing flows are Windows.
Package structure to emit
<project_name>_design_package/
├── README.md
├── handoff.md
├── SKILL.md <-- this file, for next time
├── apply.ps1
├── apply.bat
├── data/ <-- mirrors firmware data/ structure
│ ├── ds-tokens.css
│ ├── components.css
│ ├── theme-toggle.js
│ ├── <chart>-theme.js
│ ├── design.html
│ └── fonts/
└── templates/
├── index.html.template
└── <each-page>.html.template
Hard rules
- One tokens file. All color, type, space, radius, shadow, motion.
Light + dark via the existing convention (
body.dark AND
[data-theme="dark"] for safety). No second source of truth.
- components.css uses var(--*) only. Zero raw hex outside
ds-tokens.css. Search for
#[0-9a-f] after writing — should match
zero lines.
- Match existing class names. components.css must shadow the
legacy CSS without markup changes for as many components as
possible. The user removes the legacy CSS in the final patch, not
the first.
- Sentinels in templates. Every patch block in
templates/*.template
is wrapped in <!-- DS:NAME:BEGIN --> … <!-- DS:NAME:END -->
comments so the receiver knows exactly what to paste.
- Idempotent JS hooks. Use a
data-bound="1" attribute on each
bound element so re-running on a re-rendered DOM doesn't double-bind.
Listen for a project-specific <page>:rendered event for re-binding.
- Chart theme reads tokens. Helper function calls
getComputedStyle(document.body).getPropertyValue('--…') so theme
swap is one chart.setOption(theme(), true) call.
- Backup before copy. apply.ps1 always writes a timestamped zip
unless
-NoBackup. Default mode is interactive (y/n/q per file);
-Force skips prompts; -WhatIf is a dry run.
- No git, no build, no flash. Script copies files. handoff.md
documents what's left for the receiver (Claude Code).
- /design.html lives on the device. Renders every component in
light and dark side-by-side. Hosting it from the firmware means
visual regression after each flash is one URL away.
Output discipline
- ds-tokens.css opens with a comment block explaining the dual-selector
convention and the apply order.
- components.css has a numbered table-of-contents at the top.
- Each template's leading comment names the file it patches and the
scope (full replace vs. block replace vs. append).
- handoff.md is structured as Patch A/B/C/D/E with explicit commit
messages. The receiver should be able to land each as a separate
PR if they want.
- README.md has Quick Start, Apply Order, Smoke Test, Rollback,
"What the script does/doesn't do" — in that order.
- apply.ps1 uses
[CmdletBinding(SupportsShouldProcess=$true)] so
-WhatIf works without extra code.
Anti-patterns to avoid
- Self-hosting a chart library "for offline use" without checking
with the user — it bloats the partition and is rarely worth it.
Default to CDN, document the fallback.
- Hand-rolled icons. Use what's already in the firmware's
assets/
or text labels. Don't invent SVG icons.
- Adding routes/handlers to the firmware's HTTP server. The design
layer is files-only; routes are out of scope.
- Aggressive markup refactors. If a class name already exists, match
it. The receiver should be able to land the package without
rewriting partials.
When NOT to use this skill
- One-off styling tweaks (use a single PATCH.md instead).
- The user wants to explore design directions (use design_canvas).
- A from-scratch new firmware UI (build with the standard frontend
design skill; this skill is for retrofitting an existing repo).
1---2name: firmware-design-system-handoff3description: |4 Generate a complete, self-contained design-system package for an5 embedded device's on-device web UI — one tokens file, one component6 library, a /design.html reference page, page-templates with7 sentinel-marked patch blocks, a Windows installer script (PS1 + .bat8 wrapper), and a handoff.md aimed at Claude Code for the markup edits9 and per-patch commits.10metadata:11 source: https://skillmd.com/skills/rvdbreemen/firmware-design-system-handoff12---1314# Firmware design-system handoff (skill)1516Use this skill when a user has an existing firmware repo with a17hand-rolled web UI (LittleFS / SPIFFS / similar partition, no build18step on the device) and wants the design layer rebuilt as a real,19token-driven design system that:2021- ships as a drop-in package, not a refactor PR,22- backs up the existing `data/` before touching anything,23- leaves behavior untouched (no JS rewrites beyond minimum hooks),24- comes with a visual regression page hosted on the device itself,25- is applyable on Windows with a double-click.2627## Inputs to gather (questions_v2 first)2829Always ask these before writing anything:30311. **Repo + screen list.** Which firmware (path / repo URL), and which32 pages/screens does the UI have? Need: home, settings, log/monitor,33 one or more device-specific control panels, file explorer, etc.342. **Existing CSS state.** Are there hand-rolled stylesheets per page,35 or one global CSS, and is there a dark-mode variant? Get the file36 names — they show up in the apply script's plan.373. **Theme toggle mechanism.** `body.dark` class? `[data-theme]` attr?38 localStorage key? Match the existing convention so the toggle keeps39 working.404. **Chart library.** ECharts? Chart.js? None? CDN or self-host? If41 CDN: which version is pinned. The skill emits a chart-theme42 helper that reads CSS vars regardless of library.435. **Fonts.** Self-hosted WOFF2 (preferred for offline devices) or44 system stack? File-size budget if relevant — embedded partitions45 are usually 1-2 MB.466. **Variations to expose as Tweaks.** Optional — usually no, this is47 production output, not a design exploration.487. **Scope.** Just the design layer, or also a list of bugs/issues49 that need to be fixed alongside (e.g. "the X panel is broken").508. **Branding constraints.** Which colors are "the brand"? What can51 be changed and what is sacred?529. **Iconography.** Self-host PNG/SVG, icon font, or no icons?5310. **Apply target.** Windows / macOS / Linux for the script. Default54 to Windows since most firmware-flashing flows are Windows.5556## Package structure to emit5758```59<project_name>_design_package/60├── README.md61├── handoff.md62├── SKILL.md <-- this file, for next time63├── apply.ps164├── apply.bat65├── data/ <-- mirrors firmware data/ structure66│ ├── ds-tokens.css67│ ├── components.css68│ ├── theme-toggle.js69│ ├── <chart>-theme.js70│ ├── design.html71│ └── fonts/72└── templates/73 ├── index.html.template74 └── <each-page>.html.template75```7677## Hard rules7879- **One tokens file.** All color, type, space, radius, shadow, motion.80 Light + dark via the existing convention (`body.dark` AND81 `[data-theme="dark"]` for safety). No second source of truth.82- **components.css uses var(--*) only.** Zero raw hex outside83 ds-tokens.css. Search for `#[0-9a-f]` after writing — should match84 zero lines.85- **Match existing class names.** components.css must shadow the86 legacy CSS without markup changes for as many components as87 possible. The user removes the legacy CSS in the final patch, not88 the first.89- **Sentinels in templates.** Every patch block in `templates/*.template`90 is wrapped in `<!-- DS:NAME:BEGIN -->` … `<!-- DS:NAME:END -->`91 comments so the receiver knows exactly what to paste.92- **Idempotent JS hooks.** Use a `data-bound="1"` attribute on each93 bound element so re-running on a re-rendered DOM doesn't double-bind.94 Listen for a project-specific `<page>:rendered` event for re-binding.95- **Chart theme reads tokens.** Helper function calls96 `getComputedStyle(document.body).getPropertyValue('--…')` so theme97 swap is one `chart.setOption(theme(), true)` call.98- **Backup before copy.** apply.ps1 always writes a timestamped zip99 unless `-NoBackup`. Default mode is interactive (y/n/q per file);100 `-Force` skips prompts; `-WhatIf` is a dry run.101- **No git, no build, no flash.** Script copies files. handoff.md102 documents what's left for the receiver (Claude Code).103- **/design.html lives on the device.** Renders every component in104 light and dark side-by-side. Hosting it from the firmware means105 visual regression after each flash is one URL away.106107## Output discipline108109- ds-tokens.css opens with a comment block explaining the dual-selector110 convention and the apply order.111- components.css has a numbered table-of-contents at the top.112- Each template's leading comment names the file it patches and the113 scope (full replace vs. block replace vs. append).114- handoff.md is structured as Patch A/B/C/D/E with explicit commit115 messages. The receiver should be able to land each as a separate116 PR if they want.117- README.md has Quick Start, Apply Order, Smoke Test, Rollback,118 "What the script does/doesn't do" — in that order.119- apply.ps1 uses `[CmdletBinding(SupportsShouldProcess=$true)]` so120 `-WhatIf` works without extra code.121122## Anti-patterns to avoid123124- Self-hosting a chart library "for offline use" without checking125 with the user — it bloats the partition and is rarely worth it.126 Default to CDN, document the fallback.127- Hand-rolled icons. Use what's already in the firmware's `assets/`128 or text labels. Don't invent SVG icons.129- Adding routes/handlers to the firmware's HTTP server. The design130 layer is files-only; routes are out of scope.131- Aggressive markup refactors. If a class name already exists, match132 it. The receiver should be able to land the package without133 rewriting partials.134135## When NOT to use this skill136137- One-off styling tweaks (use a single PATCH.md instead).138- The user wants to explore design directions (use design_canvas).139- A from-scratch new firmware UI (build with the standard frontend140 design skill; this skill is for retrofitting an existing repo).