@pixerate/editor 0.223.6 → 0.223.8

package/skills/pixerate-brand-application/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: pixerate-brand-application
+description: The brand application workflow across Pixerate editors - applying a brand palette, type and tokens to a design, chart or document, mapping each element to its brand role (background, primary, accent, text), snapping near-miss colours to the palette, keeping text readable on brand colours, deriving tints and dark-mode variants without leaving the brand, and running the house-style checks. Use when asked to brand, rebrand, apply a brand, style guide, palette, theme or design tokens, make something on-brand, snap colours to a palette, or check brand consistency, or when check_color_contrast, check_color_palette, blend_colors or a check_*_style tool is available. Load with pixerate-color, which lists the colour tools, and the skill for the editor that holds the design.
+metadata:
+  kind: workflow
+  reference: pixerate-color
+---
+
+# Applying a brand
+
+A brand is a small set of decisions: a palette with roles (background, primary, accent, text),
+type, and rules for using them. Applying it means mapping every element of a design to a role
+and giving it that role's value exactly, not something close. Colours outside the palette are
+either snapped to the nearest brand colour or derived from one deliberately (a tint, a dark-mode
+variant), and every text pairing still meets contrast.
+
+This skill is the method. `pixerate-color` has the colour tools; the design's editor applies the
+values (`vector.setStyle`, `update_chart_series`), design tokens live in `pixerate-tokens`, type
+in `pixerate-typography`, and a host's house style in `check_*_style` tools.
+
+## Goal and quality bar
+
+- Every colour in the design is a brand colour, or a documented derivative of one (a tint, a
+  shade, a dark-mode pair).
+- Each element has the colour of its role: backgrounds, primary surfaces, accents, text.
+- Text on every brand surface meets WCAG AA (see `pixerate-accessibility-audit`).
+- Values are exact (`#1d3557`, not `#1f3759`), referenced from tokens where the editor supports
+  them.
+- Layout, geometry and content are unchanged by the rebrand.
+- House-style checks pass where the host provides them.
+
+## Inputs to confirm
+
+- **The palette with roles**, or a tokens set (`pixerate-tokens`), and the type.
+- **Which elements take which role** when it is not obvious.
+- **What to do when a pairing cannot meet contrast** (another palette colour, larger text, or an
+  approved derivative).
+
+## Working method
+
+1. **Read the design** with its editor: every element's fills, strokes and text colours.
+   **Check:** each element has a role.
+2. **Map roles to brand values.** Write the mapping (background → `#f1faee`, panel → primary,
+   badge → accent) before changing anything.
+3. **Apply exactly**, in one batch where the editor allows it (`run_commands` of
+   `vector.setStyle`, one `update_chart` call).
+   **Check:** reading the design again shows only brand values, and geometry unchanged.
+4. **Snap near-misses.** For colours close to the palette, pick the nearest brand colour by
+   perceptual distance (OKLab): `inspect_color` gives each colour's OKLCH for comparison.
+5. **Readable text.** `check_color_contrast` for each text-on-surface pair; when white fails on a
+   light brand colour, use the darkest brand colour for the text.
+   **Check:** every text pair passes AA.
+6. **Derivatives.** Tints and shades with `blend_colors` in OKLab from a brand colour; dark-mode
+   pairs with `derive_dual_color`. Name and report them.
+7. **House style.** Run the host's `check_*_style` tools (for example `check_chart_style`) and fix
+   what they report.
+
+## Decision table
+
+| Situation | Approach |
+| --- | --- |
+| A colour close to a brand colour | Snap to the nearest by OKLab distance |
+| A needed colour not in the palette | Tint or shade a brand colour (`blend_colors`), and say so |
+| White text fails on a light brand colour | The darkest brand colour for text |
+| No palette colour passes on a surface | Report it; propose larger text or another surface colour |
+| A dark mode is needed | `derive_dual_color` from each brand colour |
+| Charts | Series colours from the palette in its order, checked with `check_chart_colors` |
+| Tokens available | Apply token references, not raw values |
+
+## Recipes
+
+**Apply a palette.** Read element ids → one `run_commands` with a `vector.setStyle` per element
+and its brand `fill` → read again to confirm values and bounds.
+
+**Snap to the palette.** `inspect_color` each off-brand colour and each brand colour; pick the
+smallest OKLab distance; apply.
+
+**Readable badge text.** `check_color_contrast` white and the darkest brand colour on the badge;
+apply the one that passes.
+
+## Pitfalls
+
+- **Close is not on-brand.** `#1f3759` beside `#1d3557` looks the same and fails every audit.
+- **Inventing colours** to fix contrast leaves the brand; use a palette colour or an approved
+  derivative.
+- **Some pairings can never pass**: no text colour reaches 4.5:1 on a mid-tone red or blue.
+  Report it instead of breaking the brand silently.
+- **Rebranding moves things**: change only colours and type, not geometry or content.
+- **Accent overuse**: accents mark what matters; most of a design is background and primary.
+- **Hue-only palettes** for charts fail colour-blind readers; check them.
+
+## Tools used
+
+- `inspect_color`: parse colours and compare them in OKLCH
+- `check_color_contrast`: text on brand surfaces
+- `check_color_palette`: brand colours used for meaning, under colour-vision deficiencies
+- `blend_colors`: tints and shades of brand colours
+- `derive_dual_color`, `check_dual_color_contrast`: dark-mode variants
+- `suggest_color_harmony`: supporting colours when the palette has gaps

package/skills/pixerate-brand-application/evals/apply-palette.json

@@ -0,0 +1,148 @@
+{
+	"prompt": "Apply our brand palette to this layout: the background is #f1faee, the big panel is primary #1d3557, and the small badge is accent #e63946.",
+	"fixture": {
+		"editor": "vector",
+		"width": 200,
+		"height": 120,
+		"colorTools": true,
+		"setup": [
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "rect",
+					"x": 0,
+					"y": 0,
+					"width": 200,
+					"height": 120,
+					"name": "Background",
+					"fill": "#ffffff",
+					"stroke": null
+				}
+			},
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "rect",
+					"x": 20,
+					"y": 20,
+					"width": 160,
+					"height": 80,
+					"name": "Panel",
+					"fill": "#334455",
+					"stroke": null
+				}
+			},
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "ellipse",
+					"x": 150,
+					"y": 10,
+					"width": 30,
+					"height": 30,
+					"name": "Badge",
+					"fill": "#ff6600",
+					"stroke": null
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "each part in its brand colour",
+			"tool": "run_command",
+			"args": {
+				"id": "vector.list"
+			},
+			"expect": {
+				"result": {
+					"nodes": {
+						"$expr": "(() => { const f = (n) => (v.find((x) => x.name === n).fill || '').toLowerCase(); return f('Background') === '#f1faee' && f('Panel') === '#1d3557' && f('Badge') === '#e63946'; })()"
+					}
+				}
+			}
+		},
+		{
+			"why": "nothing moved",
+			"tool": "run_command",
+			"args": {
+				"id": "vector.list"
+			},
+			"expect": {
+				"result": {
+					"nodes": {
+						"$some": {
+							"name": "Badge",
+							"bounds": {
+								"x": 150,
+								"y": 10,
+								"width": 30,
+								"height": 30
+							}
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "run_command",
+			"args": {
+				"id": "vector.list"
+			}
+		},
+		{
+			"tool": "run_commands",
+			"args": {
+				"steps": [
+					{
+						"id": "vector.setStyle",
+						"params": {
+							"ids": [
+								{
+									"$read": "run_command",
+									"args": {
+										"id": "vector.list"
+									},
+									"path": "result.nodes.0.id"
+								}
+							],
+							"fill": "#f1faee"
+						}
+					},
+					{
+						"id": "vector.setStyle",
+						"params": {
+							"ids": [
+								{
+									"$read": "run_command",
+									"args": {
+										"id": "vector.list"
+									},
+									"path": "result.nodes.1.id"
+								}
+							],
+							"fill": "#1d3557"
+						}
+					},
+					{
+						"id": "vector.setStyle",
+						"params": {
+							"ids": [
+								{
+									"$read": "run_command",
+									"args": {
+										"id": "vector.list"
+									},
+									"path": "result.nodes.2.id"
+								}
+							],
+							"fill": "#e63946"
+						}
+					}
+				]
+			}
+		}
+	]
+}

package/skills/pixerate-brand-application/evals/readable-on-brand.json

@@ -0,0 +1,104 @@
+{
+	"prompt": "The white text on our light-blue badge fails contrast. Fix it using a colour from our palette (#1d3557, #457b9d, #a8dadc, #f1faee, #e63946), keeping the badge light blue.",
+	"fixture": {
+		"editor": "vector",
+		"width": 120,
+		"height": 60,
+		"colorTools": true,
+		"setup": [
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "rect",
+					"x": 10,
+					"y": 10,
+					"width": 100,
+					"height": 40,
+					"name": "Badge",
+					"fill": "#a8dadc",
+					"stroke": null
+				}
+			},
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "rect",
+					"x": 30,
+					"y": 24,
+					"width": 60,
+					"height": 12,
+					"name": "Text",
+					"fill": "#ffffff",
+					"stroke": null
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "the text uses a palette colour that reads on the badge at 4.5:1 or more",
+			"tool": "run_command",
+			"args": {
+				"id": "vector.list"
+			},
+			"expect": {
+				"result": {
+					"nodes": {
+						"$expr": "(() => { const L = (h) => { const c = [1, 3, 5].map((i) => parseInt(h.replace('#', '').padEnd(6, '0').slice(i - 1, i + 1), 16) / 255).map((x) => (x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4)); return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]; }; const cr = (a, b) => { const [x, y] = [L(a), L(b)].sort((p, q) => q - p); return (x + 0.05) / (y + 0.05); }; const t = v.find((n) => n.name === 'Text').fill.toLowerCase(); return ['#1d3557', '#457b9d', '#a8dadc', '#f1faee', '#e63946'].includes(t) && cr(t, v.find((n) => n.name === 'Badge').fill) >= 4.5; })()"
+					}
+				}
+			}
+		},
+		{
+			"why": "the badge stays light blue",
+			"tool": "run_command",
+			"args": {
+				"id": "vector.list"
+			},
+			"expect": {
+				"result": {
+					"nodes": {
+						"$some": {
+							"name": "Badge",
+							"fill": "#a8dadc"
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "check_color_contrast",
+			"args": {
+				"foreground": "#ffffff",
+				"background": "#a8dadc"
+			}
+		},
+		{
+			"tool": "check_color_contrast",
+			"args": {
+				"foreground": "#1d3557",
+				"background": "#a8dadc"
+			}
+		},
+		{
+			"tool": "run_command",
+			"args": {
+				"id": "vector.setStyle",
+				"params": {
+					"ids": [
+						{
+							"$read": "run_command",
+							"args": {
+								"id": "vector.list"
+							},
+							"path": "result.nodes.1.id"
+						}
+					],
+					"fill": "#1d3557"
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-brand-application/evals/snap-to-palette.json

@@ -0,0 +1,148 @@
+{
+	"prompt": "These colours are almost our brand colours but not exact. Snap each shape to the nearest colour in the palette: #1d3557, #457b9d, #a8dadc, #e63946.",
+	"fixture": {
+		"editor": "vector",
+		"width": 160,
+		"height": 40,
+		"colorTools": true,
+		"setup": [
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "rect",
+					"x": 0,
+					"y": 0,
+					"width": 40,
+					"height": 40,
+					"name": "A",
+					"fill": "#1f3759",
+					"stroke": null
+				}
+			},
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "rect",
+					"x": 40,
+					"y": 0,
+					"width": 40,
+					"height": 40,
+					"name": "B",
+					"fill": "#4a7fa0",
+					"stroke": null
+				}
+			},
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "rect",
+					"x": 80,
+					"y": 0,
+					"width": 40,
+					"height": 40,
+					"name": "C",
+					"fill": "#aadcde",
+					"stroke": null
+				}
+			},
+			{
+				"id": "vector.addShape",
+				"params": {
+					"kind": "rect",
+					"x": 120,
+					"y": 0,
+					"width": 40,
+					"height": 40,
+					"name": "D",
+					"fill": "#e43b48",
+					"stroke": null
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "each shape in its nearest brand colour",
+			"tool": "run_command",
+			"args": {
+				"id": "vector.list"
+			},
+			"expect": {
+				"result": {
+					"nodes": {
+						"$expr": "v.map((n) => (n.fill || '').toLowerCase()).join() === '#1d3557,#457b9d,#a8dadc,#e63946'"
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "run_commands",
+			"args": {
+				"steps": [
+					{
+						"id": "vector.setStyle",
+						"params": {
+							"ids": [
+								{
+									"$read": "run_command",
+									"args": {
+										"id": "vector.list"
+									},
+									"path": "result.nodes.0.id"
+								}
+							],
+							"fill": "#1d3557"
+						}
+					},
+					{
+						"id": "vector.setStyle",
+						"params": {
+							"ids": [
+								{
+									"$read": "run_command",
+									"args": {
+										"id": "vector.list"
+									},
+									"path": "result.nodes.1.id"
+								}
+							],
+							"fill": "#457b9d"
+						}
+					},
+					{
+						"id": "vector.setStyle",
+						"params": {
+							"ids": [
+								{
+									"$read": "run_command",
+									"args": {
+										"id": "vector.list"
+									},
+									"path": "result.nodes.2.id"
+								}
+							],
+							"fill": "#a8dadc"
+						}
+					},
+					{
+						"id": "vector.setStyle",
+						"params": {
+							"ids": [
+								{
+									"$read": "run_command",
+									"args": {
+										"id": "vector.list"
+									},
+									"path": "result.nodes.3.id"
+								}
+							],
+							"fill": "#e63946"
+						}
+					}
+				]
+			}
+		}
+	]
+}

package/skills/pixerate-color/SKILL.md

@@ -7,6 +7,14 @@ description: How to inspect colours, check and optimize WCAG contrast and access
 
 The colour module provides DOM-free colour tools for inspection, WCAG accessibility validation, colour-vision deficiency simulation, palette audits, colour harmony suggestions, and perceptual blending.
 
+## Workflow skills
+
+For these jobs, load the workflow skill too: it has the method, the checks between steps and
+the pitfalls, and uses the tools below.
+
+- `pixerate-accessibility-audit`: contrast, colour-blind-safe meaning, both modes, fixes and a report.
+- `pixerate-brand-application`: brand roles, exact palette values, readable text, derivatives.
+
 ## Working method
 
 1. **Inspect and convert.** Run `inspect_color` to parse any hex, `rgb()`, `hsl()`, `oklch()`, or CSS named colour into standard formats (hex, rgb, hsl, oklch) and relative luminance, and to check if it fits within the sRGB gamut.

package/skills/pixerate-effect-authoring/SKILL.md

@@ -17,6 +17,13 @@ preview frames.
 
 For general error reporting and undo conventions, see `pixerate-agent-tools`.
 
+## Workflow skills
+
+For these jobs, load the workflow skill too: it has the method, the checks between steps and
+the pitfalls, and uses the tools below.
+
+- `pixerate-effect-look-development`: tune a look, save presets, eased keyframes, seamless loops.
+
 ## Working method
 
 1. **Inspect first.** Run `effect_authoring_describe` to inspect the effect name, kind, source

package/skills/pixerate-effect-look-development/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: pixerate-effect-look-development
+description: The look development workflow for Pixerate effects - reading an effect's controls, finding the look with a few deliberate value changes, saving looks as named presets, animating controls with keyframes and easing, setting duration and looping for seamless cycles, previewing at key moments, and editing shader source only when controls cannot get there. Use when asked to design, tune, tweak or animate an effect, shader, filter or procedural look, make a preset or variant of a look, make an effect fade in or out, pulse or loop, or when effect_authoring_describe, effect_authoring_set_values, effect_authoring_set_keyframe or effect_authoring_save_preset are available. Load with pixerate-effect-authoring, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-effect-authoring
+---
+
+# Developing a look
+
+An effect is a set of controls over a shader or procedure. A look is a set of values for those
+controls, kept as a named preset; an animated look adds keyframed tracks over a duration. Find
+the look with a few deliberate moves (start from a preset, change one control at a time, look),
+save it, and animate only what should change over time.
+
+This skill is the method. `pixerate-effect-authoring` has the full tool reference.
+
+## Goal and quality bar
+
+- Every value is within its control's range (`effect_authoring_describe` lists `min`, `max`,
+  `default`).
+- The look is saved as a preset with a clear name, so it can be applied again.
+- Animation uses as few keyframes as the motion needs, with easing (`ease-out` to arrive,
+  `ease-in-out` for a pulse); duration fits the use.
+- A loop is seamless: `loop` on, and the animated values match at the start and the end.
+- `issues` is empty and `previewError` is null.
+
+## Inputs to confirm
+
+- **The look** in words (subtle, strong, warm, glitchy) or a reference.
+- **Static or animated**, and the duration and looping for animation.
+- **Whether to keep** the result as a preset, and its name.
+
+## Working method
+
+1. **Read.** `effect_authoring_describe`: controls with ranges and defaults, current values,
+   presets, tracks, duration, loop, issues.
+   **Check:** you know which control does what.
+2. **Start close.** `effect_authoring_apply_preset` when a preset is near the look;
+   `effect_authoring_reset_values` to start clean.
+3. **Tune.** `effect_authoring_set_values` with only the controls you change, a few at a time;
+   `effect_authoring_view` to look.
+   **Check:** `values` in `effect_authoring_describe` are what you set; no `issues`.
+4. **Save.** `effect_authoring_save_preset` with a descriptive `name` ("Subtle", "Warm glow").
+   **Check:** the name is in `presets`.
+5. **Animate.** `effect_authoring_set_timing` for `duration` and `loop`; then
+   `effect_authoring_set_keyframe` per control at the times that matter, with `easing` into the
+   next keyframe. For a loop, the last keyframe's value equals the first's.
+   **Check:** `tracks` list the control with the keyframe count you meant.
+6. **Preview** with `effect_authoring_seek` to key times and `effect_authoring_view`.
+7. **Source last.** `effect_authoring_get_source` / `effect_authoring_set_source` only when no
+   control can produce the look; read the returned issues and fix them.
+
+## Decision table
+
+| Want | Approach |
+| --- | --- |
+| A softer or stronger version of a look | Scale the main control (strength, amount); save as a preset |
+| A starting point | `effect_authoring_apply_preset` |
+| Back to defaults | `effect_authoring_reset_values` |
+| Fade in | Keyframes from the neutral value to the look, `ease-out` |
+| Pulse or breathe | Three keyframes (rest, peak, rest), `ease-in-out`, loop on |
+| A one-off change at a moment | Two keyframes around the moment |
+| Remove animation from a control | `effect_authoring_clear_track` |
+| Something no control does | Edit the source |
+
+## Recipes
+
+**Quarter-strength preset.** `effect_authoring_set_values` `{ values: { amount: 0.25 } }` →
+`effect_authoring_save_preset` `{ name: "Subtle" }`.
+
+**Fade in over 1.5 s in a 2 s effect.** `effect_authoring_set_timing` `{ duration: 2000 }` →
+`effect_authoring_set_keyframe` `{ control: "amount", time: 0, value: 0 }` → `{ control:
+"amount", time: 1500, value: 1, easing: "ease-out" }`.
+
+**Seamless 3 s pulse.** `effect_authoring_set_timing` `{ duration: 3000, loop: true }` → keyframes
+at 0 (0), 1500 (1, `ease-in-out`) and 3000 (0, `ease-in-out`).
+
+## Pitfalls
+
+- **Values out of range** are clamped or refused; read the control's `min` and `max`.
+- **Many keyframes** where three would do make motion lumpy and hard to edit.
+- **Linear easing** on organic motion looks mechanical.
+- **Loops that jump**: the end value must equal the start value.
+- **Overwriting a preset** by saving under an existing name; choose a new name unless replacing
+  is intended.
+- **Editing source first**: controls are safer and keep presets working.
+
+## Tools used
+
+- `effect_authoring_describe`, `effect_authoring_view`, `effect_authoring_seek`: read, look and preview
+- `effect_authoring_set_values`, `effect_authoring_reset_values`, `effect_authoring_apply_preset`: find the look
+- `effect_authoring_save_preset`: keep the look
+- `effect_authoring_set_timing`, `effect_authoring_set_keyframe`, `effect_authoring_remove_keyframe`, `effect_authoring_clear_track`: animate
+- `effect_authoring_get_source`, `effect_authoring_set_source`: edit the shader when needed
+- `effect_authoring_undo`, `effect_authoring_redo`: take back a step

package/skills/pixerate-effect-look-development/evals/fade-in.json

@@ -0,0 +1,55 @@
+{
+	"prompt": "Animate the effect fading in: no effect at the start, full strength by 1.5 seconds, in a 2-second effect.",
+	"fixture": {
+		"editor": "effect",
+		"effectId": "fake.invert"
+	},
+	"checks": [
+		{
+			"why": "a 2-second effect",
+			"tool": "effect_authoring_describe",
+			"expect": {
+				"duration": 2000
+			}
+		},
+		{
+			"why": "the amount is keyframed (at least a start and an end)",
+			"tool": "effect_authoring_describe",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"control": "amount",
+						"keyframes": {
+							"$min": 2
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "effect_authoring_set_timing",
+			"args": {
+				"duration": 2000
+			}
+		},
+		{
+			"tool": "effect_authoring_set_keyframe",
+			"args": {
+				"control": "amount",
+				"time": 0,
+				"value": 0
+			}
+		},
+		{
+			"tool": "effect_authoring_set_keyframe",
+			"args": {
+				"control": "amount",
+				"time": 1500,
+				"value": 1,
+				"easing": "ease-out"
+			}
+		}
+	]
+}