docs: state-as-glyph — show state, don't narrate it#42
Merged
Conversation
Sibling to the iconography work, same root cause (LLM text-bias). The render patterns exist (KPI cards, status dots, charts, progress) but no authoring discipline tells the agent to prefer them over a sentence. - docs/data-glyphs.md (new): the "show state, don't narrate it" UI-Skill authoring protocol (value-kind → preferred element); one small protocol 1.1 additive (`chart` variant: "spark" for inline sparklines); delta chip as a composition (text + app: arrow glyph), not a primitive. No new primitives; principle needs no wire change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Sibling to the iconography work (#41) — same root cause: the generative layer is
text-biased (the LLM emits tokens, so prose is the path of least resistance).
Where icons were missing a vocabulary, state is missing a discipline.
Verified against the repo:
chart/status/progressprimitives exist; a KPI is a composition, not a primitive (CONCEPT§302); status dots are sanctioned (§3.3); mockups already render value + delta + trend (visual-specpreview §8).chartvariant — the KPI trend mini-bars are mockup-only.Result: the agent writes "Deep work: 2h 15m so far, going well" instead of composing KPI-
text"2h 15m" + a sparkline + a delta.What
docs/data-glyphs.md(new) — the "show state, don't narrate it" UI-Skill authoring protocol: a value-kind → preferred-element table (quantity → KPI-text, trend → chart/spark, status → dot+word, progress →progress, delta → chip). Prose stays for narration/analysis, never for a bare value.chartvariant: "spark"for axisless inline sparklines (1.0 clients ignore it, render the full chart).textvalue + anapp:arrow glyph from docs: iconography — protocol 1.1 icon affordance + visual-spec §2.12 rewrite #41), documented as a recipe — no new primitive.No new primitives; the principle itself needs no wire change.
Ties to canon
Accent marks the positive/live signal (negative delta is
state.warningtext, never a red pill — §2.6); one accent slot; data-dominant typography. Anti-patterns called out: no unlabelled sparklines, no gauge/dial salad (Tremor chart-restraint), don't strip genuine narration.Open questions (doc §7)
sparkasvariantvs.densityonchart.statusneed a typed health enum (ok/warn/error) or is the semantic-state token + text enough?Companion to
visual-spec§2.7 anddocs/iconography.md(#41).🤖 Generated with Claude Code