claude-artifact-framework 0.19.0 → 0.19.1

package/README.md

@@ -988,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/llms.txt

@@ -74,6 +74,21 @@ https://cdn.jsdelivr.net/npm/claude-artifact-framework/dist/index.global.js
     the viewers are on a phone. The framework never clips (wide custom
     content scrolls), but scrolling is the fallback, not the design.
 
+## Design principles (composition choices only the spec makes)
+
+1. ONE dominant element per screen: exactly one big:true — zero reads
+   flat, two read as none.
+2. Order blocks by importance, not data model: primary action first, hero
+   result next, breakdowns after; config/branding/help LAST or collapsed.
+3. Icons: all siblings or none, one style (emoji), never half a set.
+4. Mid-tone saturated seed that names the domain; no grays/near-blacks.
+5. Never duplicate what the framework renders (title, totals, empties).
+6. Group, don't multiply cards: related inputs in ONE fields block;
+   secondary content into tabs/collapsible; >5 cards on one screen = no
+   hierarchy.
+7. State via when:, not more blocks.
+8. Charts are support: ≤2 per screen, wide for time series, donut ≤5.
+
 ## Canonical example
 
 ArtifactKit.createApp({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-artifact-framework",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Utilities for building apps inside Claude Artifacts: platform storage, chat tool-calling loops, and other primitives verified against the real runtime.",
   "type": "module",
   "main": "./dist/index.esm.js",