@leotang92/dsh-claude-dashboard 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +27 -0
- package/NOTICE.md +25 -0
- package/README.md +21 -2
- package/cordis.patch.yml +7 -0
- package/docs/DETAIL.md +27 -0
- package/docs/DETAIL.zh.md +16 -0
- package/icon.svg +9 -0
- package/lib/client.js +1800 -0
- package/lib/index.js +878 -0
- package/locale/en.json +7 -0
- package/locale/zh.json +7 -0
- package/package.json +69 -4
- package/skills/claude-dashboard/SKILL.md +495 -0
- package/skills/claude-dashboard/artifact-type/reference/admin-setup.md +106 -0
- package/skills/claude-dashboard/artifact-type/reference/dependent-calls.md +33 -0
- package/skills/claude-dashboard/artifact-type/reference/design-defaults.md +267 -0
- package/skills/claude-dashboard/artifact-type/reference/design-system.md +131 -0
- package/skills/claude-dashboard/artifact-type/reference/exporting.md +68 -0
- package/skills/claude-dashboard/artifact-type/reference/features.md +240 -0
- package/skills/claude-dashboard/artifact-type/reference/one-writer.md +104 -0
- package/skills/claude-dashboard/artifact-type/reference/read-aloud.md +118 -0
- package/skills/claude-dashboard/artifact-type/reference/remix.md +91 -0
- package/skills/claude-dashboard/artifact-type/reference/sources.md +234 -0
- package/skills/claude-dashboard/artifact-type/reference/visual-short-script.md +142 -0
- package/skills/claude-dashboard/artifact-type/reference/visual-short-skeleton.md +97 -0
- package/skills/claude-dashboard/artifact-type/reference/visual-short.md +227 -0
- package/skills/claude-dashboard/scripts/artifact.mjs +5541 -0
- package/skills/claude-dashboard/scripts/editor/assets/anthropicons-fizzy-lake-CPTdBYLV.woff2 +0 -0
- package/skills/claude-dashboard/scripts/editor/assets/index-BUtE2LuL.css +1 -0
- package/skills/claude-dashboard/scripts/editor/assets/index-DLvAt8Vr.js +553 -0
- package/skills/claude-dashboard/scripts/editor/comments.js +103 -0
- package/skills/claude-dashboard/scripts/editor/index.html +27 -0
- package/skills/claude-dashboard/scripts/editor/local-host.js +481 -0
- package/skills/claude-dashboard/scripts/editor/share-ui.js +208 -0
- package/skills/claude-dashboard/scripts/editor/third-party-licenses.txt +1141 -0
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
# Visual short
|
|
2
|
+
|
|
3
|
+
A Visual short is a dashboard that plays: one finding, told in a few chapters on
|
|
4
|
+
one stage, each a drawing that builds while a caption says what it shows, a
|
|
5
|
+
minute or two in all. It is for people who would rather watch than read: an
|
|
6
|
+
all-hands, a quarter's review, a link dropped in a channel. It works when one idea
|
|
7
|
+
is on screen at a time and each mark arrives with the words that name it.
|
|
8
|
+
|
|
9
|
+
It is built from datasets and marks like any dashboard. Below: what has to hold,
|
|
10
|
+
each with its reason, then suggestions, which give way to what the person asks
|
|
11
|
+
for.
|
|
12
|
+
|
|
13
|
+
Read `artifact-type/reference/visual-short-skeleton.md` (HTML and CSS) and
|
|
14
|
+
`artifact-type/reference/visual-short-script.md` next and start from them: they
|
|
15
|
+
already do what has to hold, so the work is the piece itself.
|
|
16
|
+
|
|
17
|
+
## What has to hold
|
|
18
|
+
|
|
19
|
+
- **One writer for each part** (`artifact-type/reference/one-writer.md`), or the
|
|
20
|
+
page check fails. Words known as you write are in the HTML. Each marked figure
|
|
21
|
+
in the HTML, each chart and whatever else a script writes is a `data-draw`;
|
|
22
|
+
outside them a script, your scenes too, sets only `class`, `style` and
|
|
23
|
+
`aria-*`.
|
|
24
|
+
- **A mark holds its real value from the first draw.** The dashboard checks
|
|
25
|
+
every mark that is rendered against its data, at any opacity and at any
|
|
26
|
+
moment. So a chapter that isn't playing is drawn whole, as at its end, and
|
|
27
|
+
only the one playing is drawn at its time. A number that counts up does so in
|
|
28
|
+
an unmarked `aria-hidden="true"` copy, a drawing of its own, laid over the
|
|
29
|
+
marked one; once the count ends the marked one shows and the copy hides.
|
|
30
|
+
- **Chapters share one place and cross-fade.** Stack the chapters in one place,
|
|
31
|
+
and the captions in a stack of their own, and fade them with `opacity`: under
|
|
32
|
+
`display: none` a drawing measures 0 wide and its marks go unchecked. A
|
|
33
|
+
chapter not showing is `aria-hidden` and takes no pointer. That doesn't stop
|
|
34
|
+
the keyboard, so put nothing in a chapter that takes focus: no link, control
|
|
35
|
+
or `tabindex`.
|
|
36
|
+
- **Captions are hidden from the eye alone.** Where a sentence or a caption is
|
|
37
|
+
hidden (the sentences not being said; all of them with CC off; not one the
|
|
38
|
+
data rules out, which is `hidden`), hide it with `opacity`, never `display:
|
|
39
|
+
none`, `visibility: hidden`, `hidden` or `aria-hidden`: under any of those a
|
|
40
|
+
screen reader loses the words and Listen doesn't read them, and under
|
|
41
|
+
`display: none` or `hidden` a figure in the caption goes unchecked. With
|
|
42
|
+
`opacity` a screen reader and Listen get every caption, in order: to a screen
|
|
43
|
+
reader they are a transcript after the chapter showing. Every chapter keeps an
|
|
44
|
+
empty `.vs-say` after its headline, the row its caption is laid over: without
|
|
45
|
+
one the caption lies over the drawing.
|
|
46
|
+
- **Motion is drawn from time, in script.** Each chapter is a function of its
|
|
47
|
+
own time `t` in seconds, whole at the end of `t`, so it can be held, replayed
|
|
48
|
+
or jumped to and still look right. For this shape that replaces what
|
|
49
|
+
`design-defaults.md` says of `@keyframes`. `t` runs in one animation-frame
|
|
50
|
+
loop, stopped while nothing plays. Each frame writes only styles and
|
|
51
|
+
attributes that aren't marks; text and elements are written only when they
|
|
52
|
+
change, since each such write under `#dash-root` has the dashboard check all
|
|
53
|
+
the marks again. On new data or a new width the drawings run again, the
|
|
54
|
+
skeleton's `settle` last, which redraws the chapter showing at its current `t`
|
|
55
|
+
and leaves `t` alone.
|
|
56
|
+
- **The reader starts it.** It opens on its title, whole and at rest, which is
|
|
57
|
+
also what a thumbnail shows, and plays only when they press Play, pick a
|
|
58
|
+
chapter or, where there is a voice, press the speaker: motion nobody asked
|
|
59
|
+
for distracts. Its controls are `<button>`s in the HTML, each with a name (its words
|
|
60
|
+
or an `aria-label`), so a keyboard and a screen reader can work them.
|
|
61
|
+
- **It fits the room it is given.** A stage that runs off the view loses its
|
|
62
|
+
foot. The room changes with the window and with the dashboard's own bars,
|
|
63
|
+
above the page and under it, so measure it in the box the page scrolls in, and
|
|
64
|
+
set the stage's width from the height there is room for, so it keeps its shape
|
|
65
|
+
(`fit` in the script).
|
|
66
|
+
- **Sizes need a container.** Nothing above the page is a container, so
|
|
67
|
+
`@container` never matches and `cqi` measures the window. Set
|
|
68
|
+
`container-type: inline-size` on the wrapper, for rules at narrow widths, and on
|
|
69
|
+
the stage. Size what is inside the stage in `cqi`
|
|
70
|
+
(`.vs-caps { font-size: max(14px, 2cqi); }`): `cqi` on an element measures the
|
|
71
|
+
nearest container above it, never the element itself.
|
|
72
|
+
- **`prefers-reduced-motion: reduce`** shows each chapter's drawing whole at once,
|
|
73
|
+
with only the fade. Its sentences still take their turns.
|
|
74
|
+
- **The voice is an extra.** Some readers have Listen
|
|
75
|
+
(`artifact-type/reference/read-aloud.md`); many don't, so the piece plays whole
|
|
76
|
+
without it. Mark it to be read, as the skeleton does: the captions' holder
|
|
77
|
+
`data-read`, with nothing in it but the captions, each caption
|
|
78
|
+
`data-read-step`, and the stage around them `data-read-stage`. Without that last
|
|
79
|
+
one the dashboard tints the words and scrolls each caption to the middle. Keep
|
|
80
|
+
the captions as the same elements throughout: the dashboard stamps the ones that
|
|
81
|
+
were there when the reading started.
|
|
82
|
+
- **While a reading is open, the dashboard keeps time.** `#dash-root` then has
|
|
83
|
+
`data-dash-read-phase`, and the caption being read, or read last, has
|
|
84
|
+
`data-dash-read-now`. When that stamp lands on another caption, or the phase
|
|
85
|
+
turns to `starting` (a press can have the same caption read again), show its
|
|
86
|
+
chapter from `t` = 0. `t` runs only while the phase is `playing`: test for that,
|
|
87
|
+
since nothing is heard during `starting` or `paused` or after `ended`. The page
|
|
88
|
+
moves to no chapter by itself: one that finishes early waits, whole, for the
|
|
89
|
+
next stamp. At `ended`, once the last caption is read, show the chapter whole
|
|
90
|
+
and stay on it. When the phase goes the voice is off, by a press or because it
|
|
91
|
+
failed: carry on without it from the same place, playing if it was playing.
|
|
92
|
+
- **One set of controls, with the voice or without, and one clock at a time.**
|
|
93
|
+
The page keeps its own controls through a reading, and the dashboard draws
|
|
94
|
+
none; `read-aloud.md` has the rules. The speaker is `data-read-sound`, stored
|
|
95
|
+
`aria-pressed="false"`: a press brings the voice in at the top of the chapter
|
|
96
|
+
that is up, a second press takes it away, and the dashboard keeps
|
|
97
|
+
`aria-pressed`, by which CSS shows a speaker or a struck-out one. Play and Pause
|
|
98
|
+
is `data-read-pause`; Back, Next and each chapter mark are `data-read-move`.
|
|
99
|
+
While a reading is open their `onclick`s still show the chapter, but start and
|
|
100
|
+
stop no clock of the page's: the two would run against each other.
|
|
101
|
+
- **Every number in a caption is marked and filled from the data,** as a
|
|
102
|
+
Letter's are, whatever the source. Words you type are stored for everyone and
|
|
103
|
+
never change, while each reader's page runs a live query on their own
|
|
104
|
+
connection: a typed number would reach readers with no access to the source,
|
|
105
|
+
could contradict the figure on their stage, and would go stale. Words that
|
|
106
|
+
turn on the data (up, down, more, fewer) are filled too, from a calc. A goal
|
|
107
|
+
the person named is one constant in the script, unmarked, drawn wherever it
|
|
108
|
+
shows (`one-writer.md`). What you type is the gist, which holds whatever the
|
|
109
|
+
numbers are.
|
|
110
|
+
|
|
111
|
+
## Suggestions
|
|
112
|
+
|
|
113
|
+
**The piece.** Five to seven chapters usually carry one finding. The first is a
|
|
114
|
+
title: what it is, the period and how long it runs (worked out from the captions,
|
|
115
|
+
not typed). Set the title at about 6cqi, or put the one figure the story turns on
|
|
116
|
+
under a headline. The last is what to do next; it reads best ending with every
|
|
117
|
+
mark at full strength, since it stays up. The stage stands alone: tiles, filters,
|
|
118
|
+
tabs, tables or text around it pull the eye from what is playing.
|
|
119
|
+
|
|
120
|
+
**The stage.** 16:9 suits a wide page; in a wrapper under 800px (beside a chat) a
|
|
121
|
+
square uses the room better, and under 560px `4 / 5`, sized as in the skeleton.
|
|
122
|
+
`background: var(--color-panel)`, `border: 1px solid var(--color-border-line)`,
|
|
123
|
+
`border-radius: var(--cds-radius)`; no shadow, gradient or rule down the left.
|
|
124
|
+
|
|
125
|
+
**A chapter's frame**, the same each time so only the content changes: a small
|
|
126
|
+
uppercase label for the part of the story; a one-sentence headline that states
|
|
127
|
+
the finding, not the topic; the caption's row; one drawing; a small muted source
|
|
128
|
+
line (measure, who, dates). The chapter marks run across the top of the stage,
|
|
129
|
+
and the controls stand at the top right, on the label's line. So keep the label
|
|
130
|
+
short, and keep it on every chapter, the title too.
|
|
131
|
+
|
|
132
|
+
**Type** is set as on a slide, in `cqi` of the stage: headline about 3.4 and 18px
|
|
133
|
+
at least, to stay larger than the caption under it, labels and values on marks
|
|
134
|
+
1.8 (1em inside a drawing), captions 2, source line 1.3, a big number 12.
|
|
135
|
+
|
|
136
|
+
**The drawing fills its box,** the room between the caption's row and the source
|
|
137
|
+
line, which is most of the stage. The skeleton makes that box a container of both its sizes:
|
|
138
|
+
inside it `cqh` is 1% of its height, `cqi` 1% of its width, a little under the
|
|
139
|
+
stage's, and `em` the labels' size, set on the box. Size what is drawn from the
|
|
140
|
+
box, not from a fixed number of pixels. Bars share its height: each row is
|
|
141
|
+
100cqh over their number, up to about 18cqh, and the bar some 60% of its row.
|
|
142
|
+
Columns stand its full height, less their labels. A dot grid is the largest
|
|
143
|
+
square the box holds, `min(100cqh, 100cqi)` a side. What can't fill the box sits
|
|
144
|
+
in its middle, as the skeleton has it, not at its top.
|
|
145
|
+
|
|
146
|
+
**The drawing** is the one that shows the sentence. A share of people: a 10 by 10
|
|
147
|
+
grid of dots that fills, then recolors. A total: one big number that counts, with
|
|
148
|
+
what made it up beside it. A comparison: horizontal bars from zero, slightly
|
|
149
|
+
rounded. A gap between two: two bars and a bracket naming the gap. A run of
|
|
150
|
+
chapters that are all bars is a sign another drawing would fit somewhere. A bar
|
|
151
|
+
or dot painted with `background` vanishes in forced colors, so give it
|
|
152
|
+
`forced-color-adjust: none` and, under `@media (forced-colors: active)`, a system
|
|
153
|
+
color such as `CanvasText`, as the chapter marks in the skeleton do.
|
|
154
|
+
|
|
155
|
+
**How marks arrive.** Bars grow from zero, a value fades in once its bar lands,
|
|
156
|
+
dots come in a quick wave. 400 to 700ms with `d3.easeCubicOut` feels right (for
|
|
157
|
+
the chapters' fade, `--cds-ease-out`); camera moves, 3D and bounce don't. Gray
|
|
158
|
+
first, with one accent color on what the sentence is about; to focus, fade the
|
|
159
|
+
rest to about 25% opacity rather than add a color. Labels sit on the marks, so
|
|
160
|
+
gridlines, axis numbers and legends can go, and so can the tooltip `SKILL.md`
|
|
161
|
+
asks of a chart: every value is labeled.
|
|
162
|
+
|
|
163
|
+
**Captions.** One paragraph a chapter, 150 to 250 characters in two to four
|
|
164
|
+
short sentences, each in its own `.vs-s` span as in the skeleton and under some
|
|
165
|
+
100 characters, so that it fits its row. They read best
|
|
166
|
+
written as if said aloud, with no brackets or symbols, and are in the HTML. A
|
|
167
|
+
voice reads only the captions, so each says what its chapter shows without
|
|
168
|
+
leaning on the headline.
|
|
169
|
+
|
|
170
|
+
**Figures in captions.** Phrase each sentence so that it reads well around a
|
|
171
|
+
filled figure. By default that figure is rounded for the ear, to about two
|
|
172
|
+
significant figures ($100 for 102.08, 1,900 for 1,937), with "about" typed before
|
|
173
|
+
it where it helps, while the stage shows the exact one. A `dash.calc` returns the
|
|
174
|
+
rounded number and the caption's mark names that calc (`said` in the script), so
|
|
175
|
+
the dashboard still checks it. A calc can return words too ("almost half"); those
|
|
176
|
+
it can't check. Or a caption can leave the number out and let the figure on the
|
|
177
|
+
stage show it. Work out each mark's cue (see Pace) after the numbers are filled,
|
|
178
|
+
since filling moves where the words fall. A Visual short usually tells of a
|
|
179
|
+
period that has ended, so pin the dates in its queries: the gist is yours, and
|
|
180
|
+
should stay true.
|
|
181
|
+
|
|
182
|
+
**How captions show.** The sentence being said stands alone under the headline,
|
|
183
|
+
as plain words, so it covers nothing drawn. Each chapter keeps a row for it
|
|
184
|
+
(`.vs-say`, empty in the HTML), and the script lays the caption over that row.
|
|
185
|
+
The row is as tall whatever is being said, and with captions off, so the drawing
|
|
186
|
+
never moves. On the title before Play the sentence is the first; once a chapter
|
|
187
|
+
is whole, the last. A CC button among the controls, `aria-pressed` and on at
|
|
188
|
+
first, switches captions off and on; a page may use no storage, so the choice
|
|
189
|
+
lasts until it is loaded again.
|
|
190
|
+
|
|
191
|
+
**Pace.** People read the caption and watch the drawing at once, so a second for
|
|
192
|
+
every 15 characters is comfortable: a chapter lasts its caption's length divided
|
|
193
|
+
by 15, in seconds, plus 1. A mark's cue is the place where its word starts in
|
|
194
|
+
the caption (`indexOf`), divided by 15, so no seconds are typed. A voice keeps
|
|
195
|
+
its own pace, which the page isn't told. So while a reading is open the script times the voice: each caption it
|
|
196
|
+
reads through sets the pace for the next, and every cue, the sentences' too, is
|
|
197
|
+
scaled by it. A mark that hasn't moved when the voice goes on is drawn whole as
|
|
198
|
+
it leaves. When the voice goes off, `t` is divided by the pace, so the piece goes
|
|
199
|
+
on from the same place. With no reading open, at a chapter's end the next starts from `t` =
|
|
200
|
+
0; at the last it stops, and Play starts over.
|
|
201
|
+
|
|
202
|
+
**Controls.** Play or Pause, Back, Next and one mark per chapter let a reader
|
|
203
|
+
hold it and find their place; a chapter is the smallest part that makes sense
|
|
204
|
+
alone, so a slider adds little. The marks are a band of bars across the top of
|
|
205
|
+
the stage, each a button named for its chapter's label that plays from that
|
|
206
|
+
chapter's start, the current one with `aria-current="true"` and filling as it
|
|
207
|
+
plays. They stay up: they show how far the piece has got. The rest are slight:
|
|
208
|
+
bare, with no box around them, at the stage's top right on the label's line,
|
|
209
|
+
away from claude.ai's own bars under the page; on a narrow stage they take a row
|
|
210
|
+
of their own above the label. In order: Play or Pause (both in the HTML, one
|
|
211
|
+
shown), Back, Next and the speaker, which the dashboard hides where there is no
|
|
212
|
+
voice, each the inline SVG in the skeleton (the dashboard's own icons; a page has no icon font, so no text,
|
|
213
|
+
emoji or other drawing in their place) and named by an `aria-label`, the
|
|
214
|
+
toggle's set by the script to Play or Pause; and CC. While the piece plays they
|
|
215
|
+
fade as a video's controls do: as the pointer leaves the stage, or after a mouse
|
|
216
|
+
has lain still on it for 3 seconds. They come back when the pointer moves or
|
|
217
|
+
presses on the stage, or the keyboard moves focus into it. At rest, paused and
|
|
218
|
+
at the end they stay up, so Play can always be found; where the main pointer
|
|
219
|
+
can't hover, as on a phone, they never fade. They fade by `opacity`, so a
|
|
220
|
+
keyboard and a screen reader still reach them. With the voice on they fade and
|
|
221
|
+
come back the same way.
|
|
222
|
+
|
|
223
|
+
## Handing over
|
|
224
|
+
|
|
225
|
+
Besides what `design-defaults.md` has you tell the person: how long it runs, and
|
|
226
|
+
that Play starts it. Of the voice, say nothing unless the person asked to listen
|
|
227
|
+
(`read-aloud.md`).
|