signage-performance-budget

Files (1)

• SKILL.md

SKILL.md (first lines)

# Signage Performance Budget Skill

## Purpose

Use this skill to check whether a signage app will run smoothly on embedded playback hardware.

React developers routinely ship 2 MB font files, heavy animation libraries, and unoptimized images that work fine on modern laptops but cripple a BrightSign player or similar embedded device. This skill encodes the actual constraints of signage hardware and provides actionable budgets.

## When to Use

Use this skill when you need to:

- review a signage app's bundle size and asset weight
- check whether animations or transitions will run smoothly on embedded hardware
- optimize images, fonts, and JavaScript for resource-constrained players
- establish performance budgets for a new signage project
- diagnose performance issues on deployed signage hardware

## Do Not Use When

Do not use this skill when:

- building a desktop or mobile web app with modern hardware targets
- the deployment target is a high-end PC or media player with desktop-class resources
- the task is about layout, legibility, or content design (use other signage skills)

## Core Principle

**Signage hardware is not a laptop. Budget for embedded ARM processors, limited RAM, and no GPU acceleration for complex CSS.**

## Performance Budgets

### JavaScript Bundle

| Metric                | Target   | Hard Limit | Notes                        |
| --------------------- | -------- | ---------- | ---------------------------- |
| Main bundle (gzipped) | < 150 KB | < 300 KB   | Total JS loaded on boot      |
| Total JS (gzipped)    | < 250 KB | < 500 KB   | Including lazy-loaded chunks |
| Third-party libraries | < 100 KB | < 200 KB   | Avoid heavy frameworks/libs  |

### Assets

| Metric                  | Target   | Hard Limit | Notes                               |
| ----------------------- | -------- | ---------- | ----------------------------------- |
| Total page weight       | < 1 MB   | < 2 MB     | All assets for initial render       |
| Individual image        | < 200 KB | < 500 KB   | After optimization                  |
| Total images per screen | < 500 KB | < 1 MB     | All images visible at once          |
| Font files (total)      | < 100 KB | < 250 KB   | Subset aggressively                 |
| Video/animation assets  | < 5 MB   | < 10 MB    | Pre-optimized for target resolution |

### Runtime Performance

| Metric                      | Target      | Minimum              | Notes                          |
| --------------------------- | ----------- | -------------------- | ------------------------------ |
| First contentful paint      | < 2 seconds | < 4 seconds          | From app load, not player boot |
| Frame rate during animation | 30 fps      | 24 fps               | Smooth perceived motion        |
| Memory usage (steady state) | < 100 MB    | < 200 MB             | After initial load stabilizes  |
| Layout recalculations       | Minimal     | No continuous reflow | Avoid per-frame layout thrash  |
| CPU usage (idle)            | < 10%       | < 25%                | When content is static         |

## Common Performance Traps

### JavaScript

| Trap                                                 | Problem                        | Solution                                                   |
| ---------------------------------------------------- | ------------------------------ | ---------------------------------------------------------- |
| Heavy animation libraries (GSAP, Framer Motion full) | Large bundle, high CPU         | Use CSS animations/transitions, or tree-shake aggressively |
| Full icon libraries                                  | 500 KB+ for a few icons        | Import individual icons only                               |
| Moment.js, Lodash (full)                             | Massive unused code            | Use date-fns, native methods, or targeted imports          |
| Polyfills for old browsers                           | Unnecessary weight             | BrightSign uses Chromium — target modern JS                |
| React dev mode in production                         | 2× bundle size, slow rendering | Ensure production builds                                   |

### Images

| Trap                                 | Problem               | Solution                                                  |
| ------------------------------------ | --------------------- | --------------------------------------------------------- |
| Unoptimized PNGs/JPEGs               | 2–5 MB per image      | Compress, resize to display resolution, use WebP          |
| 4K images on 1080p screens           | 4× the pixels needed  | Size images to deployment resolution                      |
| Many small decorative images         | HTTP request overhead | Use CSS, SVG inline, or sprite sheets                     |
| Background images at full resolution | Massive file size     | Compress aggressively — backgrounds tolerate quality loss |

### Fonts

| Trap                             | Problem                    | Solution                                            |
| -------------------------------- | -------------------------- | --------------------------------------------------- |
| Full Google Fonts downloads      | 500 KB–2 MB per family     | Subset to characters actually used                  |
| Multiple font weights/styles     | Compounds file size        | Use 2–3 weights maximum                             |
| Web font loading blocking render | Delays first paint         | Use `font-display: swap` and preload critical fonts |
| Custom fonts loaded from CDN     | Network dependency at boot | Bundle fonts locally for signage                    |

### CSS and Rendering

| Trap                                       | Problem                            | Solution                             |
| ------------------------------------------ | ---------------------------------- | ------------------------------------ |
| Complex box-shadows and filters            | GPU-intensive on embedded hardware | Use simple shadows or none           |
| CSS backdrop-filter / blur                 | Very expensive on weak GPUs        | Avoid or use sparingly               |
| Continuous CSS animations on many elements | Frame drops                        | Limit simultaneous animations to 2–3 |
| Large numbers of DOM nodes                 | Slow rendering and reflow          | Keep DOM under 500 nodes per screen  |

## Measurement and Verification

### Build-Time Checks

```bash
# Check bundle size after build
du -sh dist/assets/*.js
du -sh dist/assets/*.css

# Check total asset weight
du -sh dist/

# Check for production mode
grep -r "process.env.NODE_ENV" dist/ | head
```

### Runtime Checks

- Use Chrome DevTools Performance tab to measure frame rate and CPU usage.
- Use Chrome DevTools Network tab to measure total transfer size.

From CambridgeMonorail/WallRun, MIT.

More from CambridgeMonorail/WallRun