@ammduncan/easel 0.2.10 → 0.2.12

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.2.12 — 2026-05-23
+
+### Docs
+- **Locked-mode guidance now ships a paired light example next to the dark one.** The existing rule — "background and text are a pair, commit both, re-scope `color: inherit` to children" — was illustrated only with a dark `.terminal` block. Agents (and people) generalized the rule to "lock your dark containers" and missed the equally-common inverse: a white `.card` on the host canvas with no `color:` of its own, which in dark host mode inherits `.wrap`'s `light-dark()` and resolves to light gray → invisible titles on white. The skill and inline `push` tool description now show both shapes side by side so agents see the rule is direction-agnostic.
+
+## 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,11 @@ 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" +
+                    "• Same pairing applies in the OPPOSITE direction — locked-LIGHT containers (e.g. a white card on the host canvas). A `.card { background: #fff }` with no `color:` inherits `.wrap`'s light-dark() text, which in dark host mode resolves to a light cream/gray → invisible titles on a white card. Commit text too AND re-scope inherit on children. This bites just as often as the dark case.\n" +
+                    "  .card { background: #ffffff; color: #111111; border: 1px solid #e5e5e5; border-radius: 12px; padding: 24px 32px; }\n" +
+                    "  .card * { color: inherit; }\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.12",
   "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

@@ -189,14 +189,46 @@ When the mockup references a real thing — a real app, a real component, a real
 **If you can't reach the actuals**, say so explicitly in the chat reply (e.g. *"Couldn't find the project's theme file — colors and sizing in this mock are estimates"*) and skip the mock if it would mislead. A recreation labelled "approximation" is fine; one passed off as accurate is a trap.
 
 ```css
+/* Locked-dark container (terminal, dark code block, dark callout). */
 .terminal {
   background: #0f172a;  /* locked dark, ignores host mode */
   color: #e6edf3;       /* MUST set text too */
 }
 .terminal * { color: inherit; }  /* re-scope so .wrap's light-dark() doesn't leak in */
+
+/* Locked-LIGHT container (white card on the host canvas). Just as common a
+ * failure as the dark case: a white `.card` with no `color:` of its own
+ * inherits `.wrap`'s light-dark() text → in dark host mode that resolves to
+ * light gray → invisible titles on a white card. Commit the same way. */
+.card {
+  background: #ffffff;  /* locked white, ignores host mode */
+  color: #111111;       /* MUST set text too */
+  border: 1px solid #e5e5e5;
+  border-radius: 12px;
+  padding: 24px 32px;
+}
+.card * { color: inherit; }
+```
+
+The rule of thumb: background and text are a pair — commit one, commit the other. The direction (dark or light) doesn't matter; the pairing does.
+
+**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 */
 ```
 
-The rule of thumb: background and text are a pair — commit one, commit the other.
+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