@ammduncan/easel 0.2.10 → 0.2.11

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.2.11 — 2026-05-22
+
+### Docs
+- **Locked-mode container guidance now covers syntax highlighting explicitly.** The existing rule ("background and text are a pair — commit both, re-scope `color: inherit` to children") only addressed single-color text. Syntax-highlighted code blocks layer multiple token colors on top of that, and the recurring failure was a `property` / `punctuation` / `comment` token colored near-background (e.g. `#2c2c40` on `#0f172a`) silently rendering whole identifiers invisible. New guidance in `skills/using-easel/SKILL.md` and the inline `push` tool description spells out: use a tested theme designed for your bg (Shiki `github-dark` / `vitesse-dark` / `one-dark-pro` for `#0f172a`-ish; `github-light` / `vitesse-light` for `#f5f7fa`-ish) OR pick from a verified 6-color palette for `#0f172a` (keyword `#ff7b72`, string `#a5d6ff`, function `#d2a8ff`, property `#79c0ff`, number `#ffa657`, comment `#8b949e`, default `#e6edf3`). Fallback: drop highlighting, use single-color monospace.
+
 ## 0.2.10 — 2026-05-22
 
 ### Changed

package/dist/mcp.js

@@ -127,7 +127,8 @@ export async function main() {
                     "  .terminal { background: #0f172a; color: #e6edf3; border-radius: 12px; padding: 20px 24px; font-family: ui-monospace, 'SF Mono', Menlo, monospace; font-size: 13.5px; line-height: 1.7; }\n" +
                     "  .terminal *, .terminal span, .terminal pre { color: inherit; }\n" +
                     "  .terminal .muted { color: #94a3b8; }\n" +
-                    "  .terminal .accent { color: #6ee7b7; }\n\n" +
+                    "  .terminal .accent { color: #6ee7b7; }\n" +
+                    "• Syntax-highlighted code in a locked-bg block: EVERY token color must be verified readable against the bg, not just the body color. Recurring bug: locking to #0f172a then giving 'property' / 'punctuation' / 'comment' tokens something like #2c2c40 because it 'looked subtle' — against #0f172a it's nearly invisible and identifiers disappear. Either use a tested theme designed for your bg (Shiki github-dark / vitesse-dark / one-dark-pro for #0f172a-ish, github-light / vitesse-light for #f5f7fa-ish), or pick from this verified palette for #0f172a: keyword #ff7b72, string #a5d6ff, function #d2a8ff, property #79c0ff, number #ffa657, comment #8b949e, default text #e6edf3. If you can't articulate why each token reads against the bg, drop highlighting and use single-color monospace — that always works.\n\n" +
                     "═══ TYPOGRAPHY (presentation scale, NOT dashboard) ═══\n" +
                     "• Hero title: 44–52px, weight 500, letter-spacing -0.025em\n" +
                     "• Section titles: 28–36px, weight 500\n" +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "A live browser tab for every Claude Code (and MCP) session. The push MCP tool appends HTML cards to a scrolling feed you keep open in split-screen.",
   "type": "module",
   "license": "MIT",

package/skills/using-easel/SKILL.md

@@ -198,6 +198,24 @@ When the mockup references a real thing — a real app, a real component, a real
 
 The rule of thumb: background and text are a pair — commit one, commit the other.
 
+**Syntax highlighting in locked-bg code blocks needs *every token* verified.** "Bg + text are a pair" extends to every token color you use. The recurring failure: lock a code block to `#0f172a`, then layer syntax tokens where one (usually `property`, `punctuation`, or `comment`) is colored `#2c2c40` or `#3b4252` because it "looked subtle" — against `#0f172a` it's nearly invisible and whole identifiers disappear from the block. Two ways out:
+
+1. **Use a tested theme designed for your bg.** Shiki / Prism / Highlight.js themes like `github-dark`, `vitesse-dark`, `one-dark-pro` for `#0f172a`-ish backgrounds; `github-light`, `vitesse-light` for `#f5f7fa`-ish. The theme's author already verified contrast — don't override individual tokens.
+2. **Hand-rolling tokens? Verify each one against the bg, or pick from this verified palette for `#0f172a`:**
+
+```css
+.code            { background: #0f172a; color: #e6edf3; }
+.code .keyword   { color: #ff7b72; }   /* red-pink:   keywords, control flow */
+.code .string    { color: #a5d6ff; }   /* sky:        strings, attribute values */
+.code .function  { color: #d2a8ff; }   /* purple:     function names */
+.code .property  { color: #79c0ff; }   /* blue:       identifiers, properties, members */
+.code .number    { color: #ffa657; }   /* orange:     numbers, constants */
+.code .comment   { color: #8b949e; }   /* muted gray: comments — still readable */
+.code *          { color: inherit; }   /* default everything else to body color */
+```
+
+If you can't articulate why each token color reads against the bg, drop syntax highlighting entirely and use single-color monospace — that always works.
+
 ### 5. Visualizations — tangible over abstract
 
 When something can be represented as a real-world object — browser-chrome tab cards with red/yellow/green dots, proportional horizontal timeline bars with marked phases, device frames, code editor windows, terminal windows, merging-pipe shapes for funnels — **do that**, not abstract labeled rectangles with arrows.