@erclx/canon 5.51.0 → 5.53.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/CHANGELOG.md +20 -0
- package/README.md +1 -4
- package/claude/.claude-plugin/plugin.json +1 -1
- package/claude/skills/canon-cli/SKILL.md +0 -3
- package/claude/skills/context-fold/REQUIREMENT.md +0 -1
- package/claude/skills/design-taste/references/kinds.md +0 -1
- package/claude/skills/draw-figure/REQUIREMENT.md +2 -3
- package/claude/skills/draw-figure/SKILL.md +4 -5
- package/claude/skills/draw-figure/references/figures.md +0 -1
- package/claude/skills/draw-figure/references/hand-drawn.md +1 -1
- package/claude/skills/git-pr/references/pr.md +1 -1
- package/claude/skills/pick-by-eye/REQUIREMENT.md +0 -1
- package/claude/skills/pick-by-eye/SKILL.md +1 -1
- package/claude/skills/review-address/SKILL.md +1 -1
- package/claude/skills/review-address/references/post-review-findings.md +1 -1
- package/claude/skills/review-pr/references/post.md +2 -2
- package/claude/skills/target-check/SKILL.md +2 -0
- package/claude/skills/target-setup/SKILL.md +1 -1
- package/claude/skills/target-update/REQUIREMENT.md +33 -0
- package/claude/skills/target-update/SKILL.md +136 -0
- package/claude/skills/teach-craft/REQUIREMENT.md +30 -0
- package/claude/skills/teach-craft/SKILL.md +39 -0
- package/claude/skills/teach-craft/references/lesson-craft.md +52 -0
- package/claude/skills/{teach-workspace → teach-craft}/references/pedagogy.md +12 -4
- package/docs/agents/audits.md +0 -1
- package/docs/agents/migrate.md +2 -1
- package/docs/target/migrations.md +12 -1
- package/docs/target/projects.md +1 -1
- package/docs/target/sync.md +1 -1
- package/docs/workflow/parallel-features.md +1 -1
- package/docs/workflow/skill-map-on-request.md +10 -22
- package/docs/workflow/skill-map.md +13 -14
- package/package.json +1 -4
- package/scripts/core/regen-web-previews.ts +2 -67
- package/src/audits/catalog.ts +0 -1
- package/src/browser/engine.ts +3 -6
- package/src/capture/render.ts +1 -1
- package/src/claude/cases/authoring.ts +0 -12
- package/src/claude/cases/misc.ts +0 -17
- package/src/claude/cases/setup.ts +7 -0
- package/src/claude/cases/workflow.ts +2 -38
- package/src/claude/skills-audit.ts +0 -1
- package/src/cli/help.ts +0 -7
- package/src/cli.ts +0 -6
- package/src/commands/labels.ts +9 -7
- package/src/commands/records.ts +0 -1
- package/src/commands/serve.ts +2 -2
- package/src/design/components.ts +8 -1514
- package/src/design/css.ts +5 -6
- package/src/design/fonts.ts +3 -5
- package/src/driver/drive.ts +3 -4
- package/src/driver/steps.ts +2 -5
- package/src/inventory/walk.ts +1 -1
- package/src/markdown/scope.ts +4 -31
- package/src/migrate/status.ts +5 -1
- package/src/records/validate.ts +4 -176
- package/src/sandbox/equivalence.ts +0 -5
- package/tooling/claude/seeds/.claude/hooks/review-post-scan.sh +1 -1
- package/claude/skills/draft-and-pick/REQUIREMENT.md +0 -26
- package/claude/skills/draft-and-pick/SKILL.md +0 -11
- package/claude/skills/draft-doc/REQUIREMENT.md +0 -26
- package/claude/skills/draft-doc/SKILL.md +0 -11
- package/claude/skills/draft-figure/REQUIREMENT.md +0 -26
- package/claude/skills/draft-figure/SKILL.md +0 -11
- package/claude/skills/draft-identity/REQUIREMENT.md +0 -26
- package/claude/skills/draft-identity/SKILL.md +0 -11
- package/claude/skills/draft-ready/REQUIREMENT.md +0 -26
- package/claude/skills/draft-ready/SKILL.md +0 -11
- package/claude/skills/draft-screencast/REQUIREMENT.md +0 -26
- package/claude/skills/draft-screencast/SKILL.md +0 -11
- package/claude/skills/draft-slides/REQUIREMENT.md +0 -26
- package/claude/skills/draft-slides/SKILL.md +0 -11
- package/claude/skills/make-deck/REQUIREMENT.md +0 -36
- package/claude/skills/make-deck/SKILL.md +0 -80
- package/claude/skills/make-deck/references/deck.md +0 -183
- package/claude/skills/read-frames/REQUIREMENT.md +0 -30
- package/claude/skills/read-frames/SKILL.md +0 -55
- package/claude/skills/record-screencast/REQUIREMENT.md +0 -35
- package/claude/skills/record-screencast/SKILL.md +0 -99
- package/claude/skills/script-screencast/REQUIREMENT.md +0 -34
- package/claude/skills/script-screencast/SKILL.md +0 -70
- package/claude/skills/script-screencast/references/beats-template.md +0 -119
- package/claude/skills/teach-workspace/REQUIREMENT.md +0 -34
- package/claude/skills/teach-workspace/SKILL.md +0 -196
- package/claude/skills/teach-workspace/references/glossary.md +0 -90
- package/claude/skills/teach-workspace/references/lesson-build.md +0 -106
- package/claude/skills/teach-workspace/references/lesson-craft.md +0 -135
- package/claude/skills/teach-workspace/references/promotion-fold.md +0 -35
- package/claude/skills/teach-workspace/references/promotion.md +0 -116
- package/claude/skills/teach-workspace/references/revisit.md +0 -28
- package/claude/skills/teach-workspace/references/teach.md +0 -211
- package/claude/skills/video-craft/REQUIREMENT.md +0 -35
- package/claude/skills/video-craft/SKILL.md +0 -96
- package/claude/skills/video-craft/references/adopted.md +0 -110
- package/src/commands/demo.ts +0 -542
- package/src/commands/slides.ts +0 -184
- package/src/commands/teach.ts +0 -1401
- package/src/demo/beats.ts +0 -135
- package/src/demo/compile.ts +0 -350
- package/src/demo/container.ts +0 -219
- package/src/demo/cursors.ts +0 -55
- package/src/demo/drive.ts +0 -442
- package/src/demo/pointer.ts +0 -178
- package/src/demo/theme.ts +0 -112
- package/src/demo/timeline.ts +0 -64
- package/src/slides/convert/chart.ts +0 -165
- package/src/slides/convert/deck.ts +0 -244
- package/src/slides/convert/export.ts +0 -567
- package/src/slides/convert/master.ts +0 -198
- package/src/slides/convert/shapes.ts +0 -804
- package/src/slides/convert/svg.ts +0 -38
- package/src/slides/convert/walk.ts +0 -671
- package/src/slides/decks.ts +0 -110
- package/src/slides/open.ts +0 -18
- package/src/slides/package/fonts.ts +0 -301
- package/src/slides/package/motion.ts +0 -316
- package/src/slides/package/test-face.ts +0 -113
- package/src/teach/browser/compile.ts +0 -44
- package/src/teach/browser/dismiss.ts +0 -76
- package/src/teach/browser/focus-line.ts +0 -19
- package/src/teach/browser/glossary-filter.ts +0 -44
- package/src/teach/browser/head.ts +0 -30
- package/src/teach/browser/quiz.ts +0 -19
- package/src/teach/browser/reload.ts +0 -9
- package/src/teach/browser/sidebar.ts +0 -233
- package/src/teach/browser/theme.ts +0 -18
- package/src/teach/components/code.tsx +0 -24
- package/src/teach/components/heading.tsx +0 -11
- package/src/teach/components/list.tsx +0 -17
- package/src/teach/components/paragraph.tsx +0 -29
- package/src/teach/components/refs.tsx +0 -28
- package/src/teach/cross-references.ts +0 -78
- package/src/teach/fonts.ts +0 -16
- package/src/teach/highlight.ts +0 -71
- package/src/teach/html/jsx-dev-runtime.ts +0 -13
- package/src/teach/html/jsx-runtime.ts +0 -113
- package/src/teach/html/raw.ts +0 -28
- package/src/teach/lesson.ts +0 -178
- package/src/teach/nav.ts +0 -1337
- package/src/teach/render.ts +0 -240
- package/src/teach/workspace.ts +0 -1164
- package/src/teach/write-if-changed.ts +0 -17
|
@@ -1,211 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Teach reference
|
|
3
|
-
description: Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Teach reference
|
|
7
|
-
|
|
8
|
-
Applies to a learning workspace at `.canon/teach/<nn>-<topic>/`. One workspace holds one subject studied across sessions, and it carries both halves of what studying produces: the durable reference material a reader consults later, and the disposable lessons a learner works through once.
|
|
9
|
-
|
|
10
|
-
The folder is gitignored. Its markdown half is written in a format the authoring gates read, so a page promoted out of it later needs no conversion.
|
|
11
|
-
|
|
12
|
-
## Contents
|
|
13
|
-
|
|
14
|
-
- [Scope](#scope)
|
|
15
|
-
- [What a working workspace looks like](#what-a-working-workspace-looks-like)
|
|
16
|
-
- [Folder name](#folder-name)
|
|
17
|
-
- [Layout](#layout)
|
|
18
|
-
- [Frontmatter](#frontmatter)
|
|
19
|
-
- [File naming](#file-naming)
|
|
20
|
-
- [MISSION.md](#missionmd)
|
|
21
|
-
- [Learning records](#learning-records)
|
|
22
|
-
- [Revisit](#revisit)
|
|
23
|
-
- [GLOSSARY.md](#glossarymd)
|
|
24
|
-
- [RESOURCES.md](#resourcesmd)
|
|
25
|
-
- [Conventions](#conventions)
|
|
26
|
-
- [Anti-patterns](#anti-patterns)
|
|
27
|
-
- [Template](#template)
|
|
28
|
-
|
|
29
|
-
## Scope
|
|
30
|
-
|
|
31
|
-
Governs a learning workspace under `.canon/teach/<nn>-<topic>/`: folder layout, ordinal naming, frontmatter, and the mission and learning-record formats.
|
|
32
|
-
|
|
33
|
-
Does not govern:
|
|
34
|
-
|
|
35
|
-
- **the `teach-workspace` skill**: the frontmatter, entry shape, and ordering of the glossary the workspace holds, which that skill's reference carries
|
|
36
|
-
- **the surface driving the workspace**: what a lesson teaches, how it sequences difficulty, and what makes one worth returning to
|
|
37
|
-
- **the routing test the destination surface states**: where a durable page goes once it leaves the workspace
|
|
38
|
-
- **`groundwork.md`**: one question measured in depth before anyone can plan against it
|
|
39
|
-
- **`intake.md`**: A dump of many findings filed by domain, each carrying its own verdict
|
|
40
|
-
- **the `write-human` skill**: voice, rhythm, and sentence construction
|
|
41
|
-
- **`markdown.md`**: headings, punctuation, word choice, and file references
|
|
42
|
-
- **the surface driving it**: when a workspace opens at all, and the procedure that runs one
|
|
43
|
-
|
|
44
|
-
## What a working workspace looks like
|
|
45
|
-
|
|
46
|
-
A workspace works when a session returning after weeks can resume from the folder alone:
|
|
47
|
-
|
|
48
|
-
- Which subject is being learned, and what will the learner be able to do when the mission is finished?
|
|
49
|
-
- Which sources stand behind the material, and which were found and never opened?
|
|
50
|
-
- What has the learner already been through, and what did they get wrong?
|
|
51
|
-
- Which pages here are durable reference material, and which are disposable?
|
|
52
|
-
|
|
53
|
-
A workspace failing these is non-conforming even when it satisfies every shape rule below.
|
|
54
|
-
|
|
55
|
-
## Folder name
|
|
56
|
-
|
|
57
|
-
- Name the folder `<nn>-<topic>`, a two-digit zero-padded ordinal followed by a kebab-case topic slug.
|
|
58
|
-
- Take the ordinal from the highest one already present, incremented. A listing then sorts by when each workspace opened rather than alphabetically.
|
|
59
|
-
- Use two digits on the folder and four inside it. A person opens far fewer workspaces than one workspace holds lessons.
|
|
60
|
-
- Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
|
|
61
|
-
|
|
62
|
-
## Layout
|
|
63
|
-
|
|
64
|
-
| Path | Holds | Required |
|
|
65
|
-
| ----------------------- | ----------------------------------------------------------------------- | -------- |
|
|
66
|
-
| `MISSION.md` | The subject, the learner's starting point, and success | Always |
|
|
67
|
-
| `RESOURCES.md` | Sources read and sources found but not opened | Always |
|
|
68
|
-
| `GLOSSARY.md` | Terms the subject defines, one entry each | Always |
|
|
69
|
-
| `NOTES.md` | Session scratch that belongs to no other file | Optional |
|
|
70
|
-
| `reference/<slug>.md` | Durable reference pages, the promotable half | Optional |
|
|
71
|
-
| `reference/<slug>.html` | Each reference page rendered by `canon teach nav`, never edited by hand | Optional |
|
|
72
|
-
| `learning-records/` | Numbered records of what the learner was taken through | Optional |
|
|
73
|
-
| `lessons/` | Numbered lessons, generated and disposable | Optional |
|
|
74
|
-
| `assets/` | Files several lessons share, including the stylesheet | Optional |
|
|
75
|
-
|
|
76
|
-
Only the markdown half answers to a conformance check: `MISSION.md`, `RESOURCES.md`, `GLOSSARY.md`, `NOTES.md`, the markdown under `reference/`, and `learning-records/`.
|
|
77
|
-
|
|
78
|
-
- A lesson is generated markup nothing downstream cites, so this standard fixes its filename and location and nothing about its contents
|
|
79
|
-
- A rendered reference page is the same kind of output, rewritten from its markdown on every `nav` run
|
|
80
|
-
|
|
81
|
-
## Frontmatter
|
|
82
|
-
|
|
83
|
-
Every markdown file carries `title` and `description`. `MISSION.md` carries one field the others do not.
|
|
84
|
-
|
|
85
|
-
- `title` (required): what the file covers, in sentence case
|
|
86
|
-
- `description` (required): one line naming what a reader gets from it
|
|
87
|
-
- `date` (required, `MISSION.md` only): the day the workspace opened, as `YYYY-MM-DD`
|
|
88
|
-
|
|
89
|
-
Date the workspace once rather than every file. A per-file date leaves every other file stale the first time one is edited, and the opening date never rots.
|
|
90
|
-
|
|
91
|
-
## File naming
|
|
92
|
-
|
|
93
|
-
- Number a lesson and a learning record `0001` upward, as `<nnnn>-<slug>.html` and `<nnnn>-<slug>.md`. The number is read order and never changes.
|
|
94
|
-
- Name a reference page for its subject alone, with no number. A reference page is looked up rather than worked through, so an ordinal on one implies an order no reader follows.
|
|
95
|
-
- Keep one shared stylesheet under `assets/` and embed it in every lesson. A lesson restating its own styles makes a workspace read as a pile of one-offs rather than as one course.
|
|
96
|
-
|
|
97
|
-
## MISSION.md
|
|
98
|
-
|
|
99
|
-
Fixes what the workspace is for. Everything else in the folder answers to it.
|
|
100
|
-
|
|
101
|
-
- A one-line statement of the subject
|
|
102
|
-
- A `## Starting point` section stating what the learner already knows, so difficulty has a floor to sit above
|
|
103
|
-
- A `## Success looks like` section listing specific observable things the learner will be able to do
|
|
104
|
-
- A `## Out of scope` section naming what this workspace deliberately does not cover
|
|
105
|
-
|
|
106
|
-
Write each success line as something a learner can be asked to do rather than something they will understand. A line nobody can test is a line nothing can report progress against.
|
|
107
|
-
|
|
108
|
-
## Learning records
|
|
109
|
-
|
|
110
|
-
One record per session the learner worked through, holding what happened rather than what was taught.
|
|
111
|
-
|
|
112
|
-
- The lessons covered, by number
|
|
113
|
-
- What the learner retrieved correctly without help
|
|
114
|
-
- What they got wrong, and what the wrong answer was, including what an explanation the learner produced left out
|
|
115
|
-
- A `## Revisit` section scheduling what comes back up
|
|
116
|
-
|
|
117
|
-
Record the wrong answer rather than the fact of an error. A wrong answer names the misconception, and the count alone names nothing.
|
|
118
|
-
|
|
119
|
-
A produced explanation and a selected option are both retrieval, so a gap in an explanation goes under what the learner got wrong rather than under a heading of its own. Name the concept and where the explanation broke. Splitting the two puts one input to the next session's placement across two sections, and the placement reads both or neither.
|
|
120
|
-
|
|
121
|
-
### The revisit section
|
|
122
|
-
|
|
123
|
-
Write one bullet per item, in this shape and no other:
|
|
124
|
-
|
|
125
|
-
```markdown
|
|
126
|
-
## Revisit
|
|
127
|
-
|
|
128
|
-
- **<what comes back up>**: due <YYYY-MM-DD>, rung <n>
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
The rung is the item's place on the spacing ladder. It travels in the record rather than being counted from records naming the item, since a miss drops it back and a count only climbs.
|
|
132
|
-
|
|
133
|
-
- A later record naming the item supersedes an earlier one, so revise by writing a new entry rather than editing the old record
|
|
134
|
-
- Take the date and rung from what the driving surface reports. An entry outside this shape schedules nothing, silently.
|
|
135
|
-
|
|
136
|
-
## GLOSSARY.md
|
|
137
|
-
|
|
138
|
-
Required at the root of every workspace, one entry per term the subject defines. The glossary reference the `canon:teach-workspace` skill carries fixes the entry shape, order, grouping, and which terms it holds.
|
|
139
|
-
|
|
140
|
-
- That reference ships with the plugin rather than installing here, since a promoted glossary keeps its shape wherever it lands
|
|
141
|
-
- With no plugin to read it from, say so and stop rather than working the shape from memory
|
|
142
|
-
- Name the lesson or reference page a term first appears in, which a workspace always has
|
|
143
|
-
|
|
144
|
-
## RESOURCES.md
|
|
145
|
-
|
|
146
|
-
Splits what was read from what was found.
|
|
147
|
-
|
|
148
|
-
- List every source that stands behind the material, each with a link
|
|
149
|
-
- List under a leads heading any source found and not opened, and never cite one
|
|
150
|
-
- Say which claims in the workspace rest on which source
|
|
151
|
-
|
|
152
|
-
An unread source is a lead because a link to a page nobody opened is worse than none. Listing it stops a later session searching again.
|
|
153
|
-
|
|
154
|
-
### Choosing sources
|
|
155
|
-
|
|
156
|
-
Rest each general claim on the highest rung that covers it:
|
|
157
|
-
|
|
158
|
-
1. Documentation or a specification published by whoever owns the subject
|
|
159
|
-
2. A canonical work on the subject, such as the standard text, a reference book, or a primary paper
|
|
160
|
-
3. Other material, such as a tutorial, a course, or a post, and only for a claim the first two rungs do not cover
|
|
161
|
-
|
|
162
|
-
A subject nobody owns, such as a mathematical topic or a craft, has no first rung, so its list starts at the second and is not missing anything. Record a third-rung source with the claim it covers and why no higher rung does, since that reason is what a later session checks the choice against.
|
|
163
|
-
|
|
164
|
-
### What never counts
|
|
165
|
-
|
|
166
|
-
The learner's own projects and material specific to one employer or organization are never a source for a general claim. Either may appear in the workspace as a worked application labeled with whose it is, and neither stands in `RESOURCES.md` as proof of what the subject says.
|
|
167
|
-
|
|
168
|
-
A source reachable only through a paywall or a summary stays a lead until it is opened. A review or summary of a book is a different source from the book, so list the summary as read on its own rung and the book as a lead.
|
|
169
|
-
|
|
170
|
-
## Conventions
|
|
171
|
-
|
|
172
|
-
- Write the markdown half in the format the authoring gates read, so a page promoted later needs no conversion.
|
|
173
|
-
- Keep a reference page free of the learner. A page carrying a second person or a quiz is a lesson wearing the wrong extension, and it cannot be promoted.
|
|
174
|
-
- Revise a file the subject has moved under rather than appending a second version narrating the change.
|
|
175
|
-
|
|
176
|
-
## Anti-patterns
|
|
177
|
-
|
|
178
|
-
- **The mission with no test.** Success stated as understanding rather than as a task leaves nothing able to say the mission is finished.
|
|
179
|
-
- **The lesson filed as reference.** A page written to be worked through once sits in `lessons/`, and putting it in `reference/` puts disposable output in the half that gets promoted.
|
|
180
|
-
- **The record that counts errors.** A tally of how many were missed carries none of the misconception, which is the only part a later session can act on.
|
|
181
|
-
- **The revisit note with no date.** A line naming what to come back to and not when schedules nothing, so the next session picks from the last record alone, the state the section exists to end.
|
|
182
|
-
- **The date left in the body.** A frontmatter field and a sentence both claiming the opening date resolve to whichever a reader hits, and a walker reads only one.
|
|
183
|
-
- **The first search result as the source list.** A workspace resting on the first search hit teaches the weakest account of the subject, and nothing in the folder says a stronger one went unsought.
|
|
184
|
-
- **The renumbered folder.** Closing a gap in the ordinals moves every name a reader or a record already cited.
|
|
185
|
-
|
|
186
|
-
## Template
|
|
187
|
-
|
|
188
|
-
```markdown
|
|
189
|
-
---
|
|
190
|
-
title: <Subject>
|
|
191
|
-
description: <one line naming what a learner gets from this workspace>
|
|
192
|
-
date: <YYYY-MM-DD>
|
|
193
|
-
---
|
|
194
|
-
|
|
195
|
-
# <Subject>
|
|
196
|
-
|
|
197
|
-
<One line stating the subject.>
|
|
198
|
-
|
|
199
|
-
## Starting point
|
|
200
|
-
|
|
201
|
-
<What the learner already knows.>
|
|
202
|
-
|
|
203
|
-
## Success looks like
|
|
204
|
-
|
|
205
|
-
- <a specific thing the learner will be able to do>
|
|
206
|
-
- <a specific thing the learner will be able to do>
|
|
207
|
-
|
|
208
|
-
## Out of scope
|
|
209
|
-
|
|
210
|
-
- <what this workspace deliberately does not cover>
|
|
211
|
-
```
|
|
@@ -1,35 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: video-craft
|
|
3
|
-
description: Why a session composing a video of software needs sourced judgment on captions, zoom, pointer, and audio beyond what HyperFrames' own skills carry, and why every number in it has to trace to a source
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Video craft requirement
|
|
7
|
-
|
|
8
|
-
## Gap
|
|
9
|
-
|
|
10
|
-
Without this skill, a composed video of software gets general motion craft from HyperFrames and nothing on top. Nothing says what a caption says, which moment earns a zoom, how a recorded pointer behaves, or how far music sits under a voice. A render pushes in slowly, narrates the whole flow in one caption, and opens on a slogan card.
|
|
11
|
-
|
|
12
|
-
Numbers from recall are the second gap. HyperFrames states its zoom duration with no source, and its default music bed sits closer under a voice than the accessibility guideline asks. A session taking either as given reproduces the defaults that read generic.
|
|
13
|
-
|
|
14
|
-
## Must
|
|
15
|
-
|
|
16
|
-
- A caption names only what its frame shows, with its timing, line count, line length, and reading rate traced to published subtitle guidelines
|
|
17
|
-
- A zoom lands on an action, aimed from the take's timeline with a sourced push duration, and one pointer clicks inside each recorded target
|
|
18
|
-
- The choice of music or silence, the music's level under a voice, and a voiceover's pace each carry a sourced number
|
|
19
|
-
- A checker finding is dismissed only after the frame it names is read
|
|
20
|
-
- Every number traces to a source in `references/adopted.md`, a conflict between sources names its pick, and the body closes with the practice skill's three closing sections
|
|
21
|
-
|
|
22
|
-
## Must not
|
|
23
|
-
|
|
24
|
-
- Restate a rule HyperFrames' own skills carry, such as ease variety, anchoring, click timing, a zoom's scale and dwell, safe margins, or the carve under a voice
|
|
25
|
-
- State a number `references/adopted.md` does not trace to a source, or claim loading the skill improves a render before a with-and-without comparison
|
|
26
|
-
- Fetch, generate, or install a media file or HyperFrames itself
|
|
27
|
-
- Name this repository's demos, branches, or render files, since the body ships to targets holding none of them
|
|
28
|
-
- Set pointer smoothing or hiding, which are recorder settings a composition cannot change
|
|
29
|
-
|
|
30
|
-
## Out of scope
|
|
31
|
-
|
|
32
|
-
- General motion and composition rules, which `hyperframes-animation` and `hyperframes-creative` own
|
|
33
|
-
- Sourcing media, which `media-use` owns
|
|
34
|
-
- Recording the take, and loading this skill before it composes, which `record-screencast` owns
|
|
35
|
-
- Vertical 9:16 framing, which no skill owns until a project asks for it
|
|
@@ -1,96 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: video-craft
|
|
3
|
-
description: Carries what makes a composed video of software read as designed rather than generic, being captions that name only what the frame shows, which moment earns a zoom and how fast it lands, how a real pointer behaves on a real interface, music or silence and how far under a voice the music sits, and reading a frame before dismissing a checker finding. Every number traces to a source. Use before composing or judging any video, whether a product demo, an explainer, a pull request walkthrough, or a launch clip, when a render reads generic or slow, or when asked "make this video look designed", "is this zoom too slow", "what should this caption say", "should this have music", or "the checker flagged a frame, is it real". Do NOT use for general motion such as easing, speed variety, and click timing, which HyperFrames' `hyperframes-animation` and `hyperframes-creative` carry, to fetch or generate a media file, which is `media-use`, or to record the take, which is `record-screencast`.
|
|
4
|
-
metadata:
|
|
5
|
-
family: build
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
# Video craft
|
|
9
|
-
|
|
10
|
-
A session composing a video with no stated direction reaches for defaults, such as a slow push-in, one ease on every move, a centered caption pill, and a slogan intro card. Together they read as generic. This skill carries the judgment specific to a video of software, which HyperFrames' own skills leave out.
|
|
11
|
-
|
|
12
|
-
Load `hyperframes-creative` and `hyperframes-animation` first. They own general motion, being ease and speed variety, anchoring, and click timing, and this body names none of their rules.
|
|
13
|
-
|
|
14
|
-
## Scope and sources
|
|
15
|
-
|
|
16
|
-
The guidance covers landscape 16:9 video, and vertical 9:16 framing is not covered yet. Read `${CLAUDE_SKILL_DIR}/references/adopted.md` for the source behind every number below, only when extending this guidance or arguing against a rule in it.
|
|
17
|
-
|
|
18
|
-
## Captions name what the frame shows
|
|
19
|
-
|
|
20
|
-
- Write each caption about the frame on screen while it shows, never about the step before or the one after. A caption narrating the whole flow describes a frame the viewer is not looking at.
|
|
21
|
-
- Name the visible change, such as the card landing or the field filling, rather than the feature's pitch. The pitch belongs in an intro card or the voiceover.
|
|
22
|
-
- Start a caption on the first frame of the action it names, and keep it on screen for at least 5/6 of a second and at most 7 seconds.
|
|
23
|
-
- Hold a caption to two lines of at most 42 characters, read at no more than 20 characters per second, or 17 for an audience of children. Cut words rather than shorten the hold.
|
|
24
|
-
- Place a caption where it covers nothing the frame is about. Move it off the element the step acts on, rather than centering it by default. HyperFrames' studio skill owns the title-safe margins.
|
|
25
|
-
|
|
26
|
-
## A zoom is earned by an action
|
|
27
|
-
|
|
28
|
-
- Zoom only on a click, fill, or hover whose result is too small to read at full frame. A navigate, a wait, or a hold has nothing to aim at.
|
|
29
|
-
- Aim the zoom at the action's own place and moment. `canon demo run` writes a timeline beside the take with each step's start, end, and target box, so read the zoom off it, never summing holds.
|
|
30
|
-
- Run a push that lands on an action no faster than the floor HyperFrames' `viewport-change` rule states, and never past 1 second
|
|
31
|
-
- That rule's own range suits an ambient reveal with no action to land on, and reads slow on a push onto a click
|
|
32
|
-
- Leave the scale and the dwell after a zoom settles to the `viewport-change` rule, which states both.
|
|
33
|
-
|
|
34
|
-
## A real pointer on a real interface
|
|
35
|
-
|
|
36
|
-
- Keep the pointer the take recorded. Never draw a second, synthetic cursor over a real interface, since two pointers on one frame leave the viewer guessing which one acted.
|
|
37
|
-
- Check that each click lands inside the target box the timeline records for it. A pointer arriving beside the button it claims to press reads as a fake.
|
|
38
|
-
|
|
39
|
-
## Music, silence, and a voice
|
|
40
|
-
|
|
41
|
-
- Choose silence over a music bed that competes with a voiceover. A bed earns its place on a video with no voice, where it carries the pacing between beats.
|
|
42
|
-
- Sit music at least 20 dB under the voice. Check `media-use`'s narrated bed default against that floor, since it has sat short of it.
|
|
43
|
-
- The mechanism, a carve rather than a flat duck, is `hyperframes-audio`'s
|
|
44
|
-
- Keep a captioned voiceover at or under 160 words a minute, since a faster voice forces captions past their reading limit. `hyperframes-creative`'s narration pace sits under that ceiling.
|
|
45
|
-
|
|
46
|
-
## Read the frame before dismissing a finding
|
|
47
|
-
|
|
48
|
-
- Open the frame at the timestamp a checker names before calling its finding a false positive, whether the checker is `hyperframes check`, `canon demo frames`, or `read-frames`.
|
|
49
|
-
- Report what the frame shows beside the dismissal. A dismissal with no frame read is a guess about the render, and the viewer sees the render.
|
|
50
|
-
|
|
51
|
-
## Excuses and rebuttals
|
|
52
|
-
|
|
53
|
-
| Excuse | Rebuttal |
|
|
54
|
-
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
55
|
-
| A slow zoom feels cinematic | A push onto an action is interface motion. Past 1 second the viewer waits on the camera instead of watching the action land. |
|
|
56
|
-
| The caption explains the whole feature, so it is more useful | A caption about anything but the frame on screen makes the viewer read one thing and watch another. |
|
|
57
|
-
| The checker flagged a frame I already know is fine | Knowing is a memory of the composition, not of the render. Open the frame. |
|
|
58
|
-
| Music makes it feel finished | Music under a voice that is not 20 dB down masks the words, and the words carry the explanation. |
|
|
59
|
-
| A drawn cursor looks cleaner than the recorded one | The recorded pointer is the one that pressed the button. A drawn one is a claim about an action the take already shows. |
|
|
60
|
-
|
|
61
|
-
## Red flags
|
|
62
|
-
|
|
63
|
-
- A push onto a click runs longer than 1 second.
|
|
64
|
-
- Every move in the composition shares one duration.
|
|
65
|
-
- A caption is centered on screen and covers the element the step acts on.
|
|
66
|
-
- A caption names a step the frame is not showing.
|
|
67
|
-
|
|
68
|
-
### Timing and checks
|
|
69
|
-
|
|
70
|
-
These flags catch a composition built from memory rather than from the take.
|
|
71
|
-
|
|
72
|
-
- The zoom's start time was added up by hand while a timeline file sits beside the take.
|
|
73
|
-
- Two pointers appear on one frame.
|
|
74
|
-
- A checker finding was dismissed and no frame was opened.
|
|
75
|
-
|
|
76
|
-
## Before handing over
|
|
77
|
-
|
|
78
|
-
- Every caption names what its frame shows, starts on its action's first frame, and holds within its time and length limits.
|
|
79
|
-
- Every zoom aims at a click, fill, or hover read from the timeline, and lands within its duration.
|
|
80
|
-
- One pointer is on screen, and each click lands inside its recorded box.
|
|
81
|
-
- Music, when present, sits at least 20 dB under any voice, and a captioned voice stays at or under 160 words a minute.
|
|
82
|
-
- Every checker finding was either fixed or dismissed with the frame it names read and reported.
|
|
83
|
-
|
|
84
|
-
## What this delegates
|
|
85
|
-
|
|
86
|
-
- Easing, speed variety, anchoring, click timing, and every other general motion rule: `hyperframes-animation` and `hyperframes-creative`
|
|
87
|
-
- Title-safe margins and timeline layout: `hyperframes-studio`
|
|
88
|
-
- The carve that sits music under a voice: `hyperframes-audio`
|
|
89
|
-
|
|
90
|
-
### Media, capture, and reading
|
|
91
|
-
|
|
92
|
-
The assets around the composition belong to other skills too.
|
|
93
|
-
|
|
94
|
-
- Fetching or generating music, effects, voice, and imagery: `media-use`
|
|
95
|
-
- Recording the take and writing its timeline: `record-screencast` through `canon demo run`
|
|
96
|
-
- Reading a render frame by frame: `read-frames`
|
|
@@ -1,110 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Adopted and declined
|
|
3
|
-
description: The source behind every number in the video-craft body, by field, which conflicts between sources were picked and why, and what was declined
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Adopted and declined
|
|
7
|
-
|
|
8
|
-
Each number in the body traces to a source here, read through the `search-craft` method: the field named first, its authorities derived from the kind of body it trusts, and each question searched scoped to those authorities and open beside it. A later session extending the skill adds to this file rather than re-arguing an item settled here.
|
|
9
|
-
|
|
10
|
-
## Captions
|
|
11
|
-
|
|
12
|
-
Field: subtitling and captioning. Authorities: broadcasters' and streamers' published subtitle guidelines, and the captioning program that sets educational practice.
|
|
13
|
-
|
|
14
|
-
| Rule | Source |
|
|
15
|
-
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
16
|
-
| On screen for 5/6 of a second to 7 seconds | Netflix's [Timed Text Style Guide: General Requirements](https://partnerhelp.netflixstudios.com/hc/en-us/articles/215758617-Timed-Text-Style-Guide-General-Requirements), a minimum of 20 frames at 24 fps |
|
|
17
|
-
| Two lines, 42 characters a line | Netflix's [English (USA) guide](https://partnerhelp.netflixstudios.com/hc/en-us/articles/217350977-English-USA-Timed-Text-Style-Guide) |
|
|
18
|
-
| 20 characters per second, 17 for children | The same English (USA) guide, adult and children's programs respectively |
|
|
19
|
-
| Never over what the frame is about | The DCMP [Captioning Tip Sheet](https://dcmp.org/learn/225-captioning-tip-sheet): "Placement must not interfere with existing visuals/graphics." |
|
|
20
|
-
|
|
21
|
-
### Start on the first frame of the action
|
|
22
|
-
|
|
23
|
-
Netflix's [Subtitle Timing Guidelines](https://partnerhelp.netflixstudios.com/hc/en-us/articles/360051554394-Timed-Text-Style-Guide-Subtitle-Timing-Guidelines) put a subtitle's in-time on the first frame of its audio. A software video's caption names an action rather than a line of speech, so the body keys the in-time on the action's first frame.
|
|
24
|
-
|
|
25
|
-
### Captions name what the frame shows
|
|
26
|
-
|
|
27
|
-
No source states this for a software video. It is the operator's read of an unguided render whose caption narrated the whole flow, kept because the timing rules above already assume a caption tied to one moment.
|
|
28
|
-
|
|
29
|
-
## Zoom
|
|
30
|
-
|
|
31
|
-
Fields: interface motion design, and screen recording practice. Authorities: design systems that publish motion specs, and the reference documentation of a screen recording tool.
|
|
32
|
-
|
|
33
|
-
### A push onto an action stays under 1 second
|
|
34
|
-
|
|
35
|
-
The floor is HyperFrames'. Its `viewport-change` rule states a zoom of 1.0 to 2.0 seconds with the reason beside it, "under 0.8s teleports, over 2.5s drags", and the body points at the rule rather than restating it.
|
|
36
|
-
|
|
37
|
-
- Measured: an unguided render pushed in over 2.2 seconds and a second over 1.4 seconds, and the operator judged both slow, so the range's lower half already reads slow on a push onto a click
|
|
38
|
-
- Published: Material Design 3's [easing and duration tokens](https://m3.material.io/styles/motion/easing-and-duration/tokens-specs) end at 1000 ms, the top of a band reserved for ambient transitions, so no input-driven transition there runs longer
|
|
39
|
-
|
|
40
|
-
### Zoom on a click
|
|
41
|
-
|
|
42
|
-
Screen Studio's [auto zoom guide](https://screen.studio/guide/auto-zoom) keys its zoom on click positions and zooms nowhere a click did not occur.
|
|
43
|
-
|
|
44
|
-
### Conflict, and the pick
|
|
45
|
-
|
|
46
|
-
HyperFrames' range and the measured renders disagree on the push onto an action. The body takes the overlap, HyperFrames' teleport floor below and 1 second above, which sits inside HyperFrames' range at its fast end.
|
|
47
|
-
|
|
48
|
-
- HyperFrames' full range stays with an ambient reveal, matching Material's own split between input-driven and ambient motion
|
|
49
|
-
- A tighter band was declined. Material puts large expressive transitions at 450 to 600 ms, and Nielsen Norman Group's [animation duration article](https://www.nngroup.com/articles/animation-duration/) calls 400 ms "very slow".
|
|
50
|
-
- Both write for an interface a user waits on, which a video viewer is not, and that band sits below HyperFrames' teleport floor with nothing measured to show it reads right
|
|
51
|
-
|
|
52
|
-
Narrow the band once a composed demo is compared against the unguided renders.
|
|
53
|
-
|
|
54
|
-
## Pointer
|
|
55
|
-
|
|
56
|
-
The two pointer rules in the body carry no number. One pointer on a frame and a click landing inside its recorded box both follow from the take recording the real pointer and the timeline recording each target's box.
|
|
57
|
-
|
|
58
|
-
## Audio
|
|
59
|
-
|
|
60
|
-
Fields: web accessibility, and audio post-production. Authorities: the W3C's accessibility guidelines, and the audio engineering society's streaming recommendation.
|
|
61
|
-
|
|
62
|
-
### Music at least 20 dB under the voice
|
|
63
|
-
|
|
64
|
-
WCAG 2.1 [Success Criterion 1.4.7](https://www.w3.org/WAI/WCAG21/Understanding/low-or-no-background-audio.html) is the source, reading "The background sounds are at least 20 decibels lower than the foreground speech content, with the exception of occasional sounds that last for only one or two seconds."
|
|
65
|
-
|
|
66
|
-
HyperFrames' `media-use` sets its narrated bed at a volume of 0.12, about 18 dB under a voice at full scale. The body takes WCAG's 20 dB, since it is the published floor and the bed default sits 2 dB short of it.
|
|
67
|
-
|
|
68
|
-
### Overall loudness is delegated
|
|
69
|
-
|
|
70
|
-
The AES [TD1008](https://aes.org/wp-content/uploads/2024/01/20210924_TD1008_v3.13.pdf) streaming recommendation normalizes speech to -18 LUFS with a true peak no higher than -1 dBTP. `media-use` ships -14 and -16 LUFS targets for social and podcast delivery.
|
|
71
|
-
|
|
72
|
-
The body states no overall target, since the right one depends on where the video is published and `media-use` owns that operation.
|
|
73
|
-
|
|
74
|
-
## Voiceover
|
|
75
|
-
|
|
76
|
-
Field: captioning, for the reading ceiling a voiceover's captions inherit. Authority: the captioning program's presentation rate guidance.
|
|
77
|
-
|
|
78
|
-
### At or under 160 words a minute when captioned
|
|
79
|
-
|
|
80
|
-
The DCMP [Captioning Key: Presentation Rate](https://dcmp.org/learn/601-captioning-key---presentation-rate) caps upper-level captions at 160 words a minute.
|
|
81
|
-
|
|
82
|
-
- `hyperframes-creative`'s narration reference states 2.5 words a second, 150 a minute, under the ceiling, so the two do not conflict
|
|
83
|
-
- An open search of voiceover practitioners put explainers at 140 to 160 words a minute, which agrees
|
|
84
|
-
- Narration has no standards body for pace, and the scoped search found none, so the body sets only the ceiling and points at HyperFrames for pace
|
|
85
|
-
|
|
86
|
-
## Declined
|
|
87
|
-
|
|
88
|
-
Each item below stays out of the body for the reason given.
|
|
89
|
-
|
|
90
|
-
### Restating HyperFrames' motion rules
|
|
91
|
-
|
|
92
|
-
Ease variety, anchoring, click timing, the scale and dwell of a zoom, and title-safe margins are stated in HyperFrames' own skills, which update on their own cadence. A copy here goes stale on theirs.
|
|
93
|
-
|
|
94
|
-
### A loudness target in the body
|
|
95
|
-
|
|
96
|
-
See Audio above.
|
|
97
|
-
|
|
98
|
-
### Pointer smoothing and hiding at rest
|
|
99
|
-
|
|
100
|
-
Screen Studio's [cursor guide](https://screen.studio/guide/cursor) smooths the pointer and hides it when idle, and its [guide to disabling smooth movement](https://screen.studio/guide/disable-smooth-mouse-movement) turns smoothing off for a dropdown menu.
|
|
101
|
-
|
|
102
|
-
Both are recorder settings. A take is composed with its pointer baked into the frames, so a session composing from it cannot change either, and they belong to whatever records the take.
|
|
103
|
-
|
|
104
|
-
### Zoom out before a cut, and a sound effect only on a meaningful click
|
|
105
|
-
|
|
106
|
-
Neither has a source, and no operator read stands behind either, so both stay out until one does.
|
|
107
|
-
|
|
108
|
-
### Vertical 9:16 framing
|
|
109
|
-
|
|
110
|
-
Every video measured when this skill was written was landscape. Add it when a project asks for vertical video, with its safe areas sourced from the platform's own creator documentation.
|