Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions sdk/guides/craft/modes/explain.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,33 @@ everything, just one loop, all the way through.
- **Honest time.** Cut the waits and keep the result at real speed. Never show a speed the product doesn't have.
- **The payoff.** The last scene shows the result of the loop, the thing the viewer now knows how to make.

## The decisions

- **The loop.** Choose the task a newcomer does most often. The easy default is the most impressive feature, but
a viewer can't repeat an impressive feature on day one.
- **The project.** Use a real project with real names: the person's own, if they gave you one. The easy default is
an empty demo workspace, and its blank lists teach nothing.
- **How close the camera sits.** Get close enough that the words that matter can be read at the size the piece
ships. A full-screen recording almost never is that close.
- **Voice or words on screen.** Use a voice for a walkthrough people choose to watch. Burn in captions when it plays
muted in a feed. Many pieces need both.
- **What gets cut.** Cut the waits, the loading and any mistake fixed on camera. Show the result at real speed.

## The rut

Feature lists read aloud. A cursor wandering over a full-size recording. Device mock-ups floating on a gradient.
Narration that describes what the viewer can already see instead of why it matters.

## How it fails

| What you see | Why | What to change |
|---|---|---|
| viewers lose the thread halfway | a scene relies on a step that comes later, or one scene holds two steps | reorder the scenes, or split the scene in two (`recut`) |
| the voice names something nobody can find | the name isn't on screen when it's said, or it's too small to read | zoom to it as it's said, or change the line (`clarify`) |
| it plays like a feature tour | the scenes don't move one project forward | rebuild it around one loop and one project |
| the cursor gets there after the voice | the cues were timed by eye | time the camera and the cursor from the transcript |
| it ends on a logo | the payoff is missing | end on the finished thing the loop made |

## Check

- Pace: hold each step until its result has landed, then move on. A step that depends on a later one confuses
Expand Down
25 changes: 25 additions & 0 deletions sdk/guides/craft/modes/pitch.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,36 @@ A viewer who had no plan to watch stops, believes the brief's `believe:` line, a
the angle isn't specific enough yet.
- **Plan it.** Hook · problem · proof · ask as a storyboard, approved before anything renders.

## The decisions

Each one has a default that comes easily. Question it before you take it.

- **The belief.** Write the `believe:` line the way a viewer would repeat it to a friend. The easy default is a
feature ("it has AI editing"). A belief is what changes for the viewer ("my edit ships the same day").
- **What opens.** The easy default is problem first, then proof. When the proof is striking enough to stop someone
scrolling, open on the proof, and let the problem be the reason it matters.
- **What carries it with the sound off.** Feeds play muted. The picture and the burned-in words make the argument,
and the voice adds to it. A piece that only the voice explains fails the mute test.
- **The length.** Use the delivery's length. Each cutdown is its own edit with its own hook (`motion/delivery`). The
easy default is the long cut stopped early.
- **The ask.** Use the action the brief names: install, try, book. The easy default, "learn more", only makes sense
when the brief has no real action.

## The rut

The template ad: white captions with one yellow word, a zoom on every sentence, a whoosh on every entrance. A big
number with nothing behind it. Glass cards floating over footage.

## How it fails

| What you see | Why | What to change |
|---|---|---|
| people leave in the first seconds | the opening is a logo, a slow push or a setup line | open on the proof or the sharpest line |
| viewers remember the ad but not the product | the proof is generic: stock footage, a mood, a claim with nothing shown | show this product doing its thing, on screen, as the voice says it |
| it reads as a template ad | a zoom on every sentence and a whoosh on every entrance | keep motion and sound for the two or three moments that carry the argument (`quieter`) |
| the ask goes by unread | the end card is up for less than two seconds, or sits under a platform's buttons | hold it long enough to act on, inside the safe zones |
| a claim nobody can stand behind | a number, quote or result that isn't in the brief | remove it, or ask the person for the real one |

## Check

- Mute it: does the picture alone make the argument?
Expand Down
22 changes: 22 additions & 0 deletions sdk/guides/craft/modes/play.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,33 @@ and hear, and when it ends they press to play again.
- **Clear failure, quick restart.** The player sees why they lost and is playing again in a moment.
- **Deterministic.** State lives in `useGameState` with a pure step, so a logged play renders back to the same pixels.

## The decisions

- **The core move and its numbers.** Set the speed, the acceleration, how long a jump hangs and the frame where it
lands. The easy default is whatever the physics gives you. Tune the numbers by hand while you play.
- **What the camera shows.** Show what the player needs to see coming. The easy default is a fixed camera centred
on the player, which hides the danger on a fast run toward the edge of the screen.
- **The first minute.** Let the first obstacle teach the move. The easy default is a line of instructions.
- **The run and the restart.** Decide how long a run lasts and how quickly the player is back in after losing. Both
should be short enough that one more go is easy to say yes to.
- **Sound.** Give every input and every outcome a sound (`games`). Silence after a jump reads as a missed jump.
- **What is random.** Seed it from the game's state, so a logged play renders back the same.

## The rut

A title screen before anything happens. Controls explained in text instead of taught by the first obstacle. A score
that means nothing.

## How it fails

| What you see | Why | What to change |
|---|---|---|
| new players stand still | the goal or the player doesn't stand out | separate them by shape and contrast first, then by colour |
| the controls feel floaty or stiff | the feel numbers were never tuned: slow acceleration, no landing frame | tune them live, one at a time |
| deaths feel unfair | the cause wasn't visible: a hitbox bigger than the sprite, danger off screen | make hitboxes match the drawing, and show danger before it arrives |
| a replay doesn't match the play | some state lives outside `useGameState`: `Math.random()`, the clock, a ref | move it into the step, seeded from state (`harden`) |
| it stutters live | the frame costs too much | reduce the cost (`optimize`). Never swap in a video |

## Check

- Playtest it live, with real input, not from a rendered video.
Expand Down
23 changes: 23 additions & 0 deletions sdk/guides/craft/modes/story.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,34 @@ they want the whole film.
only repeat.
- **One image to remember.** Decide which frame is the poster and build toward it.

## The decisions

- **The feeling.** Name it in a word or two before you plan a single shot: homesick, giddy, dread. "Epic" and
"beautiful" describe a look, not a feeling, and they lead to shots with no subject.
- **The world's rules.** Decide what the colours mean, where the light comes from, which lens, and how the camera
moves. The easy default is choosing a look shot by shot from references, and that ends up as several films.
- **Each shot's subject.** Choose the person, object or action each shot is about. The easy default is a wide
establishing shot, so question every one.
- **What the music does.** It either leads, and you cut to its map, or it sits under the picture as a score. The easy
default is a cut on every bar.
- **The poster frame.** Choose it before anything renders, and build the edit toward it.

## The rut

A montage of pretty shots with no subject. Slow pushes on empty rooms. Every cut on the bar line. Grain, bloom and
lens flare doing the work the idea should do.

## How it fails

| What you see | Why | What to change |
|---|---|---|
| a montage nobody remembers | the shots have no subject | put a person, an object or an action in every shot |
| it plays like a slideshow | each camera eases to a stop before the cut | start and end each shot while the camera is still moving (`recut`) |
| the cutting feels mechanical | every cut lands on the bar line | cut on the song's events: downbeats, builds, stops, the drop |
| shots look like they come from different films | the light, colour or lens drifts from the world | re-light or regrade to the world's rules (`regrade`) |
| the narration explains the picture | a line repeats what is already on screen | cut the line, or give it what the picture can't show |
| the ending fizzles | nothing was built toward | end on the poster frame or the line the piece was made for |

## Check

- The arc: does the energy build, breathe and land, or stay at one level?
Expand Down
26 changes: 26 additions & 0 deletions sdk/guides/craft/modes/tool.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,37 @@ The person finishes what they came to do, knows what happened, and never wondere
- **Real content.** Lay it out with real names, real lengths and real numbers, never placeholder text.
- **Built for real.** A screen for a raea app is built in the app itself, never mocked up as a picture.

## The decisions

- **The task.** Decide what the person came to do, and the two or three steps that do it. The first screen opens on
that task. The easy default is an overview dashboard, which makes everyone hunt for the task.
- **Density.** Design for the person who uses it most. Someone who uses it all day wants more on screen and keyboard
shortcuts. Someone who opens it once a month wants less, with labels.
- **Where things live.** Follow the platform's conventions for menus, settings, shortcuts and Undo. The easy default
is a custom layout, and it costs every user a moment of looking.
- **What's in view and what's a click away.** Keep the task's next step in view. Put settings and rarely used
actions behind a click.
- **How an action answers.** Every action shows that it happened, at the place where it happened. A toast in a far
corner is easy to miss.
- **The target.** Choose web or native for the app (`motion/interface`).

## The rut

Cards in cards. A dashboard of numbers nobody asked for. Icons with no labels. Every element given the same weight.

## How it fails

| What you see | Why | What to change |
|---|---|---|
| people ask "where is…" | the action is buried in a menu, shown only as an icon, or out of view | put the task's next step in view, with words |
| people don't know whether it worked | the action gives no answer where it happened | show the change in place |
| an error leaves them stuck | it says what happened, but not what to do next | say what to do, and clear the error once they act |
| it breaks with real data | a long name overflows, an empty list is blank, 500 rows are slow | design every state with real content (`harden`) |
| it looks busy | everything has the same weight, with cards inside cards | one accent, one level of container, and the rest quieter (`quieter`, `layout`) |
| keyboard or screen reader can't use it | controls have no role or label in tree.json | real buttons with words in them, and `role` and `aria-label` where there's no button |

## Check

- Do the task yourself, start to finish, at the size it ships.
- Find the state nobody designed.
- `raea app check APP --png out/` with steps that walk every state, read PNG by PNG (`motion/interface`).
13 changes: 13 additions & 0 deletions sdk/guides/craft/verbs/adapt.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,13 @@ YouTube". The same piece made right for another size, length or platform; never
- For each size, find what no longer fits: type that wraps, a face cut off, a part in a platform's button zone, a
hold that's too long for a shorter cut.

## Decide
- Which size leads. Lay out the size the brief favours first, and make the others from it. The easy default is
designing at 16:9 and adapting down. A vertical made that way is a crop, however it was built.
- What each size drops. A smaller or shorter version loses a whole element, such as a secondary line or a shot.
Shrinking everything is not the answer.
- Whether a cut needs its own hook. A 6 s cut is a different edit from a 30 s one, not the first 6 seconds of it.

## Change
- Register one `<Composition>` per size in the same root, sharing the parts; each lays out for its own frame
(`raea guide motion/compositions`). Never scale or crop one size into another.
Expand All @@ -19,3 +26,9 @@ YouTube". The same piece made right for another size, length or platform; never
## Verify
- `raea render --composition ID --at 0,45,89` stills for every size; `raea check` on each export.
- Every size says the same thing; nothing is cut off or crowded in any of them.

## When it goes wrong
- Type that's tiny in 9:16 was scaled from 16:9. Lay out each frame for its own shape.
- A face sits behind a platform's buttons: place it from the safe zones, not by eye.
- The short cut ends mid-sentence. Cut on words, and keep the ending.
- The sizes drift apart after a later note. Change the shared part, not one composition.
14 changes: 14 additions & 0 deletions sdk/guides/craft/verbs/animate.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,13 @@ something that holds still, so each move says something.
with nothing to say stays still.
- Find the beats it lands on: the voice's words, the music's hits (`raea song FILE --plot`), the cuts.

## Decide
- What moves first in each beat, and what stays still. The easy default, everything entering at once, means
nothing leads.
- One easing and one speed for the piece: snappy for a pitch, slower and heavier for a story.
- Whether motion is the answer. A frame that feels static may need a cut (`recut`) or a shorter hold (`retime`), not
movement.

## Change
- Animate entrances, the one emphasis per beat and exits; leave everything else still.
- One easing family for the whole piece; springs for things with weight, short eases for type (`raea guide
Expand All @@ -19,3 +26,10 @@ something that holds still, so each move says something.
- Play it at full speed, then step the frames around each beat: each move starts on its cue and settles before
the next.
- Nothing moves without a reason you could say in a few words.

## When it goes wrong
- Everything bobs or drifts all the time. Idle motion with nothing to say pulls the eye from what does. Hold it
still.
- Moves land between beats because they were timed by eye. Take the cues from the transcript and the song's map.
- Type overshoots and wobbles: a spring on text. Use a short ease.
- A part pops or jitters on one frame, from an unclamped `interpolate` or state kept outside the frame.
10 changes: 10 additions & 0 deletions sdk/guides/craft/verbs/bolder.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,11 @@ exists. Almost always one beat, not the whole piece.
- Is it weak because of what's on screen, or because of what's around it? A beat often feels flat because the moment
before it is just as loud.

## Decide
- Which beat. When the note doesn't say, pick the hook and tell the person which one you took.
- Which lever: quiet before it, a closer frame, a harder cut, or one sound. Pick one, and the next only if one
isn't enough.

## Change
- Contrast first: make the moment before quieter or stiller, so the beat lands by difference.
- Then the beat itself: a closer frame, a harder cut on the downbeat, a larger scale change, one strong sound under it.
Expand All @@ -16,3 +21,8 @@ exists. Almost always one beat, not the whole piece.

## Verify
- Watch the beat with the two seconds before it. It hits now, and nothing else got louder to compete.

## When it goes wrong
- Everything got louder and the beat still doesn't stand out. Pull back what's around it.
- Effects pile up: a shake, a flash and a zoom at once. Keep one.
- The bold moment outshouts the message: the product or the ask is now the second-loudest thing on screen.
11 changes: 11 additions & 0 deletions sdk/guides/craft/verbs/clarify.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,11 @@ The words: narration, captions, titles and labels.
hearing, and each name the voice says that isn't on screen when it's said.
- Find jargon, abstractions and lines that describe what the picture already shows.

## Decide
- Whose words: the vocabulary of the audience in the brief, not the team's or the product's.
- What the picture carries and what the words carry. A line that repeats the picture goes.
- Cut or rewrite. Try cutting the line first. Rewrite it only if the piece needs what it says.

## Change
- Plain, specific words in the person's own vocabulary. One idea a line.
- Narration says why it matters; the picture shows what it is.
Expand All @@ -16,3 +21,9 @@ The words: narration, captions, titles and labels.

## Verify
- Play it with sound only, then with picture only. Both make sense; together they don't repeat each other.

## When it goes wrong
- The lines got longer while getting "clearer", and a scene now runs over its words. Split the scene or cut a line.
- Plain turned vague: "it's easy", "everything you need". Use specific nouns and verbs.
- Captions no longer match the voice. Remake them from the new transcript.
- Cues drift after a rewrite. Re-time them from the transcript.
11 changes: 11 additions & 0 deletions sdk/guides/craft/verbs/critique.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,11 @@ Judge the piece as it rendered, not as you meant it, before you call it done or
- Judge it against the brief (`believe:`, `audience:`), the person's taste, the mode's guide and the floor.
- Run `raea check` for what can be measured, and judge the rest by the rubric (`raea guide rubric`).

## Decide
- Judge against the brief and the mode first, and the person's taste second. Your own taste is the easy default.
- Judge severity: would the audience notice this? If not, it is P2 or below, however much it bothers you.
- Rank the few that matter most. Thirty equal notes give the next pass nothing to act on.

## Write it down
- Each issue: where (the part or the moment), what's wrong, and why it matters to the audience.
- Rank each one: P0 breaks the piece (a floor defect, a wrong fact), P1 the audience would notice, P2 makes it better,
Expand All @@ -17,3 +22,9 @@ Judge the piece as it rendered, not as you meant it, before you call it done or

## Then
- Fix P0 and P1 before showing anyone. `polish` works through the rest.

## When it goes wrong
- The critique was written from the code or the plan, not from the render.
- Every issue is P2, so nothing is fixed first.
- A fix sanded off the strongest moment, because nobody named it.
- A clean `raea check` was read as the piece being good. The check finds defects; it doesn't judge the work.
10 changes: 10 additions & 0 deletions sdk/guides/craft/verbs/delight.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,11 @@ detail that rewards attention, in the piece's own voice.
- Is the piece right first? Delight on a piece that doesn't land is noise: fix the note's real problem before this.
- Find a moment with room: a hold, a transition, the end card, a game's idle or its win.

## Decide
- Where it goes: a moment that has room. The opening is the easy default, and it's where the piece most needs to
be about its point.
- Whose voice it's in: the brand's, or the subject's. Never a generic flourish.

## Change
- One detail, maybe two: a character's blink, a sound on a hit, the logo doing one thing it only does here, a line
of copy that's a little warmer than it has to be.
Expand All @@ -16,3 +21,8 @@ detail that rewards attention, in the piece's own voice.
## Verify
- Watch it as someone seeing it for the first time: the detail is noticed second, not first.
- Take it out and watch again: if nothing is lost, it wasn't worth keeping.

## When it goes wrong
- It upstages the message: people remember the joke and not the product.
- It's generic: confetti, sparkles, a bounce any piece could have.
- It repeats. A touch used in every scene stops being a surprise by the second time.
Loading
Loading