Skip to content

Commit 5cc9a9a

Browse files
cryptomilkclaude
andcommitted
skills: update implement-widget to reflect transparent SVG backgrounds
After commit be80841 removed per-widget white background rects, the skill's blanket "every template must start with a white rect" rule became wrong. Update the guidance: only templates whose rendered geometry is smaller than the SVG viewport (separator-style) need the white rect; card-style and chip-style templates omit it because the alpha-mask compositing in render_dashboard() handles transparency correctly. Also switch the simple-pattern example from hardcoded fill="white" to {{ hex_white }} to match the actual separator template. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent b5287a8 commit 5cc9a9a

1 file changed

Lines changed: 28 additions & 12 deletions

File tree

.agents/skills/implement-widget/SKILL.md

Lines changed: 28 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -151,20 +151,29 @@ The template receives a pre-computed context dict from the Python
151151
context builder. All layout math (positions, sizes, icon SVG strings,
152152
chip widths) is computed in Python. Templates only emit SVG markup.
153153

154-
Every template must begin with a white background rect so the widget
155-
is opaque when composited onto the dashboard canvas:
156-
157-
```xml
158-
<rect width="{{ w }}" height="{{ h }}" fill="white"/>
159-
```
154+
Widget SVGs are composited onto a white canvas using the alpha
155+
channel as a mask (`render_dashboard()` in `render.py`). Transparent
156+
pixels preserve whatever is already on the canvas (white by default),
157+
so most templates do **not** need a white background rect.
158+
159+
Add a full-viewport white background rect **only** when the template's
160+
rendered geometry is smaller than its SVG viewport — i.e. when content
161+
does not fill `w` × `h`. The separator is the canonical example: its
162+
bar (`bar_w` × `bar_h`) is much smaller than the widget viewport, so
163+
surrounding transparent area would let earlier widget content bleed
164+
through without the rect.
165+
166+
Card-style and chip-style templates omit the rect because the card
167+
chrome (via `card_container`) or chip flow covers the meaningful area,
168+
and any remaining transparent edge pixels are harmless (canvas is
169+
white).
160170

161171
**Card-style template pattern** (tile, waste_schedule):
162172

163173
```jinja
164174
{%- from "_macros.svg.j2" import card_container, card_row -%}
165175
<svg xmlns="http://www.w3.org/2000/svg"
166176
width="{{ w }}" height="{{ h }}">
167-
<rect width="{{ w }}" height="{{ h }}" fill="white"/>
168177
{%- call(x_off, r_inset) card_container(
169178
x=0, y=0, w=w, h=h,
170179
card_style=card_style,
@@ -204,7 +213,6 @@ is opaque when composited onto the dashboard canvas:
204213
{%- from "_macros.svg.j2" import chip -%}
205214
<svg xmlns="http://www.w3.org/2000/svg"
206215
width="{{ w }}" height="{{ h }}">
207-
<rect width="{{ w }}" height="{{ h }}" fill="white"/>
208216
{%- for c in chips -%}
209217
{{ chip(
210218
x=c.x, y=c.y, w=c.w, h=chip_h,
@@ -215,12 +223,16 @@ is opaque when composited onto the dashboard canvas:
215223
</svg>
216224
```
217225

218-
**Simple template pattern** (text, separator):
226+
**Simple template pattern** (separator):
227+
228+
When rendered geometry (e.g. a bar or line) is smaller than the SVG
229+
viewport, include a full-size white rect before it so the surrounding
230+
area is not transparent:
219231

220232
```jinja
221233
<svg xmlns="http://www.w3.org/2000/svg"
222234
width="{{ w }}" height="{{ h }}">
223-
<rect width="{{ w }}" height="{{ h }}" fill="white"/>
235+
<rect width="{{ w }}" height="{{ h }}" fill="{{ hex_white }}"/>
224236
<!-- widget-specific SVG elements here -->
225237
</svg>
226238
```
@@ -470,8 +482,12 @@ behavior.
470482
- **All layout math in Python.** Templates receive final coordinates
471483
and data. No arithmetic or conditionals in Jinja2 beyond what the
472484
macros already compute internally.
473-
- **White background rect.** Every template starts with
474-
`<rect width="{{ w }}" height="{{ h }}" fill="white"/>`.
485+
- **White background rect.** Only add
486+
`<rect width="{{ w }}" height="{{ h }}" fill="{{ hex_white }}"/>`
487+
when the template's rendered geometry is smaller than its SVG
488+
viewport (e.g. separator bar). Card-style and chip-style templates
489+
omit it — the canvas is pre-filled white and alpha masking handles
490+
compositing.
475491
- **Missing state = skip.** If `states.get(entity_id)` returns
476492
`None`, skip the entity and continue. Do not crash.
477493
- **Icon inlining via filter functions.** Call `_mdi_svg_filter(name,

0 commit comments

Comments
 (0)