claude-artifact-framework 0.18.0 → 0.19.1

package/README.md

@@ -909,9 +909,10 @@ keys must be unique across steps.
 
 **Formats** (`format:` on output/chart/compute items): `money`, `percent`,
 `number`, `date`. `percent` expects 0–100 (pass `ratio * 100`, not the raw
-ratio). `big: true` renders an item at hero size — reserve it for the ONE
-number that is the screen's main result (a total, a final score), not for
-every stat; more than one hero per screen means no hero at all.
+ratio). `big: true` renders an item at hero size AND promotes its block to
+the screen's one feature surface (accent-tinted card) — reserve it for the
+ONE number that is the screen's main result (a total, a final score), not
+for every stat; more than one hero per screen means no hero at all.
 
 **Quick-add pattern** — a lightweight alternative to `records` when you just
 need "type something, press a button, it lands in a list":
@@ -987,6 +988,40 @@ Conflict handling is last-write-wins: if two viewers change the same key
 within one poll window, whichever write reaches storage last overwrites the
 other. There is no merge/CRDT logic.
 
+## Design principles — composing a screen that reads
+
+The framework owns the CSS, but whether a screen has visual hierarchy is
+decided by choices only the SPEC can make. Every beautiful app follows
+these; every generic-looking one breaks at least two:
+
+1. **One dominant element per screen.** Exactly one `big: true` stat — the
+   screen's answer (the total, the score, the net). It automatically
+   becomes the highlighted feature card. Zero heroes reads flat; two
+   heroes read as none.
+2. **Order blocks by importance, not by data model.** First what the user
+   DOES most (the quick-add, the main fields), then the hero result, then
+   breakdowns and charts, then history. Configuration, branding text, and
+   help go LAST — or inside `collapsible: "collapsed"` — never first.
+3. **Icons: all siblings or none.** If one tab/section gets an `icon`,
+   every tab/section in that same set gets one, same style (all emoji). A
+   half-iconed set reads as an accident. Don't use emoji as bullet points
+   inside stat labels or titles that already live in an iconed set.
+4. **Pick a mid-tone, saturated seed that names the domain** — warm
+   orange/red for food, teal/blue for finance, green for health. Grays and
+   near-blacks kill the entire accent system; neons burn it.
+5. **Never duplicate what the framework already renders.** No text block
+   repeating the app's own title (the header shows it), no hand-built
+   totals when `summary`/`output` computes them, no "empty list" messages.
+6. **Group; don't multiply cards.** Related inputs belong in ONE `fields`
+   block with one title. Secondary content goes into `tabs` or a
+   collapsible. A first screen with more than ~5 cards has no hierarchy
+   left — and a block whose only content is one lonely button probably
+   belongs next to the fields it acts on.
+7. **Say state with `when`, not with more blocks.** Hide what doesn't
+   apply right now instead of stacking every possibility on screen.
+8. **Charts are support, not wallpaper.** At most two per screen; `wide:
+   true` for time series; donuts only up to ~5 slices.
+
 ## Hard rules — the short list
 
 The rules that decide whether a generated app works, all in one place

package/dist/index.esm.js

@@ -761,9 +761,10 @@ function OutputBlock({ spec, ctx }) {
   if (!items.length) {
     return createElement("div", { className: "caf-block caf-empty" }, spec.empty || "Nothing to show yet.");
   }
+  const hero = items.some((it) => it && it.big);
   return createElement(
     "div",
-    { className: "caf-block caf-output" },
+    { className: hero ? "caf-block caf-output caf-block-feature" : "caf-block caf-output" },
     spec.title ? createElement("h2", { className: "caf-block-title" }, spec.title) : null,
     createElement(
       "div",
@@ -780,10 +781,9 @@ function OutputBlock({ spec, ctx }) {
     )
   );
 }
-function BannerBlock({ spec, ctx }) {
+function BannerBlock({ spec }) {
   const b = typeof spec.banner === "string" ? { title: spec.banner } : spec.banner || {};
-  const [c1, c2] = ctx.colors(2);
-  const background = b.image ? `linear-gradient(rgba(0,0,0,0.35), rgba(0,0,0,0.35)), url(${JSON.stringify(b.image)}) center / cover` : `linear-gradient(135deg, ${c1}, ${c2})`;
+  const background = b.image ? `linear-gradient(rgba(0,0,0,0.35), rgba(0,0,0,0.35)), url(${JSON.stringify(b.image)}) center / cover` : `linear-gradient(135deg, color-mix(in srgb, var(--caf-accent) 82%, #000), var(--caf-accent) 55%, color-mix(in srgb, var(--caf-accent) 72%, #fff))`;
   return createElement(
     "div",
     { className: "caf-banner", style: { background } },
@@ -1100,9 +1100,10 @@ function Summary({ spec, records }) {
   if (!spec.summary) return null;
   const items = spec.summary(records) || [];
   if (!items.length) return null;
+  const hero = items.some((it) => it && it.big);
   return createElement(
     "div",
-    { className: "caf-block caf-output" },
+    { className: hero ? "caf-block caf-output caf-block-feature" : "caf-block caf-output" },
     createElement(
       "div",
       { className: "caf-output-grid" },
@@ -1373,7 +1374,8 @@ function ResultScreen({ step, ctx }) {
     { className: "caf-steps-result" },
     createElement(
       "div",
-      { className: "caf-block caf-output" },
+      // Same rule as OutputBlock: the hero (big) result gets the feature card.
+      { className: items.some((it) => it && it.big) ? "caf-block caf-output caf-block-feature" : "caf-block caf-output" },
       step.title ? createElement("h2", { className: "caf-block-title" }, step.title) : null,
       createElement(
         "div",
@@ -2446,7 +2448,9 @@ function createApp(spec = {}) {
     const logoEl = !spec.brand ? null : logo && logo.trim().startsWith("<svg") ? createElement("span", { className: "caf-logo caf-logo-svg", dangerouslySetInnerHTML: { __html: logo } }) : logo && /^https?:\/\//.test(logo) ? createElement("img", { className: "caf-logo", src: logo, alt: "" }) : logo ? createElement("span", { className: "caf-logo caf-logo-emoji", "aria-hidden": true }, logo) : createElement(
       "span",
       { className: "caf-logo caf-logo-mono", "aria-hidden": true },
-      (spec.title || "?").split(/\s+/).map((w) => w[0]).filter(Boolean).slice(0, 2).join("").toUpperCase()
+      // First letter/digit of each word — punctuation "words" like the
+      // "-" in "Caja - Camión" must not become half the monogram.
+      (spec.title || "?").split(/\s+/).map((w) => (w.match(/[\p{L}\p{N}]/u) || [])[0]).filter(Boolean).slice(0, 2).join("").toUpperCase() || "?"
     );
     return createElement(
       "div",
@@ -2487,7 +2491,9 @@ var BASE_CSS = `
   --caf-control-radius: 7px; /* one radius for every control: buttons, inputs, rows */
   --caf-btn-pad-y: 0.45rem;
   --caf-btn-pad-x: 0.8rem;
-  --caf-num-primary: 2.1rem; /* the one size for a block's dominant number */
+  --caf-num-primary: 2.6rem; /* the one size for a block's dominant number \u2014 the largest thing on screen, bigger than the H1 */
+  --caf-accent-tint: color-mix(in srgb, var(--caf-accent) 7%, var(--caf-surface)); /* soft accent surface for the feature card */
+  --caf-block-gap: 1.75rem; /* ONE value for air between blocks, every layout (audited: workspace used a smaller gap for the same visual role) */
   box-sizing: border-box;
   min-height: 100vh;
   padding: 2rem 1.25rem 4rem;
@@ -2503,7 +2509,9 @@ var BASE_CSS = `
 .caf-header h1 { margin: 0; font-size: 1.5rem; font-weight: 650; letter-spacing: -0.01em; text-wrap: balance; }
 .caf-header p { margin: 0.4rem 0 0; color: var(--caf-muted); font-size: 0.95rem; line-height: 1.5; }
 /* Between-card air must beat within-card padding (1.1rem), or groups dissolve. */
-.caf-panel { max-width: 760px; margin: 0 auto; display: grid; grid-template-columns: 1fr 1fr; gap: 1.75rem 1rem; }
+/* align-items: start \u2014 a short card must not stretch to its tall neighbor's
+   height; the stretched version reads as dead air (audited). */
+.caf-panel { max-width: 760px; margin: 0 auto; display: grid; grid-template-columns: 1fr 1fr; gap: var(--caf-block-gap) 1rem; align-items: start; }
 .caf-slot { grid-column: span 2; min-width: 0; }
 @media (min-width: 720px) { .caf-slot { grid-column: span 1; } .caf-slot-wide { grid-column: span 2; } }
 .caf-block {
@@ -2597,7 +2605,9 @@ var BASE_CSS = `
 .caf-timer-done { color: var(--caf-accent); }
 .caf-timer-fill { transition: width 0.9s linear; }
 .caf-timer-controls { display: flex; gap: 0.6rem; }
-.caf-btn:disabled { opacity: 0.45; cursor: not-allowed; }
+/* Disabled goes NEUTRAL, not pale-accent: a washed-out primary reads as
+   broken (audited on the chat Send with an empty input). */
+.caf-btn:disabled { cursor: not-allowed; background: var(--caf-sunken); color: var(--caf-muted); border-color: var(--caf-border); opacity: 1; }
 .caf-steps-progress { display: flex; flex-direction: column; gap: 0.35rem; margin-bottom: 0.2rem; }
 .caf-steps-result { display: flex; flex-direction: column; gap: 1rem; min-width: 0; }
 .caf-steps-fill { transition: width 0.25s ease; }
@@ -2629,7 +2639,9 @@ var BASE_CSS = `
 .caf-row-wrap { display: flex; align-items: center; gap: 0.4rem; }
 .caf-row-wrap .caf-row { flex: 1; min-width: 0; }
 .caf-row-actions { display: flex; gap: 0.35rem; flex: none; padding-right: 0.3rem; }
-.caf-btn-sm { font-size: 0.78rem; padding: calc(var(--caf-btn-pad-y) * 0.67) calc(var(--caf-btn-pad-x) * 0.75); }
+/* min-width keeps row actions' left edges aligned across rows even when
+   labels differ ("Hecho" vs "Desmarcar" \u2014 audited misalignment). */
+.caf-btn-sm { font-size: 0.78rem; padding: calc(var(--caf-btn-pad-y) * 0.67) calc(var(--caf-btn-pad-x) * 0.75); min-width: 76px; text-align: center; }
 .caf-items { display: flex; flex-direction: column; gap: 0.5rem; border-top: 1px solid var(--caf-border); padding-top: 0.7rem; }
 .caf-item-row { display: flex; align-items: flex-end; gap: 0.5rem; }
 .caf-item-row .caf-field { flex: 1; min-width: 0; }
@@ -2643,8 +2655,8 @@ var BASE_CSS = `
 .caf-md-li { display: block; padding-left: 1rem; position: relative; }
 .caf-md-li::before { content: "\u2022"; position: absolute; left: 0.2rem; opacity: 0.6; }
 .caf-workspace { max-width: 1200px; margin: 0 auto; display: flex; gap: 1rem; align-items: flex-start; }
-.caf-ws-main { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 1rem; }
-.caf-ws-side { width: 340px; flex: none; display: flex; flex-direction: column; gap: 1rem; position: sticky; top: 1rem; }
+.caf-ws-main { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: var(--caf-block-gap); }
+.caf-ws-side { width: 340px; flex: none; display: flex; flex-direction: column; gap: var(--caf-block-gap); position: sticky; top: 1rem; }
 .caf-ws-slot { min-width: 0; }
 .caf-chat-panel { display: flex; flex-direction: column; min-height: 0; }
 .caf-ws-side .caf-chat-log { max-height: calc(100vh - 220px); }
@@ -2729,6 +2741,11 @@ var BASE_CSS = `
 /* Never-clip guarantee: content inside a custom block that is wider than the
    phone (column grids, week views) must scroll, not disappear off-screen. */
 .caf-custom { overflow-x: auto; }
+/* The one differentiated surface per screen: accent top rule + tinted bg on
+   the block holding the hero number. Everything-is-the-same-card was the
+   audited root cause of the "generic template" look. (Late in the sheet on
+   purpose \u2014 it must win over .caf-block's border/background.) */
+.caf-block-feature { border-top: 3px solid var(--caf-accent); background: var(--caf-accent-tint); }
 /* mobile.nav: "bottom" \u2014 the app-shell tab bar pinned to the thumb zone.
    Tabs share the width evenly so every section stays visible; the root
    reserves space so the bar never covers the end of the content. */