as the first child of an SVG gives it a name a screen reader can read aloud. Pair it with role="img"; decorative SVGs get aria-hidden="true" instead) as its first child. If it is decoration, hide it with `aria-hidden="true"`. Never meaning with no name; never a name on decoration. **Step: Sensible numbers.** Whole numbers on a sensible grid (24 for icons, 100 or 1000 for illustrations), one or two decimals at most. `12.000000` is six characters saying nothing. **Step: Groups that mean something.** `<g id="arm-left">` can be animated by anyone. A hundred unnamed `<g>`s cannot, including by you next week. Order groups back to front, like layers in a design tool. ## Shapes, paths and repeats Simple static shapes can stay as `<rect>` and `<circle>`: they are small and easy to read. Anything that will animate or change shape should be a path (The SVG element that draws any shape from a list of commands in its d attribute: M moves the pen, L draws a line, C draws a curve, Z closes the shape), a list of drawing commands, because a morph needs matching command lists (lesson three). Repeats belong in one place. Gradients, masks and filters go in `<defs>`; a shape used five times goes in a `<symbol>` and is placed with `<use>`. One edit then changes every copy. And never paste a photo inside an SVG. A base64 PNG wrapped in SVG is a PNG with worse compression. ## Shrink it, carefully SVGO (A free tool that shrinks SVG files by removing editor junk and rounding numbers. It needs a few settings turned off so it keeps the viewBox, titles and the ids you animate) strips editor junk and rounds numbers. Run it with `--multipass`, but switch off the parts that break things: keep the viewBox, keep `<title>` and `<desc>`, keep the ids and `data-*` attributes you animate against. When several SVGs sit inline on one page, prefix their ids so two gradients called `g1` don't collide. ```bash npx svgo icon.svg --multipass ``` Then look at it. A shrunken file that renders differently is not smaller, it is broken. *(Inline `<style>` inside an SVG becomes global CSS the moment you paste the SVG into a page. Scope it under the SVG's id, or move it out.)* ## The tells of a generated SVG Once you know them, you can spot them in the source in seconds: **Generated (avoid):** - `width` and `height` on the root, no viewBox - every color a hard-coded hex - nests of empty, unnamed `<g>` - circles converted to 8-decimal paths - the same gradient defined four times - an embedded PNG **Clean (do this):** - viewBox only, size from CSS - `currentColor` or CSS variables - a few groups, each named - primitives where static, paths where they move - one gradient in `<defs>` - no rasters Each of these is cheap to fix and **expensive to leave in**, because every later step (theming, animating, shipping) pays for it again. ## Get your agent to do it You don't have to fix these by hand. Hand the file to your agent with the rules spelled out. **Clean an SVG (paste into your agent):** ```text Clean up this SVG for production: - keep viewBox, remove width/height on the root - monochrome: fill="currentColor"; multi-color: CSS variables with fallbacks - if it carries meaning: role="img" + <title> first, aria-labelledby; if decorative: aria-hidden="true" focusable="false" - round coordinates to 1 decimal, remove empty groups and editor metadata - name the groups by what they are (arm-left, eyes) - no embedded rasters, gradients only in <defs> Return the file and a short table of what changed and why. ``` **Check yourself:** An icon stays 24px no matter what width CSS gives it, and stays gray in dark mode. What is the likely fix? - [ ] Redraw it at 48px and export again - [x] Add a viewBox, remove the fixed width and height, and fill it with currentColor - [ ] Wrap it in a div with overflow: hidden - [ ] Convert it to a PNG with a transparent background *Why:* Fixed width/height without a viewBox stops scaling, and a hard-coded hex ignores the theme. viewBox plus currentColor fixes both without redrawing anything. ## In the skill - https://school.agents.org.in/skill/svg/MOC-svg.md - https://school.agents.org.in/skill/svg/svg-creation.md --- # Making SVG move > Choose the right animation engine for where an SVG lives, draw a line on with two CSS properties, and stop rotations from orbiting the corner. Module: SVG and icons · Level: intermediate · 8 min · https://school.agents.org.in/visual/svg/animating-svg Press replay. Then grab the slider and drag it yourself. *[Interactive demo: The drawing animation is one property moving from 1 to 0. The slider moves the same property by hand.]* That line is not being drawn. It is already all there. It is hidden behind one very long dash, and the dash is sliding out of the way. That trick, and a handful like it, covers most of the SVG animation you will ever need. ## First question: where does the file live? Before easing, before duration, ask where the SVG renders. That decides which tools can even reach it. | Where it renders | What can animate it | |---|---| | Inline in the page (React, HTML), reacting to clicks and state | CSS transitions or the Web Animations API | | Inline, but driven by a drag, a spring or a long timeline | Motion or GSAP, whichever the project already uses | | Loaded as `<img>`, a background image, in an email, on social, in Figma | Only what is *inside the file*: CSS `@keyframes` in its own `<style>`, or SMIL (Animation written as tags inside the SVG file itself (<animate>, <animateMotion>). It keeps playing even when the SVG is loaded as a plain image, where page CSS and JavaScript cannot reach) tags | | A rich After Effects export that already needs a player | Lottie (A format that plays After Effects animations in apps and on the web through a JavaScript player. Handy for rich exports, but usually several times larger than the same motion as plain SVG) or Rive, and only then | The third row catches people out. An SVG loaded as an image is sealed: your page's CSS and JavaScript can't touch it. Animation has to travel inside the file. CSS keyframes are the most portable choice; SMIL still wins for moving something along a path with `<animateMotion>`. > **Usually smaller than the Lottie.** Native SVG with CSS or SMIL is often five to ten times smaller than the Lottie export of the same motion, and it keeps the `<title>` a screen reader needs. Lottie earns its place when the animation is genuinely rich. ## Drawing a line on The trick in the demo uses stroke-dasharray (The SVG setting that turns a line into dashes. Make one dash as long as the whole line, slide it with stroke-dashoffset, and the line looks like it is being drawn), which turns a stroke into dashes, and `stroke-dashoffset`, which slides them along. Measuring a path's length is fiddly, so skip it. Set `pathLength="1"` on the path and the browser treats the whole line as one unit long, whatever its real size. ```css path { stroke-dasharray: 1; /* one dash, as long as the whole path */ stroke-dashoffset: 1; /* pushed fully out of view */ stroke-linecap: round; /* soft ends while it draws */ animation: draw 1600ms cubic-bezier(0.65, 0, 0.35, 1) forwards; } @keyframes draw { to { stroke-dashoffset: 0; } } ``` Drawing is one of the few places an ease-in-out curve is right: the line is moving across the screen on its own, not answering a click. ## The corner problem Now press rotate, a few times. *[Interactive demo: Same rotate, same gear. On the left it swings around the top-left corner of the drawing (the red dot). On the right it turns in place.]* In HTML, a rotation turns around the element's center. In SVG, it turns around **(0, 0)**, the top-left corner of the whole drawing. So every rotation and scale you copy from HTML orbits the corner. The fix is two lines. transform-box (A CSS setting that decides what a transform measures from. In SVG the default is the corner of the whole drawing, so set transform-box: fill-box to rotate or scale a part around its own center) tells the browser to measure from the shape's own box, and then `transform-origin` means what you expect. ```css .gear { transform-box: fill-box; transform-origin: center; } .arm { transform-box: fill-box; transform-origin: 10% 20%; } /* the shoulder */ ``` For a mascot, put the origin where the part would hinge in life: a shoulder, a wrist, a lid. *(Most "my SVG animation goes haywire" bugs are this one.)* ## Keep it cheap The rules from motion apply unchanged. `transform` and `opacity` are cheap: the browser moves a finished picture. Animating `d`, `points`, `r`, `stroke-width` or a filter makes it repaint every frame. Fine for one small icon; **ruinous for a whole scene**. - **Move groups, not paths.** Animate `<g id="arm">`, `<g id="eyes">`, not three hundred separate paths. - **Stagger by 30 to 80ms.** Paired parts (two eyes, two arms) share duration and easing. - **Budget the file.** About 2 KB for an animated icon, 10 to 30 KB for a hero mascot. Reuse shapes with `<use>`, move them with transforms instead of redrawing. ## Reduced motion travels with the file Some people turn on "reduce motion" in their system settings because movement makes them unwell. Inline SVG respects it only if you wrote the media query. A self-contained file can carry its own: ```css @media (prefers-reduced-motion: reduce) { .gear, path { animation: none; } } ``` That query works even inside a file loaded as `<img>`. SMIL can't read it, so a SMIL-only file needs a still fallback image. A copied animated icon with its own keyframes and no reduced-motion query is the most common miss in generated UI. Check every one. ## Ask for it precisely **Animate an SVG (paste into your agent):** ```text Animate this SVG. It is used as <img> in our marketing page, so the animation must live inside the file. - CSS @keyframes in the file's own <style>, selectors scoped under the root id - draw the outline on with pathLength="1", stroke-dasharray: 1, stroke-dashoffset 1 → 0, round linecaps - the lid rotates around its hinge: transform-box: fill-box with transform-origin at the hinge - only transform, opacity and stroke-dashoffset animate - @media (prefers-reduced-motion: reduce) shows the finished drawing - keep it under 10 KB; report the final size ``` **Check yourself:** A logo SVG ships as an <img> tag on your landing page. Your agent added the animation to the page's global CSS file. What happens? - [ ] It works, but only in Chrome - [x] Nothing animates: page CSS can't reach inside an SVG loaded as an image - [ ] It animates, but ignores reduced motion - [ ] It animates twice as fast *Why:* An SVG in an <img> is sealed off from the page. The animation has to live inside the file, as CSS keyframes in its own <style> or as SMIL. ## In the skill - https://school.agents.org.in/skill/svg/svg-animation.md --- # Morphing shapes, and when not to > Author two paths that really morph into each other, recognise the ones that never will, and know when a simple icon swap is the better answer. Module: SVG and icons · Level: intermediate · 7 min · https://school.agents.org.in/visual/svg/path-morphing Morph the circle into a square. Then switch to "Mismatched" and try again. *[Interactive demo: Matched: the square is written with the circle's own command list, so it glides. Mismatched: a plain square, so the browser can only flip halfway.]* Both squares look identical when they sit still. Only one can be reached from the circle. The difference is not the shape. It is how the shape is written down. ## The one rule A path morph (One SVG shape smoothly turning into another by sliding every number in its path to a new value. It only works when both paths have the same commands in the same order) is the browser sliding each number in one path to the matching number in the other. So it needs every number to have a partner: **both paths need the same commands, in the same order, of the same type.** Four curves can become four curves. Four straight lines can't become four arcs, because there is nothing to pair up. When the lists don't match, the browser gives up and swaps one shape for the other. > **In plain words.** A path is a recipe: "move to here (M), curve to there (C), close up (Z)". A morph walks two recipes side by side, step by step. If one recipe has a step the other doesn't, the walk can't happen. ## Writing two shapes that match Decide the command list first, then place the points for each shape. ```css .shape { d: path("M4 12 C4 7.6 7.6 4 12 4 C16.4 4 20 7.6 20 12 C20 16.4 16.4 20 12 20 C7.6 20 4 16.4 4 12 Z"); transition: d 240ms cubic-bezier(0.25, 1, 0.5, 1); } .shape[data-state="square"] { d: path("M4 12 C4 4 4 4 12 4 C20 4 20 4 20 12 C20 20 20 20 12 20 C4 20 4 20 4 12 Z"); } ``` Both are `M`, four `C`, `Z`. The square cheats: each "curve" has its control points pulled into the corner, so it looks straight. **Step: Pick one point budget.** Say `M` plus eight `C` plus `Z`. Both shapes use exactly that. If one shape needs less detail, add points that sit on top of each other; never delete commands. **Step: Same start, same direction.** Start both at the same spot and draw both clockwise (or both counter-clockwise). Otherwise the morph twists through itself. **Step: Match the holes.** A shape with two holes needs two holes in the other state. Shrink an unused hole to nothing instead of removing it. **Step: Normalise before shipping.** Convert both to absolute cubic curves (`C`, not `c` or `S`). A morph that works in Chrome and jumps in Safari almost always mixes `S` and `C`, or `l` and `L`: one browser quietly converts them, the other doesn't. ## When the shapes just don't match For two unrelated shapes (a logo becoming a word, a blob becoming a star), a library can resample both to the same number of points. flubber (A small JavaScript library that resamples two unrelated shapes so they can morph into each other. Worth it when the morph is the product, not for an icon toggle) does this with one function, `interpolate(pathA, pathB)`, and GSAP's MorphSVG does the same inside GSAP. The cost is a dependency and a JavaScript loop. Pay it when the morph *is* the product: a logo transformation, a shape-shifting hero. Not for a button. *(Animating `d` repaints every frame. One hero shape is fine. Twenty morphing at once is not.)* ## Most of the time, swap instead Play to pause. Copy to check. Menu to close. These feel like morphs, but the honest version is an icon swap (Changing one icon for another (copy to check, play to pause) by fading, scaling and blurring the old one out while the new one comes in, instead of morphing between them). Press each button a few times, quickly. *[Interactive demo: Left: the icon just changes. Right: the old one scales to 0.3, fades and blurs as the new one arrives. Press it twice fast and it reverses smoothly.]* Both icons are rendered at once, stacked. The outgoing one goes to `scale(0.3)`, `opacity: 0` and `blur(3px)`; the incoming one comes back from there. Because both are always on the page, pressing again mid-change just reverses the transition. A swap reads as a real change of meaning. A timid morph between unrelated shapes, a copy icon stretching into a tick, reads as a glitch. | Situation | Use | |---|---| | Two states of the same shape (chevron up and down) | Rotate it | | Icons designed together on one line budget | A morph | | Two different icons (copy and check, play and pause) | A swap | | A logo or hero that shape-shifts | A morph, with flubber if the paths don't match | ## Ask for the right one **Morph or swap (paste into your agent):** ```text Our copy button should turn into a check when pressed. Don't morph the paths. Render both icons stacked; outgoing goes to scale(0.3), opacity 0, blur(3px), incoming reverses that, 200-260ms with cubic-bezier(0.23, 1, 0.32, 1), interruptible. Separately, the hero blob morphs between three shapes: author all three as M + 8 absolute C + Z, same start point, clockwise, and transition the d property. Tell me if any shape can't fit the budget. ``` **Check yourself:** Your agent morphs a hamburger icon (three M/L lines) into an X drawn as two M/L lines. It jumps instead of animating. Why? - [ ] The duration is too short - [x] The paths have different numbers of commands, so nothing pairs up - [ ] transform-box is missing - [ ] Morphs only work with circles *Why:* Three lines have more commands than two. A native morph needs the same commands in the same order; keep three lines in both states (collapse one) or rotate the lines instead. ## In the skill - https://school.agents.org.in/skill/svg/svg-path-morphing.md --- # Stickers and mascots > Build an isometric sticker that reads as a made object, and turn a flat animated clip into one editable, recolorable SVG. Module: SVG and icons · Level: intermediate · 9 min · https://school.agents.org.in/visual/svg/stickers-and-flipbooks Play the clasp. Then switch to "Flat clip-art" and play it again. *[Interactive demo: The same lock. The sticker has thickness, parts and a still hold after the action. The clip-art is one shape with the detail painted on.]* The flat one is not wrong, exactly. It just looks like it was generated. The sticker looks like someone made it. That difference comes from a short list of rules, most of them from Kelvin Adithya's fun-isometric, a skill that draws and animates exactly this kind of sticker. ## Where stickers belong Empty states, onboarding, feature cards: the rare, friendly screens. Not inside buttons, not in a list of fifty rows. A sticker is illustration, so it gets illustration time (a second of action, then rest), never the 200ms of a control's feedback. ## Drawing one **Step: One square, one outline.** A 500-unit canvas, the subject filling about half of it with room to swing. One ink outline, about 5 units, on every part, with sharp corners. No gradients, no drop shadows, no glow. **Step: Faces lean.** An isometric (A way of drawing 3D objects without perspective: faces lean at fixed angles, so a box shows its top and two sides and parallel lines stay parallel) face is tilted back, so rectangles become slanted parallelograms and circles become ellipses. It is not just rotated. The side falls the same way (down and left) on every part. **Step: Every part is a slab.** Each part is a slab (A flat shape given thickness, like a cookie cut from dough. Isometric stickers build every part as a slab so it reads as a made object, not a flat drawing): a flat shape with its own thickness. The lock is a body slab, a shackle slab and a raised keyhole plate. Three to six parts for one object. **Step: Sparse ink detail.** One keyhole. Two pupils. A few lines. Sparkles are small white stars with the same outline. **Painting the detail flat onto one shape** is the tell of a generated sticker. Build it from parts. ## Colors as jobs, not hex codes The sticker's fills are named by palette role (A named job for a color (main, deep, tint, gold, ink) instead of a fixed hex value, so a whole illustration can be recolored to a new brand without losing what each part means): `main` for bodies, `deep` for the dark side, `tint` for pale fills, `gold` for coins and stars, plus `ink` and `white`. Two accents and white per icon. Roles are what let a sticker move to a new brand. Map `main` and `deep` to your design tokens and every part keeps its meaning. Leave a sticker on its default six-color palette in a two-color product and everyone can tell nobody mapped it. ## Moving one - **Pick the motion by the verb.** A lock *clasps*, a coin *bounces*, a bell *wiggles*, a plane *drifts*. The verb decides the movement, not the noun. - **Use tuned keyframes, not a sine wave.** The presets come from After Effects keys an animator already tuned. Change the amplitude or start; never stretch them. - **Pivot where it would hinge.** Children follow 4 to 6 frames late, so nothing moves in lockstep. - **Sparkle on the beat.** The glint starts on the slam, the landing, the reveal. - **Then hold still.** Loops run two to three seconds with the action in the first half. Filling the hold with idle wobble is the quickest way to cheapen it. - **Pop with scale, never fade.** A slab is drawn as a stack of copies, so fading it shows the stack. > **Where its rules meet the rest of the course.** Its entrance pops from a small scale on a bounce. Menus and modals still enter from 0.95, never from nearly zero; a sticker's pop is a character moment, so it keeps its own. Idle loops are for one hero sticker on a rare screen; in a list, play once and rest. And your brand's palette always wins over its default inks. If fun-isometric is installed, let it draw, check and export the sticker (live on a canvas or as looping video with a still poster). If not, build to these rules as an animated SVG. Either way, check it at 160px beside your other stickers: same line weight, faces leaning, every part with thickness. ## From a video clip to a vector mascot Sometimes the source isn't drawn by hand at all. It is a short, flat animated clip, perhaps made by a video model: a rooster typing, a blob waving. That can become one SVG that is tiny, sharp at any size and recolorable. *[Interactive demo: A vector flipbook: six traced frames, each its own group, shown one at a time at 12 frames a second. Try the jitter and the recolor.]* It only works for **simple, flat art**: solid fills, two to eight colors, clean outlines, no gradients or texture. Ask for that when you generate the clip ("flat vector style, solid colors, no gradients, plain background"). **Step: Extract frames.** `ffmpeg -i clip.mp4 -vf "fps=12,scale=512:-1" frames/f_%03d.png`. Twelve frames a second reads as animation; 24 doubles the file for little gain. **Step: Reduce the colors, then trace.** Quantize each frame to its handful of colors first, then vectorize (Trace a pixel image into vector shapes. Tools like vtracer turn each flat color region of a frame into a path) with vtracer (Potrace for pure black and white). **Step: Clean and name.** Remove specks, merge near-identical colors, delete the background, run SVGO. Name each color region the same in every frame (`body`, `beak`, `eye-l`), matched by position and color. Named layers are what make it editable. **Step: Assemble and budget.** One SVG, one group per frame, a stepped animation: a vector flipbook (One SVG file holding every frame of an animation as its own group, shown one at a time by a stepped animation, like flipping the pages of a sketchbook). Colors become CSS variables. Merge identical frames into longer holds. A simple 24-frame loop lands around 20 to 60 KB; bigger means slivers survived step three. *(Traced frames wobble by a pixel because each was traced alone. Trace at one resolution, and reuse the last frame's paths for a hold.)* The SVG stays the editable source. Export onward to Lottie, Rive or MP4 only when a platform needs it. **Brief a sticker (paste into your agent):** ```text Make an animated isometric sticker of a padlock for our empty "No saved passwords" state. - 500-unit canvas, one 5-unit ink outline, faces leaning, side falling down-left - three parts, each its own slab: body, shackle, keyhole plate - fills by role (main, deep, tint, ink, white), mapped to our tokens --accent and --accent-deep - verb "clasp": shackle drops, two small bounces, sparkle on the slam, then a still hold; play once, no idle loop - reduced motion shows the closed lock Check it at 160px next to our existing stickers. ``` **Check yourself:** You turn a mascot clip into a vector flipbook and the file is 900 KB. What most likely went wrong? - [ ] The clip was 12 frames a second - [x] The vectorizer left thousands of slivers: the art wasn't flat enough, or colors weren't reduced before tracing - [ ] The colors are CSS variables - [ ] Each frame is its own group *Why:* A simple loop should land around 20 to 60 KB. Gradients, texture or skipping the color-reduction step turn each frame into slivers; go back, quantize, clean and dedupe. ## In the skill - https://school.agents.org.in/skill/svg/isometric-stickers.md - https://school.agents.org.in/skill/svg/fun-isometric-reconciliation.md - https://school.agents.org.in/skill/svg/video-to-vector-pipeline.md --- # Silence is the default > Decide whether a moment in your interface should make a sound at all, using how often it happens, what it is for and the 100th-use test. Module: Sound · Level: beginner · 6 min · https://school.agents.org.in/media/sound/silence-is-the-default Press the button below. With sound off, nothing happens to your ears, and the button still feels fine. Now turn sound on and press it again. *[Interactive demo: A 50 ms tick, made in code. Sound starts off, and the switch is right there.]* That tiny tick is pleasant once. Imagine it on every button in an app you use all day. By lunch you would be hunting for the mute switch, and you would remember the product as the noisy one. That is the whole problem with interface sound. **A bad sound is worse than no sound, and people remember it.** So this module starts with the question most teams skip: should this make a sound at all? ## Why sound has to work harder than motion You can look away from an animation. You cannot un-hear a chime. And while operating systems have a setting that turns motion down (the reduced-motion preference), there is no setting that turns *your* sounds off. Your product has to do that job itself. So the default is silence. A sound has to earn its place, and the bar is higher than it is for animation. > **In plain words.** A **UI sound** is any noise an interface makes when you do something: a click, a whoosh, a chime. This module is about deciding which moments deserve one, designing a small set that belong together, and playing them at the exact right moment. ## Question one: how often? Frequency decides most cases before anything else. The more often a person hears a sound, the faster it goes from charming to grating. | How often | Example | Sound? | |---|---|---| | Constantly | Typing, scrolling, hovering | Never | | Many times an hour | Pressing a button, picking an option | No, unless the product is built to feel physical | | A few times a day | Message sent, file saved | Maybe: one short sound, and only if the person opts in | | Rarely | First payment, setup finished | Yes. This is where the sound budget goes | The keyboard never gets sound. Hover never gets sound. A plain button press already has motion and, on phones, a buzz; adding a click there makes the product feel like a toy. ## Question two: what is it for? Apple's sound designers put it as one word: utility. A sound is worth adding only when it tells you something your eyes might miss. Four reasons pass: - **Your attention is elsewhere.** You hit send and are already typing the next message. A soft tone confirms it went. - **Something changed with nothing to see.** A timer ended in a tab you are not looking at. An upload finished in the background. - **The product is physical by design.** A wallet card snapping into place, a game piece landing. - **It is a brand moment.** A launch film or an onboarding hero, where sound is part of the medium. The last lesson covers that. Four reasons fail: decoration, "the animation felt quiet", filling the wait during a slow request, and copying a competitor's ping. *[Interactive demo: Pick a moment. Most of them stay silent; the ones that pass let you hear their sound.]* ## Question three: does it survive the 100th time? This is the test Apple's team uses. Picture the sound the first time you hear it. Now picture the hundredth time. If the hundredth makes you reach for mute, cut the sound or make it smaller. The 100th-use test (Imagine a sound the first time you hear it, then the hundredth. If the hundredth makes you want to mute it, cut the sound or make it smaller) is lopsided in a useful way. A sound that is a little too loud or a little too long is annoying by the tenth time. A sound that is a little too quiet or too short is never noticed as a flaw. So when you are unsure: halve the length and turn it down a notch. *(Halve it, then drop it 3 dB. You will almost never regret it.)* ## Question four: is there a visual twin? A sound may back something up. It must never be the only signal. Most people use their devices muted, in an office, on a train, or with a screen reader that is already talking. If the sound carries information nothing else shows, the design is broken for all of them. Every sound in this module has a visual twin: the toast, the checkmark, the shake. ## Question five: can people turn it off? Product sound ships **off**, with a switch people can find and reach by keyboard, and the choice is remembered. People who turn sound on often love it. People who cannot turn it off uninstall. **Before (avoid):** A soft click on every button, a whoosh on every page change, a chime on load. No setting to turn it off. **After (do this):** Silent by default. One short tone when a message sends, for people who turn sound on in settings. A three-note figure the day the first payment lands. ## Two surfaces, opposite defaults Everything above is about the **product**: the app people use every day. There, sound is opt-in, rare and tiny. A **launch film** flips it. In a short video that introduces the product, sound is the emotional layer and silence is something you place on purpose. Same skill, opposite default, so keep them apart in your head. The film side gets its own lesson at the end of this module. ## Getting your agent to ask the question Agents love adding sound once you mention it. Give them the decision first, and let them say no. **Decide before adding any sound (paste into your agent):** ```text Before adding any sound to this UI, go through every moment that might get one and make a table: moment, how often a person hears it, what it is for, does it survive the 100th use, and its visual twin. Default to silence. Typing, scrolling, hover and ordinary button presses get no sound. Only moments that confirm something while attention is elsewhere, signal a change with nothing to see, or mark a rare milestone may pass. Sound ships off by default behind a visible, keyboard-reachable setting that persists. Show me the table and wait before generating or wiring any audio. ``` **Check yourself:** A team wants a soft click on every button press in their project-management app. What is the best answer? - [ ] Yes, a click makes it feel responsive - [ ] Yes, but make it quieter - [x] No: presses are frequent, already have visual feedback, and the click would fail the 100th-use test - [ ] Yes, as long as it is under 300 ms *Why:* Frequency comes first. A press happens many times an hour and already answers with motion, so sound there reads as a toy and gets muted. Save the sound budget for rare or attention-elsewhere moments. ## In the skill - https://school.agents.org.in/skill/sound/sound-decision-framework.md - https://school.agents.org.in/skill/sound/MOC-sound.md --- # One family of sounds > Design four to six sounds that share one material, and give each one the right pitch, length, loudness and file format. Module: Sound · Level: intermediate · 7 min · https://school.agents.org.in/media/sound/one-family-of-sounds Tap each card below with sound on. Five different jobs, and yet they clearly come from the same product. That is not luck. They are all the same small struck bar, played higher, lower, shorter or longer. *[Interactive demo: One material, five sounds. Higher dot, higher pitch. Longer bar, longer sound.]* A product's sounds work like a typeface. One family, several weights. **Five sounds from one material feel like a product; five sounds from five packs feel like clip art.** ## Pick one material Start with a physical thing, not a style. "A felt mallet on a wooden bar." "A fingernail on thin plastic." "A muted glockenspiel." Every sound in the family is that thing, struck differently. Apple's sound team works this way: they record real instruments like marimba and kalimba, and once tapped a hollow watch case with mallets to find its ring. Real materials make new technology feel familiar. The default AI failure is the opposite: a glossy sci-fi "digital blip" that belongs to no product. > **In plain words.** An earcon (A short interface sound whose meaning you learn from its shape, like a rising tone for joining a call. It does not imitate a real-world noise) is a short sound whose meaning you learn, like the rising tone when someone joins a call. It does not imitate anything real; its shape tells you what happened. A sound palette (The small, matched set of four to six sounds a product uses, all made from one material, like one typeface in several weights) is the small, matched set of them a product uses. ## The grammar of a family Meaning comes from the shape of the sound. People learn it in a handful of hearings. | What changes | Rule | Why it works | |---|---|---| | Size → pitch and length | Small things tick high and short (40 to 120 ms). Big things land low and long (300 to 800 ms). | Physics. A chip is lighter than a page. | | Direction → meaning | Rising = success, open, join. Falling = dismiss, leave, error. | Every operating system you have used. | | Interval → feeling | A major third or a fifth confirms. A tight, clashing step warns. | Consonance sounds safe; dissonance sounds tense. | | Complexity → priority | One hit for frequent things. Several notes only for rare ones. | A busy sound heard often tires people out in a day. | Notice the cards above: `send` rises, `error` falls and clashes, `success` is the only one with three notes. ## A family is small Most products need four to six sounds, not forty: - **tick** for a toggle, a selection, a snap. One hit, 80 ms or less, high. - **tap** for a press, only in products built to feel physical. Up to 120 ms. - **send** for sent, saved, done. One or two rising notes, up to 250 ms. - **receive** for an incoming message. Two notes, lower than send, up to 400 ms. - **error** for a rejected submit. Low, falling, up to 200 ms, beside a shake. - **success** for a rare milestone. Three notes, up to 800 ms. Write the family down as a list before generating anything. It is your sound design system. **Design the family first (paste into your agent):** ```text Design a sound family for this product before making any audio. Pick ONE physical material (for example "soft felt mallet on a small wooden bar") and derive every sound from it. List 4-6 sounds max as a table: name, role, contour (rising/falling), notes or pitch, duration in ms. Rules: small/frequent = high, short, single hit; rising = success; falling and dissonant = error; only rare milestones get 3 notes. No stock UI packs, no sci-fi blips. ``` ## The numbers Most "this sound feels wrong" complaints are a spec miss, not a taste miss: too long for its animation, too loud next to speech, or a sliver of silence before the hit. | Kind | Length | |---|---| | Tick, toggle, snap | 40 to 80 ms | | Tap, press | 80 to 150 ms | | Hover | 0 ms. Hover is silent. | | Send, save | 150 to 250 ms | | Notification | 200 to 600 ms | | Error | 100 to 200 ms | A handy rule from Toptal: a sound should not outlast the animation it goes with by more than about 300 ms. A 120 ms press with an 800 ms tail is a bell, not feedback. **Loudness.** Taps and ticks sit around −18 to −14 LUFS (Loudness Units relative to Full Scale: how loud a whole piece of audio sounds to a person. Closer to zero is louder; −14 is loud, −30 is quiet), below speech and above silence. Notifications may go to about −12. Peak every file at −3 dBFS (Decibels below the loudest a digital file can go. 0 dBFS is the ceiling where sound distorts, so UI sounds peak at about −3 dBFS) so it never clips. Put the design level in the file and the person's level in the volume control; never bake "a bit quieter" into the asset. **Format.** Mono (Sound on one channel instead of separate left and right. UI sounds are mono because phone and laptop speakers fold stereo into one anyway), 44.1 kHz. Phones and laptop speakers fold stereo into mono anyway. Keep a WAV as the master and ship MP3 or Opus. Trim the start to the first audible sample: five milliseconds of silence up front is a visible sync error. Fade the last 10 ms so it ends without a click. **Shape.** Cut everything under 150 to 200 Hz; laptop speakers cannot play it and it only eats headroom. Keep the body between 500 Hz and 4 kHz, where every device is honest. *(Check on the worst laptop speaker you own, not studio headphones at midnight.)* ## What a designed effect is made of For films and marketing pieces, Leon Lin's earshot project measured dozens of professional sound effects and found the same habits again and again: 1. **One gesture each.** A pitch that sweeps, notes that step up, a gate that speeds up into the cut. 2. **Its own frequency band.** Typing has nothing low; impacts live low with a thin tick on top. The middle is left for voice and music. 3. **A hard end.** Short sounds hold, then stop. No long reverb ride-out. 4. **Mono for objects, wide for textures.** A click is mono; a shimmer can be wide. 5. **Placed by kind.** Clicks land their attack on the moment; a whoosh peaks on the fastest frame; a riser ends on the hit. Repeated sounds vary in *take* (four recordings cycled, a tiny level change) rather than random pitch. The UI click is the exception: one voice, one level, every time. **Check yourself:** A product's error sound is a bright, rising two-note chime, 700 ms long. What is wrong? - [ ] Nothing, it is pleasant - [x] It rises and is consonant, which reads as success, and it is far too long for an error - [ ] It should be stereo - [ ] It should be louder so people notice *Why:* Direction and interval carry meaning: rising and consonant says success. An error should be low, short (100 to 200 ms) and falling, with a shake as its visual twin. ## In the skill - https://school.agents.org.in/skill/sound/sound-palette.md - https://school.agents.org.in/skill/sound/sound-spec.md - https://school.agents.org.in/skill/sound/designed-sfx-anatomy.md --- # Sound from motion > Place a sound on the exact frame where the motion makes contact, and derive its pitch, length and position from the motion itself. Module: Sound · Level: intermediate · 7 min · https://school.agents.org.in/media/sound/sound-from-motion Drop the tile below, then make it bigger and drop it again. The small one ticks high and quick. The big one lands lower and rings a little longer. Nobody picked those sounds from a library: the size of the tile decided them. *[Interactive demo: Change the size, drop the tile. Bigger means lower and longer, and the sound fires as it lands.]* When a sound feels wrong next to an animation, it is almost always because the sound and the picture disagree. A tiny chip lands with a heavy thud. A card on the right sounds from the middle. A whoosh peaks where nothing is moving. The fix is not a better sound pack. **Let the motion decide the sound.** ## Sound and motion are one event Apple calls this harmony: things should feel the way they look and sound the way they move. In the physical world, physics gives you that for free. In software, you build it by hand. The rule that produces it: the transient (The sharp, loud first instant of a sound, like the crack at the start of a clap. It is the part you line up with the picture) (the sharp start of the sound) sits on the contact frame (The frame of an animation where the moving thing visibly lands or arrives. Sounds that confirm a motion belong on this frame, not where the motion starts), the frame where the visual lands. The card stops, the toggle seats, the logo appears. Not the frame where the motion begins. > **In plain words.** A **frame** is one still picture in an animation; at 30 frames a second, one frame lasts about 33 ms. The **contact frame** is the one where the thing visibly arrives. That is where the "click" belongs. ## Late is forgiven, early is not Broadcast engineers measured how far apart sound and picture can drift before people notice. The numbers are lopsided: | | Sound arrives early | Sound arrives late | |---|---|---| | People notice at | 45 ms | 125 ms | | Still acceptable up to | 90 ms | 185 ms | We forgive sound that comes a little after the picture, because that is how the world works: light travels faster than sound. Sound that comes *before* the picture reads as broken almost at once. So: never let the sound lead. Aim for 0 to 30 ms late, about one frame. *[Interactive demo: The same landing, three placements. The dot on the timeline is when the sound fires.]* Try all three. "Early" sounds wrong even though it is only 90 ms off. "Late" at 200 ms becomes two events: a landing and then an echo. ## Each kind of sound has its own sync point - **Clicks, keys, pops, impacts** put their *attack* on the contact frame. - **A whoosh** puts its *peak* on the fastest frame of the move, starting 0.1 to 0.45 s before. - **A riser** *ends* on the hit, or just before it to leave a breath of air. - **A slow entrance** gets two sounds: the travel early, then a small landing on the settle. ## Finding the contact frame in code For a strong ease-out (How speed changes during an animation: start fast and slow down, start slow and speed up, or both. It decides whether motion feels snappy or sluggish), the motion has visibly stopped long before the math says it has. A good rule is about 85% of the way through the duration. A 480 ms landing makes contact around 408 ms. Fire the sound from the same event that starts the change, timed to the landing: ```ts // Confirming a landing: play when // the transform transition ends. card.addEventListener("transitionend", (e) => { if (e.propertyName === "transform") { play("land"); } }, { once: true }); // A tick that goes with a toggle // fires with the change itself. toggle.addEventListener("change", () => play("tick")); ``` *(Springs never stop cleanly. Sync to the first time they cross the rest position, not to the end.)* Firing on a spring's `animationend` lands the sound late by its whole wobbly tail. And every sound file must start at its first audible sample, or the file's own silence makes you late. ## The mapping: what the motion tells the sound Once timing is right, let the motion set the rest. | The motion says | The sound does | |---|---| | **Size** | Pitch and decay. A 60 px chip rings near 5 kHz for about 165 ms; a 460 px headline near 1.1 kHz for 600 ms. | | **Position left to right** | Stereo pan, gently, never hard left or right. In films only; product UI stays mono. | | **Height on screen** | Brightness of the attack. Higher sounds brighter. | | **Direction** | Contour. Leaving upward, the sweep goes up. | | **Duration and ease** | Length of a whoosh, and where it peaks. | | **A stepped reveal** | One click per step. Words at 110 ms each, cells at 210 ms. The rhythm *is* the sound. | The tile at the top uses the first row directly: pitch is `5200 × (60 / size)^0.75` Hz, and decay grows with size. ## Fewer sounds than tweens Deriving is not the same as sonifying everything. A scene with forty moving parts does not get forty sounds. It gets the few the eye actually follows. Two things landing on the same frame are one sound: voice the bigger one. For films, write the sound as data first: a cue sheet (A list written before any audio is made: one row per visual event, with its time, kind of sound, size and position, so the sound can be placed exactly), one row per visual event with its time, size and position. Lock the picture before you place anything, because a moved frame moves every cue after it. **Sync a sound to its animation (paste into your agent):** ```text Wire the "land" sound to the card's enter animation so it confirms the landing. Find the contact frame: for this ease-out, about 85% of the duration (or the transform's transitionend). The sound's attack goes there, 0-30 ms late at most, never early. For springs, use the first crossing of the rest position, not animationend. Trim leading silence from the file to zero. Derive pitch from size: small element = higher and shorter. One sound per event the eye tracks, not one per tween. ``` **Check yourself:** A drawer slides in over 400 ms with a strong ease-out. When should its soft landing sound fire? - [ ] At 0 ms, when the click starts the motion - [x] About 340 ms in, when it visibly arrives, or a frame after - [ ] At 400 ms plus the spring's settle time - [ ] 100 ms before it arrives, so it feels snappy *Why:* The attack belongs on the contact frame: for a strong ease-out, about 85% of the duration. A little late is fine; early reads as broken. ## In the skill - https://school.agents.org.in/skill/sound/sound-motion-sync.md - https://school.agents.org.in/skill/sound/sound-from-motion.md --- # Playing and making sounds > Wire sound into a web app the right way (unlock on a gesture, off by default, a visual twin for every sound) and make the files with code, a model or a free library. Module: Sound · Level: intermediate · 7 min · https://school.agents.org.in/media/sound/sound-on-the-web Here is a tiny chat. Send a message with sound off: you still see it land, with "Sent" under it. Turn sound effects on in the setting above and send again: now a two-note tone joins the checkmark. Reload the page and the setting is still how you left it. *[Interactive demo: Off by default, remembered, and every sound has a visual twin.]* That small demo holds the five rules for sound on the web. Each one exists because someone shipped the opposite. ## The five rules 1. **Off by default, with a switch people can find.** In settings, reachable by keyboard, and remembered across visits. This is why sound on the web is trusted at all. 2. **No sound-only information.** Every sound has a visual twin: the checkmark, the toast, the shake. Most people are muted most of the time. 3. **No autoplay, no sound on page load.** A sound the person did not cause is a notification, and notifications need permission. 4. **Respect the device's silence.** On iPhone, the silent switch mutes sounds like yours. Do not play UI sounds in a hidden tab. 5. **Treat the mute switch as reduced motion for your ears.** There is no CSS setting for sound. If someone has asked for reduced motion, keep sound off and skip any "turn on sound?" prompt. > **In plain words.** Browsers play sound through an AudioContext (The browser's little audio engine that a page creates to play sound. It starts paused until the person clicks or presses a key), a little audio engine your page creates. Browsers keep it **suspended** until the person clicks or presses a key, so pages cannot blast noise at you. Your code has to wake it up inside that first click. ## The bug everyone hits first Create the audio engine when the page loads and it seems to work, except nothing plays. It starts suspended, and every sound is silently dropped until something wakes it. The symptom: "sound only works on the second click." **Before:** created at load, on by default, sound on focus. ```ts // starts suspended const ctx = new AudioContext(); let enabled = true; // talks over screen readers button.onfocus = () => play("tick"); ``` **After:** created in the gesture, off until chosen. ```ts let ctx: AudioContext | null = null; const saved = localStorage.getItem("sound"); let enabled = saved === "on"; // call inside a click or keydown function unlock() { ctx ??= new AudioContext(); if (ctx.state === "suspended") { ctx.resume(); } } button.onclick = () => { unlock(); if (enabled) play("send"); }; ``` Two more details. Play each sound from a fresh `AudioBufferSourceNode`; they are cheap, and it is the only web primitive with no start-up delay (an `<audio>` element adds tens of milliseconds). And never attach sound to focus: screen readers are already speaking when focus moves, and your tick lands on top of their voice. *("Works on the second click" means the context was created at load. Create it in the gesture.)* ## Where the sounds come from Three paths without paying anyone, and one with a key. Pick by what you need, not by what happens to be installed. | You need | Path | |---|---| | Sounds right now, no files, tweakable in code | **Synthesize them.** A few lines of Web Audio, or ZzFX (under 1 KB) | | Safe, decent sounds today | **A free library** with a CC0 (A licence that gives a work to the public with no conditions: you may use, edit and sell it without credit. The safest licence for sounds) licence: Kenney's interface packs, soundcn, Freesound | | A custom material that matches the brand | **An open-weight model** like Stable Audio 3 Small-SFX, which runs on a laptop CPU | | Iterate in words ("more felt, less glass") | **ElevenLabs** sound effects, with an API key | ### Synthesis Every sound in this module is procedural (Sound built by code from oscillators and envelopes instead of loaded from a file. Weighs nothing and its pitch and length can follow the UI): built in code, zero bytes of audio. For ticks, taps and two-note tones it beats any model. It is the same every time, and its pitch and length are numbers you can tie to the UI. ```ts // A tick: 60 ms of high sine, fast decay. // No file, no fetch. function tick(ctx: AudioContext, freq = 2400, ms = 60) { const t = ctx.currentTime; const end = t + ms / 1000; const o = ctx.createOscillator(); const g = ctx.createGain(); o.frequency.value = freq; g.gain.setValueAtTime(0.5, t); g.gain.exponentialRampToValueAtTime( 0.001, end); o.connect(g).connect(ctx.destination); o.start(t); o.stop(end); } ``` ### Libraries Kenney's packs are the most used free UI sounds in existence, which is also their problem: people recognize them. Use them as a starting family and re-pitch or layer. Whatever the source, keep one material. A grab-bag of free sounds is the audio version of the default icon set. ### Models Prompt any sound model with **material + action + envelope + contour + purpose**, never a UI noun. "A success sound" gets you a stock jingle. This gets you a sound: **Generate a sound family with ElevenLabs (paste into your agent):** ```text Generate this family with ElevenLabs text-to-sound-effects (model eleven_text_to_sound_v2), all in one session with the same material phrase: tick: "single very short tick, fingernail on thin plastic, dry, no tail, bright, one-shot UI feedback" send: "two quick rising notes on a muted kalimba, warm, dry, short decay, confirmation" error: "short low dull thud with a slight downward pitch, rubber on wood, dry, no tail" Use duration_seconds 0.5 and prompt_influence 0.8 or higher. Then trim leading silence to zero, high-pass at 150 Hz, peak at -3 dBFS, mono. Commit the files and record the prompts and settings in a manifest. ``` Say "dry" and "no tail" every time; the default has room echo. Ask for half a second and cut it down. And commit the files: regenerating one sound next month gives you a *different* sound, and a family with one re-rolled member sounds patched. > **Open source is not the same as commercial use.** Meta's AudioGen code is open, but its weights are non-commercial. Stability's licence changes above US $1M a year in revenue. Some sound packs mix free and restricted files. Write the licence next to every file. **Check yourself:** Sound plays on the second click but never on the first. What is the likely cause? - [ ] The file is too large - [x] The AudioContext was created at page load, so it started suspended and only woke up later - [ ] The sound is mono - [ ] The volume is set to -3 dBFS *Why:* Browsers start an AudioContext suspended until a user gesture. Create and resume it inside the click or keydown handler, before playing. ## In the skill - https://school.agents.org.in/skill/sound/sound-playback-web.md - https://school.agents.org.in/skill/sound/sound-generation-open-source.md - https://school.agents.org.in/skill/sound/sound-generation-elevenlabs.md --- # Sound in launch films > Pick a sound register for a launch film, place the track's structure on the picture, take sound away before the reveal, and only use recordings you are licensed to. Module: Sound · Level: advanced · 8 min · https://school.agents.org.in/media/sound/sound-in-launch-films Same 12-second film, five soundtracks. Click through them below. They sound nothing alike, and yet every one does two things: its structure sits on what the picture is doing, and something drops out just before the name appears. *[Interactive demo: One picture, five sound registers. The dashed line is where the product's name lands.]* A launch film flips everything from the first four lessons. In the product, sound is opt-in, rare and quiet. In a short film that introduces the product, sound is the emotional layer, and silence is a material you place on purpose. ## Five registers A sound register (The overall kind of soundtrack a film uses, such as a dry reveal, a low drone with clicks, a beat track, a voice, or soft foley) is the overall kind of soundtrack. Measurements across dozens of launch films found five that read as crafted. Choose from the picture, not from taste. | Register | What carries it | Use it for | |---|---|---| | **A · Dry reveal** | Hits only, each on a motion peak; true silence between | Logo reveals and stings under 15 seconds | | **B · One-key bed + clicks** | A low drone in one key, dry clicks on stepped reveals | Brand films and kinetic type (OpenAI's *Refreshed.* and GPT-5 films) | | **C · Beat track** | A track whose drop lands on the reveal | UI motion, keynote cards, fast sizzles | | **D · Voice-led** | The voice, with the music 10 to 13 dB under it | Founder-led and live-action films | | **E · Product camera + foley** | A soft pad, plus foley (Everyday sounds added to match on-screen actions, like keys clicking or a button pressing. In a product film they get louder the more an action matters) louder the more an action matters | The real product, one action at a time (Linear, Raycast) | Linear's agent film shows that last idea well: typing sits just over the pad, pressing Enter is louder, and Send is loudest of all. The level follows the consequence. ## Take something away before the reveal **Most crafted films go quiet for a moment right before the name.** 23 of 28 films from one studio did it; so did 14 of 18 acclaimed launches. The gap is short, usually 0.1 to 0.9 seconds, often just the low end pulled out, and it ends exactly on the reveal frame. The picture does the same thing at the same moment: a beat of stillness. Silence plus stillness is what makes the name land. *(The gap must line up with something you can see. Phones cannot play the low end, so a bass-only gap is invisible there.)* ## Placing a music track A track is placed by the picture's structure, not laid under it from second zero. - **Put the drop on the reveal.** The drop (The moment in a music track where the beat and bass come in hard. In a launch film it should land on the reveal of the name) (where the beat and bass come in hard) lands on the brand or title. Move the track, not the picture: trim the file's start so its drop plays on the reveal frame. - **Break down under reading.** When the viewer has to read (typing, a headline, a diagram), the beat thins or the bass leaves. - **Lock only what you choose.** Pick one layer to sync, act changes or the beat grid, and land it on the beat. Or lock nothing. A cut a few frames off a strong beat reads as a miss. - **Edit on bars, stay in key.** Shorten a track by cutting whole bars from the middle. Anything tonal you add on top, a chime or a boom, sits in the track's key. - **Under a voice, the voice is the clock.** Time scenes to the spoken words, leave a short silence before key lines, and keep the music 10 to 13 dB below. > **The AI default.** An unstructured bed (Music or a drone that runs quietly underneath a whole film or section. A bed laid flat from the first second with nothing placed on the reveal is the default mistake): one stock track started at 0 s, at one level, with no drop on the reveal, nothing taken away, and cuts landing wherever. If nothing in the track can go on the reveal, use register B's drone or register A's silence instead. ## Loudness, stated on purpose There is one fixed number: **−1 dBTP** true peak (The highest point the audio wave really reaches, including between samples. Keep it at or below −1 dBTP so it never clips on playback), so nothing distorts on any device. Overall loudness is a choice per register. Acclaimed films sit around −18 LUFS in the middle; short beat-cut sizzles run hotter, around −13; long, calm product walkthroughs go much quieter. Write the target next to the register. And listen once on phone speakers before you ship. ## Can you use that recording? A recording in a launch film is used **commercially**, **edited** (trimming and syncing counts) and **published** where platforms scan audio. Its licence has to allow all three. *[Interactive demo: Pick a licence. Commercial, edited and published: it has to allow all three.]* - **Yes:** CC0 (A licence that gives a work to the public with no conditions: you may use, edit and sell it without credit. The safest licence for sounds); CC BY with a full credit (title, author, link, licence, "edited"); Mixkit's and Pixabay's free licences. - **No:** anything NC (non-commercial), ND (no edits), SA (your film would inherit the licence), "royalty free" with no licence text, and any case where two sources disagree. - **Read the item's own page.** On Freesound, licences are per sound, not per person. Aggregator sites are not authoritative. Save the licence text, link, author and date next to the file. - **Watch for Content ID (YouTube's system that scans uploads for registered music and files automatic claims, sometimes even when your use is properly licensed).** Some composers register their CC BY tracks, so a correct use can still get an automatic claim. Credit in the description and dispute citing the licence. Sounds you rendered in code are yours. ## Giving your agent ears An agent cannot hear what it makes, so it should never describe how audio sounds without a measurement behind it. Leon Lin's **earshot** is that measurement: a local tool that describes a file, finds and trims the right take, lays out a film's sound on a timeline, and renders effects from code. Let it do the listening; keep the decisions (register, placement, loudness) with the rules above. Where earshot's defaults differ, such as letting sound lead by a frame or a −14 LUFS target, the measured rules here win. **Plan a launch film's sound (paste into your agent):** ```text Plan the sound for this launch film before rendering any audio. Lock picture first. 1. Pick a register from the picture: A dry reveal, B one-key bed + clicks, C beat track, D voice-led, E product camera + foley. Write its loudness target next to it; true peak is always -1 dBTP. 2. Mark the reveal frame. Take something away 0.1-0.9 s before it (the low end or the whole mix) and end the gap on the reveal, with a beat of visual stillness. 3. If there is a track: trim its head so the drop lands on the reveal, break the beat down under anything the viewer reads, lock one layer to the beat or none. 4. List every recording with its licence read from the item's own page (CC0 or CC BY only; no NC, ND or SA), URL, author and date. Show me the plan as a table of times before mixing. ``` **Check yourself:** A film uses a great track under the whole thing, from 0 s to the end, at one level. The name appears at 21 s. What is the first fix? - [ ] Make the track louder - [x] Trim the track's start so its drop lands on the name, and take sound away for a moment just before it - [ ] Add clicks from a free pack over every cut - [ ] Switch to a CC BY-NC track *Why:* A flat bed from 0 s is the unstructured default. Move the track so its drop lands on the reveal, and leave a short gap before it. Library blips over a beat track and non-commercial licences are both mistakes. ## In the skill - https://school.agents.org.in/skill/sound/launch-video-sound.md - https://school.agents.org.in/skill/sound/launch-video-music.md - https://school.agents.org.in/skill/sound/sound-licensing.md - https://school.agents.org.in/skill/sound/earshot-reconciliation.md --- # Pick the register first > Name the kind of launch film you are making before anything else, so cut rate, stillness and loudness all have a target. Module: Launch films · Level: beginner · 7 min · https://school.agents.org.in/media/film/register-first Here is one moment, "the agent opens a pull request", shot three ways. Same product, same beat. Flip between them. *[Interactive demo: One beat in three registers. The numbers under the frame come with the register, not with the quality.]* None of the three is better. They are different **kinds** of film, and each kind has its own measured habits: how often it cuts, how much of it sits still, how loud it is. That kind is called the register (The kind of launch film you are making, such as UI motion graphics, product camera or kinetic type. It sets the cut rate, stillness and loudness), and it is the first decision on any launch film (The short video, usually 30 to 90 seconds, a company posts when it ships a product or feature). > **In plain words.** A **launch film** is the short video (usually 30 to 90 seconds) a company posts when it ships something. A **register** is its genre: a lively motion-graphics piece, a calm close-up of the real product, a film made of words. Pick the genre, and most of the numbers pick themselves. ## Why register comes before everything Every number later in this module depends on it. Four cuts a minute is normal for one kind of film and sluggish for another. Half the frames sitting still is calm in one register and dead in the next. The numbers here come from a measured set of 47 launch films: 29 made by the studio Skale, and 18 acclaimed films from 2024 to 2026 by Linear, Raycast, Anthropic, Figma, Apple, Notion, Google and others. Each was timed frame by frame at its own frame rate, with cuts counted by eye. | Register | Typical films | Cuts a minute | Still share | |---|---|---|---| | UI motion graphics | Skale's Replit, Bolt, Aside films | 4 | 9 % | | Product camera | Linear Agent, Raycast, Claude Cowork | 14 | 49 % | | Keynote cards + demo | Cursor 2.0, Notion Mail, Granola 2.0 | 12 | 37 % | | Kinetic type | Claude Opus 4.6, the Gemini app | 3.3 | 17 % | | Beat-cut sizzle | Figma glass, Arc on Windows, Spline Hana | 31 | 29 % | | Founder-led hybrid | Typesafe, Browserbase | ~13 or 0-4 | 18 % | Cut rate (How many times a minute the picture jumps to a new shot. About 4 in UI motion films, 14 in product-camera films, 31 in beat-cut sizzles) is how many times a minute the picture jumps to a new shot. Still share (The fraction of a film's frames where nothing visible changes. A blinking caret or a moving cursor counts as motion) is the fraction of frames where nothing visible changes at all; even a blinking caret counts as motion. *(Never average two rows into a target. Half UI motion, half product camera gives a film neither register makes.)* ## How to pick You rarely need a long debate. The product and the brief decide it. **Step: A known brand, the product is the hero.** Product camera. If the demo needs chapters, keynote cards with demos between them. **Step: A feed sizzle under 40 seconds, every shot a live component.** Beat-cut sizzle. These are also the loudest films in the set. **Step: A founder explains the product or a raise.** Founder-led hybrid, carried by the voice. **Step: The words are the product, like a model launch.** Kinetic type. **Step: None of these: a new product, no founder on camera, no brief.** UI motion graphics, the biggest measured row (18 of Skale's 29), with the name said early. A second register can ride inside the first, like a material act inside Framer 3.0's tagline. Take the numbers from the main one. ## What every register keeps Some rules held across all 47 films, whatever the genre. These are your floor. - **No dead cut (A cut from a settled frame to a new scene that just waits. Neither side is moving, so the film stalls. It fails in every register).** Never cut from a settled frame to a scene that just waits. One side of the cut should be moving. - **Nothing decorative moves on UI.** No floating, pulsing or breathing cards in any of the 18 acclaimed films. A slow camera drift under a hold is fine. - **Words are built, not faded in.** 27 of 29 Skale films build copy word by word or letter by letter. - **The bass arrives on the first reveal.** The music's low end lands with the name or the first big reveal. - **Silence punctuates.** A pulled bass or a gap before a reveal, in 23 of 28 Skale films with sound. **Cut rate, stillness and loudness are properties of the register, not marks of quality.** A calm product-camera film judged against a lively motion-graphics one looks too still. It is not; it is a different film. ## The order of decisions Once the register is named, the rest of a film is a chain of decisions, each with its own owner. This module walks it in order. 1. **Register** (this lesson). 2. **Beats:** when the first word, the name and the endcard land. 3. **Words and product:** type cadence, the cursor, typed prompts. 4. **Cuts, seams and motion:** how one shot hands over to the next. 5. **Sound:** covered in the Sound module. 6. **Review:** check the render against its own register, then ship the loop, sting and vertical cuts. A tool such as HeyGen's HyperFrames builds the film from code. The design-engineering skill decides it: register, beats, words and sound. **Start a launch film with the register (paste into your agent):** ```text Before you storyboard, name the launch-film register for this product (UI motion graphics, product camera, keynote cards + demo, kinetic type, beat-cut sizzle or founder-led hybrid) and say why in one line. Then state the target cut rate and still share from that register's row, and keep every later decision inside it. ``` **Check yourself:** A brand-new developer tool, no founder on camera, no brief. Which register is the safe default? - [ ] Product camera, because it is calm - [x] UI motion graphics, with the name early - [ ] Beat-cut sizzle, because feeds reward energy - [ ] An average of all the registers *Why:* With nothing else to go on, the largest measured row is UI motion graphics (18 of Skale's 29 films). An unknown product names itself early, not at 70 %. ## In the skill - https://school.agents.org.in/skill/launch-video/MOC-launch-video.md - https://school.agents.org.in/skill/launch-video/launch-video-registers.md --- # Time the beats > Place the hook, the name, the proof and the endcard at the moments real launch films use, and know which of three name modes you are in. Module: Launch films · Level: beginner · 7 min · https://school.agents.org.in/media/film/beats Drag the playhead. This is a 60-second film for a made-up product called Relay, timed to the measured medians. Every frame in the preview is drawn from the time alone. *[Interactive demo: Scrub, or tap a beat. The blue ticks mark the first word, the name and the final hold.]* A launch film's structure is not a matter of taste. Across 47 measured films, the same moments land in the same places. Each section is a beat (A stretch of a film with one job: the hook, the problem, the name, the product, the proof, the endcard): a stretch of the film with one job. ## The first two seconds Put a readable word on screen by **0.2 to 0.7 seconds**. Skale's films median 0.2 s; the acclaimed films 0.68 s, and six of them show a word on frame zero. The first scene change, the first seam (Any change from one scene to the next, whether a cut, a fill or a morph. A good seam reads as one continuous move), lands by about **2 seconds**. That opening is the hook (The first two or three seconds of a film, which decide whether anyone keeps watching. A readable word should be on screen by 0.2 to 0.7 seconds). In the acclaimed films it is usually the product already working (five films), a claim or question (seven), or the brand mark (three). > **The poster frame trick.** 9 of Skale's 29 films bake 1 to 4 frames of the finished title at t = 0, then cut. That frame becomes the autoplay thumbnail, at a cost of about a tenth of a second. It is called a poster frame (The frame shown before a video plays, as its thumbnail. Some films bake 1 to 4 frames of the finished title at the very start so the thumbnail names the product). ## When to say the name This is the beat people get wrong most. There are three measured modes. Pick one and commit. | Mode | When the name lands | Who does it | |---|---|---| | Early | by 11 % of the runtime | brand-first films, either corpus | | End of the problem act | median 29 % (6-51 %) | problem-first films | | Late | around 70 %, after the demo | known brands only: Apple, Arc, Anthropic, Figma, Raycast | **Five of the six late-name films come from brands the audience already knew.** Holding an unknown product's name back for 70 % of the film means most viewers leave without hearing it. *(Don't time a problem act to 15 %. That number mixes all the films that were not brand-first. A problem act runs to the name: median 29 %, never much past half.)* The music agrees with the name. The **low end** (the bass) lands on the first reveal: in 12 of 18 Skale music films and 10 of 18 acclaimed ones. ## The body: show, or prove Problem-first films tend to prove: 9 of Skale's 13 carry a proof beat, usually a counter rolling up to one number. Product-first films tend to show the product working instead. Five acclaimed films land a **payoff** just before the endcard: the finished result or the user's reaction, 0.1 to 1.2 seconds before the cut. Cursor 2.0's hot reload lands 1.2 s before; Notion Mail ends on Send. **Before (avoid):** The demo ends mid-task, then the logo fades up over a blank frame. **After (do this):** The pull request merges, a beat later the mark grows from a dot, the wordmark lands, the last two seconds hold still. ## The endcard The endcard (The closing frame of a film with the mark, the name and maybe a URL. In measured films it runs 4.4 to 6.3 seconds and its last 2 seconds hold still) is the closing frame: the mark, the name, maybe a URL. It runs longer than people expect. - **Length:** 4.4 s (Skale) to 6.3 s (acclaimed). - **Final hold:** about 2 seconds where nothing changes, so it can be read and screenshotted. - **A URL only with a verb**, and only when there is somewhere to go. "Try it at relay.dev", not a bare address. Only about half of Skale's endcards carry a URL at all. - **Build the mark** from a primitive or the film's own objects. Five acclaimed films grow it from a single dot; Claude Cowork blooms its mark out of the button the user just clicked. - **Bookend:** repeat the opening move at the end (7 of 29 Skale, 10 of 18 acclaimed). ## A series is a template Replit shipped three films in a month on one kit: red keywords, a cream canvas, named cursors, the same lockup hold. To make the next film in a series, write the new product into the slots and keep every frame number, ease and cut. **Storyboard to measured beats (paste into your agent):** ```text Storyboard this launch film (register: <name it>) with timestamps: - a readable word by 0.7 s, the first seam by about 2 s - the name in ONE mode: early (by 11 % of runtime), at the end of the problem act (about 29 %), or late (~70 %, only for a known brand) - the music's low end on the first reveal - a payoff just before the endcard - an endcard of 4.4-6.3 s that holds still for the last ~2 s; a URL only with a verb ("Try it at ...") Show the name time as a percentage of the runtime. ``` **Check yourself:** A 60-second film for a product nobody has heard of names itself at 42 seconds. What is wrong? - [ ] Nothing, late names build suspense - [x] 42 s is 70 %: the late mode is only seen from brands people already know - [ ] The name should be at exactly 15 % - [ ] It should never name the product before the endcard *Why:* The late-name mode (~70 %) comes almost entirely from known brands. An unknown product should name itself early or where its problem act ends, around 29 %. ## In the skill - https://school.agents.org.in/skill/launch-video/launch-video-structure.md --- # Words and product on screen > Build on-screen type at a readable cadence, and drive the product UI with a cursor, typed prompts and an honest wait. Module: Launch films · Level: intermediate · 8 min · https://school.agents.org.in/media/film/words-and-product Move the slider. The same line builds word by word at whatever pace you set, and the newest word lands blue before it settles to ink. *[Interactive demo: Word stagger from 0.05 s to 0.9 s. Try 0.2 s, then tick “Fade as a block”.]* At 0.05 s the line is a blur; at 0.9 s it is a voice speaking slowly. Around 0.2 s it reads as it builds. That gap between words is the word stagger (The gap between one word appearing and the next when a line builds word by word. About 0.2 seconds in a music film), and in a music-only film it is the edit itself: the type is the script. ## Build words, never fade a block A sentence faded in as one block reads as a slide. 27 of Skale's 29 films build copy per word or per letter; the two exceptions are a phrase-caption film and a CG teaser with no copy at all. | Job | Stagger | |---|---| | Music film | 0.13-0.2 s (median 0.18 s) | | Captions synced to a voice | ~0.3 s | | One word per beat of the track | 0.4-0.5 s (Arc on Windows) | | The type is the voice | 0.5-0.9 s | **Mark the newest word.** 15 of 29 Skale films land each new word in an accent or a pale grey, then settle it to ink within **0.13 to 0.3 seconds**. The eye always knows where the sentence has got to. **Hold it long enough.** After the last word, keep the line up **1.15 s** (Skale's median); acclaimed title cards stay about 1.5 s in all. That is the hold (How long a line stays on screen after its last word lands, so it can be read. About 1.15 to 1.5 seconds in launch films). *(Elements in a list can cascade fast (around 0.05 s apart). A sentence someone has to read cannot. Don't squeeze one into the other.)* ## Size and the slam Statements in these films are small: about **5 % of frame height**, around 54 px on a 1080 px frame. They caption the UI; they are not headlines. Body text never goes below about 20 px at 1080p. Six of Skale's films use one slam word (One word that arrives huge, a quarter of the frame or more, holds a moment, then drops into its sentence. Used once in a film, if at all): a single word arriving huge (25-61 % of the frame), holding a few frames, then dropping into its sentence. Replit Slides holds its slam about 0.23 s, then drops it from 5× to 1× in one frame. Once per film is plenty. ## The product as a character Now the product itself. In most films the interface is **rebuilt as vector**, not screen-recorded (22 of 29 Skale films, 11 of 18 acclaimed), then cropped tight on the one control that matters. Eight acclaimed films use a macro crop (Framing a single control, like one button or field, so it fills the frame, instead of showing the whole app): one button or field filling the frame. **Before (avoid):** A full-screen recording of the app, a tiny macOS pointer wandering across it, every panel in full colour. **After (do this):** The one panel rebuilt and cropped tight, an oversized cursor entering from below, colour saved for the state change. **Colour is saved for state.** Raycast floods its dialog green only on save; Linear Agent shows colour only in issue icons. ## The cursor A cursor appears in 17 of 29 Skale films and 11 of 18 acclaimed ones. When it does, it must read at video size. - **Size:** the oversized cursor (A pointer drawn far bigger than on a real screen, about 7 % of the frame's width, so it reads in a video), about 7 % of the frame's width (≈134 px on a 1920 frame), or a normal pointer inside a crop cut in until it reads (Cursor 2.0 cuts about 3×). - **Entry:** from off-frame, on one decelerating glide of 0.4-0.9 s. The tip lands on the target. - **Press:** shrink to 0.84 over 0.1 s, back over 0.22 s. The button dips with it. - **Exit:** off the nearest edge, or as the carrier into the next shot. Never faded out in place. - **Cause, then effect.** Nothing starts on its own; the click causes the next beat. ## Typed prompts: read or recognise How fast should a prompt type? It depends on its job. | The viewer must… | Speed | Seen in | |---|---|---| | **read** it (it carries the argument) | ~15 characters a second | Raycast 10, Notion 3.0 12-15, Cursor 2.0 20 | | **recognise** it (only its shape matters) | ~53 characters a second | Skale's films | | skim title cards | 40-65 characters a second | Cursor 2.0's cards | A 33-character prompt meant to be read types for about 2.2 seconds, then holds 1.15-1.5 s. Keys land unevenly, slower at the ends, with a little extra time after spaces. ## Human and agent, told apart In an AI product, show who is speaking. Framer 3.0 types the human at 21 characters a second and the AI at 160 after a 0.9 s thinking state. Linear Agent gives the human a caret and resolves the agent's rows from blur 0.25 s apart. Claude Cowork sets the agent in a serif and the user in grey sans pills. **The agent's wait is either honest stepped state or it is cut past.** Notion 3.0 steps a counter 1 → 61 while the agent works; Linear Agent simply cuts to the prompt already posted, the answer half a second later. **Type and UI for a launch film (paste into your agent):** ```text For every line of on-screen copy: build it per word at ~0.2 s (music) or ~0.3 s (synced to voice), land the newest word in the accent and settle it to ink within 0.3 s, hold 1.15-1.5 s after the last word. Statements at ~5 % of frame height. No block fades. Product: rebuild the UI as vector and crop to the control that matters. Cursor ~7 % of frame width, enters from off-frame, presses (0.84 scale, 0.1 s down / 0.22 s up), exits off an edge. Prompts to be read type at ~15 chars/s. Show the agent's wait as stepped state, or cut past it. ``` **Check yourself:** A prompt in your film carries the whole argument: “Find every flaky test and fix it.” How fast should it type? - [x] About 15 characters a second, so it can be read - [ ] About 53 characters a second, the Skale median - [ ] Instantly, as one block - [ ] As fast as the agent's reply *Why:* A prompt the viewer must read types at about 15 characters a second. 53 is for prompts that only need to be recognised by their shape. ## In the skill - https://school.agents.org.in/skill/launch-video/launch-video-type.md - https://school.agents.org.in/skill/launch-video/launch-video-ui-demo.md --- # Cuts, seams and motion > Make every scene change read as one move, avoid the two cuts that fail in every register, and keep motion inside a shot calm and causal. Module: Launch films · Level: intermediate · 8 min · https://school.agents.org.in/media/film/cuts-and-seams Here is one scene change done three ways, laid out the way a reviewer checks it: frames a tenth of a second apart, either side of the cut. *[Interactive demo: A contact sheet around the cut. Look for frames where nothing changes, and for a frame neither shot contains.]* The dead cut shows identical frames on both sides of the cut. The crossfade shows a grey frame that belongs to neither shot. The cut on motion just looks like one card throwing to the next. That last one is the craft of this lesson. ## Films cut, and that is fine A hard cut (An instant jump from one shot to the next, with no fade or transition between them. Most launch films use them) is an instant jump from one shot to the next. 26 of Skale's 29 films and 14 of the 18 acclaimed films hard-cut. Banning cuts forces every film into a continuous morph, which only five of the 47 chose. How often a film cuts belongs to its register. Pick one below and feel the difference. *[Interactive demo: Thirty seconds of film at each register's measured cut rate. Untick “Varied” for an even rhythm.]* An even rhythm is a metronome. The films that feel alive vary it, and many end a run on an **accelerating ladder**: figma-launch cuts nine times on holds shrinking .8, .5, .4, .3, .2, .15, .12, .1 s, then lands on a hold. ## The two cuts that always fail **Step: The dead cut.** A settled frame, then a scene that waits. The outgoing shot is not moving on the cut frame, and the incoming one does nothing for more than ~0.3-0.4 s. The film stalls. **Step: The crossfade dip.** Both scenes fade at once, so at the midpoint whatever is underneath shows through: the page's white, a different background. Fade through a ground both scenes share, or cut. A crossfade (The flash you get when two scenes fade at the same time: at the midpoint, whatever is underneath (often white) shows through) is not banned. 11 of 29 Skale films dissolve or dip (0.45 s median). Adaline dips to its paper colour; Extend dips through its brand colour. Those pass because the ground is shared. ## Where the eye accepts a cut A good cut lands where the eye is already going. The measured places: - **On the click.** Linear Agent clears the input on Enter, cuts 0.7 s later to the prompt already posted. - **On a constant ground.** Keep one world or layout and cut freely; Raycast cuts 9 times in 28 s. - **On the element being read.** A 2-3× scale jump of the same thing, anchored so it lands where it really sits. - **Into motion.** Cut mid-drift on a moving camera, or onto things already travelling. - **Inside a fill.** The Gemini app hides all four of its cuts in full-frame glyph fills. - **To a still frame that acts within a beat** (0.3-0.4 s). ## Seams: what carries the eye A seam (Any change from one scene to the next, whether a cut, a fill or a morph. A good seam reads as one continuous move) is any scene change, cut or not. It reads as one move when the outgoing element is still travelling on the last frame and the incoming one carries on: same axis, same direction, matched speed. **One current per film.** Pick one dominant direction (leftward is a common default) and spend the others on purpose: up for a conclusion, a pull back for an arrival. | Seam | How it works | Timing | |---|---|---| | Fill the frame | a pressed button or shape grows until its colour is the next ground | 0.33 s median | | Zoom-through (A seam where the outgoing scene pushes in and blurs, the scene swaps, and the new one arrives from slightly smaller, as if the camera flew through) | out 1 → 1.2 with blur, hard swap, in from 0.75 | out 0.2 s, in 0.5 s | | Zoom into type | letters grow 4-6× until they fill the frame | 0.33 s median | | Shared element | one object carries across: a pill becomes a progress bar becomes a chart bar | ~2 s chains | The thing that crosses is the carrier (The thing that crosses a scene change and carries the eye with it: a button filling the frame, a dot, a line that becomes a chart). Use **2-3 seam types** per film, one of them for 60-70 % of the changes. *(Write the seams down before animating: one row per seam, typed cut, match-cut or morph, with what exits and what enters.)* ## Motion inside a shot Inside a shot, things arrive on a fast exponential settle and leave on the mirror curve. The speed of a settle is its time constant (How fast an exponential settle comes to rest. A smaller tau settles faster; about 0.1 to 0.15 seconds for an object in a film): about **0.1-0.15 s** for an object, slower for long travel (Raycast's big crane ~0.43 s, counters 0.6-0.8 s). - **Nothing decorative moves on UI.** No float, pulse or breathe. A slow camera creep under a hold is fine. - **Overshoot is a register,** not a default: only 4 of 29 Skale films and 3 of 18 acclaimed show visible bounce. Never spring a camera. - **Blur is a choice.** Velocity blur peaks around 10 px on text, 18-20 px on full-frame surfaces. Plenty of films whip completely sharp. - **Decisions are stamped, not tweened.** A typed letter, a selection hop, a page swap happens in one frame. - **A cause launches its effect.** Click, squash, release, impact. That is what makes a film feel lively, not bounce. **Cut and seam a launch film (paste into your agent):** ```text Plan every scene change before animating. For each seam write one row: type (cut / match-cut / morph), what exits and what enters, axis and direction. Rules: no dead cuts (one side always moving, or the new shot acts within 0.3-0.4 s); no crossfade between two opaque scenes unless they share a ground; one dominant direction for ordinary seams; 2-3 seam types, one primary. Inside shots: exponential settles (tau 0.1-0.15 s for objects), nothing decorative moving on UI, no spring on the camera. ``` **Check yourself:** Two dark scenes on a white page are crossfaded over 0.6 s. What does the viewer see at the midpoint? - [ ] A smooth blend of the two scenes - [x] A grey flash, because the white page shows through - [ ] Nothing, crossfades are invisible - [ ] The first scene frozen *Why:* When both scenes fade at once, their summed opacity drops below 1 and the page underneath shows through: the crossfade dip. Fade through a ground both scenes share, or hard-cut. ## In the skill - https://school.agents.org.in/skill/launch-video/launch-video-cuts.md - https://school.agents.org.in/skill/launch-video/launch-video-seams.md - https://school.agents.org.in/skill/launch-video/launch-video-motion.md --- # Review, render and ship > Review a render against its own register, render it from code without the classic traps, and ship the loop, sting and vertical cuts that go with it. Module: Launch films · Level: advanced · 9 min · https://school.agents.org.in/media/film/review-and-ship Your film is going to the feeds. Here is the 16:9 master turned into a 9:16 phone cut two ways. Tick the overlay to see what the app's own buttons cover. *[Interactive demo: A centre crop against a re-layout, inside the feed's safe zones.]* The crop cuts the line in half and loses the product. The re-layout is a new composition on the same timeline. That is the last step of a film. Before it comes the review. ## Review against its own register Numbers first, taste second. A film is judged against the medians of **its own** register: a product-camera film next to a motion-graphics one always looks too still. > **Measure honestly.** Review at the film's native frame rate (The frame rate a video was made at, like 24, 30 or 60 frames a second. Review at that rate; converting adds fake duplicate frames). Resampling a 24 fps film to 30 inserts duplicate frames that fake short moves. And recount cuts by eye on a contact sheet (A grid of still frames taken at small steps through a video, so you can see exactly what happens around a cut): the automatic cut detector agreed with a frame reading in only 9 of 29 Skale films and 5 of 18 acclaimed ones. The skill reviews a film on eleven rows. Each row has an owner and a target. | # | Check | Target | |---|---|---| | 1 | Register | named; cut rate inside its row | | 2 | Hook | a readable word by ~1.3 s, first seam by ~3.6 s | | 3 | Name | one measured mode; the low end on the first reveal | | 4 | Words | built per word ~0.2 s apart; newest settles in ~0.3 s; holds 1.15-1.5 s | | 5 | UI demo | prompts ~15 chars/s to read; cursor ~7 % of width; the wait stepped or cut | | 6 | Motion | nothing decorative on UI; no spring on a camera | | 7 | Seams and cuts | no dead cut; no crossfade dip; one current; 2-3 seam types | | 8 | Endcard | 4.4-6.3 s with a ~2 s final hold; a URL only with a verb | | 9 | Sound sync | every hit on its contact frame or one after (0-30 ms), never ahead | | 10 | Level | ≤ −1 dBTP true peak (The highest point the audio wave really reaches, including between samples. Keep it at or below −1 dBTP so it never clips on playback); loudness in LUFS (Loudness Units relative to Full Scale: how loud a whole piece of audio sounds to a person. Closer to zero is louder; −14 is loud, −30 is quiet) stated for the register | | 11 | Source | the film's own sound, no mix bolted on after | Write each finding as one row: what you saw, what to change, why. ## A film is a function of time When a film is built from code, as with HeyGen's HyperFrames (HeyGen's open tool for making videos from HTML: you write the film as a web page and it renders it frame by frame), every frame must be a pure function of the time `t`. No `Math.random()`, no clock, nothing carried from the last frame. Seeded randomness is fine. That rule buys real motion blur. The renderer samples several moments inside each frame and averages them: a 180° shutter (Real motion blur made by sampling several moments inside each frame and averaging them, like a camera's shutter staying open), four samples a frame by default, up to 24 on a whip pan. One unseeded `Math.random` makes those samples disagree and the blur turns to noise. *(Never let the shutter cross a hard cut. Slide it back so it ends on the cut, or the fastest frame renders sharp and stutters.)* **Place everything on a beat grid (The music's beats as a timeline you place everything on, measured from the actual track so cuts and hits land on the beat)** taken from the actual track, not from the brief. A generated track's tempo is a hope until measured: over 50 s, a 0.15 % tempo error puts the last hits about 70 ms late, past the 30 ms sync budget. ## Delivery gates Hand nothing over until every file passes. **Step: Frame count matches.** A mux with <code>-shortest</code> silently drops the last frames when the audio ends early. **Step: H.264 level fits.** Level ≤ 4.2 at 1080p, ≤ 5.2 at 4K. A slow preset without <code>-level</code> writes 6.0, which fails in Safari, QuickTime and on phones. **Step: Under 1 GB at 4K.** CRF around 12 at a slower preset; higher quality nobody can see just doubles the file. **Step: Decodes on the hardware decoder.** That is what phones use; a software decode passing proves nothing. **Step: Loudness written, −1 dBTP.** For the register, chosen on purpose. −14 LUFS is an engine default, not a standard. ## The formats around the film A launch film rarely ships alone. Each companion breaks a different rule of the master. - **Feature loop (A short looping video for a landing page that runs as a seamless cycle, with no visible start or end)** for the landing page: a cycle, not enter-hold-exit. The last frame flows into the first with no visible seam; frame 0 is the poster and names the product. Ship MP4/WebM; GIF only at 25 or 50 fps (GIF delays are whole hundredths, so 30 fps plays 11 % fast). - **Logo sting (A 3 to 8 second clip that assembles the logo and holds it, played at the start or end of other videos):** 3-8 s, the name plus three words at most. Assemble the mark from 2-4 pieces with one hit on contact; hold the lockup at least 1.5 s. - **Vertical and square:** re-lay out, never crop. In 9:16 keep text inside top 270, right 120, bottom 420 and left 64 px of a 1080 × 1920 frame, type about 1.4× its 16:9 size, captions burned in because feeds autoplay muted. Those are the safe zones (The part of a video frame that the app's own buttons, captions and headers will not cover, where text and key action must stay). ## Who owns what Three build tools appear next to the skill. The split is the same each time: **the tool owns the build; the skill owns register, beats, type cadence and sound.** | Tool | Owns | Where the skill's measured value wins | |---|---|---| | HyperFrames | the build, seam eases and zoom values inside its projects, captions | register, structure, type cadence, sound | | cinetic (Remotion) | scaffold, render, delivery, layout and sync checks | endcard 4.4-6.3 s not 2.2 s; text hold 1.15 s not 0.77 s; crossfades allowed over a shared ground | | scenario-kinetic-film | one-page beat-cut type films, generated music and key art | loudness is a register choice; a 9:16 cut is re-laid out, never the master centred on black | **Inside a HyperFrames project, its seam values win; everywhere, the skill's measured beats and sound win.** **Review a launch-film render (paste into your agent):** ```text Review this render against its own register, at its native frame rate. Recount cuts by eye from a contact sheet around each seam; don't trust a detector count. Go through the 11 rows (register, hook, name, words, UI demo, motion, seams and cuts, endcard, sound sync, level, source) and write one Before | After | Why row per issue. Then check the delivery gates: frame count, H.264 level, size, hardware decode, loudness and -1 dBTP. Make the 9:16 cut as a re-layout inside the feed safe zones. ``` **Check yourself:** Your automatic cut detector reports 6 cuts in a 40-second film. What should you do before comparing it to the register's cut rate? - [ ] Trust it, detectors are exact - [x] Recount by eye on a contact sheet at native frame rate - [ ] Resample the film to 30 fps and run it again - [ ] Average it with the register median *Why:* The detector matched a frame reading in only 9 of 29 and 5 of 18 films; it misses dark, white-on-white and scale cuts and fires on fills. Resampling adds fake frames. ## In the skill - https://school.agents.org.in/skill/launch-video/launch-video-review.md - https://school.agents.org.in/skill/launch-video/launch-video-formats.md - https://school.agents.org.in/skill/launch-video/film-as-function-of-time.md - https://school.agents.org.in/skill/launch-video/hyperframes-reconciliation.md - https://school.agents.org.in/skill/launch-video/cinetic-reconciliation.md - https://school.agents.org.in/skill/launch-video/scenario-kinetic-reconciliation.md --- # Should you draw it? > Decide whether a picture beats a sentence or a table, then pick where the picture should live by who touches it next. Module: Diagrams · Level: beginner · 6 min · https://school.agents.org.in/visual/diagrams/should-you-draw-it Here is the same idea said three ways. Pick a piece of content, then flip between a sentence, a table and a picture. Only one of them is the best fit each time, and it is not always the picture. *[Interactive demo: Three plans want a table. A checkout with a retry loop wants a picture. One relationship wants a sentence.]* A diagram is the most expensive way to say something. It costs layout, labels, a legend and a review. And a wrong one teaches the wrong structure faster than a paragraph ever could, because people trust pictures. So the first question is never "which kind of diagram?". It is **does a reader learn more from a picture than from a paragraph or a table?** ## Picture, table or sentence Most content falls into one of a few shapes. Each shape has a format that suits it. | The content is… | Use | |---|---| | A list of things, or attributes side by side | a table or bullets | | One relationship ("the API calls the queue") | the sentence | | A before and after where only attributes change | a table | | Flow, nesting, order in time, dependency, position on two axes | a diagram | | Live numbers inside your product | a chart component, not a figure | The test is simple. If a three-column table carries the same meaning, the table wins. If a sentence does, the sentence wins. > **In plain words.** A diagram earns its place when the **shape** of the idea is the point: something that loops, branches, nests, or happens in order. If you could read it out as a list without losing anything, it is a list. The trap is "before and after". If a redesign only changes attributes (a new price, a new name), that is a table. If it changes the **topology**, meaning which thing connects to which, that is a diagram. ## Who touches it next? Once you know a picture helps, the next question decides where it lives. A picture has a surface (Where a picture lives: a finished figure, an editable canvas, a Mermaid block in the docs, or FigJam. You pick it by who touches the picture next), and you choose it by asking who will touch it next. **Step: Readers only read it.** A doc, a blog post, a README, a deck, a pull request. Make a finished editorial figure (A finished diagram made for people to read, in a doc, post, README or deck. It is polished once and not edited by hand afterwards): one HTML file with the drawing inside it as SVG. Cathryn Lavery's diagram-design skill draws these. **Step: A team keeps moving boxes.** Planning, whiteboarding, reviewing in comments. Use an editable canvas (An endless editable whiteboard, like tldraw or FigJam, where a team keeps moving boxes and arrows around after the first draft) like tldraw, where arrows stay attached when someone drags a box. **Step: It lives beside the code.** A picture that changes when the code changes. Write it as a Mermaid (A way to write a diagram as short text (A --> B) that a docs site turns into a picture. Good for structure kept next to code; its automatic layout looks generated in a finished figure) block in the Markdown, versioned with the text it explains. **Step: The team lives in Figma.** Use FigJam. Meet people where they already work. One picture, one surface. When a canvas grows up into a published figure, redraw it from its structure. Never paste a screenshot of a whiteboard into a doc and call it the figure. *("Make a diagram" from someone who edits it tomorrow is a canvas job.)* ## Try the whole decision Here is that flow as three questions. Answer them for something you have been meaning to diagram. *[Interactive demo: What it is, who touches it next and how big it is. The answer is a format and a surface, not a style.]* Notice that three of the four first answers end in "don't draw it". That is the honest ratio. Most "can you diagram this?" requests are tables wearing a costume. ## The budget A single figure holds about **9 boxes, 12 arrows and 2 accent colors**. That is the diagram budget (The most one figure should hold: about 9 boxes, 12 arrows and 2 accent colors. Past that, split it into an overview and a detail). Past it, the figure is really two figures: an overview that shows the big parts, and a detail that zooms into one of them. diagram-design aims for a density of about 4 out of 10: complete enough to be correct, sparse enough that nobody needs a guide to read it. A canvas has no hard budget, but if a board needs a legend to find your way around, it needs frames (labelled groups) instead. **Before (avoid):** One architecture figure with 22 boxes, 31 arrows and five highlight colors. Every part is there; nobody can find the path a request takes. **After (do this):** An overview with 6 boxes (the main services), plus one detail figure for the payments service with its 8 parts. Each fits the budget and has one thing to say. ## Ask your agent the right way Agents love to say yes to "diagram this". The skill makes them ask the cheap questions first. You can too, in the prompt. **Decide before drawing (paste into your agent):** ```text Before you draw anything, decide whether this should be a sentence, a table or a diagram, and say why in one line. If it is a diagram, ask me who will touch it next (readers, a team editing it, the code, or Figma) and pick the surface from that. Keep one figure under 9 nodes, 12 connectors and 2 accent colors; if it needs more, propose an overview and a detail instead. ``` Two gotchas to remember. A chart inside a live product is not a figure at all: it is a component with loading, empty and error states. And if the request does not say who edits the picture next, that is a question to ask, not a guess to make. **Check yourself:** A teammate asks for a diagram comparing your three pricing plans on seats, storage and support. What should you make? - [ ] A flowchart from Free to Pro to Team - [x] A table with a column per plan - [ ] An editable tldraw board - [ ] Three boxes with the attributes inside, joined by arrows *Why:* Attributes compared side by side are a table's job. There is no flow between the plans, so arrows would invent a relationship that isn't there. ## In the skill - https://school.agents.org.in/skill/diagram/MOC-diagram.md - https://school.agents.org.in/skill/diagram/diagram-decision.md --- # Drawing the real mechanism > Draw a figure that shows how the thing actually works, with one accent, right-angle connectors, readable labels and an SVG a screen reader can describe. Module: Diagrams · Level: intermediate · 8 min · https://school.agents.org.in/visual/diagrams/drawing-the-mechanism Ask an agent to "diagram how password reset works" and you will often get the vague version. Here is the real one; flip to Vague to compare. *[Interactive demo: Same system. The vague version could describe any app. The real one shows the token, the queue, the async hop and the email that matters.]* The vague one is not wrong, exactly. It is just empty. "Backend" and "Cloud" could be any system on earth, the arrows go every direction, and nothing tells you what happens first. The real one **names the actual parts and shows the order they act in**. That is the whole job of a figure: show the mechanism, so a reader could rebuild it. ## Delete first A designed diagram is mostly deletion. Before you draw, run four tests on your list of parts. **Step: Can a node go?.** Every node (One box (or shape) in a diagram, standing for one distinct thing: a service, a step, a person, a store of data) should be a distinct idea. A "Load balancer" nobody asked about can usually go. **Step: Can two nodes merge?.** If two boxes always travel together, they are one box. **Step: Can an arrow go?.** If the layout already implies it (left to right, top to bottom), the arrow repeats it. **Step: Can a label go?.** If the shape or color already says it, the word is noise. Then hold the budget from the last lesson: about 9 nodes, 12 connectors, 2 accents and 2 callouts. The figure is done when nothing else can be removed. ## One accent, and hierarchy by treatment A focal accent (The one bright color reserved for the one or two things a reader must see first. Everything else stays in quiet grays) is one bright color on one or two elements: the thing the reader must see first. In the password reset figure that is the email worker and the link it sends. An accent on five boxes is no accent at all. Everything else gets a **treatment** instead of a size or a color. Identical boxes erase the hierarchy, so each kind of node looks slightly different: | Kind | Treatment | |---|---| | Focal | accent tint fill, accent stroke | | Service | white fill, ink stroke | | Store (a database, a cache) | ink at 5% | | External (the user, a third party) | ink at 3%, stroke at 30% | | Optional | dashed `4,3` | Use borders, not shadows. Nodes get a corner radius of 6, never a pill and never a soft floating card. A figure is print, so the rules for shadows in a live interface don't apply here. *(Purple glow and rounded-everything is the generated-diagram look.)* ## The six connector rules Connectors (A line or arrow between two boxes that says they are related: one calls, feeds, or leads to the other) are where most figures fail. These six rules come from Cathryn Lavery's diagram-design, and they are what make the right-hand picture look calm. 1. **Orthogonal (Running only across and up or down, turning at right angles, never on a slant. Diagrams with right-angle lines look drawn on purpose) only.** Right-angle elbows rounded at 8px. A straight line only when both ends share an x or a y. 2. **Labels on a mask (A small patch of background color behind a label on a line, so the line stops short of the words instead of running through them).** Each arrow label sits on a patch of paper color, 6 to 10px clear of its line, never on it. 14 characters at most. 3. **No stacked lines.** Parallel routes sit at least 12px apart. Hop at a single crossing. 4. **Own attach points.** Several arrows on one edge spread out evenly, at least 12px apart, instead of meeting at the middle. 5. **Never behind a box.** A line that passes behind a box it doesn't end at gets rerouted. 6. **Arrows before boxes.** Draw lines first, so they sit behind the nodes and no label covers a box. **Before (avoid):** Diagonal lines from center to center. "request" written across the stroke. Three arrows meeting at one point on the API box. A legend floating between nodes. **After (do this):** Right angles. "request" on a paper mask above the line. Three arrows spread along the edge. The legend in a strip under the figure. Strokes are muted gray by default. The headline path gets the accent, and async or return paths are dashed (`5,4`), like the "user clicks" line looping back to the browser. ## Grid, type and legend Put every position, size, gap and padding on a **4px grid**: if it doesn't divide by 4, nudge it. Node names go in a sans font at weight 600. Technical sublabels (ports, URLs, commands) go in mono. Never use mono as a blanket "developer" font for everything. The legend is a horizontal strip **under** the figure, never floating among the nodes. Widen the drawing by about 60px to make room for it. On a phone, try the demo above at a narrow width: it switches to a vertical layout, a redesign rather than a squeeze. If you can't redesign it, keep the SVG at its full width inside a small scrolling wrapper, so the figure scrolls sideways and the page doesn't. ## An SVG a screen reader can describe A figure is an image, so it needs a name. Put `role="img"` on the SVG and point `aria-labelledby` at a `<title>` and `<desc>` (Two tags inside an SVG that name the picture and describe it in one sentence, so a screen reader can say what it shows). ```html <svg viewBox="0 0 710 320" role="img" aria-labelledby="reset-flow-title reset-flow-desc"> <title id="reset-flow-title">How a password reset works

# Design Engineering > A free course for people and agents who build UI with AI. Start from zero, learn the words and the craft, take an exam on your own or with your agent, and get certified. A free course at https://school.agents.org.in, built on the open design-engineering skill (AgentsORG/design-engineering 3.3.1). Every lesson is available as markdown by adding `.md` to its URL. ## For agents - MCP server (streamable HTTP, no auth): https://school.agents.org.in/mcp — tools: list_modules, get_lesson, search_skill, get_skill_install, get_skill_file, list_exams, start_exam, submit_exam, verify_certificate - Install the skill: `npx skills add AgentsORG/design-engineering` (or the Claude Code plugin `design-engineering@agentsorg`) - Exams: call `start_exam` with an exam id (`quiz:`, `exam:`, `final:`) and a candidate, answer, then `submit_exam`. Passing returns a signed certificate URL. - REST mirror: https://school.agents.org.in/openapi.json - Every skill node: https://school.agents.org.in/skill//.md # Welcome > The difference between a screen that works and one that feels right, and how you will learn to see it and get an agent to build it, starting from zero. Module: Start from zero · Level: beginner · 5 min · https://school.agents.org.in/foundations/start/welcome More and more interfaces are built by asking an AI to build them. You describe a screen, an agent (A language model plus a harness: the model decides what to do, the harness gives it tools to read files, write code, run it and check the result) writes the code, and a minute later it runs. That part is solved. What is not solved is the difference between a screen that works and a screen that **feels right**: the button that answers your press, the menu that opens from where you clicked, the error that tells you what to do next. That difference is called design engineering (The craft between design and code: building the details (motion, states, type, color, copy) that make a working interface feel right), and it is what this lesson starts you on. You will learn it twice over: once as a person who can see and name the details, and once as a person who can get an agent to build them. *[Interactive demo: Install the skill once; from then on, your agent reviews UI the way a design engineer would.]* ## Who this is for You do not need to know how to design or how to code. If you have never opened a terminal, the next lessons walk you through it, one click at a time. If you are already a designer or an engineer, skim the first module and start where it gets new. > **In plain words.** An **agent** is an AI that does work on your computer instead of only chatting: it reads files, writes code and runs it. A **skill** is a folder of notes you hand the agent so it knows how *you* want the work done. This course is built on one skill, called design-engineering. ## How the course is laid out The course has four parts. 1. **Start here.** Set up an agent, give it the skill, learn the words designers use and get your first screen reviewed. 2. **The craft.** Motion, color, type, layout, components and the tells of AI-made UI. One discipline per module. 3. **Making things.** Product demos, icons, sound, launch films and diagrams. 4. **Working with agents.** How to brief, review and check what your agent builds, and the toolkit of commands that does it. Every lesson is short. Most have a demo you can watch, a prompt you can copy into your agent, and a question to check yourself. Words that might be new have a dotted underline: hover or tap one, like easing (How speed changes during an animation: start fast and slow down, start slow and speed up, or both. It decides whether motion feels snappy or sluggish), to see what it means in one sentence. ## How to get the most out of it - **Do the prompts.** Reading about a detail teaches you to recognise it. Asking your agent to build it, and seeing it get it wrong, teaches you to direct it. - **Learn the words.** The fastest way to better results from an agent is a more precise word. The [vocabulary](/vocabulary) collects every term in the course. - **Take the quick quiz** at the end of a module, then the exam when you are ready. Pass it and you get a certificate you can share. > **Take the exam with your agent.** Every exam can be taken on your own, or **with your agent**: connect your agent to this course (one command, covered in [Connect your agent](/learn/start/connect-your-agent)) and it sits the exam with you. Since this course is about building with AI, a certificate earned together says something real: you can direct an agent to do this well. ## For agents reading this This page is also written for you. Every lesson is available as markdown (add `.md` to the address), the whole course is at [/llms-full.txt](/llms-full.txt), and the [MCP server](/agents) lets you install the skill, study a topic and sit an exam that grades how you apply it. **Check yourself:** What does this course mean by design engineering? - [ ] Making an interface work at all - [x] The details that make a working interface feel right - [ ] Choosing a color palette - [ ] Writing the backend for a website *Why:* An agent can already make a screen work. Design engineering is the layer on top: motion, states, type, color and copy that make it feel considered. --- # What is design engineering? > Tell vibe coding from design engineering, and know which on-ramp is yours whether you come from design, from code or from neither. Module: Start from zero · Level: beginner · 6 min · https://school.agents.org.in/foundations/start/what-is-design-engineering Two people ask an agent for the same pricing card. Ten minutes later, both have one that works. One of them looks like every other AI-made card on the internet. The other looks like someone cared. The difference was not the agent. It was what each person did before and after the prompt. *[Interactive demo: Same request, two processes. Step through both and compare what comes out.]* ## Vibe coding: prompt, accept, hope Vibe coding (Asking an agent for something, accepting whatever runs and hoping it is good. Fine for throwaways; it ships the agent's average guess) is asking an agent for something, accepting whatever runs, and hoping it is good. It is a fine way to make a throwaway tool on a Saturday. It is a poor way to make something people will use every day. The trouble is that an agent, left alone, builds the *average* of everything it has seen. The average pricing card has a purple gradient, three buttons of equal weight and light gray text nobody can read. None of that is a bug, so nothing tells you it is wrong. ## Design engineering: decide, direct, check Design engineering (The craft between design and code: building the details (motion, states, type, color, copy) that make a working interface feel right) is the craft of building the details that make a working interface feel right: the motion, the states, the type, the color and the words. A design engineer works in the real material (code, in a real browser) rather than in pictures of it, and is judged by how the thing feels in the hand. With an agent, that becomes a loop of three moves: **Step: Decide.** Make the calls an agent cannot make for you. One primary button. Body text dark enough to read. The price is the biggest thing on the card. **Step: Direct.** Hand those decisions to the agent in exact words, with the design-engineering skill (A folder of written instructions an agent loads when a task matches, so it does the work the way you want instead of its default way) loaded so it knows the craft rules too. **Step: Check.** Look at the result. Run a review. Fix what it found, then look again. **The agent does the typing; you own the judgement.** That split is the whole course in one line. **Vibe coding (avoid):** "Make me a nice pricing card." Accept it. Ship it. Find out from users that the gray text is unreadable on their phone. **Design engineering (do this):** "Pricing card: price at 40px, one dark primary button, a quiet text link for the second action, body text at 4.5:1 contrast." Then `/design-engineering review` and a look at the screen. ## What a design engineer actually does The job sits in the gap between a design and a shipped product. A designer draws what the screen should look like; an engineer makes it work; and somewhere in between, a hundred small things get decided by nobody. How long the menu takes to open. What happens when the list is empty. Whether the button shows it was pressed. A design engineer decides those things on purpose. Some days that means prototyping an interaction to see if it feels right before anyone writes a spec. Some days it means building the components a whole team uses. Increasingly, it means steering an agent through all of that. > **In plain words.** Designers ask "what should this look like?" Engineers ask "how does this work?" Design engineers ask "how does this **feel** to use, and what exactly would make it feel better?" ## Pick your on-ramp You do not need to be both a designer and an engineer to start. You need to be curious about the gap. Where you begin depends on where you come from. **From design:** You already have the eye: you see when spacing is off or a color is muddy. What is new is the material. Learn to read the code an agent writes well enough to spot a problem, and learn to judge a design **in the browser**, moving, at real sizes, not in a static mockup. Start with [Set up your agent](/learn/start/set-up-your-agent), then the Motion module: motion is the part a static design tool never shows you. **From code:** You already have the material: you can build anything. What is new is the eye. Learn the names for what you are looking at ([words matter](/learn/start/words-matter)), and train yourself to notice the details you used to skip: the hover state, the empty state, the 4px that makes two things look grouped. Start with [How good interfaces think](/learn/philosophy/taste-is-trained), then the craft modules in order. **From neither:** Good news: you skip the habits the others have to unlearn. Go in order. Set up an agent, learn the words, and get your first screen reviewed. Every lesson assumes nothing. Start with [What is an agent?](/learn/start/what-is-an-agent) *(Your agent can already write code. What it cannot do is want something. That part is you.)* ## The prompt that starts the habit Before you ask for any new screen, ask the agent to slow down and make you decide. It is the single cheapest habit in this course. **Make me decide first (paste into your agent):** ```text Before you build this, ask me up to five questions about what matters most on this screen: the one action people should take, what they need to read first, and what states it can be in (empty, loading, error). Then build it with the design-engineering skill and show me a review table of anything you were unsure about. ``` **Check yourself:** A friend asks an agent for a sign-up form, it runs, and they ship it without looking closely. What were they doing? - [ ] Design engineering, because it works - [x] Vibe coding: prompt, accept, hope - [ ] Directing the agent - [ ] Checking the result *Why:* Working is the starting line, not the finish. Without deciding what matters and checking the result, they shipped the agent's average guess. ## In the skill - https://school.agents.org.in/skill/meta/directing-agents.md - https://school.agents.org.in/skill/philosophy/feeling-right.md --- # What is an agent? > Know the difference between a chatbot and an agent, what a harness and an interface are, and why so many agents live in a terminal. Module: Start from zero · Level: beginner · 7 min · https://school.agents.org.in/foundations/start/what-is-an-agent Ask a chatbot to add a dark mode switch to your app, and it writes you a nice answer with some code to paste. Ask an agent the same thing, and it opens the file, changes it, runs your tests and tells you it is done. Same words in. One gives you homework; the other does the work. *[Interactive demo: The same request to a chatbot and to an agent. One explains, the other edits the file and runs it.]* ## A model only writes text Under every chatbot and every agent is a large language model (The AI itself, like Claude or GPT. On its own it only reads text and writes text; it cannot open files or run anything) (an LLM): the AI itself, like Claude or GPT. On its own, a model can do exactly one thing. It reads text and writes more text. It cannot open a file. It cannot run a command. It cannot see your screen. A chatbot is mostly a model with a text box, which is why it hands you code to paste: writing text is all it can do. ## A harness gives it hands So how does an agent edit files? Theo Browne explains it well in [What is a harness?](https://x.com/theo/article/2113424203345265053): the model is wrapped in a layer of ordinary code called a harness (The hidden layer of ordinary code around a model: it lists the tools, notices when the model asks for one, runs it and sends the result back. Model + harness = agent). The harness does four jobs: **Step: It lists the tools.** It tells the model which tools (One thing a harness can do for the model, like read_file, edit_file, run a command or search. Most run on your computer; an MCP server's tools run somewhere else) exist, such as `read_file`, `edit_file`, `bash` (run a command) and `search`, and the text format for asking to use one. **Step: It watches the model's text.** When the model writes something like `read_file("src/Settings.tsx")`, the harness notices that this is a request, not a sentence. **Step: It runs the tool.** The harness, not the model, actually opens the file or runs the command on your computer. **Step: It sends the result back.** The file's contents go back to the model, which reads them and writes its next step. Round and round until the job is done. **An agent is a model plus a harness.** The model decides; the harness does. *[Interactive demo: Step through one request. It goes down to the model, out to a tool, and back up to you.]* ## The interface is what you see There is one more layer, the one you actually look at: the interface (The screen you see and type into: the claude screen in a terminal, Cursor's window, a desktop app. Not the same as the harness behind it). It is the screen where you type and read answers. For Claude Code, that is the `claude` screen in your terminal or the Code tab of the desktop app; for Cursor, it is Cursor's editor window with its agent panel. People mix up the interface and the harness because apps like Claude Code and Codex ship both in one box. But they are different things. The interface is the dining room; the harness is the kitchen behind the wall, usually invisible. > **The kitchen picture.** The model is the **chef**: it knows how to cook but has no hands of its own here. The harness is the **kitchen**: the counters, the stove, the staff who fetch things. The tools are the **pots and knives**. You are the diner, and the interface is the dining room where you order and get your plate. ## Tools here, and tools over there Most tools run right on your computer: read this file, run that command. An MCP (Model Context Protocol: a standard way for an agent to use tools that live somewhere else, by sending a request to a server, like this course's exam server) server is a tool that lives somewhere else. Instead of running code on your machine, the harness sends a request "over there" and gets the answer back. Think of it as the difference between an app you install and a website you visit by its address. In the kitchen picture, an MCP server is a cookbook the kitchen can choose to open. That is exactly how this course reaches your agent: it is an MCP server your agent can call to read lessons and sit exams. You will connect it in [Connect your agent](/learn/start/connect-your-agent). ## Which harness? Several apps bundle a harness with an interface. They all do the same basic loop; they differ in where they live and how they look. | App | Where it lives | Good first pick if… | |---|---|---| | Claude Code | Your terminal, plus a desktop app | You want the agent this course is tested with most | | Cursor | A code editor (an app with windows and files) | You would rather click than type commands | | Codex | Your terminal | You already use OpenAI's tools | | VS Code | A code editor, with an agent panel | You already have VS Code open all day | All of them can load the design-engineering skill and connect to this course. Pick one; you can switch later. ## What is a terminal? Many agents live in a terminal (A window where you type commands to your computer instead of clicking. Many agents live in one): a plain window where you type commands to your computer instead of clicking. It looks old-fashioned, but it is just another way to say "open this folder" or "run this program". **Clicking (avoid):** Open Finder or File Explorer, find Documents, make a new folder, name it `my-app`, double-click into it. **Typing in a terminal (do this):** ``` mkdir my-app && cd my-app ``` Same result, one line. And an agent can type it for you. That last part is the point. Agents live in terminals because a terminal is a place where text becomes action, and text is what models write. *(You do not need to learn terminal commands. You need to know how to open one and paste a line into it.)* **Ask your agent to show its work (paste into your agent):** ```text Before you change anything, tell me which files you will read, which you will edit and which commands you will run. Then do it, and list each tool call as you make it. ``` **Check yourself:** What turns a language model into an agent that can edit your files? - [ ] A bigger model - [x] A harness that gives it tools, runs them and sends the results back - [ ] A nicer chat window - [ ] Typing your request in a terminal *Why:* A model only writes text. The harness lists tools, notices when the model asks for one, runs it on your computer and returns the result. Agent = model + harness. ## In the skill - https://school.agents.org.in/skill/meta/directing-agents.md --- # Set up your agent > Go from nothing installed to an agent building your first screen, on a Mac or on Windows, in about fifteen minutes. Module: Start from zero · Level: beginner · 8 min · https://school.agents.org.in/foundations/start/set-up-your-agent By the end of this page you will have typed one sentence and watched an agent make a web page from it. Here is where you are heading: *[Interactive demo: An empty folder, one sentence, a first screen.]* Four steps get you there: open a terminal, install Node.js, install an agent, and ask it for something. Each one is a few clicks or one pasted line. ## 1. Open a terminal A terminal (A window where you type commands to your computer instead of clicking. Many agents live in one) is the window where you type commands. Every computer already has one. **Mac:** Press Cmd + Space, type **Terminal** and press Enter. A window opens with a line ending in `%` or `$`. That line is the prompt: it is waiting for you to type. **Windows:** Press the Windows key, type **Terminal** and press Enter. (On older Windows, type **PowerShell** instead.) A window opens with a line ending in `>`. That is the prompt, waiting for you. To run a command, paste it after the prompt and press Enter. To paste in a terminal, use Cmd + V on a Mac, or right-click (or Ctrl + V) on Windows. ## 2. Install Node.js Node.js (A free program that lets your computer run JavaScript tools. Installing it also gives you npm, which installs agents like Claude Code and Codex) lets your computer run JavaScript tools, and it comes with npm (The tool that comes with Node.js for installing JavaScript packages. npx runs a package once without installing it for good), the tool that installs them. Claude Code and Codex are installed with npm, and most web projects need Node anyway. **Step: Download it.** Go to [nodejs.org](https://nodejs.org) and download the version marked **LTS** (long-term support, the steady one). **Step: Install it.** Open the file you downloaded and click through the installer with the default choices. **Step: Check it worked.** Close your terminal, open a new one, and run the line below. You should see a version number like `v22.x.x`. ```bash node -v ``` > **If it says “command not found”.** The terminal you had open started before Node existed. Close it completely and open a fresh one. That fixes it nine times out of ten. ## 3. Install an agent Pick one. They all work with this course; you can try another later. **Claude Code:** Install it, then start it: ```bash npm install -g @anthropic-ai/claude-code ``` ```bash claude ``` The first time, it opens your browser to sign in. **You need a Claude account with a paid plan (Pro or Max) or Anthropic API credit.** On Windows, Claude Code also needs [Git for Windows](https://git-scm.com/downloads/win) installed; it will tell you if it is missing. **Cursor:** Cursor is an app, not a command. 1. Download it from [cursor.com](https://cursor.com) and install it like any app. 2. Sign in. **Cursor needs a free account**; heavy use needs a paid plan. 3. Choose **File → Open Folder** and pick a folder (make one first, below). 4. Open the agent panel with Cmd + L on a Mac or Ctrl + L on Windows, and make sure it is set to **Agent**. **Codex:** Install it, then start it: ```bash npm install -g @openai/codex ``` ```bash codex ``` The first time, it asks you to sign in. **You need a ChatGPT account on a paid plan, or an OpenAI API key.** Windows support is newer; if it gives you trouble, OpenAI's docs suggest running it inside WSL (Linux on Windows). **VS Code:** 1. Download [VS Code](https://code.visualstudio.com) and install it. 2. Choose **File → Open Folder** and pick a folder (make one first, below). 3. Open the Chat view from the title bar and switch it to **Agent** mode. 4. Sign in with GitHub when asked. **Agent mode uses GitHub Copilot, which has a free plan.** *(Every one of these needs an account. That is the price of the model, not of this course, which is free.)* ## 4. Make a project folder An agent works inside one folder at a time, and it can change anything in it. So give it a fresh, empty folder of its own. In your terminal: ```bash mkdir my-first-app ``` ```bash cd my-first-app ``` `mkdir` makes a directory (a folder); `cd` changes into it. Now start your agent here (`claude` or `codex`), or open this folder in Cursor or VS Code. ## 5. Ask for your first screen Type a plain sentence. Be specific about what is on the screen and keep it small. **Your first screen (paste into your agent):** ```text Make a sign-up screen in one file, index.html: a heading, one line of text under it, an email field and one button. Plain HTML and CSS, no frameworks. Then tell me how to open it. ``` The agent will ask permission before it writes the file or runs anything. Read what it wants to do and say yes. When it is done, open `index.html` in your browser (double-click it in your file manager, or ask the agent to open it). **Too vague (avoid):** "Make me a website." The agent has to guess everything, so it guesses the average: a hero, three cards, a footer. **Small and specific (do this):** "A sign-up screen: heading, one line, email field, one button, in index.html." You can check every part of the answer at a glance. It will look plain, maybe a little generic. That is fine: in [Your first review](/learn/start/your-first-review) you will make it better, with the skill doing half the work. **Check yourself:** Why should you start your agent inside a new, empty folder? - [ ] It runs faster there - [x] An agent can change anything in the folder it is in, so give it one of its own - [ ] Agents cannot open folders that have files - [ ] npm needs an empty folder *Why:* The agent can read, edit and delete files in its folder. A fresh project folder keeps its work contained and easy to see. ## In the skill - https://school.agents.org.in/skill/meta/directing-agents.md --- # What is a skill? > Understand what a skill is, how an agent decides to load one, and how design-engineering routes every request through one entry point to the right note. Module: Start from zero · Level: beginner · 6 min · https://school.agents.org.in/foundations/start/what-is-a-skill Tell your agent "this dropdown feels slow" and, with the design-engineering skill installed, it does not guess. It opens a note about easing curves, reads that a menu should take about 200ms with a strong ease-out, and fixes it to that. Try a few requests and watch where each one lands: *[Interactive demo: Every request goes in through one door and lands on the note that owns it.]* ## A folder of notes A skill (A folder of written instructions an agent loads when a task matches, so it does the work the way you want instead of its default way) is a folder of plain text files written for an agent. At the top sits one file, `SKILL.md`, with a short description of when the skill applies. Beside it are the notes themselves. That is all it is. No code to run, no magic. Just instructions, written down once, so the agent does the work the way an expert would instead of the way the average of the internet would. ``` design-engineering/ SKILL.md ← "load me when reviewing UI, picking easing…" references/ motion/easing-curves.md motion/duration-table.md surface/contrast-and-color-scheme.md … about 200 more ``` ## How the agent knows when to load it Your agent reads only the short description of every installed skill at first. When your request matches one ("review this card", "why does this feel off"), it opens that skill's `SKILL.md`. From there it follows links to the one or two notes the job needs, and ignores the rest. > **In plain words.** A skill is like a shelf of recipe cards. The agent reads the labels on the spines all the time, but only pulls out a card when you ask for that dish, and only reads the cards that recipe needs. This matters because an agent can only hold so much in mind at once. Loading two notes about motion beats loading two hundred notes about everything. ## One skill, one door design-engineering is a single skill with a single entry point. Whatever you want, you start the same way: ```bash /design-engineering [verb] [target] ``` The slash command (A command you type into an agent starting with /, like /design-engineering. It runs a skill or a built-in action instead of being read as a normal message) `/design-engineering` opens the skill. What you type after it decides where it goes: **Step: A verb.** If the first word is a verb (The first word after /design-engineering, like review, polish or motion. It picks which procedure the skill follows) like `review`, `polish`, `motion` or `tells`, the agent opens that command and follows it step by step. `/design-engineering review src/PricingCard.tsx` reviews that file. **Step: A plain request.** If you just describe the problem, a router note reads it, decides which part of the craft owns it, and hands off. `/design-engineering why does this card feel flat`. **Step: Nothing at all.** On its own, `/design-engineering` shows a menu of verbs, leading with the two or three that fit what you are doing. It never runs one without asking. ## Thirteen clusters, two hundred notes Behind the door, the notes are grouped into 13 clusters (A group of related notes in the design-engineering skill, one per part of the craft: motion, typography, layout and so on. There are 13), one per part of the craft: philosophy, motion, surface (color and depth), typography, layout, components, anti-patterns (the tells of AI-made UI), faux UI, SVG, sound, launch video, diagrams, and meta (how to review and direct). Each note is a node (One note inside a skill: one idea with exact values and links to related notes, like "never scale from zero"): one idea, a few hundred words, with exact values and links to related nodes. "Never scale from zero" is a node. "The duration table" is a node. **The modules of this course follow the same clusters**, so what you learn here is exactly what your agent reads. **Agent without the skill (avoid):** "The dropdown feels slow." It tries `transition: all 0.5s ease-in-out`, because that is common. Now it feels slower. **Agent with the skill (do this):** Routes to `motion/easing-curves`. Sets `transform` and `opacity` only, 200ms, `cubic-bezier(0.23, 1, 0.32, 1)`, origin at the button. Tells you why. *(Most of the time you will not type a verb at all. Describe the problem in plain words; the router is there for that.)* ## Your own taste, on top Two files in the skill are meant for you to edit: `pov.md`, where you write opinions that override the skill's defaults, and `gotchas.md`, where you jot down mistakes the agent made so it never makes them again. You will not need them on day one. Just know the skill is a starting point you can make your own. **See the router think (paste into your agent):** ```text /design-engineering which: I want the settings page to feel less cramped. Tell me which cluster and which node own this, and why, before you change anything. ``` **Check yourself:** You type /design-engineering with nothing after it. What happens? - [ ] It reviews every file in the project - [x] It shows a menu of verbs, leading with the ones that fit, and waits - [ ] It installs the skill again - [ ] Nothing; you must always give a verb *Why:* With no arguments and no request on the table, the skill shows its verb menu and waits for you to pick. It never auto-runs a verb. ## In the skill - https://school.agents.org.in/skill/meta/skill-router.md - https://school.agents.org.in/skill/meta/routing-table.md --- # Install design-engineering > Install the skill one way (skills.sh or the Claude Code plugin), check that it loaded, and use its menu. Module: Start from zero · Level: beginner · 5 min · https://school.agents.org.in/foundations/start/install-design-engineering Once the skill is in, one line brings up its menu. If you see this, everything worked: *[Interactive demo: Type the entry point with nothing after it: the menu comes back, leading with what fits right now.]* There are two ways to get there. **Pick one.** Both install the same skill; they differ in how you call it afterwards. ## Way 1: skills.sh (any agent) skills.sh (An installer that copies a skill into the place your agents look for it (Claude Code, Cursor, Codex and others), with one npx command) is an installer that puts a skill where your agent looks for it: Claude Code, Cursor, Codex and many more. Run this in your terminal, inside your project folder: ```bash npx skills add AgentsORG/design-engineering ``` `npx` runs a tool from npm without installing it for good, so you need [Node.js](/learn/start/set-up-your-agent) for this. The installer asks which agents to link the skill into; pick the one you use. Afterwards, you call it as: ```bash /design-engineering ``` ## Way 2: the Claude Code plugin If you use Claude Code, you can install it as a plugin (A package that adds skills, commands or helpers to a harness in one install. design-engineering ships as a Claude Code plugin and as a plain skill) instead. A plugin can bring extra helpers along with the skill, such as specialist reviewers for motion or accessibility. These two lines go **inside Claude Code** (after you have run `claude`), not in a plain terminal: ```bash /plugin marketplace add AgentsORG/design-engineering ``` ```bash /plugin install design-engineering@agentsorg ``` The first line adds the marketplace (A published list of plugins you add to Claude Code once, so you can install plugins from it by name) (a list of plugins someone publishes); the second installs this plugin from it. Plugins name their commands after themselves, so afterwards you call it as: ```bash /design-engineering:design-engineering ``` **Both ways at once (avoid):** Two copies of the skill. Your agent sees two that match every design request, loads both, and may follow two slightly different versions. Confusing and wasteful. **One way (do this):** One copy, one entry point. If you switch, remove the old one first: `npx skills remove design-engineering`, or `/plugin uninstall design-engineering@agentsorg` in Claude Code. > **Which should I pick?.** Using Claude Code? The plugin is the fuller install. Using Cursor, Codex or several agents? skills.sh. Not sure? skills.sh works everywhere. ## Check that it loaded Start a fresh agent session (skills are read when a session starts, so restart after installing). Then type the entry point with nothing after it: **Claude Code:** Type `/design-engineering` (skills.sh) or `/design-engineering:design-engineering` (plugin). As you type the slash, it should appear in the list of commands. Press Enter and the menu comes back. **Cursor:** In the agent panel, type `/design-engineering` and send it. If the menu of verbs comes back, it loaded. If not, check that you picked Cursor when skills.sh asked which agents to link. **Codex:** Type `/design-engineering` and send it, or just ask "Use the design-engineering skill: show me its menu." The verbs should come back. **VS Code:** In Agent mode, type `/design-engineering` or ask "Use the design-engineering skill: show me its menu." The verbs should come back. If the agent answers with a general reply about design instead of the menu, the skill did not load. Restart the session; if that does not help, run the install again and read what it prints. ## The no-argument menu The menu is your map. It lists every verb with a one-line job, and it puts the two or three that fit first: an unfinished change in your project suggests `review`, a `.design` file suggests `tokens`, a video file suggests `film review`. | Verb | What it does | |---|---| | `review` | Reviews UI code as a Before / After / Why table | | `polish` | For screens that work but feel unfinished | | `motion` | Should it move? Then the timing, easing and springs | | `tells` | Lists what makes a screen look AI-made, to delete | | `a11y` | An accessibility audit with evidence | | `ship` | A whole-app pass before launch | **It never runs a verb on its own.** It shows the menu and waits for you to pick, or to describe the job in plain words. *(Remember which way you installed. Every prompt in this course says `/design-engineering`; with the plugin, read it as `/design-engineering:design-engineering`.)* **Confirm the install (paste into your agent):** ```text Is the design-engineering skill loaded? If it is, show me its menu with no verb and tell me which two verbs fit this project right now. If it is not, tell me exactly what you see instead. ``` **Check yourself:** You installed the skill with skills.sh, then also installed the Claude Code plugin. What should you do? - [ ] Nothing, two copies are more thorough - [x] Remove one, so the agent loads a single copy - [ ] Delete Node.js - [ ] Rename one of them *Why:* Install one way only. Two copies both match every design request, so the agent may load both and follow two versions. ## In the skill - https://school.agents.org.in/skill/commands/MOC-commands.md - https://school.agents.org.in/skill/meta/skill-router.md --- # Connect your agent > Connect this course's MCP server to your agent so it can study lessons and sit exams, alone or with you as a pair. Module: Start from zero · Level: beginner · 6 min · https://school.agents.org.in/foundations/start/connect-your-agent This course is also a server your agent can talk to. Connect it once, and your agent can read any lesson, install the skill and sit an exam, with you watching every answer before it is handed in: *[Interactive demo: An exam taken as a pair: the agent answers, shows you its work, and submits only when you say yes.]* ## What you are connecting In [What is an agent?](/learn/start/what-is-an-agent) you met tools (One thing a harness can do for the model, like read_file, edit_file, run a command or search. Most run on your computer; an MCP server's tools run somewhere else): things the harness can do on your computer. An MCP (Model Context Protocol: a standard way for an agent to use tools that live somewhere else, by sending a request to a server, like this course's exam server) server is a set of tools that live somewhere else. This course is one, at this address: ```bash https://school.agents.org.in/mcp ``` Once connected, your agent gets eight new tools: | Tool | What it does | |---|---| | `list_modules` | Lists every module and lesson | | `get_lesson` | Reads one lesson | | `get_skill_install` | Says how to install the skill in this agent | | `get_skill_file` | Reads one note from the skill | | `list_exams` | Lists every quiz and exam | | `start_exam` | Starts a sitting and returns the questions | | `submit_exam` | Hands in the answers and gets the grade | | `verify_certificate` | Checks a certificate is real | ## Connect it One command or one small file, depending on your agent. **Claude Code:** Run this in your terminal (not inside Claude Code): ```bash claude mcp add --transport http design-course https://school.agents.org.in/mcp ``` Then start `claude` again and type `/mcp`: `design-course` should be listed as connected. **Cursor:** In your project folder, make a folder called `.cursor` and a file inside it called `mcp.json` with exactly this: ```json {"mcpServers":{"design-course":{"url":"https://school.agents.org.in/mcp"}}} ``` Then open **Cursor Settings → MCP**: `design-course` should be listed with a green dot. **Codex:** Run this in your terminal: ```bash codex mcp add design-course --url https://school.agents.org.in/mcp ``` Then start `codex` again; `/mcp` lists the servers it can see. **VS Code:** In your project folder, make a folder called `.vscode` and a file inside it called `mcp.json` with exactly this: ```json {"servers":{"design-course":{"type":"http","url":"https://school.agents.org.in/mcp"}}} ``` VS Code shows a small **Start** button above the server in that file. Press it, then use Agent mode. > **Check it worked.** Ask your agent: "Use the design-course MCP server and list its modules." If it replies with the course's modules, you are connected. ## Two ways to sit an exam Every exam has multiple-choice questions and **practical tasks**: small pieces of code to fix, which are checked automatically. You can sit it two ways. **The agent alone (avoid):** Your agent sits the exam by itself and earns a certificate in its own name, with its harness and model printed on it. Useful for testing how well an agent applies the skill. **You with your agent (do this):** A **pair** certificate, in your name. The agent answers, but shows you its practical answers before it submits, and you decide. This one says you can direct an agent to do the work well. **The pair certificate is the one this course is really about.** Building UI with AI is a team of two; the exam should be too. ## The prompt to paste Pick an exam (each module has one, like `exam-motion`, and there is a final exam across everything). Then paste this into your agent, with your own name: **Take an exam as a pair (paste into your agent):** ```text Use the design-course MCP server. Take the exam \`exam-motion\` as a pair for : install the skill first, answer each question yourself, show me your practical answers before you submit, then give me the certificate link. ``` Here is what happens next: **Step: It installs the skill.** The agent calls `get_skill_install` and sets up design-engineering, because the practical tasks test whether it applies the skill. **Step: It starts the exam.** `start_exam` returns the questions. The answers never leave the server. **Step: It shows you its work.** Before it submits, it shows its practical answers. Read them. If one looks wrong, say so; that is your half of the pair. **Step: It submits and gets the grade.** `submit_exam` grades everything at once and, if you passed, returns a certificate link you can share. *(Say no if an answer looks wrong. A pair that never pushes back is just the agent alone with your name on it.)* ## Just studying You do not have to sit an exam to use the server. It is a good study partner too: **Study with the course (paste into your agent):** ```text Use the design-course MCP server. Read the lesson on easing curves, then quiz me with three questions from it, one at a time, and explain anything I get wrong. ``` **Check yourself:** What makes a pair certificate different from an agent-alone one? - [ ] It has more questions - [x] The agent shows you its practical answers before submitting, and the certificate is in your name - [ ] You answer without the agent - [ ] It does not need the skill installed *Why:* In a pair, the agent does the answering but you review its work before it is handed in, so the certificate shows you can direct an agent. --- # Words matter > Learn why the exact word you use changes what an agent builds, and how to turn "make it pop" into a request it can get right. Module: Start from zero · Level: beginner · 6 min · https://school.agents.org.in/foundations/start/words-matter Here is a small dialog and four ways to ask an agent to improve it. Tap each one and watch what the agent does with your words: *[Interactive demo: The vaguer the words, the more the agent guesses. Its guess is the average of everything it has seen.]* "Make it pop" got a gradient, a glow and a button that grew. The agent did exactly what you asked. The problem is you did not ask for anything in particular, so it filled the gap with the most common idea of "pop" it knows. ## Vague words get average results An agent cannot see what you see. When you say "make it pop", it has to guess what "it" is and what "pop" means, and its best guess is the middle of everything it was trained on. That middle has a name in this course: AI-default UI. The fix is not a longer prompt. It is a **more exact** one. **A wish (avoid):** "Make the button pop." **A spec (do this):** "Raise the contrast of the primary button's text to 4.5:1. Keep the secondary button quiet." The second one names *which* element, *what* property and *how much*. There is nothing left to guess, so there is nothing to get wrong. ## What design vocabulary is Design vocabulary (The exact names for how interfaces look and move, like tracking, easing or hierarchy. The right word gets you the right result from an agent) is the set of exact names for how interfaces look and move. Designers use these words to talk to each other quickly; you can use them to talk to an agent precisely. A few you will meet soon: | You might say | The exact word | What it means | |---|---|---| | "the text is hard to read" | contrast ratio (How different the text color is from its background, as a number like 4.5:1. Body text needs at least 4.5:1 to be readable for most people; large text 3:1) | How much darker the text is than its background. 4.5:1 is the minimum for body text. | | "the letters are squished" | tracking | The space between all the letters in a line | | "the menu feels slow" | easing (How speed changes during an animation: start fast and slow down, start slow and speed up, or both. It decides whether motion feels snappy or sluggish) | How speed changes during an animation: fast start, gentle stop | | "the numbers jump around" | tabular figures | Digits that are all the same width, so columns line up | | "the main button" | primary action (The one thing you most want people to do on a screen, usually the one filled, strongest button. A screen should have one) | The one thing you most want people to do on this screen | You do not need to memorise them. You need to know they exist, so that when something feels off you can look up its name. The [vocabulary page](/vocabulary) collects every term in this course, each with a phrase you can hand an agent. > **In plain words.** "It feels off" is a feeling. "The line height is too tight" is a fix. The gap between them is not talent, it is knowing the word. ## Point, don't describe Sometimes the best word is no word at all. Telling an agent "the blue button in the sidebar" sends it searching through your files. Showing it the exact thing sends it straight there. **Step: Name the file.** "In src/components/PlanCard.tsx…" beats "on the pricing page". **Step: Show a picture.** A screenshot with a circle around the problem beats a paragraph describing it. **Step: Link a reference.** "Make the hover like Linear's sidebar" beats five adjectives. **Point at the exact thing, then name exactly what is wrong with it.** The [philosophy module](/learn/philosophy/say-it-precisely) goes deeper, including tools that let you click an element and hand the agent its exact address. ## The precise version is often plainer Precision is not jargon. "The button has no hover state" is precise and plain. "The affordance lacks an interactive feedback layer" is just harder to read. Use the shortest words that leave nothing to guess. *(When you are stuck for the word, ask the agent: "what is it called when…". The skill has a verb for exactly that.)* **Find the word (paste into your agent):** ```text /design-engineering name: the numbers in my pricing table shift sideways when they change. What is this called, and what is the exact CSS fix? ``` And when you know what you want, say it like a spec: **A precise request (paste into your agent):** ```text On the upgrade dialog, make the primary button's text contrast at least 4.5:1 against its background, keep "Not now" as a quiet text button, and change nothing else. Tell me the contrast ratio before and after. ``` **Check yourself:** Which request will an agent most reliably get right? - [ ] Make the card look more premium - [ ] Make it pop - [x] Raise the card title to 20px semibold and the body text contrast to 4.5:1 - [ ] Make it look like a real designer made it *Why:* It names the element, the property and the amount. The others are wishes, so the agent fills them with its average guess. ## In the skill - https://school.agents.org.in/skill/meta/design-vocabulary.md - https://school.agents.org.in/skill/philosophy/articulate-precisely.md --- # Your first review > Ask an agent for a pricing card, review it with the skill, read the Before / After / Why table and apply the fixes. Module: Start from zero · Level: beginner · 8 min · https://school.agents.org.in/foundations/start/your-first-review This is the loop you will use for the rest of the course: build, review, fix, look. Here is the pricing card an agent made on its first try, and the review the skill wrote for it. Apply the fixes one at a time and watch the card change: *[Interactive demo: Each row of the review is one change. Apply them one by one, then press the buttons to feel row 4.]* Every row was small. Together they turn a card that looks generated into one that looks considered. Now do it yourself, in your own project. ## 1. Ask for a pricing card In your project folder, with your agent running, ask for something small enough to check at a glance: **Build the card (paste into your agent):** ```text Make a pricing card component for a "Pro" plan at $24/month: the plan name, the price, three features and two buttons, "Start free trial" and "Compare plans". Put it on a page I can open in the browser. Don't use the design-engineering skill yet. ``` The last line is on purpose. You want to see the agent's default first, so you can see what the review changes. Open the page and take a screenshot. You will want it later. ## 2. Run the review Now ask the skill to review what it made. Give it the file it just wrote: ```bash /design-engineering review src/PricingCard.tsx ``` (Use whatever file name the agent created. With the plugin install, type `/design-engineering:design-engineering review …`.) The `review` verb (The first word after /design-engineering, like review, polish or motion. It picks which procedure the skill follows) reads the code against a checklist of a few dozen common mistakes: animating everything, gray text that fails contrast, missing focus styles, buttons that do not respond to a press. It does not change anything yet. It reports. ## 3. Read the table The review always comes back in the same shape: a Before / After / Why (The table a design-engineering review comes back in: the exact line, its replacement, and one sentence of reason. One problem per row) table. One row per problem. | Before | After | Why | |---|---|---| | `color: #9ca3af` | `color: oklch(0.45 0 0)` | Body text was 2.5:1 contrast; now about 7:1 | | `transition: all 300ms` | `transition: transform 160ms` | Animate only what moves | | `outline: none` | a 2px `:focus-visible` ring | Keyboard users can see where they are | Each column has a job: **Step: Before.** The exact line from your code, quoted. So you can find it. **Step: After.** The replacement. Same job, better result. **Step: Why.** One sentence of reason. If the agent cannot say why in a sentence, the change is probably not worth making. **Read the Why column first.** It is where you learn. After a few reviews you will start spotting these problems before the agent does. > **You can disagree.** A review is advice, not orders. If a row is wrong for your design ("no, I want the price small, it is a quiet page"), say so. If you disagree with the skill often in the same way, write it in `pov.md` and it will stop suggesting it. ## 4. Apply the fixes Once you have read the table, ask the agent to apply it: **Apply the review (paste into your agent):** ```text Apply every row of that review table except any you think is wrong for this card; tell me which you skipped and why. Then show me the page again. ``` Reviews only report; you decide what changes. That is on purpose: the skill keeps "judge" verbs like `review` separate from "do" verbs like `polish`, so nothing is changed behind your back. ## 5. Compare before and after Open the page again and put it next to your screenshot from step 1. Look for: **Before (typical) (avoid):** Light gray text that is hard to read. A small price. Three buttons fighting for attention. Nothing happens when you press a button. No visible focus when you press Tab. **After (do this):** Text you can read. The price is the first thing you see. One obvious button. Buttons that dip slightly when pressed. A clear ring when you Tab through. Try the keyboard too: press Tab to move between the buttons. If you cannot see where you are, the focus row was skipped. *(Look at the screen, not just the table. A review that reads well and looks wrong is still wrong.)* ## The loop That is it: build, review, apply, look. It works on any screen, and the next modules teach you what each row in a review means, so you can direct the fixes yourself instead of only accepting them. **Check yourself:** In a Before / After / Why review, why does every row need a Why? - [ ] To make the table longer - [x] So you can judge whether the change is right, and learn the rule for next time - [ ] Because the agent cannot apply a fix without it - [ ] To link to the documentation *Why:* The Why is what lets you accept, reject or learn from a change. A change nobody can explain in a sentence is usually not worth making. ## In the skill - https://school.agents.org.in/skill/commands/cmd-review.md - https://school.agents.org.in/skill/meta/review-format.md - https://school.agents.org.in/skill/meta/review-checklist.md --- # Taste is trained > See why the details nobody notices decide whether people trust a product, and how to build the taste to spot them. Module: How good interfaces think · Level: beginner · 7 min · https://school.agents.org.in/design/philosophy/taste-is-trained Here is a small receipt card with six details switched on. Switch them off one at a time: each one alone is almost invisible. Then press All off, and All on again: *[Interactive demo: Six details nobody would name. Together they are the difference between fine and nice.]* Nobody using this card would say "lovely tabular figures". They would say "this feels nice", or nothing at all, and keep using it. That is the whole idea of this module. ## Unseen details compound Paul Graham made the point first and Emil Kowalski sharpened it for interfaces: **the details people consciously notice are mostly noise; the ones they don't notice are what earn their trust.** Each invisible detail does one of two things. It removes a tiny bit of friction (the amounts line up, so you compare them without effort), or it signals that someone cared (the button answers your press). People cannot point at either. They just feel the product is considered. **Details nobody tuned (avoid):** Text in pure `#000`. One heavy gray shadow. Amounts that wobble because every digit is a different width. A button that does nothing when pressed. **Details someone tuned (do this):** Text in a deep gray. Three soft shadow layers at 4 to 8% opacity. `font-variant-numeric: tabular-nums`. `transform: scale(0.97)` on press, 160ms. Twenty of these and a product stops feeling generated. That is why the skill exists: to write the unseen details down so an agent applies them every time. > **Know when to stop.** Detail work can turn into procrastination. Three days on the loading spinner of a page people see once a quarter is not craft; it is avoidance. Spend detail time where people spend their time. ## Beauty is leverage Most software does the same job as its competitors. There are dozens of to-do apps, chat apps and CRMs with the same features. When the feature list is a tie, people choose on feel, and feel is made of exactly these details. Emil's framing is that polish (The small, mostly invisible details (press feedback, aligned numbers, soft shadows, real copy) that make a working product feel considered) is not a cost; it is leverage. Features plateau, competitors copy them in a sprint, but the last few percent of polish is slow and hard to copy. So "polish is not a priority right now" usually has it backwards: once the features are there, polish is what sets you apart. Two limits keep this honest: **Step: Correct first.** A broken product with lovely animations is still broken, and looks worse for it. Polish multiplies the trust that working software earns; it never replaces it. **Step: Invisible, not theatrical.** The best polish is the kind nobody sees. Confetti on every click is not polish; a button that responds in 160ms is. ## Taste is trained, not born So who decides which details matter? Someone with taste (A trained instinct for what works, built by looking closely at a lot of good work. Not a gift you are born with), and taste is not a gift. It is a trained instinct, built the way any instinct is: by looking at a lot of good work, closely, for a long time. The people whose work feels obviously right (Emil Kowalski, Benji Taylor, the Vercel design team) share one habit. They collect references: screenshots, screen recordings, products opened just to feel how a menu moves. That collection is their training set. **Step: Keep a reference library.** When an interaction stops you, save it: a screenshot, a recording, a link. Rewatch them when you are stuck. **Step: Use constraints.** Two fonts, three colors, one accent. Fewer choices force real decisions; unlimited choice produces average work. **Step: Imitate before you invent.** Your first hundred buttons should look like buttons. A button that copies a well-made one is more tasteful than one that "innovates" with a gradient and an odd shape. **Step: Expect the first version to be ugly.** Taste compounds with care. Version three is where things start to feel inevitable. *(Imitating considered work is taste. Reinventing a solved problem is not.)* ## What this means with an agent An agent has seen everything and collected nothing. It reproduces the average of all the buttons it has read, which is why its first try looks like everyone else's. Your reference library is what pulls it away from the average. **Hand the agent your references (paste into your agent):** ```text Here are three references for this settings page: [links or screenshots]. Before building, tell me in one line each what these three have in common (spacing, type, how they handle buttons). Then build the page to match those qualities, not the average settings page. ``` And when a screen is "done", spend the last pass on the unseen: **The unseen pass (paste into your agent):** ```text This screen works. Now find the details nobody would notice but everyone would feel: numbers that should use tabular figures, buttons without press feedback, pure black text, a single heavy shadow, uppercase labels without tracking. List them as a Before / After / Why table, then apply them. ``` **Check yourself:** Two apps have the same features. Why do people often prefer one without being able to say why? - [ ] It has more features hidden in menus - [x] Its unseen details remove friction and signal care, and those compound - [ ] It uses a brighter color palette - [ ] It animates more things *Why:* When features tie, feel decides. Feel is made of details people do not consciously notice, and their effect adds up. ## In the skill - https://school.agents.org.in/skill/philosophy/taste-is-trained.md - https://school.agents.org.in/skill/philosophy/unseen-details-compound.md - https://school.agents.org.in/skill/philosophy/beauty-is-leverage.md --- # Delight has a budget > Decide how much delight a moment can carry from how often people see it, tell marketing UI from product UI, and test whether a screen feels right. Module: How good interfaces think · Level: beginner · 7 min · https://school.agents.org.in/design/philosophy/delight-has-a-budget Move the slider from "every keystroke" to "rare milestone" and try each example. Notice how much each moment is allowed to do: *[Interactive demo: The more often people see something, the less it may perform. Rare moments can celebrate.]* Typing gets nothing. A button gets a tiny dip. Finishing onboarding gets confetti. Swap any two and it feels wrong: confetti on every save would be unbearable by Wednesday. ## The delight-impact curve This is Benji Taylor's rule, and it is the most useful single question in this course: **how often will someone see this?** Delight (A small flourish that makes a product feel alive, like a tick on save or confetti at the end of onboarding. It wears out the more often you see it), the small flourishes that make a product feel alive, wears out with repetition. Something you see once a year stays fresh; something you see a hundred times a day becomes friction by lunchtime. | How often | Delight allowed | |---|---| | Every keystroke, every scroll | None. Any animation is friction. | | Every action (a button press, hovering a row) | Subtle: about 100 to 160ms, a slight press. | | Daily (save, send) | Small: a tick, a brief highlight. | | Weekly (new project, share) | Medium: a short stagger or scale-in. | | Rare milestones (signup done, first export) | Big. Confetti is allowed here. | So when someone says "let's make this more fun", ask how often people see it. For anything frequent, the right answer is usually *less* visible, not more. > **The one exception.** First-run moments (onboarding) are rare for each person but matter a lot, so they can carry more delight than their frequency suggests. Once onboarding is over, the budget drops back to normal. ## Marketing UI is not product UI The same rule explains a mistake you will see everywhere: building the inside of an app like a landing page, or the reverse. A marketing page (Pages people see once or twice, like a landing page. Their job is to explain and impress, so they can take bigger visual risks) is visited once or twice. Its job is to impress and explain. A product screen (Screens people use hundreds of times inside an app. Their job is to get out of the way: calm, consistent and fast) is used hundreds of times. Its job is to get out of the way. **Marketing energy in the product (avoid):** The dashboard's cards stagger in every time you open it. Headlines in a display font. An off-center, playful layout. Delightful on day one; by session fifty it is slow and the asymmetry looks broken. **Each in its place (do this):** The landing page gets the scroll-driven hero, the custom type and the asymmetric grid. The dashboard is calm, dense, consistent and instant, and earns its personality in small moments like a keyboard shortcut. | | Marketing | Product | |---|---|---| | Seen | Once or twice | Hundreds of times | | Goal | Convert, explain, impress | Get out of the way | | Motion budget | Generous | Tight | | Layout | Can break the system | Must follow the system | | The real work | The story | The states | *(Onboarding sits in between: theatrical like marketing, disciplined in layout like product.)* Before reviewing any screen, ask which one it is. The same animation can be right on the landing page and wrong in the app. ## Feeling right A screen can be correct, accessible, fast and consistent, and still feel cheap. What is left after every box is ticked is whether it **feels right**, and it is the part an agent is weakest at. Benji Taylor put it plainly after building morphing icons with Claude: the agent got them technically correct but could not tell when something looked wrong. That judgement is yours. Feeling right is not the same as fancy. A still screen with clear hierarchy and good type feels more right than a busy one with five animations. Restraint reads as confidence; over-design reads as anxiety. You cannot test feel with an automated check, but you can test it: **Step: The next-day review.** Build it, sleep, look again. If you still like it tomorrow, ship it. (Emil Kowalski's habit.) **Step: The slow-motion replay.** Record the interaction and play it at a quarter speed. Almost every motion bug shows up frame by frame. **Step: The cold-eyes test.** Show it to someone who has never seen it. Their first reaction is the truth. **Step: The phone-call demo.** Demo it to a friend over a call. If they say "wait, what?", the timing is off. Do this last, after correctness and accessibility. When something "works but feels off", the fix is rarely one property; it is usually rhythm and timing across several elements. **Check the budget (paste into your agent):** ```text For every animation on this screen, tell me how often a user will see it (every keystroke, every action, daily, weekly, rare) and whether this is marketing or product UI. Remove or shrink anything that performs more than its frequency allows, and list what you changed. ``` **Check yourself:** Your team wants a bouncy, 600ms celebration every time someone saves a note. What does the delight-impact curve say? - [ ] Great idea, saving should feel rewarding - [x] Saving is daily: a small tick or highlight at most; save the big celebration for rare milestones - [ ] Make it 1,200ms so people notice - [ ] Only animate it on marketing pages *Why:* Saving happens many times a day. Big delight on a frequent action becomes friction within a week; it belongs on rare moments. ## In the skill - https://school.agents.org.in/skill/philosophy/delight-impact-curve.md - https://school.agents.org.in/skill/philosophy/marketing-vs-product-ui.md - https://school.agents.org.in/skill/philosophy/feeling-right.md --- # States are the work > Design every state a screen can be in, not just the happy one, and treat tables and charts with the same care as a landing page. Module: How good interfaces think · Level: beginner · 7 min · https://school.agents.org.in/design/philosophy/states-are-the-work This inbox has six tabs. The first one is the screen everybody designs. Click through the other five: *[Interactive demo: One component, six states. The happy path is one of them.]* Loading, empty, error, offline, half-loaded. Every one of those is a screen a real person will see, often more often than the perfect one. And every one needs its own design and its own words. ## The happy path is the easy part The happy path (The screen when everything goes right: data loaded, user signed in, content present. The easy state, and the one everyone designs first) is the screen with everything going right: data loaded, user signed in, content present. Designers draw it, engineers build it, agents generate it. Then real people show up on a slow train, with an empty account, with an expired session, and the product looks broken. **Most "this feels broken" reports trace back to a state nobody designed,** not to a bug in the happy path. So fixing states is some of the highest-value design work there is. ## The states to check, every screen You will not need all of these for every screen, but you should be able to say why each one does not apply: | State | What is happening | |---|---| | Loading | The data is on its way | | Empty | Nothing here yet: new account, zero results | | Partial | Some content loaded, some still coming | | Error | Something failed, like the server or the network | | Offline | No connection at all, different from one failed request | | No permission | Signed in, but not allowed to see this | | Stale | Showing saved data from a while ago | | Over limit | A plan limit reached; read-only | | First run | Onboarding, sample data | Each state (One of the situations a screen can be in, like loading, empty, error, offline or no permission. Each needs its own design and words) needs real copy, not "Error: something went wrong", and a designed way to get from one to the next without a flash. **One message for everything (avoid):** "No data." Shown when the inbox is empty, and when the server is down. The person cannot tell whether they are caught up or whether their mail is gone. **Empty and error, apart (do this):** Empty: "You're all caught up. New mail will show up here." Error: "We couldn't load your mail. Your messages are safe. Try again." Different look, different words, a way forward. > **Break it on purpose.** Turn off your wifi, sign out in another tab, use an account with nothing in it. Most apps show an unhandled state within a minute. Better you find it than your users. ## Data is content There is a second place the craft usually stops: tables, charts and lists. Teams spend a week on a hero image and half an hour on the table people look at every single day. That is backwards. In most working software, data *is* the content. *[Interactive demo: The same five rows: a library's default, and treated as content.]* **Step: Right-align numbers, left-align text.** Numbers compare when their last digits line up. Text reads from the left. **Step: Use tabular figures.** `font-variant-numeric: tabular-nums` gives every digit the same width, so a column of amounts lines up and values stop jittering when they change. **Step: Quiet the lines.** Heavy borders on every cell and zebra stripes are the spreadsheet look. Use space and a hairline divider, like `1px solid rgba(0,0,0,0.06)`. **Step: Label with meaning.** "Value" says nothing. "Revenue, USD" says what and in what unit. Charts follow the same rules. Pick two to four colors from your palette instead of the library's rainbow. Remove default chartjunk (Decoration in a chart that carries no information: extra gridlines, needless legends, 3D effects, a rainbow of default colors. Edward Tufte's word) (extra gridlines, legends nobody needs). Make tooltips useful: the exact value, the date and a comparison, not "y: 47". Animate the chart drawing in once, on first load; updates should be instant. *(Charts may have a little personality. Tables and lists should be predictable.)* For tools people use all day, density matters too. Power users want compact rows (about 28px), casual users want comfortable ones (about 44px); offer both. Let people edit a cell in place and move with the arrow keys, the way every spreadsheet already works. **Design the states (paste into your agent):** ```text For this screen, list every state it can be in: loading, empty, partial, error, offline, no permission, stale, over limit, first run. For each, say whether it applies. For the ones that do, build it with real copy (no "something went wrong") and make sure empty and error look and read differently. ``` **Treat the table as content (paste into your agent):** ```text Review this table as content: right-align numeric columns with tabular-nums, left-align text, replace cell borders and zebra stripes with a 6% hairline between rows, make the header say what each column is and in what unit, and keep the header visible on scroll. ``` **Check yourself:** An inbox shows the same 'No data' message when it is empty and when the server fails. What is wrong? - [ ] Nothing, it is consistent - [x] Empty and error are different states; collapsing them leaves people unsure whether anything is missing - [ ] It should show a spinner instead - [ ] The message should be in red *Why:* An empty inbox and a broken one mean very different things. Each needs its own look, words and next step. ## In the skill - https://school.agents.org.in/skill/philosophy/states-are-the-work.md - https://school.agents.org.in/skill/philosophy/data-is-content.md --- # Say it precisely > Give feedback an agent can act on first time, by pointing at the exact element and naming exactly what is wrong with it. Module: How good interfaces think · Level: beginner · 6 min · https://school.agents.org.in/design/philosophy/say-it-precisely Same problem, two ways to report it. In **Describe**, the agent gets a sentence. In **Point**, tap the part of the card you mean: *[Interactive demo: A sentence sends the agent searching. A pointer sends it to the line.]* "The button on the pricing thing looks kind of off" opened four files and ended in a guess. Tapping the button handed over its exact address, its file and line, and its current style. The agent had nothing left to search for. ## Pointing beats describing Benji Taylor's rule: **when feedback is going to an agent, precise selection beats prose.** Agents are good at making changes and comparatively bad at finding where to make them. Every step spent searching is a step not spent on the fix, and a chance to fix the wrong thing. | Prose | Pointing | |---|---| | "the blue button in the sidebar" | `.sidebar > button.primary` | | "the spacing on the card feels off" | `.product-card`, `ProductCard.tsx:42`, `padding: 16px 12px` | | "make this section more interesting" | `section#hero`, plus a link to a hero you like | That address in the right column is a selector (The exact address of an element on a web page, like .plan-card > button.primary. Handing one to an agent tells it precisely which thing you mean): the exact path to one element on the page, the same thing CSS uses to style it. ## How to point You do not have to write selectors by hand. **Step: Click to annotate.** Benji Taylor's Agentation (Benji Taylor's development toolbar: click any element in your running app, write a short note, and it hands an agent the element's selector, file and your words) adds a small toolbar to your app while you develop. Click an element, type your note, and it hands the agent the selector, file and styles. **Step: Copy from the browser.** Right-click the element, choose Inspect, then right-click it in the panel and pick Copy → Copy selector. Free and built in. **Step: Screenshot with a mark.** For anything that is not a web page, a screenshot with a circle drawn on it is pointing too. **Step: Quote the lines.** In code review, paste the exact lines, not "the function near the top". > **Fragile addresses break.** `.card > div:nth-child(3) > span` is a selector, but it breaks the moment someone adds a div. Prefer names that describe the thing: `.product-card__name` or `[data-testid="price"]`. ## Point, then say why A bare pointer is worse than prose. "`.sidebar > button.primary`, fix it" tells the agent *where* but not *what*, so it guesses. Pointing finds the element; words explain the problem. **Pointer, no reason (avoid):** `.plan-card > button.primary` — fix this. **Pointer plus reason (do this):** `.plan-card > button.primary` (`PlanCard.tsx:42`): padding is `6px 10px`, cramped for the main action. Make it `10px 16px` with a 44px minimum height so it is easy to tap. ## Articulate precisely The words half of feedback has its own rule. Two people look at the same screen. One says "it feels off". The other says "the line height is too tight and the small uppercase labels need more letter spacing". Only the second can fix it, hand it to someone or teach it. The difference is not taste. It is vocabulary (The exact names for how interfaces look and move, like tracking, easing or hierarchy. The right word gets you the right result from an agent). "Say precisely what you mean" is the idea behind Index, the design vocabulary project by Emil Kowalski and Glenn Carstens-Peters. Naming something exactly is what lets you discuss it, critique it and instruct it. "Make it pop" is a wish; "raise the contrast to 4.5:1" is a spec. Precision runs both ways: - **Your input.** The exact word ("widow", "optical center", "layout shift") tells the agent exactly what to change. - **Its output.** A good review names the thing: "the play icon looks off-center because it is centered by its box, not by its visual weight". "The icon looks weird" is not reviewable. *(Every "don't" needs a "because". A rule without a reason does not survive the next prompt.)* Watch the pairs that vague language blurs together: kerning (one pair of letters) versus tracking (a whole line), a tag versus a badge, a widow versus an orphan. Mixing them up quietly tells the agent you cannot see the difference. And precise does not mean jargon. "The button has no hover state" is precise and plain. Use the shortest words that leave nothing to guess. **The two-channel note (paste into your agent):** ```text In src/components/PlanCard.tsx, the element .plan-card__price (line 21): the digits shift sideways when the price toggles between monthly and annual, because they are proportional figures. Add font-variant-numeric: tabular-nums. Change nothing else, and tell me the line you edited. ``` **Ask the agent to be precise back (paste into your agent):** ```text When you review this screen, name each problem exactly (the element's selector and file, the property, the value) and give one sentence of why. No "looks off" or "feels weird". ``` **Check yourself:** Which piece of feedback will an agent act on correctly first time? - [ ] The pricing card looks a bit off - [ ] .plan-card > button.primary — fix it - [x] .plan-card > button.primary (PlanCard.tsx:42): padding 6px 10px is cramped for the main action; use 10px 16px - [ ] Make the button pop more *Why:* It points at the exact element and says what is wrong and what to change. A bare selector says where but not what; prose says neither. ## In the skill - https://school.agents.org.in/skill/philosophy/pointing-beats-describing.md - https://school.agents.org.in/skill/philosophy/articulate-precisely.md --- # The bundle is design > Treat every dependency as a cost the user pays, and know when to use the platform, a few lines of your own, or a library. Module: How good interfaces think · Level: intermediate · 6 min · https://school.agents.org.in/design/philosophy/the-bundle-is-design Here are five libraries a typical web app ships, and what each costs a phone before the page can respond. Tap a row to swap the library for what the browser already has built in: *[Interactive demo: Every library is downloaded by every visitor, on every network. The platform is already there.]* Swap them all and roughly 145 KB disappears: around three seconds on a slow mobile connection, gone, with nothing lost. ## Every dependency is a tax A dependency (Code someone else wrote that your project pulls in, usually with npm install. Convenient once, then a cost every visitor pays) is code someone else wrote that your project pulls in, usually with `npm install`. Each one is convenient on the day you add it, and then it is a cost forever: more for every visitor to download, more code that could have a security hole, more updates to keep up with. All of that ends up in the bundle (The JavaScript files a browser has to download before your page works. Every dependency makes it bigger), the JavaScript file the browser downloads before your page works. **A 5 MB bundle is a design decision, and so is a 50 KB one.** The person on a cheap phone on a train feels the difference before they see a single pixel you designed. So the bar for adding a dependency should be higher than "it's convenient". ## Use what the browser already has The web platform has grown a lot. Many libraries that "everyone uses" now have a built-in replacement, a native API (A feature already built into the browser, like fetch, Intl or crypto.randomUUID, so it costs nothing to download), that costs nothing to download. | Instead of | Use | |---|---| | `moment` for dates | `Intl.DateTimeFormat`, `Intl.RelativeTimeFormat` | | `axios` for requests | `fetch()` | | most of `lodash` | `Array` methods, `Set`, `Object.fromEntries` | | `uuid` | `crypto.randomUUID()` | | `query-string` | `URLSearchParams` | | jQuery | `querySelector`, `closest`, `matches` | ## Write the five lines If you only use two functions from a big library, write the two functions. **A library for one line (avoid):** ```js import uniq from "lodash/uniq"; const tags = uniq(allTags); ``` **The one line (do this):** ```js const tags = [...new Set(allTags)]; ``` ## Draw simple shapes in CSS The same goes for images. A dot, a ring or a chevron does not need a file to download. ```css .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--accent); } .chevron { width: 8px; height: 8px; border-right: 2px solid currentColor; border-bottom: 2px solid currentColor; transform: rotate(45deg); } ``` No request, no image to decode, no alt text to maintain. The shape lives in the stylesheet. ## When a library is the right call This is not "never install anything". Some things are genuinely worth it: **Step: Hard to get right.** Cryptography, a framework like React, tricky date parsing. Writing your own is how bugs get in. **Step: Security-maintained.** Payment and sign-in clients, where a dedicated team watches for problems. **Step: Small and focused.** A tiny package with one clear job, like `clsx` for joining class names. **Step: Speed matters more right now.** A prototype or an internal tool can grab whatever is fastest. Calibrate to how long the code will live and who will load it. *("It's convenient" is not on that list.)* Agents reach for packages by reflex, because most code they have read imports them. So ask the question for them: **Before you install (paste into your agent):** ```text Before adding any new dependency, tell me its gzipped size and whether the browser or a few lines of our own code can do the same job. Only install it if it is hard to get right, security-maintained or tiny and focused, and say which. ``` **Audit the bundle (paste into your agent):** ```text List our dependencies with their approximate gzipped sizes. For each one, say whether a native browser API or a short utility could replace it (Intl for moment, fetch for axios, crypto.randomUUID for uuid, Array and Set for lodash). Don't change anything yet; give me a table. ``` **Check yourself:** Your agent wants to install moment to format one date on a page. What is the better first move? - [ ] Install moment; it is the standard - [x] Use Intl.DateTimeFormat, which is built into the browser - [ ] Install moment and lodash together - [ ] Format the date on the server with jQuery *Why:* Intl.DateTimeFormat formats dates natively at zero download cost. moment adds tens of kilobytes every visitor pays for. ## In the skill - https://school.agents.org.in/skill/philosophy/dependency-discipline.md --- # Should it move at all? > Decide whether something deserves an animation before you build one, and take motion out safely when it doesn't. Module: Motion · Level: beginner · 7 min · https://school.agents.org.in/design/motion/should-it-move Press the button below a few times, fast. Both command palettes open the same menu. One of them is pretty the first time and in your way every time after. *[Interactive demo: The same palette, opened from the keyboard. Count how often you'd do this in a day.]* That is the whole first lesson of motion: **the default answer to "should this animate?" is no.** Motion has to earn its place. Most of the craft in this module is about the cases where it does, but the most useful habit is asking the question at all. ## Ask how often Emil Kowalski, who built the toast library Sonner and the drawer library Vaul, starts every animation decision with one question: how often will someone see this? *[Interactive demo: Pick a moment. The more often it happens, the less motion it can afford.]* | How often | What it gets | |---|---| | 100+ times a day (shortcuts, tab switches, a command palette) | No animation | | Tens of times a day (hover, moving through a list) | Almost nothing | | Now and then (a modal, a drawer, a toast) | A standard animation | | Rare or once (onboarding, a first success) | This is where delight lives | Two hard rules sit on top of the table. **Anything triggered from the keyboard doesn't animate.** Someone who presses a shortcut wants the result, not a show. And **data people are reading** (a chart, a table, a number) doesn't move for decoration; it moves only when the value really changes. ## Name the job If it passes the frequency test, the motion still needs a job. Name one, or don't build it: - **Feedback**: the button shows it heard your press. - **Where it came from**: a menu grows out of the button you clicked. - **What changed**: a toggle slides so you see it switch. - **Smoothing a jump**: content that would otherwise teleport glides instead. - **Explaining**: a demo shows how a feature works (marketing and onboarding only). - **Delight**: only in the rare tier. Three jobs that don't count: decoration, hiding slow code ("fix the code"), and "the animation library is installed, so let's use it". > **In plain words.** An animation is a change you can watch happen. If nobody would miss it, it is a cost: a few hundred milliseconds of waiting, every time. ## Then pick the cheapest tool Once something earns motion, reach for the simplest tool that does the job. A CSS transition (A CSS rule that animates a property from its current value to a new one when it changes. Because it starts from wherever it is, it can reverse smoothly if interrupted) for a state you toggle. CSS `@starting-style` for something appearing for the first time. A CSS animation for motion planned in advance. A JavaScript library like Motion only for springs, gestures and exits that need it. The later lessons cover each decision in order: easing (How speed changes during an animation: start fast and slow down, start slow and speed up, or both. It decides whether motion feels snappy or sluggish), then duration, then entering and leaving, then springs. **Step: How often?.** Use the table. Keyboard-triggered means no. **Step: What job?.** Feedback, origin, state, smoothing a jump, explaining, or rare delight. **Step: Which tool?.** The cheapest one that works. **Step: Which curve, how long, which property?.** The next three lessons. Four quick checks before you keep any animation: would the UI feel broken without it? Does it work with reduced motion on? Does it still look right played at quarter speed? Will it still feel right the fiftieth time? ## Taking motion out without breaking things The opposite job comes up just as often: "the app feels slow, tone down the motion." Deleting an animation looks like deleting one line. It rarely is. *(The animation is usually holding something up you can't see in the diff.)* - **Hidden start states.** If an element starts at `opacity: 0` and an animation fades it in, deleting the animation leaves it invisible forever. Delete both together. - **Code that waits.** A `setTimeout` sized to the animation, or a handler waiting for it to end, keeps pausing the UI for motion that no longer exists. - **Exits that delay unmounting.** Libraries hold a closing component on screen until its exit finishes; with no exit, whatever ran "after" must run immediately. - **Layout animations hiding a jump.** If removing one makes content lurch, keep it and fix the lurch separately. - **Focus and tests** that were timed to the animation. Before deleting, try reducing: | Today | Reduced to | |---|---| | Hover with scale, lift or a growing shadow | Color or opacity only, 150ms or less | | A slide or scale entrance on something frequent | Opacity only, 150ms | | Any UI animation over 300ms | 200–250ms on the same curve | | A stagger over 80ms per item or 300ms total | 30ms per item, or fade the group at once | | An endless pulse or shimmer | Play once, keep the end state | Then clean up what the removal orphaned: unused keyframes, empty wrappers, imports. And keep a short list of what you deliberately *kept*, with the job that saved each one. That list is what makes it a restraint pass rather than deleting every transition in the repo. **A restraint pass (paste into your agent):** ```text Go through the animations in this app. For each one, tell me how often a user sees it and what job it does (feedback, origin, state change, smoothing a jump). Remove or reduce any that are keyboard-triggered, decorative, or seen 100+ times a day. When you remove one, also remove its start state (like opacity: 0), any timeouts or animation-end handlers that waited on it, and any orphaned keyframes. List what you kept and why. ``` ## Going deeper This module teaches the decisions and the exact values. If you want to learn motion in depth, Emil Kowalski's course at animations.dev is the canonical resource; his libraries Sonner and Vaul, Jakub Antalik's transitions.dev catalog and the animated icon set at lucide-animated.com are the best places to read real, production motion code. **Check yourself:** A user opens your command palette with ⌘K about 150 times a day. What should its open animation be? - [ ] A 300ms scale and fade, so it feels polished - [ ] A 150ms fade, as a compromise - [x] No animation at all - [ ] A spring with a little bounce *Why:* It's keyboard-triggered and seen 100+ times a day: both rules say no animation. Any motion becomes a wait between the shortcut and the result. ## In the skill - https://school.agents.org.in/skill/motion/MOC-motion.md - https://school.agents.org.in/skill/motion/animation-decision-framework.md - https://school.agents.org.in/skill/motion/animation-removal-hazards.md - https://school.agents.org.in/skill/motion/animations-dev-curriculum.md --- # Easing curves > Pick the right easing curve for anything that moves, and know why ease-out makes the same animation feel faster. Module: Motion · Level: beginner · 7 min · https://school.agents.org.in/design/motion/easing Open both dropdowns at once. They take exactly the same 250 milliseconds. One of them feels sluggish. *[Interactive demo: Same menu, same duration. Only the curve differs. Try slow-mo to see why.]* The difference is the easing (How speed changes during an animation: start fast and slow down, start slow and speed up, or both. It decides whether motion feels snappy or sluggish): how the speed changes during the animation. The left one uses ease-in (An easing that starts slowly and speeds up toward the end. It makes UI feel sluggish because nothing happens right when you're watching, so avoid it in interfaces), which starts slowly and speeds up. The right one uses ease-out (An easing that moves fast at the start and slows into the end. The right default for anything entering or leaving, because it reacts the moment you act), which moves most of the way at once and spends the rest of its time settling. When you click, your eye goes straight to where the menu should appear. Ease-out puts something there in the very first frames. Ease-in makes you watch almost nothing happen, right at the moment you're paying the most attention. **Never use ease-in on UI, exits included.** ## The decision order You don't need to memorise curves. You need one rule per situation: | What's happening | Curve | |---|---| | Something entering or leaving (menu, toast, modal) | ease-out | | Something already on screen moving from A to B (a tab indicator) | ease-in-out | | A hover or a color change | `ease` | | Constant motion: a progress bar, a marquee, a hold-to-confirm fill | `linear` | | Not sure | ease-out | A drag, a flick or anything your finger is steering doesn't use a curve at all. It uses a spring, which gets its own lesson. ## Custom curves beat the built-ins CSS ships `ease`, `ease-in`, `ease-out` and `ease-in-out`. They were fine defaults a decade ago; today they read as "nobody chose this". A cubic-bezier (A way to write your own easing curve as four numbers, like cubic-bezier(0.23, 1, 0.32, 1). Custom curves feel more deliberate than the built-in ones) lets you write your own curve as four numbers, and a slightly stronger curve is most of what makes motion feel deliberate. *[Interactive demo: Pick a curve to see its shape and watch the ball run it. The red one is the one to avoid.]* Here is a small set worth keeping as tokens, mostly from Emil Kowalski's practice: ```css :root { --ease-out: cubic-bezier(0.23, 1, 0.32, 1); /* menus, popovers, toasts, modals */ --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1); /* on-screen travel, tab indicators */ --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1); /* sheets and drawers from an edge */ --ease-out-soft: cubic-bezier(0.25, 1, 0.5, 1); /* gentler hovers and menus */ --ease-back: cubic-bezier(0.34, 1.56, 0.64, 1); /* overshoots: playful moments only */ } ``` Read the curve like a graph: time runs left to right, progress bottom to top. A steep start means it moves early. A number above 1 (like the `1.56` in back-out) means it shoots past the end and settles back, which is cute on a sticker and wrong on a delete dialog. > **In plain words.** ease-out = fast then gentle. ease-in = gentle then fast. For anything a person just asked for, fast first. ## Curve and duration go together A beautiful curve on the wrong duration looks worse than a plain ease-out on the right one. Tune them as a pair, which is the next lesson. Need a curve that isn't on the list? Take one from easing.dev or easings.co rather than hand-rolling four numbers. **Before (avoid):** ```css .menu { transition: all 300ms ease-in; } ``` **After (do this):** ```css .menu { transition: opacity 200ms var(--ease-out), transform 200ms var(--ease-out); } ``` Three fixes in one line: ease-out instead of ease-in, a named list of properties instead of `all`, and a shorter duration. ## A note on writing it down Small conventions make motion CSS easier to read and review. They come from Ben DC's frontend guidelines: - **Pick one time unit and stick to it.** This course uses milliseconds (`200ms`) everywhere, because they match JavaScript timers and design tokens. Mixing `200ms` and `0.2s` in one file is the actual bug. - **Rotate in turns.** `rotate(0.25turn)` is a quarter turn, `rotate(1turn)` a full spin. Keep degrees for arbitrary angles like `14deg`. - **Unitless line-heights**, `rem` for things that should scale with the reader's font size and `px` for hairlines. - **Avoid `!important`**; it usually means a specificity fight the cascade should settle. When you join an existing codebase, its conventions win. These are for when you're starting fresh. **Fix the easing (paste into your agent):** ```text Audit the CSS transitions and animations in this project. Replace any ease-in on UI with ease-out. Use these tokens: --ease-out: cubic-bezier(0.23, 1, 0.32, 1) for things entering or leaving, --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1) for things moving across the screen, --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1) for sheets. Use linear only for progress. Name the properties in every transition instead of "all", and keep durations in milliseconds. ``` **Check yourself:** A dropdown uses transition: opacity 250ms ease-in. A user says it feels slow. What's the best first fix? - [ ] Make it 400ms so it's smoother - [x] Switch to ease-out (or a strong custom ease-out) at the same or shorter duration - [ ] Add a spring with bounce - [ ] Use linear so the speed is even *Why:* ease-in starts slowly exactly when the eye is watching, so the same 250ms feels slower. A strong ease-out moves at once and feels faster without changing the duration. ## In the skill - https://school.agents.org.in/skill/motion/easing-curves.md - https://school.agents.org.in/skill/motion/css-conventions.md --- # Duration and feedback > Choose how long an animation should last for each kind of element, and add the small press and tooltip responses that make UI feel answered. Module: Motion · Level: beginner · 7 min · https://school.agents.org.in/design/motion/duration-and-feedback Drag the slider to 600ms and open the menu. Then try 200ms. Same curve, same menu: one is a small show, the other just answers you. *[Interactive demo: One dropdown, one curve. Slide the duration and open it again.]* The duration (How long an animation lasts. Almost all interface motion belongs under 300 milliseconds; button presses take 100 to 160) is how long the animation lasts. There is no single right number; it depends on what is moving and how often people see it. But there are good ranges, and **almost all UI motion belongs under 300 milliseconds.** ## The table | Element | Duration | |---|---| | Button press | 100–160ms | | Hover change | 120–200ms | | Tooltip | 125–200ms, after a first delay | | Dropdown or popover | 150–250ms | | Modal | 200–300ms | | Tab content swap | 200–250ms | | Page transition | 250–400ms, the longest normal UI motion | | Skeleton to content | 150ms | | Celebration, confetti | 600–1200ms (rare, so it can afford it) | | First-run onboarding | 400–800ms | Three rules of thumb cover anything not on the list. **Smaller is shorter**: a 12px icon doesn't need 300ms. **More frequent is shorter.** **More important is a little longer**: a modal changes what you're looking at, so it earns more time than a tooltip. > **If unsure, halve it.** Most animations that "feel slow" are simply too long. Most that "feel jumpy" are too short. When in doubt, halve the number and look again. ## Exits are shorter than entrances When something closes, the person has already moved on. Make the exit about 60 to 80 percent of the entrance: a panel that opens in 250ms closes in about 180ms. ```css .panel { transition: transform 180ms var(--ease-out); } /* closing */ .panel[data-state="open"] { transition-duration: 250ms; } /* opening */ ``` Use transitions here, not keyframes. A transition starts from wherever the element is right now, so if someone closes the panel halfway through opening, it simply turns around. A keyframe animation would jump back to its first frame. There's a second kind of asymmetry for moments where the person is deciding. A hold-to-delete button fills slowly while you hold (2 seconds, linear) and snaps back fast if you let go (200ms, ease-out). The slow part is their decision; the fast part is the system answering. You'll build that in the choreography lesson. *(Sonner's toasts run a calm ~400ms on purpose. That's a personality choice, not the default.)* ## Press feedback The smallest animation with the biggest effect: a button that shrinks a little under your finger. Press and hold each of these. *[Interactive demo: Press and hold each one, then let go halfway through.]* ```css .button { transition: transform 120ms var(--ease-out); } .button:active { transform: scale(0.97); } ``` The canonical numbers: **0.97** for buttons, **0.96** for small controls like icon buttons and chips, and never below **0.95**, where it starts looking squishy. Keep it 100–160ms. Because it's a transition, a release mid-press glides back. Two exceptions: text inputs don't scale (shift the border or background instead), and controls used hundreds of times a day can skip it. ## Tooltips that don't make you wait twice Tooltips need a delay before the first one appears, roughly 400–700ms, so a pointer passing over a toolbar doesn't spray labels everywhere. But once one is open, the neighbours should appear **instantly**, with no delay and no animation. Move across this toolbar with each setting. *[Interactive demo: Hover across the buttons, or tab through them, in both modes.]* This "skip delay" is one of the most reused details in good interfaces; without it, exploring a toolbar feels gluey. Radix UI's tooltip provider has it built in (`skipDelayDuration`), and sets a `data-instant` attribute you can use to drop the animation. Give tooltips and hover popovers a small close delay too, about 150ms, so a slight wobble of the mouse doesn't make them flicker. One more responsiveness rule lives with popovers: a menu should grow out of the button that opened it. That's the next lesson. **Durations and feedback (paste into your agent):** ```text Check every transition in this UI against these budgets: button press 100–160ms, hover 120–200ms, dropdowns and popovers 150–250ms, modals 200–300ms, page transitions up to 400ms. Make exits about 70% of the entrance duration, using transitions (not keyframes) so they can reverse mid-way. Add :active { transform: scale(0.97) } with a 120ms ease-out to buttons (0.96 for icon buttons), but not to text inputs. Give tooltips a ~500ms first delay and make neighbouring tooltips appear instantly while one is open. ``` **Check yourself:** A panel slides in over 250ms. How long should its exit take? - [ ] 250ms, exits should mirror entrances - [x] About 180ms, because the person has already moved on - [ ] 400ms, so the exit feels gentle - [ ] 0ms, exits don't need animation *Why:* Exits are usually 60–80% of the entrance. The person has made their decision; a shorter, quieter exit gets out of the way. ## In the skill - https://school.agents.org.in/skill/motion/duration-table.md - https://school.agents.org.in/skill/motion/responsive-feedback.md --- # Entering and leaving > Make things appear and disappear well, from the right size, out of the right place, with a quieter exit than entrance. Module: Motion · Level: beginner · 9 min · https://school.agents.org.in/design/motion/enter-and-exit Open both dialogs. The left one inflates from a dot like a balloon. The right one simply arrives. *[Interactive demo: Both are 'a scale animation'. Only one looks like software.]* The left one starts at `scale(0)`. For its first few frames it's invisible, then a blurry speck, then a toy growing out of a single point. The right one starts at `scale(0.95)` with `opacity: 0`. **Nothing in a UI should scale up from zero.** The 5% size change is enough to read as motion; the opacity (How see-through something is, from 0 (invisible) to 1 (solid). Fading opacity is cheap to animate and does most of the work of making things appear) does the work of making it visible. ```css .dialog { opacity: 0; transform: scale(0.95); transition: opacity 200ms var(--ease-out), transform 200ms var(--ease-out); } .dialog[data-state="open"] { opacity: 1; transform: scale(1); } ``` Both properties share one duration and one curve, so they read as one move. > **In plain words.** **transform** moves, scales or rotates an element without disturbing anything around it. **opacity** is how see-through it is, from 0 (invisible) to 1 (solid). Together they do almost all good UI motion. ## Appearing the first time To animate something the moment it's added to the page, modern CSS has `@starting-style`: you describe where it starts, and the browser animates from there. ```css .toast { opacity: 1; transform: none; transition: opacity 200ms var(--ease-out), transform 200ms var(--ease-out); } @starting-style { .toast { opacity: 0; transform: translateY(8px); } } ``` Where that isn't supported, the common React pattern is a `data-mounted` attribute set one frame after mount, with the start state in the base rule and the end state under `[data-mounted="true"]`. Either way, list the properties; never `transition: all`. ## Grow from where it came from A menu that opens from a button should look like it unfolds out of that button. The pivot point for a scale is the transform-origin (The pivot point for scaling or rotating an element. Setting it to where a menu's button is makes the menu look like it grows out of that button), which is the center by default. Press the ••• button in each mode. *[Interactive demo: Center origin grows from nowhere. Origin on the button grows from your press.]* ```css .popover { transform-origin: var(--popover-origin, top right); } ``` Radix, React Aria and Floating UI all tell you where the trigger is, so set the origin from that. The exception is a modal: it isn't attached to anything, so it stays centered. ## Three transform tricks worth knowing These come from Emil Kowalski's notes on transform (The CSS property that moves, scales and rotates an element without disturbing anything around it. It's one of the two properties that are cheap to animate): - **`translateY(100%)` moves an element by its own height.** A sheet hidden with it works whether it's 200px or 800px tall; no magic numbers. - **`scale()` scales the children too**, text included. If a card grows on hover, its text grows with it. Scale an icon or image inside instead. - **Order matters, and `transform` is one property.** `translate(10px) rotate(45deg)` is not `rotate(45deg) translate(10px)`. And writing `transform: scale(1.05)` on hover silently throws away a `translateY` set elsewhere; write both. ## Leave quieter than you arrived Show and hide this check. The first exit plays the entrance backwards. The second keeps three quiet properties and lets go. *[Interactive demo: Enter with five properties; exit with three, in half the time.]* This is a signature pattern from Jakub Antalik's transitions.dev: **compose on enter, subtract on exit**. The entrance is the news, so it can use several properties (opacity, scale, a little rotation, a bob, a stroke drawing on). The exit is "going away", so it keeps the essentials (opacity, a hint of scale, a 2px blur) and drops the theatre. A rewound entrance is technically correct and still feels mechanical. Pair it with the shorter exit timing from the last lesson. Don't skip the exit entirely, though. Something that pops onto the screen with care and then vanishes in one frame looks broken. ## Toasts: a small library's worth of lessons A toast (A small message that slides in at the edge of the screen to confirm something ("Changes saved") and leaves on its own. One with an Undo button has to stay longer and pause while you look at it) is the little message that slides up to confirm something ("Invite resent"). Emil Kowalski's library Sonner is the most copied toast on the web, and its principles apply to any component you hand to other people. *[Interactive demo: Each toast rises from the edge it will leave by; the older one steps back instead of vanishing.]* - **The API is the product.** `toast("Saved")` beats `toast({ message, type, duration })`. Default everything. - **Good defaults beat options.** "What happens if I pass nothing?" should always look right. - **Handle edge cases quietly**: stack many toasts, dedupe identical ones, survive rapid clicks. - **Transitions, not keyframes**, so spam-dismissing reverses smoothly instead of restarting. - **Match motion to personality.** Sonner is calm, so its toasts use a slower ~400ms `ease`. Vaul is physical; cmdk is snappy. Pick one and stay consistent. - **Leave by the way you came**: in from the bottom, out through the bottom, with fewer properties. - **Look again tomorrow.** Build it today, review it after sleep. The cheapest QA there is. ## Errors: a shake that means it One more entrance: the error. When a form field fails on submit, a short shake points at it. Try both styles with an empty field. *[Interactive demo: Submit with the field empty. Then type an email to clear it.]* The version that reads as physical, from Jakub Antalik: 280ms, five stops, shrinking from 4px to 2px, on a snappy curve. ```css @keyframes shake { 0% { transform: translateX(0); } 28.57% { transform: translateX(-4px); } 57.14% { transform: translateX(4px); } 78.57% { transform: translateX(-2px); } 100% { transform: translateX(0); } } .field--error { animation: shake 280ms cubic-bezier(0.36, 0.07, 0.19, 0.97); } ``` Shake the field's **wrapper**, never the input itself, or the text cursor jumps. Keep the red border after the shake (the shake gets attention; the state explains). Fire it on submit or blur, never on each keystroke. **Better entrances and exits (paste into your agent):** ```text Review how elements enter and leave in this UI. Replace any scale(0) with scale(0.95) plus opacity 0 → 1 on the same duration and ease-out curve. Set transform-origin on popovers and menus to the trigger's position (modals stay centered). Make exits shorter (about 70% of the entrance) and quieter: drop translate, rotate and bounce on exit, keep opacity and a small scale. For form errors, shake the field wrapper 280ms with keyframes at 0, 28.57, 57.14, 78.57, 100% (0, -4px, 4px, -2px, 0) and keep the error border afterwards. ``` **Check yourself:** A tooltip enters with scale(0.94), opacity and a small translate. What should its exit do? - [ ] Play the same three properties in reverse at the same speed - [x] Fade out with opacity (maybe a hint of scale), faster than it entered - [ ] Scale down to 0 so it disappears into its anchor - [ ] Nothing; remove it instantly with display: none *Why:* Compose on enter, subtract on exit: the leaving element keeps the essentials and drops the theatre, at about 60–80% of the entrance time. Instant removal looks broken; scale(0) is the balloon. ## In the skill - https://school.agents.org.in/skill/motion/never-scale-from-zero.md - https://school.agents.org.in/skill/motion/transform-mastery.md - https://school.agents.org.in/skill/motion/compose-subtract-asymmetry.md - https://school.agents.org.in/skill/motion/sonner-principles.md - https://school.agents.org.in/skill/motion/multi-segment-shake.md --- # Springs > Know when a spring beats a curve, tune stiffness and damping by feel, and keep hand-written motion landing in the same place at any frame rate. Module: Motion · Level: intermediate · 8 min · https://school.agents.org.in/design/motion/springs Send the ball right, then press again before it arrives. It turns around without stopping dead, carrying its speed into the new direction. That is a spring. *[Interactive demo: Tune the spring, then interrupt it mid-flight.]* A curve says "get there in 200ms, with this shape". A spring (Motion driven by physics instead of a fixed duration: a pull toward the target plus friction. It keeps its speed when interrupted, which makes drags and flicks feel natural) says "pull toward the target with this much force and this much friction", and the duration falls out of the physics. That difference only matters in one situation, but it matters a lot there: **when the person is steering the motion, use a spring.** ## When springs win, and when they don't Use a spring when: - The motion can be **interrupted** halfway: a drag, a swipe, a sheet you grab again. - It starts from a real **speed**, like the flick of a finger. - The target can **change while it's moving**. Use a curve when a discrete event triggers it (a click, a route change), when you need exact timing so several things land together, or when the element is small enough that nobody could tell. A two-state press doesn't need a spring either: a CSS transition already reverses from wherever it is. > **In plain words.** **Stiffness** is how hard the spring pulls toward its target: higher is snappier. **Damping** is friction: lower lets it overshoot and wobble, higher settles it calmly. **Mass** is how heavy the thing feels; leave it at 1. ## The two springs to remember **Apple's default is critically damped**: no bounce, a perceived duration around 0.3–0.4 seconds. In Motion you can write it in the form that's easiest to reason about: ```ts const settle = { type: "spring", duration: 0.35, bounce: 0 }; ``` **The drawer spring** settles a sheet or drawer after you let go of it: ```ts const drawer = { type: "spring", stiffness: 380, damping: 30, mass: 1 }; ``` Bounce is earned. A card you flicked may overshoot a touch (bounce 0.1 to 0.3, never more); a menu that simply opened should not. And never leave a spring on library defaults: they tend to be slow and floaty (try "Library default" above). Always set `duration` and `bounce`, or both `stiffness` and `damping`. Not everything polished is a spring, either. Sonner, the usual example of polished motion, uses plain CSS transitions. ## Writing your own: frame-rate independence Libraries handle the physics for you. If you write a spring or a decay by hand, there's a trap. Flick both balls below in each mode. *[Interactive demo: The same flick on a 60fps and a 30fps screen.]* Code written "per frame" (`velocity *= 0.95` every frame) runs twice as many frames on a 60Hz screen as on a 30Hz one, and the same gesture ends somewhere different. Cheng Lou measured the same input landing up to 359px apart between 10 and 120fps. The rules from his work, in plain words: **Step: Step on a fixed clock.** Advance springs in fixed 4ms steps (four per frame at 60fps), or use a formula that gives the exact value at any time, like `x0 · e^(−kt)`. **Step: Cap the catch-up.** After the tab freezes, don't run thousands of steps at once. Cap at about 300 (1.2s), then either carry the rest over or snap to the destination, on purpose. **Step: Apply input at its timestamp.** Step up to the moment of the press, then apply it, so recorded input replays identically. **Step: Store what the person placed.** Keep the panel size they chose; compute the squeezed-to-fit version each frame without saving it. **Step: Never decide from last frame's value.** A lagging position is fine to draw; a lagging width that picks a column count makes things jump. Ending a spring needs care too: it never reaches the target exactly. Stop it when both the distance and the speed are tiny (under about 0.01), then set it exactly on target. The playground above does all of this, which is why interrupting it feels clean. *(The ball above is stepped every 4ms no matter how fast your screen is.)* ## Live data: breathe as one A cousin of the spring comes from Benji Taylor's live chart, Liveline. When several things show the same changing number (the line, the price badge, the axis labels), move them all toward the new value at **the same rate**, so the chart inhales as one instead of jittering in pieces. He uses a lerp (Short for linear interpolation: moving a value a fixed fraction of the remaining way toward its target each frame, like 8%. Used to make live data glide instead of jump) of 8% per frame: ```ts current += (target - current) * 0.08; // for every element that shows this value, in one loop ``` If a new value lands outside the visible range, snap the range out instantly, then let the line glide into it. Run everything in one `requestAnimationFrame` loop that writes to the page directly rather than through React state. And give live data its states: a loading line that breathes and then becomes the chart, a quiet empty message, a paused view that catches up on resume. Test it on ugly data: wild swings, fast reversals, long silences then bursts. **Springs that feel right (paste into your agent):** ```text Use springs only where the user drives the motion (drag, swipe, sheets, anything interruptible); keep curves for click-triggered animations. Default to a critically damped spring ({ type: "spring", duration: 0.35, bounce: 0 }); for drawers and sheets after a drag use { stiffness: 380, damping: 30 } and pass the release velocity. Only allow bounce (0.1–0.3) after a flick. Never leave spring parameters on defaults. If you hand-write any physics, step it on a fixed 4ms clock with a capped catch-up, not once per frame. ``` **Check yourself:** Which of these should use a spring rather than a cubic-bezier curve? - [ ] A modal that opens when a button is clicked - [x] A bottom sheet the user drags and releases - [ ] A tooltip fading in - [ ] A page transition after a link click *Why:* The sheet is driven by the user's finger, can be grabbed again mid-flight and starts with real velocity. That's exactly where springs beat fixed-duration curves. ## In the skill - https://school.agents.org.in/skill/motion/spring-animations.md - https://school.agents.org.in/skill/motion/frame-rate-independence.md - https://school.agents.org.in/skill/motion/lerp-breathing.md --- # Choreography > Make several things move together with intent, using stagger, travelling elements, clip-path reveals and grouped hover. Module: Motion · Level: intermediate · 9 min · https://school.agents.org.in/design/motion/choreography Slide the delay to 150ms and press replay. The last row arrives so late it feels like the search is still loading. Now try 40ms. *[Interactive demo: Search results arriving in a cascade. Watch the total, not the per-row number.]* A stagger (Playing the same entrance on several items one after another, a few tens of milliseconds apart, so a list arrives as a quick wave) is the same entrance played on several items, each a little after the last. Done well it shows order and pulls the eye down the list. Done badly it makes a fast app feel slow. ## Stagger: small gaps, short cascade - **30–80ms between items.** Under 30 looks like everything at once with extra steps. Over 80 starts to feel like loading. - **Keep the whole cascade under about 300ms.** Past around a dozen items, cap it: items past the cap arrive with the last staggered one. - **Only on first appearance.** The first search result list can cascade; refining the search, sorting or filtering should not re-stagger. Update in place. - **Only when order means something.** A stagger implies a reading order. Identical items in arbitrary order shouldn't pretend to have one. - **Exit together.** If you must stagger an exit, reverse it; usually a faster, single fade is better. For a page or hero section, split it into heading, text and button and offset them ~90–100ms, each entering with opacity, `translateY(8px)` and a 2px blur. And remember that **first paint is not an entrance**: what's already on screen when the page loads should simply be there. ```ts const delay = (i: number) => Math.min(i, 12) * 0.05; // 50ms apart, capped at 12 ``` ## Fly, don't teleport Benji Taylor's rule from the Family app: **if something is on screen before and after a change, it should travel, not disappear and reappear.** Click between tabs that are far apart in each mode. *[Interactive demo: The active pill is one thing in two places. Let it move.]* When the pill teleports, your eye has to search for where it went. When it flies, you watch it get there. The same goes for a list item moving to a new position, a card expanding into a full screen, or a stacked modal: the one underneath recedes slightly (scale 0.96, a little blur) because it's coming back, rather than vanishing. The technique behind most of these is called FLIP (A technique for animating an element to a new position: measure First and Last positions, Invert the difference with a transform, then Play it back to zero): measure where the element is (First), let it move to its new spot (Last), shift it back with a transform so it *looks* unmoved (Invert), then transition the transform away (Play). Motion's `layoutId` does this for you. Crossfading is still right when two things are genuinely different content; forcing travel between unrelated cards is decoration. *(The pill in this demo moves by clip-path, not width. More on that next.)* ## clip-path: the underrated one clip-path (A CSS property that cuts away part of an element, like a mask. It animates cheaply and smoothly, which makes it great for reveals, wipes and sliding highlights) cuts away part of an element, and it animates smoothly and cheaply. `inset(top right bottom left)` clips from each edge; both ends of a transition must use the same shape function. Hold this button down. *[Interactive demo: Hold to delete. Let go early and it snaps back.]* ```css .fill { clip-path: inset(0 100% 0 0); transition: clip-path 200ms var(--ease-out); } /* release: fast */ .button:active .fill { clip-path: inset(0 0 0 0); transition: clip-path 2s linear; } /* hold: slow */ ``` The press is slow and `linear` because it's progress and you're deciding; the release answers in 200ms. Put a single duration on the base rule and an aborted hold crawls back for two whole seconds. Other patterns from Emil Kowalski's notes: - **Tabs whose text flips color exactly under a sliding pill**: two text layers, the top one clipped to the pill. - **Image reveals on scroll**: `inset(20% 0 20% 0)` to `inset(0)`, like a letterbox opening. - **Before/after sliders**: the "after" image clipped by a CSS variable that follows the pointer. - **Directional swaps**: one panel clips out to the left as the next clips in from the right, with no layout shift. Combine it with rounded corners using `inset(… round 12px)` rather than `border-radius`, which double-clips in Safari. ## Grouped hover: the falloff Hover or tap a face in this stack. Its neighbours lift too, a little less with each step away. *[Interactive demo: lift × falloff^distance. Slide the falloff and compare.]* From Jakub Antalik's avatar group: `shift = lift × falloff^distance`, with the same idea for scale. With a lift of −8px and a falloff of 0.45, the neighbour moves −3.6px, the next −1.6px, and by four away it's under a pixel. **0.4–0.5 is the sweet spot**: 0.8 drags the whole row along, 0.2 is just one face. The lift uses ease-out; the return uses a slight overshoot, so it settles with life. Skip it on dense data tables and lists over ~20 items, and note it can't fire on touch-only screens without a tap. **Choreograph a list and tabs (paste into your agent):** ```text Stagger the search results only on their first appearance: 40ms between rows, capped so the whole cascade stays under 300ms, opacity plus translateY(8px), ease-out. Don't re-stagger on filter or sort. Make the active tab indicator one persistent element that slides between tabs (FLIP, layoutId, or clip-path inset on a full-width pill) with cubic-bezier(0.77, 0, 0.175, 1) over ~300ms, instead of re-rendering under each tab. ``` **Check yourself:** A results list staggers 120ms per row across 15 rows every time the user changes a filter. What's wrong? - [ ] Nothing; stagger makes lists feel polished - [ ] Only the curve; switch to a spring - [x] The gap is too long, the cascade far over 300ms, and it re-staggers on every filter change - [ ] It should stagger from the bottom up *Why:* 15 rows at 120ms is a 1.7s cascade, the gap is past 80ms, and stagger belongs on first appearance only. Refinements should update in place. ## In the skill - https://school.agents.org.in/skill/motion/stagger-choreography.md - https://school.agents.org.in/skill/motion/fly-not-teleport.md - https://school.agents.org.in/skill/motion/clip-path-tricks.md - https://school.agents.org.in/skill/motion/distance-falloff-propagation.md --- # Morphs and swaps > Change a label, an icon or an image in place so it reads as the same thing changing, not two things trading places. Module: Motion · Level: intermediate · 7 min · https://school.agents.org.in/design/motion/morphs Press the button in each mode and watch the first three letters. *[Interactive demo: Continue becomes Confirm. In one mode, 'Con' never moves.]* In the crossfade, the whole word fades out and a new word fades in. Your brain sees two buttons. In the shared-letter version, "Con" stays put and only the ending changes, so it reads as one button changing its mind: "got it, now confirm". That's the last lesson's rule applied to text. **What stays the same should stay still; only the difference moves.** ## Shared-letter text This is a Benji Taylor pattern from Family. The recipe: split the label into characters, keep the characters that match at the same position, and animate only the ones that change (a short fade and an 8px slide, about 180ms, with a tiny stagger). ```tsx // inside Motion's AnimatePresence, mode="popLayout" text.split("").map((char, i) => ( {char} )); ``` The key, made of the position and the character, is what keeps shared letters mounted. Good pairs share a start: Save → Saved, Connecting → Connected, 12 → 13. Skip it when nothing is shared (Cancel → Done: crossfade instead), for long sentences, and for translated text, where the shared letters change by language. ## Icons that morph Pick icons one after another and watch the big one. *[Interactive demo: Every icon is exactly three lines; spares collapse to an invisible dot.]* Benji Taylor built the Claude app's animated icons on one constraint: **every icon is three SVG lines**. An icon that needs only two collapses its third line to an invisible point at the center. Because every icon has the same shape of data, any icon can morph (Changing one shape smoothly into another in front of the viewer, so it reads as the same object changing rather than two objects swapping) into any other by moving coordinates. Two strategies, depending on the pair: - **Different shapes** (menu → close, plus → check): interpolate each line's coordinates. - **Same shape, different direction** (the four arrows, or plus → × by 45°): just rotate. It's cheaper and reads more clearly as the same object turning. It works for a small active set (play/pause, expand/collapse, chevrons, a dot → ring → check status), roughly 5 to 20 icons. It's stroke-only, so filled icons and big marketing sets belong to a normal icon pack. When two stock icons can't share a schema, like copy → check, swap them with a deep scale instead: `scale 0.3 → 1`, opacity `0 → 1` and `blur(3px) → 0`, a 0.35s spring with no bounce. A timid 0.8–0.9 scale looks like a glitch. > **In plain words.** A **morph** changes one shape into another in front of you. A **crossfade** fades one thing out while another fades in on top of it. ## When you must crossfade, add blur Some swaps are between things that can't morph: two photos, two illustrations, a sun and a moon. Tap the icon several times in each mode. *[Interactive demo: Halfway through a plain crossfade you see two ghosts. Blur turns them into one soft shape.]* Jakub Antalik's most reused trick: pair the crossfade (Fading one thing out while another fades in on top of it. Fine for unrelated content; halfway through it shows two ghost images, which blur can hide) with a small blur, 2px on desktop and 4px on phones, on the same timing. ```css .swap { opacity: 0; filter: blur(2px); transition: opacity 250ms var(--ease-out), filter 250ms var(--ease-out); } .swap[data-state="visible"] { opacity: 1; filter: blur(0); } ``` At the midpoint of a plain crossfade, both images sit at half opacity, a double exposure your eye reads as two objects. Blur replaces that moment with one out-of-focus shape that resolves into the next. Don't blur text (it reads as broken focus), don't use it on hover, and test anything bigger than ~400px on a slow phone. *(Blur is cheap to move but expensive to draw on big surfaces.)* ## Animated icons: hover by default, a trigger for everything else If you ship animated icons as components, the pattern from lucide-animated.com is worth copying. The icon plays on `:hover` of its button with zero setup, which is fast, needs no JavaScript and can fire on keyboard focus too. But touch screens have no hover, and some moments aren't hovers at all (a "saved" celebration, an onboarding sequence). So the component also exposes an imperative handle: ```tsx const ref = useRef(null); // the like button: onClick={() => ref.current?.trigger()} // the heart icon component receives ref={ref} and plays when trigger() is called ``` Gate the hover rule behind `@media (hover: hover)` so taps don't leave icons stuck mid-animation. Don't add `trigger()` to icons that don't animate, and don't wrap a permanently spinning loader in a ref. **Morph instead of swap (paste into your agent):** ```text For the submit button that changes from "Continue" to "Confirm", keep the shared letters ("Con") in place and animate only the changing characters (opacity and 8px translateY, ~180ms) using AnimatePresence mode="popLayout" with keys of index+char. For icon swaps that can't morph (copy → check), use scale 0.3 → 1, opacity, and blur(3px) → 0 with a spring { duration: 0.35, bounce: 0 }. For image crossfades, add filter: blur(2px) (4px on mobile) on the same timing as the opacity. Never blur text. ``` **Check yourself:** A theme toggle swaps a sun icon for a moon. What's the best transition? - [ ] An instant swap - [ ] A plain opacity crossfade - [x] A crossfade paired with a small blur (2px desktop, 4px mobile) on the same timing - [ ] Scale the sun down to 0, then the moon up from 0 *Why:* The shapes are too different to morph, and a plain crossfade shows two ghosts at the midpoint. Cross-blur makes that moment one soft shape. Scaling from 0 is the balloon again. ## In the skill - https://school.agents.org.in/skill/motion/shared-letter-morph.md - https://school.agents.org.in/skill/motion/morphing-icons.md - https://school.agents.org.in/skill/motion/cross-blur-transitions.md - https://school.agents.org.in/skill/motion/hover-default-imperative.md --- # Gestures, sheets and trays > Make drags, flicks and bottom sheets feel native, from velocity on release to presses that land on moving things. Module: Motion · Level: advanced · 10 min · https://school.agents.org.in/design/motion/gestures Drag the sheet down slowly, about a third of the way, and let go. It snaps back. Now flick it down from the same spot. It's gone. *[Interactive demo: Drag slowly, then flick. Switch to 'position only' to feel what's missing.]* With "position only", the sheet ignores how you let go. A quick flick near the top snaps back, and it feels like the app didn't listen. With velocity, a throw is a throw. When a drag "feels off", it's almost always one of three things: **no velocity on release, no resistance at the edges, or no pointer capture.** ## The three fixes **Velocity on release.** Measure how fast the finger was moving when it lifted. Above roughly 0.11 pixels per millisecond, treat it as a flick and dismiss in that direction; below, snap to whichever position is closer. Don't compute the velocity (How fast and in which direction something is moving, often in pixels per millisecond. Measured when a finger lifts, it tells a flick from a slow release) from the last two events; one late event can halve or double it. Keep the last ~20 pointer samples and measure across the final ~100ms, using each event's own timestamp. **Resistance at the edges.** Drag the sheet *up* past its open position: it moves, but less and less. That's Apple's rubber band (The resistance you feel when dragging past an edge on iOS: the content follows less and less the further you pull, then springs back when you let go): ```ts // x = distance past the edge, d = the container's size const rubberband = (x: number, d: number, c = 0.55) => (x * d * c) / (d + c * Math.abs(x)); ``` Near the edge it follows at about 55% of the finger; far past it the offset levels off, so no drag can fling content off-screen. A hard stop feels like hitting a wall. **Pointer capture.** Call `setPointerCapture(e.pointerId)` on pointer down, and the drag keeps tracking even when a fast finger leaves the element. Also ignore second fingers (`if (!e.isPrimary) return`) so a stray touch doesn't break the gesture. > **In plain words.** **Velocity** is speed with a direction, here in pixels per millisecond. **Pointer capture** tells the browser "keep sending this finger's moves to me until it lifts". ## After the finger lifts A flick is a small input asking for a big output. The sheet above does two more things, both from Apple's *Designing Fluid Interfaces* talk as Emil Kowalski distilled it. **Project, then pick.** Work out where the flick would come to rest, the way scrolling decelerates, then snap to the target nearest *that* point, not the release point: ```js const project = (v /* px/s */, d = 0.998) => (v / 1000) * d / (1 - d); const target = nearestSnapPoint(current + project(releaseVelocity)); ``` At 1000px/s that's about 500px ahead; a gentle 200px/s stays on its current snap. Decide commit-or-reverse by the velocity's **direction**: a sheet dragged 70% open and flicked down closes. **Hand the speed to the spring.** Start the spring with the release velocity so there's no seam between finger and animation. Projection without the hand-off picks the right target and then starts from rest, which looks like a stall. A few more rules for interruptible motion: - Start any new animation from where the element is **drawn**, never from where it was heading. - Never lock input during a transition. Grab a closing sheet and it follows your finger at once. - Keep the **grab offset**: the element stays where your finger took it, never recentred. - Two-dimensional throws get **one spring per axis**. ## Presses on moving things A stack of toasts slides up after you dismiss one. You press the same spot three times quickly. Which toasts close? Cheng Lou's answer, measured in his handwired project: test presses against where each item is **heading**, not where it's drawn. Then three quick presses close three toasts, the way rapid clicks close Safari tabs one after another. Test against the drawn position and only the first press lands; the rest hit the gap a toast is still sliding into. This is called hit testing (Working out which element a press landed on. For things still animating, test against where they are heading, so quick repeated presses land where people expect). - **A press** goes to the destination. **The start of a drag** grabs what's drawn under the finger. - **While dragging**, pin the spring to the pointer (position and target both follow it), so there's no springy lag. - **After release**, keep the item above its neighbours until it settles, or it slides *under* them on the way home. - **In a scrolling list**, select on release, not on press: a press that starts a scroll would otherwise select every row it touches. ## Trays: Benji Taylor's six rules A tray (A sheet that rises from the bottom over the current screen for one short task; the next step stacks over it. Each tray has a title, a dismiss and its own height) is a sheet that rises from the bottom over the current screen, and the next one stacks over it. Family, the crypto wallet Benji Taylor designed, is built on them. *[Interactive demo: A send flow in trays: three heights, one job each, the screen still there behind.]* **Step: User-initiated.** Trays open because someone tapped something. Never on load or on a timer; that's a banner's job. **Step: Heights vary.** Each tray in a stack is noticeably taller or shorter than the last. Same-height trays look like nothing happened. This is the rule teams break most. **Step: One job each.** One question, one choice, one form. A second question is a second tray. **Step: Title and dismiss, always.** A clear title, an × button, tap-outside and swipe-down to close (with velocity, not "more than 50px"). **Step: Overlay, don't navigate.** The previous screen stays visible, dimmed, behind. You've risen a layer, not left. **Step: Short tasks only.** Confirm, enter a code, pick a person, rename. Onboarding, settings and long forms get real screens. *(The tray in the demo is one tall sheet moved with transform, so its edge glides without animating height.)* ## On a phone app If you build for React Native or Expo, the same rules apply with three changes: there's no hover, there are two threads, and a finger is on the element. Emil Kowalski's digest: - Run motion on the UI thread with **Reanimated**, gestures with `Gesture.Pan()`, and never `setState` inside a gesture handler. - **Use the platform's navigation** (native stack, form sheets, native tabs). Tabs never slide. - Springs for anything a finger touched, with the release velocity: settle `{ duration: 400, dampingRatio: 1 }`, sheet `{ duration: 300, dampingRatio: 0.8, velocity }`. - Press is `scale: 0.97` in 100–150ms; targets 44pt (48dp on Android), grown with `hitSlop` rather than visually. - **Haptics on the causal frame**, once per action: a light impact when something snaps home, a notification for success or error. Never as the only feedback. - Judge feel on a **release build** on your slowest phone. The simulator hides exactly the problems that matter. **A sheet that feels native (paste into your agent):** ```text Make the bottom sheet draggable with pointer events: setPointerCapture on pointerdown, ignore non-primary pointers, keep the grab offset. Past the open position apply a rubber band (x*d*0.55 / (d + 0.55*|x|)). On release, compute velocity over the last ~100ms of samples (event timestamps). Dismiss if velocity > 0.11 px/ms downward or it's past halfway; reverse if flicked up. Hand the release velocity to a spring { stiffness: 380, damping: 30 } and start from the drawn position. Never block input during the animation. ``` **Check yourself:** A user flicks a sheet downward quickly but releases it only 20% of the way down. What should happen? - [ ] Snap back open, because it's less than 50% down - [x] Dismiss it, because the release velocity says the user threw it - [ ] Stop exactly where it was released - [ ] Bounce several times, then settle open *Why:* Above roughly 0.11 px/ms the release reads as a throw, so the direction of the velocity decides, not the position. Ignoring it is why position-only sheets feel like they didn't listen. ## In the skill - https://school.agents.org.in/skill/motion/gesture-momentum.md - https://school.agents.org.in/skill/motion/momentum-projection.md - https://school.agents.org.in/skill/motion/animated-hit-testing.md - https://school.agents.org.in/skill/motion/tray-rules.md - https://school.agents.org.in/skill/motion/react-native-motion.md --- # Smooth, kind and checked > Keep animation smooth on slow phones, respect people who ask for less motion, and debug or review motion before it ships. Module: Motion · Level: intermediate · 10 min · https://school.agents.org.in/design/motion/performance-and-review Tap a property you might animate. Some cost the browser almost nothing per frame. Others make it recalculate the whole page, sixty times a second. *[Interactive demo: What each property costs per frame, and what to animate instead.]* A screen redraws 60 times a second (16.7ms per frame), and a 120Hz phone gives you 8ms. Design against 8. One layout pass on a busy page can take longer than that by itself. ## Cheap properties only There are three tiers. **Composite**: the browser hands a finished picture to the graphics chip and slides it around; that's `transform` and `opacity` (and, in current browsers, `filter` and `clip-path`). **Paint**: it redraws pixels every frame, like `box-shadow` or `color`. **Layout**: it re-measures everything and moves the neighbours, like `width`, `height`, `top`, `margin`. **Animate transform and opacity; swap everything else down a tier.** Size becomes `scale()`, position becomes `translate()`, showing and hiding becomes `opacity`, a growing shadow becomes the opacity of a layer that already has it. A collapsing panel uses `grid-template-rows: 0fr → 1fr` rather than animating `height`. **Before (avoid):** ```css .card { transition: all 300ms; } .card:hover { width: 320px; box-shadow: 0 12px 32px #0002; } ``` **After (do this):** ```css .card { transition: transform 200ms var(--ease-out); } .card:hover { transform: translateY(-2px); } ``` ## The rest of the discipline Most jank is self-inflicted. From Emil Kowalski's performance notes: - **Name the properties.** `transition: all` watches every style change. Tailwind's bare `transition` class compiles to the same thing; use `transition-transform` or `transition-[opacity,transform]`. - **`will-change` is a targeted fix, not a sprinkle.** Add `will-change: transform` only to an element where you've seen a first-frame hitch. On every card, it eats graphics memory and fixes nothing. - **Never animate a CSS variable on a shared parent**; every child recalculates. Vaul's drawer got laggy at ~20 items for exactly this reason. - **Frames never go through React state.** Write per-frame values through refs, the Web Animations API or the library's own loop. In Motion, the string `transform: "translateX(100px)"` is hardware-accelerated; the `x: 100` shorthand runs on the main thread, which only hurts when the page is busy. - **Use CSS for planned motion** that has to stay smooth while the page loads. Vercel's dashboard tab indicator dropped frames during navigation until a CSS animation replaced a JavaScript one. - **Virtualize lists past ~50 rows**, pause off-screen loops, reserve space for images and loading content, and mute all transitions for a frame while switching themes so colors don't tween in a ragged cascade. When it stutters, name the cause before changing code, in this order: a non-composite property, jank that lines up with loading, React re-rendering per frame, slowdown as content grows, an animated CSS variable, a large blur, and only then `will-change`. ## Reduced motion Some people set their device to reduce motion (A device setting people turn on when movement makes them unwell or distracted. Interfaces should drop slides, zooms and parallax, but keep short fades): people with vestibular conditions, for whom sliding and zooming cause real nausea, and others who simply prefer less. Try each setting here. *[Interactive demo: Four ways to honour the setting. Only one is right; one is a real bug.]* Reduced motion doesn't mean "no animation"; it means **no travel**. Drop large slides, zooms, parallax, autoplay and spinning loaders. Keep short opacity fades and color changes, which explain a change without moving anything. ```css @media (prefers-reduced-motion: reduce) { .modal { transform: none; transition: opacity 150ms ease-out; } } ``` In React with Motion, `useReducedMotion()` lets you set the slide distance to 0 and keep the fade. Some teams take the stricter line and remove the fades too; either way, ship the reduced version with the animation, not later. *(The worst bug: text that starts at opacity 0 and only fades in under "no-preference".)* The worst bug is in the demo's last mode. If an entrance starts from `opacity: 0` and the animation only runs when motion is allowed, people who reduce motion never see the content at all. The reduced state is the **finished** state. Test with the setting on. ## Debugging: watch it slowly Open this popover at full speed. It looks fine. Now try 10%. *[Interactive demo: A bug that only shows when you slow down. Then apply the fix.]* At full speed, the eye can't see that the box finishes growing while it's still half see-through, because its scale and opacity run on different curves and times. At quarter speed it's obvious. Almost every "it feels off" bug is visible at 25% and invisible at 100%. **Step: Slow it down.** Chrome DevTools has an Animations panel with 10%, 25% and 50% playback, no code changes needed. Or wrap a Motion app in its MotionConfig component with `transition={{ duration: 2 }}`. Scope any `!important` speed hack to the one component, and never ship it. **Step: Look frame by frame.** Record in the Performance panel. Frames over 16ms, and layout or paint during an animation, point at the property you're animating. **Step: Use a real phone.** Connect it over USB and inspect it (Safari's Develop menu for iPhone, `chrome://inspect` for Android). Desktop throttling doesn't model a weak graphics chip. **Step: Record before and after.** A fix to one animation quietly changes others. Record the same interaction twice and compare by moments (the click, the peak, the settle), not milliseconds. When you review someone else's motion, slow it to 25% before you approve it. **Make motion fast and kind (paste into your agent):** ```text Audit the animations in this app. Replace any transition: all (including Tailwind's bare transition class) with named properties. Rewrite animations of width, height, top, left, margin or box-shadow to use transform, opacity, or the opacity of a pre-shadowed layer. Remove blanket will-change. Add a prefers-reduced-motion: reduce block for each animated component that removes translate and scale but keeps a short opacity fade, and make sure no content stays at opacity 0 when motion is reduced. Tell me which animations you checked at 25% speed and what you found. ``` **Check yourself:** With reduced motion on, a hero heading never appears. Its CSS sets opacity: 0 and runs a fade-in only inside @media (prefers-reduced-motion: no-preference). What's the fix? - [ ] Set every animation to 0ms with !important - [x] Make the visible, finished state the default and only add the hidden start state when motion is allowed (or keep a short fade under reduce) - [ ] Remove the heading for those users - [ ] Use a spinner while the heading loads *Why:* The reduced state must be the finished state. The start state (opacity: 0) belongs inside the motion-allowed rule, or the reduced path keeps a short fade so the text still arrives. ## In the skill - https://school.agents.org.in/skill/motion/transform-opacity-only.md - https://school.agents.org.in/skill/motion/performance-discipline.md - https://school.agents.org.in/skill/motion/prefers-reduced-motion.md - https://school.agents.org.in/skill/motion/debugging-animations.md --- # Color you can do math with > Read and write colors in OKLCH, build an even color ramp from one hue, and get an agent to migrate a hex palette without breaking it. Module: Color, depth and surfaces · Level: beginner · 8 min · https://school.agents.org.in/design/surface/oklch Drag the **L** slider below. The color gets lighter, and it stays the same blue. Now drag **H**: the hue spins round the wheel, and the color stays exactly as light. That is the whole trick of this lesson. *[Interactive demo: One color, three numbers. The ramp underneath is built from the same hue.]* ## Three numbers you can read Most colors on the web are written as hex (The familiar #3b82f6 style of writing a color: amounts of red, green and blue in base 16. Easy for screens, meaningless to read: you can't tell how light #3b82f6 looks): `#3b82f6`. A screen understands that. A person doesn't. You can't look at `#3b82f6` and know whether it is light or dark, or what happens if you nudge it. OKLCH (A way of writing a color as three numbers: L (how light it looks to a person), C (how vivid) and H (which hue, as an angle). Because the numbers follow what eyes see, you can do math with them) writes the same blue as `oklch(0.623 0.188 260)`, three numbers in a row: - **L**, lightness (How bright a color looks to a person, from 0 (black) to 1 (white). In OKLCH it is measured, so two colors with the same L really look equally light): how bright it looks to a person, 0 (black) to 1 (white). - **C**, chroma (How vivid a color is. 0 is gray; around 0.3 is as saturated as most screens go. The highest chroma you can use depends on the hue and the lightness): how vivid. 0 is gray; around 0.3 is the loudest most screens show. - **H**, hue (Which color it is, as an angle on a wheel: about 25 is red, 90 yellow, 145 green, 260 blue, 330 pink): which color, as an angle. Roughly 25 red, 90 yellow, 145 green, 260 blue, 330 pink. > **In plain words.** OKLCH is a way of writing colors where the numbers mean what they say. Two colors with the same L really look equally light, so you can build palettes, fix contrast and make dark mode with simple arithmetic instead of guesswork. ## Why not HSL? You may have met HSL (An older color notation (hue, saturation, lightness). Its lightness is a guess: yellow and blue at the same HSL lightness look nothing alike, so ramps built in HSL come out uneven), which also has a "lightness". The problem is that it lies. Toggle between the two rows below: at "50% lightness" HSL's yellow glows and its blue sinks. OKLCH's L 0.7 is one level across every hue. *[Interactive demo: The gray bars measure how light each swatch really looks.]* A ramp spaced on HSL inherits that lie: some steps jump, others barely move, and the light tints drift toward violet. **Never generate a scale in HSL.** ## Building a ramp A ramp (One hue in a row of steps from nearly white to nearly black, usually numbered 50 to 950. A palette is a few ramps, not a pile of colors) is one hue in eleven steps, named 50, 100, 200 … 900, 950. The recipe the skill teaches has four parts, and you can watch each one in the demo above. **Step: Anchor L and space it evenly.** Step 50 sits near L 0.97, step 950 near L 0.22, and the steps between are evenly spaced. Even spacing is the point: every neighbor looks equally far apart. Never run to pure 0 or 1, where the color stops reading as its hue. **Step: Shape chroma as a curve.** Give each step a share of the most chroma it can hold: about 30% at the ends, rising to about 85% around 400–500. Tints stay airy, shades stay rich. **Step: Clamp per step.** The ceiling moves with lightness, so a vivid blue necessarily loses chroma toward both ends. That is the geometry of color, not a bug. **Step: Keep the hue fixed.** One H for all eleven steps. If an inherited scale wanders more than about 10° end to end, rebuild it on its middle hue. ## Colors a screen can't show Push **C** up in the first demo and a warning appears: "past sRGB". OKLCH can name colors no ordinary screen shows. The range a screen can show is its gamut (The set of colors a screen can actually show. OKLCH can name colors outside it; those get clamped to the nearest one the screen can display), and its edge moves with hue and lightness. At L 0.5, violet can go to C 0.29 while cyan tops out near 0.09. So two hues never share one chroma number. A brand blue, a success green and a warning amber feel like one family when each sits at the **same L** and the **same share of its own ceiling**. When a value goes past the edge, clamp it yourself: keep L and H, lower C until it fits. Left alone, the browser maps it in a way you didn't choose. ```css .cta { background: oklch(0.66 0.2 330); } /* safe everywhere */ @media (color-gamut: p3) { .cta { background: oklch(0.66 0.32 330); } } /* extra punch on wide-gamut screens */ ``` That second line is for Display P3 (A wider gamut than standard sRGB, found on most recent phones and Macs. Extra-vivid colors can be layered on for these screens with a media query), the wider gamut on recent phones and Macs. *(The punch goes in the P3 layer. Raising the base color's chroma breaks it on every ordinary screen.)* ## Migrating a hex palette Moving an existing file to OKLCH is a value-for-value swap. Nothing else in the file should change: not the order, not the comments, not the gradient shapes. Watch an agent do it properly. *[Interactive demo: The agent converts values, keeps keywords, and flags a contrast problem instead of quietly fixing it.]* The rules it followed: 1. Hex first, then `rgb()`/`rgba()`, then `hsl()`. 2. Alpha goes behind a slash: `rgba(255,255,255,.12)` becomes `oklch(1 0 0 / 0.12)`. 3. Never convert keywords (`currentColor`, `transparent`, `inherit`) or anything a third-party library reads as hex. 4. Re-check contrast on the pairs that matter, and report every changed line, old beside new. **Migrate a palette to OKLCH (paste into your agent):** ```text Migrate the colors in src/styles/tokens.css to oklch(). - Value for value: hex first, then rgb()/rgba(), then hsl(). Alpha goes after a slash. - Keep comments, order and indentation; don't touch keywords (currentColor, transparent) or hex a library parses. - Clamp anything out of sRGB by lowering chroma, holding L and H. - Re-run contrast on text pairs and list any that fail 4.5:1. Don't fix them silently. - Report every changed line: old value, new value, one-clause reason. ``` **Check yourself:** A brand teal and a brand violet should feel equally vivid. What do you copy between them? - [ ] The same C value, e.g. 0.2 - [x] The same L and the same share of each hue's own chroma ceiling - [ ] The same hex brightness - [ ] The same HSL saturation *Why:* Cyan-ish hues have a far lower chroma ceiling than violet. Copying one C over-saturates the roomy hue or flattens the tight one; matching L and the share of each ceiling keeps them a family. ## In the skill - https://school.agents.org.in/skill/surface/MOC-surface.md - https://school.agents.org.in/skill/surface/color-scales-oklch.md - https://school.agents.org.in/skill/surface/oklch-gamut-and-migration.md --- # One neutral, one accent > Build a palette from a gray ramp and one accent, give every step a job, and name your colors so a dark theme is a five-minute change. Module: Color, depth and surfaces · Level: beginner · 8 min · https://school.agents.org.in/design/surface/palette Here is the same little project list twice. Flip between them and notice where your eye goes first. *[Interactive demo: Six colors compete; one accent leads.]* With a color per thing, everything shouts and nothing wins. In grays with one blue, your eye lands on the blue button and the one live project, which is exactly where it should land. ## The whole palette is about fourteen colors The skill's recipe, borrowed from how Linear, Vercel and Notion work: 1. One neutral (The gray ramp that carries most of an interface: backgrounds, borders and text. It can be pure gray or tinted very slightly warm or cool) ramp, 8 to 12 steps of gray. Pure gray is fine; a hint of warm or cool is nicer. 2. One accent (The one saturated brand color, kept for what you can act on: the main button, links, the selected item. It works because almost nothing else is colorful), saturated and deliberate, kept for things you can act on. 3. Optionally, quiet status colors (danger, warning, success) for the states your product actually shows. That's it. A tokens file with sixty colors isn't richer; it's undecided. > **The purple gradient.** A violet-to-fuchsia gradient, or "a different bright color per card", is the single most recognizable sign of a generated page. Gradient text on a hero headline counts too. Delete it first. Three small rules keep the set coherent: - **Neutrals share the brand's temperature.** A blue brand wants cool grays. An untinted `#808080` next to a tinted surface reads as a placeholder. - **Light tints come from lower chroma, not lower opacity.** A see-through accent turns gray on some backgrounds. - **Disabled gets its own token**, never `opacity: 0.5`, which passes contrast on one surface and fails on the next. ## Every step has a job A ramp (One hue in a row of steps from nearly white to nearly black, usually numbered 50 to 950. A palette is a few ramps, not a pile of colors) isn't a gradient to pick from by eye. Each step exists because some part of the UI uses it: the page background, the hover state, the border, the button fill, the text. Tap a role below and watch which parts of the card light up. *[Interactive demo: Tap a role. Toggle the names to see Tailwind's numbers and Radix's.]* Two naming styles exist. Tailwind numbers steps **by lightness** (50 is lightest), so in dark mode the mapping flips. Radix numbers them **by role** (step 9 is always the solid fill, in light and dark), so component CSS never changes. Match the project you're in; for a new system the role model is kinder. Notice the line under the card. **Solid fills sit on 600, not 500**, because white text on most 500 hues fails the 4.5:1 contrast you'll meet in the next lesson. A few more rules that hold across every palette: - **One color, one meaning.** Hues within about 15° look like the same color, so a link blue and a decorative blue heading are one meaning used twice. - **Status sits at least 15° from the accent.** A red brand can't also use red for "delete"; give destruction a distinct treatment. - **One filled button per view.** The fill is what says "primary" from across the room. ## Name colors by job, not by look Now the part that makes a palette survive a redesign. Tokens come in two tiers. Primitives (A token that names a raw value by what it is, like --blue-600. Primitives never get used directly inside a component) name a value: `--blue-600`, `--neutral-200`. They say what the color *is* and never change meaning. Semantics (A token that names a job, like --color-bg-page, and points at a primitive. Components use only these, so a dark theme just repoints them) name a job and point at a primitive: `--color-text-secondary: var(--neutral-700)`. **Components use only these.** *[Interactive demo: Switch to dark. The primitives and the component stay as written; only the arrows move.]* That's why the split matters. If a component says `--blue-600` directly, adding dark mode means reading every usage to guess which ones meant "the accent". If it says `--color-accent-solid`, dark mode repoints one line. **Named by look (avoid):** `--color-blue-button`, `--color-sidebar-gray`, `--color-light-gray` (which is the dark one in dark mode), `--color-text-2`. **Named by job (do this):** `--color-accent-solid`, `--color-bg-surface`, `--neutral-200` (a primitive), `--color-text-secondary`. Two naming rules from Jakub Krehel's work save real pain: - **One word per concept.** Pick `text`, `bg`, `border`, `accent` and never mix in `fg`, `foreground` or `brand`. Someone who has seen `--color-text-primary` should be able to guess `--color-text-disabled`. - **Call the brand `accent`, not `primary`.** Otherwise `--color-primary` (the brand) sits next to `--color-text-primary` (body text), the most common collision there is. Build against a full list of roles from day one (page, surface, raised, sunken; text primary, secondary, disabled, on-accent; border subtle, default, strong, focus; separator), not one token at a time as screens ask. *(Separator and border are two roles even when they share a color today. They split the first time someone restyles inputs.)* **Set up a palette (paste into your agent):** ```text Build our color tokens: - One neutral ramp (11 steps, OKLCH, slightly cool to match the blue brand) and one accent ramp. Status colors only for danger and success, each ≥15° of hue from the accent. - Two tiers: primitives named by hue and step (--blue-600), semantics named by role (--color-bg-page, --color-text-secondary, --color-accent-solid). Components use semantics only. - Solid fills on step 600. Disabled gets its own tokens, never opacity. - Before restructuring anything existing, list every color literal in the repo, sorted by hue and lightness, and show me the inventory first. ``` **Check yourself:** A component uses bg-blue-600 directly. You're adding dark mode. What's the fix? - [ ] Add a dark: variant on that component - [x] Point the component at a semantic token like --color-accent-solid, and repoint that token for dark - [ ] Lower the button's opacity in dark mode - [ ] Invert the colors with a CSS filter *Why:* Components should reference only semantic tokens. Then dark mode (or any theme) repoints the semantics in one place and no component changes. ## In the skill - https://school.agents.org.in/skill/surface/color-monochromatic.md - https://school.agents.org.in/skill/surface/palette-step-roles.md - https://school.agents.org.in/skill/surface/color-token-tiers.md --- # Contrast you can read > Check text against 4.5:1 and APCA, repair a failing pair by moving lightness only, make hover states raise contrast, and pick the space a gradient mixes in. Module: Color, depth and surfaces · Level: beginner · 8 min · https://school.agents.org.in/design/surface/contrast The gray in this box is `#999` on white, the most popular "subtle" text color on the web. Read the paragraph, then look at the score. *[Interactive demo: Drag the text's lightness, or press the fix. Only L moves.]* 2.85:1. It fails. Light gray on white looks calm and refined in a mockup, and on a sunny phone or a tired pair of eyes it simply isn't there. ## What the numbers mean A contrast ratio (How different the text color is from its background, as a number like 4.5:1. Body text needs at least 4.5:1 to be readable for most people; large text 3:1) compares how light the text is with how light its background is. 1:1 is invisible; 21:1 is black on white. The rule most laws point to comes from WCAG (The Web Content Accessibility Guidelines, the standard most laws point to. Its contrast rule is the familiar 4.5:1 for body text and 3:1 for large text): | Text | Needs at least | |---|---| | Body text | **4.5:1** | | Large text (about 24px, or bold from about 18.5px) | **3:1** | | Icons, borders, focus rings | **3:1** | APCA (A newer contrast formula that models how people actually perceive text, scored as Lc: about 75 for body text, 60 for labels, 45 for headlines) is a newer formula that tracks how people actually perceive text, especially light text on dark. It scores in **Lc**: 75 or more for body text (90 is better), 60 for labels, 45 for headlines, 30 as the floor for icons and disabled states. The skill's advice: **run both, pass both.** > **In plain words.** WCAG's 4.5:1 is the legal line. APCA is the better eye test. A color pair that clears both reads well for nearly everyone. ## Fix contrast by moving L only Here is where OKLCH from the first lesson pays off. Contrast lives almost entirely in the gap between the two **lightness** values. Chroma and hue barely move it. So to repair a failing pair, push the text's L away from the background's L and leave C and H alone. "Make it more saturated so it pops" does nothing for readability. A fast triage before you measure: - On near-white backgrounds (L 0.85 and up), text wants L 0.45 or below. - On near-black backgrounds (L 0.25 and down), text wants L 0.75 or above. - Anything with L above about 0.6 wants dark text on it. **Before (avoid):** `color: #999;` on white. 2.8:1, fails body text. **After (do this):** `color: oklch(0.5 0 0);` on white. 6:1, passes. Same hue, same chroma, lower L. Two more traps: - **No text on a see-through color.** A color with alpha mixes with whatever is under it, so no single measurement describes it. Text sits on solid tokens. - **Text on a gradient** has a different contrast at every pixel. Measure the worst spot, not the average, or put a solid scrim behind the words. ## Hover should raise contrast, not lower it A common reflex is to fade a button on hover. Backwards. The skill's rule: hover makes an element a little *more* contrasty, pressed more again. **Disabled is the only state that lowers contrast**, and it does so with its own tokens, not opacity. ```css .button { background: var(--bg-elevated); border-color: var(--border-default); } .button:hover { background: var(--bg-elevated-hover); border-color: var(--border-strong); } .button:active { background: var(--bg-elevated-active); } .button:disabled { background: var(--bg-disabled); color: var(--text-disabled); } ``` ## Tell the browser which theme you drew Two small declarations make the browser's own parts match your page. `color-scheme` (A CSS property that tells the browser whether to draw its own parts (scrollbars, form controls) light or dark. Declare only the themes you actually designed) tells it whether to draw scrollbars, checkboxes and `` menus stay light. - **Images** get a white 10% inset outline instead of the black one. - **The phone's status bar**: one `theme-color` per scheme, matched to the top of the page. ## Half done is broken A dark mode with one white modal, one light dropdown or one black logo on black makes the whole product look broken. The skill treats it as a blocker, not a nit. If the theme isn't finished, don't ship the toggle and don't declare `color-scheme: dark`. That is also why this course has no dark mode: one well-made theme beats two half-made ones. **Build a dark theme (paste into your agent):** ```text Add a dark theme by remapping our existing scale, not inverting it: - Surfaces: near-black (e.g. #18181b), getting lighter as they rise (card, menu, dialog). No pure #000. - Elevation in dark is a lighter surface plus a ring (0 0 0 1px rgb(255 255 255 / .09)), not shadows. Dividers stay solid grays. - Text: 92% white primary, 62% secondary, only on one known surface; elsewhere solid tokens. - Repoint semantic tokens in a .dark block; no per-component dark: overrides. - Desaturate the accent 20–30%. SVGs use currentColor. Set color-scheme: dark and a dark theme-color. - Re-check every text pair for contrast and list the results. ``` **Check yourself:** In a dark theme, how should a dropdown menu show it floats above a card? - [ ] A bigger, darker shadow - [x] A lighter surface than the card, with a faint white ring - [ ] Pure black, to stand out - [ ] A bright accent border *Why:* Shadows have nothing to fall on in the dark. Higher layers are lighter surfaces, and a low-opacity white ring defines the edge. ## In the skill - https://school.agents.org.in/skill/surface/dark-mode.md --- # Glass and layers > Use translucent surfaces where they help orientation, keep text on them legible, and stack layers with a plan instead of z-index 9999. Module: Color, depth and surfaces · Level: intermediate · 7 min · https://school.agents.org.in/design/surface/glass-and-layers Scroll the photos under the toolbar. The bar is see-through, so you never lose track of what's behind it. *[Interactive demo: Drag the sliders, then stack a second glass layer on top and watch the label drown.]* That is what a translucent material (A see-through, blurred surface (CSS backdrop-filter) such as a toolbar that content scrolls under. Its job is to keep you oriented, not to decorate) is for. A see-through bar lets content run under the chrome instead of losing a fixed strip of screen to it, and keeps you oriented. Chosen for looks alone, it fails at both. ## Glass by hierarchy Emil Kowalski distils Apple's guidance into a few rules: - **Heavier, more opaque glass for structure** (sidebars, tab bars), lighter for the interactive bits you want noticed. - **Never light glass on light glass.** Two blurs compound and text legibility collapses. Make one of them solid. (That's the second switch above.) - **Bigger reads thicker.** A full sheet gets more blur and a deeper shadow than a small chip. ```css .toolbar { background: rgb(255 255 255 / 0.6); backdrop-filter: blur(20px) saturate(180%); border-top: 1px solid rgb(255 255 255 / 0.4); /* a lit top edge */ } ``` ## Modal or parallel A **modal task**, one that blocks everything until you answer, pairs its surface with a scrim (A dark see-through layer laid over the page behind a dialog, which pushes the page back so the dialog has your full attention): a dark see-through layer that pushes the page back. A **parallel** panel that you work beside stays translucent with no scrim, so your flow isn't broken. When glass appears, let it *materialize*: animate the blur and a slight scale together, so it arrives as a material rather than fading in like a ghost. ## Text on glass Flat mid-gray text dies over a backdrop that keeps changing. On glass: - raise the contrast and step the weight up one, - add a hair of letter-spacing (about 0.01em), - put brand color on a solid layer, never on the see-through foreground, - measure contrast over the **worst** thing the bar can sit on. And respect the people who asked for less of it: ```css @media (prefers-reduced-transparency: reduce) { .toolbar { background: var(--surface); backdrop-filter: none; } } @media (prefers-contrast: more) { .toolbar { background: var(--surface); border-color: var(--border-strong); } } ``` > **Glass that renders flat.** `backdrop-filter` only blurs what is painted behind the element inside its own group of layers. A parent with `overflow: hidden`, a `transform` or `isolation` can leave it sampling nothing, so the glass shows as a flat tint. Check in Safari and Firefox. That warning leads straight into the second half of this lesson: layers. ## Who's on top When things overlap, CSS draws them in order. `z-index` (The CSS number that decides which overlapping thing is drawn on top. It only competes with siblings inside the same stacking context) changes the order. Here is the same screen with three different strategies; each one is real CSS painting live. *[Interactive demo: Magic numbers bury the toast. A transform traps the modal under the header.]* `z-index: 9999` is a confession that nobody knows the order. The skill, drawing on Cheng Lou's notes, gives three tools, in order of preference: **Step: No z-index at all.** Later elements in the HTML paint over earlier ones. Arrange the markup so source order matches stacking order and most layers need nothing. **Step: One global file for app-wide layers.** Nav, menus, tooltips, modals and toasts compete across the whole app, so give them sequential constants in a single file, in order. Adding a layer means inserting one line in the right place. **Step: Local numbers inside an isolated group.** When a component's own parts must overlap, wrap it in `isolation: isolate` and use 1 and 2 inside. Nothing escapes the wrapper, so local numbers can't collide with global ones. ```ts let d = 1 export const nav = d++, contextMenu = d++, tooltip = d++, modal = d++, toast = d++ ``` ## The sealed box The "transformed parent" case is the one that confuses everyone. Some properties turn an element into a stacking context (A sealed group of layers. Things inside it are sorted among themselves and the whole group is drawn as one layer, so a z-index of 9999 inside can't beat something outside): a sealed box of layers. Everything inside is sorted among itself, then the whole box is painted as one layer. A child with `z-index: 9999` beats its siblings and nothing outside. What creates the box: a `z-index` on a positioned element, `position: fixed` or `sticky`, `opacity` below 1, and the quiet ones, **`transform`, `filter` and `will-change: transform`**. That's the classic bug. Someone adds a `transform` for an entrance animation, or `will-change` "for performance", and a modal inside can no longer rise above the header, while a tooltip that used to escape its card gets clipped. *(After adding any animation to a container, re-check what's drawn on top.)* **Fix the layers (paste into your agent):** ```text Clean up stacking in this codebase: - List every z-index. Remove the ones DOM order already handles. - App-wide layers (nav, menu, tooltip, modal, toast) become sequential constants in one file; no magic numbers like 50 or 9999. - Components that overlap internally get isolation: isolate and local values 1–2. - Flag any transform, filter or will-change on a container that holds a modal, menu or tooltip. - Translucent bars: no light glass on light glass; add prefers-reduced-transparency and prefers-contrast fallbacks to a solid surface. ``` **Check yourself:** A modal has z-index: 9999 but still appears under the sticky header. What's the likely cause? - [ ] 9999 isn't high enough; use 99999 - [x] A parent of the modal has a transform (or similar), making a stacking context it can't escape - [ ] The header has position: sticky - [ ] The modal needs opacity: 1 *Why:* Inside a stacking context, z-index only competes with siblings. Move the modal out (a portal) or remove the property that created the context. ## In the skill - https://school.agents.org.in/skill/surface/translucent-materials.md - https://school.agents.org.in/skill/surface/z-index-strategy.md --- # A type scale and its rhythm > Set every text size from a short scale named by role, give each step the right line-height and tracking, and load fonts so nothing fakes or jumps. Module: Typography · Level: beginner · 8 min · https://school.agents.org.in/design/typography/type-scale Pick a ratio below. Every size on the page recalculates from one base number, and each step already knows its line spacing and letter spacing. *[Interactive demo: One base, one ratio, five roles. Change either and the whole page moves together.]* That list is a type scale (A short, fixed list of text sizes a product is allowed to use, often each one a set ratio bigger than the last. Every piece of text picks a step instead of a one-off size). It is the single most effective thing you can do for text on a screen, and the thing generated UIs skip most often. ## Why a short list beats free choice When every component picks its own size (15px here, 17px there, 13.5px in a badge), the page feels cramped in one spot and airy in the next, and nobody can say why. The cause is one-off sizes. A scale is a short, closed list. A new size needs a reason. Two common ways to build one: - **A ratio**: each step is the last one times 1.2 or 1.25, starting from a 16px body. - **A stock scale**, like Tailwind's `text-sm`, `text-base`, `text-lg`. Both are fine. What matters more is the **names**. On a team, name steps by role, `text-caption`, `text-card-title`, `text-page-title`, because a role polices itself in a way `text-lg` can't. Nobody puts a page title in `text-caption`. > **In plain words.** A type scale is a menu of five or six text sizes. Every piece of text orders from the menu. It makes the page feel consistent even when nobody can say why. Sizes go in rem (A CSS unit relative to the root font size (usually 16px). Sizes in rem grow when a reader sets a bigger default text size; px sizes ignore them), not px, so a reader who bumped up their browser's text size gets bigger text. Pixels are for hairlines, not words. ## Leading follows the role Leading (The vertical space from one line of text to the next. Body text wants about 1.5 times the font size; big headings about 1.1) is the space between lines, set in CSS as `line-height`. - **Body text: 1.5 to 1.6.** Paragraphs need room for the eye to find the next line. - **Headings and display: about 1.1.** Big letters carry their own space; 1.5 on a headline looks like double spacing. And always **unitless**. Push the slider below as if the reader zoomed in. *[Interactive demo: Fixed 24px leading stacks lines on top of each other as the text grows. Unitless 1.5 grows with it.]* `line-height: 24px` looks identical to `1.5` at 16px, then breaks on the first size change or zoom. Space between paragraphs is about one line-height, not some arbitrary pixel number. ## Tracking follows the size Fonts are spaced for body sizes. At headline sizes that spacing looks loose; on tiny labels it looks cramped. So: | Size | Letter-spacing | |---|---| | Tiny uppercase labels | about **+0.06em** | | Body, 14–18px | **0** | | Headings, 20–48px | **−0.01 to −0.03em** | | Display, 64px+ | **−0.04em** or so | Track in `em`, so it scales with the text. You'll play with this properly in the next lesson. ## Files that load cleanly Three rules from Emil Kowalski's practice stop the most common font bugs: 1. **Ship woff2 (The compressed font file format every modern browser reads. It is the only format a website needs to ship) and nothing else.** It's compressed and universal. A `.ttf` in `public/fonts` is a bug. Load only the weights you use. 2. **`font-synthesis: none` at the root.** Ask for a bold you never loaded and the browser fakes one by smearing the letters (faux bold (When a page asks for a bold or italic the font didn't load, the browser fakes one by smearing or slanting letters. font-synthesis: none turns that off so the problem is visible)). Turn that off so a missing file looks missing. 3. **Use the high-level property, not the raw code.** `font-weight: 620`, not `font-variation-settings: "wght" 620`; `font-variant-numeric: tabular-nums`, not `"tnum" 1`. Properties still do something sensible when a fallback font loads; raw codes silently do nothing. ```css :root { font-synthesis: none; -webkit-font-smoothing: antialiased; } ``` Light weights are size-bound: a 300 weight that looks elegant at 32px is unreadable at 11px. ## Never change weight on hover or select One last trap, and it's everywhere. Click through these tabs in both modes. *[Interactive demo: Bold-on-select pushes every label after it sideways. Color doesn't move anything.]* Bold letters are wider, so the selected word grows and shoves its neighbours. **Hold the weight constant and show state with color** (or an underline). *(The same goes for hover: a menu item that turns bold under the pointer makes the whole row twitch.)* ## Pairing, briefly Two typefaces cover most products; three is the ceiling. Pair across categories, a serif for display over a sans for text, never two similar sans faces, which read as an accident. And because two families at the same `font-size` rarely look the same size (the x-height (How tall a font's lowercase letters are. Two fonts at the same font-size can look very different sizes because of it) decides), re-tune sizes whenever you swap a face. **Set up type (paste into your agent):** ```text Set up our typography: - A closed type scale of 5–6 steps in rem, named by role (text-caption, text-body, text-card-title, text-section, text-page-title). Replace every one-off font-size with a step. - Unitless line-height: 1.5–1.6 for body, ~1.1 for headings. Paragraph spacing ≈ one line-height. - Tracking in em: 0 for body, -0.01 to -0.03em for headings, +0.06em for small uppercase labels. - woff2 only, only the weights we use; font-synthesis: none on :root; high-level properties instead of font-variation-settings. - No font-weight change on hover or selected states; use color. ``` **Check yourself:** A heading is set with line-height: 32px. What's wrong with it? - [ ] Nothing, 32px is a good value - [x] It's fixed: when the font size changes or the reader zooms, the lines overlap or gape. Use a unitless value like 1.1 - [ ] Headings shouldn't have a line-height - [ ] It should be in rem *Why:* Unitless line-height scales with the font size. A fixed pixel value breaks on the first size tweak or zoom. ## In the skill - https://school.agents.org.in/skill/typography/MOC-typography.md - https://school.agents.org.in/skill/typography/type-scale-and-rhythm.md --- # Line length and tracking > Keep paragraphs between 45 and 75 characters a line, tighten big type and open tiny labels, and choose how headings and blurbs wrap. Module: Typography · Level: beginner · 7 min · https://school.agents.org.in/design/typography/line-length This paragraph starts too wide on a laptop. Pull the width slider left until the count turns green, and read it again. *[Interactive demo: The count is how many characters fit on a line at that width. Widen your window to see very long lines.]* The text didn't change. The reading did. ## 45 to 75 characters The number of characters per line is called the measure (How many characters fit on one line of a paragraph. 45 to 75 reads comfortably, about 65 is the sweet spot). Robert Bringhurst's rule, which typographers have used for decades: **45 to 75 characters**, with about 65 as the sweet spot for prose. Why it matters: your eye reads a line, then swings back to find the start of the next. Too long and it loses its place on the way back. Too short and the constant swinging turns reading into work. In CSS it's one line, thanks to the ch unit (A CSS unit equal to the width of the digit 0 in the current font. max-width: 65ch makes a column roughly 65 characters wide): ```css .prose { max-width: 65ch; } /* Tailwind: max-w-prose */ ``` *(Re-check when you change font: the same width holds a different number of characters in a different face.)* On a wide screen this means a narrow column with space either side. That's correct. A 2,400px-wide paragraph is not "using the space", it's unreadable. ## Tracking: tighter as type grows Tracking (Extra space added evenly between all letters. Big headings want it slightly tighter (negative), tiny uppercase labels slightly looser) is space added evenly between all letters (`letter-spacing`). It runs opposite to size. Drag the size up to a headline, then find the spacing that looks right. *[Interactive demo: The band is the skill's starting range for each size. Snap applies it.]* | Size | Tracking | |---|---| | 10–12px | **+0.04 to +0.08em** (often uppercase) | | 14–18px body | **0** | | 20–28px | **−0.01 to −0.02em** | | 32–48px | **−0.02 to −0.04em** | | 64px+ | **−0.04 to −0.06em** | **Forgetting to tighten display text is one of the most common amateur tells.** A 56px headline at default spacing looks loose and slightly cheap. Don't confuse tracking with kerning (The font's own spacing adjustments between specific letter pairs, like AV or To. Unlike tracking, it is built into the font and should stay on), the font's own fixes for specific pairs like "AV". Kerning is built in and stays on. ## Uppercase has rules All-caps text is harder to read because every letter is the same height. Use it only: - at small sizes (10–12px) with wide tracking, for nav, badges and table headers, - or for very short phrases, under about four words. Never for paragraphs. And be careful with the tiny tracked label above every heading (the "eyebrow"): taste-skill's gallery study found it on more than half of weak sites and a sixth of strong ones. Usually its words belong in the heading itself. ## Choose how lines break Two newer CSS values decide where lines wrap. Try them on a narrow column. *[Interactive demo: balance evens a heading's lines; pretty saves a blurb's last word.]* - **`text-wrap: balance`** for headings. It evens out the line lengths so you don't get a long line and a one-word line. - **`text-wrap: pretty`** for card blurbs, standfirsts and empty-state copy. It stops the stranded last word, the orphan (A single short word left alone on the last line of a paragraph or heading. It looks like a mistake; text-wrap: pretty fixes most of them). - **Neither on long paragraphs.** Browsers cap balance at a few lines, and a balanced paragraph narrows every line. These two (CSS that controls where lines break. balance evens out the lines of a heading; pretty stops a paragraph ending on one stranded word) are supported in current Chrome and Safari, so you can ship them without a fallback; older browsers simply wrap normally. ## Left-aligned, almost always The ragged right edge is the eye's landmark. Justified text without hyphenation opens "rivers" of white space; centered text works for a short headline and fails past two lines. **Fix reading comfort (paste into your agent):** ```text Tune the reading experience: - Cap every reading column at max-width: 65ch (check the count again if the font changes). - Letter-spacing by size, in em: 0 for body, -0.02em around 32px, -0.04em at 64px+, +0.06em on small uppercase labels. - text-wrap: balance on h1–h3; text-wrap: pretty on card descriptions and empty states; nothing on article paragraphs. - Left-align body copy. Uppercase only for short labels at small sizes. ``` **Check yourself:** A blog post's paragraphs run the full 1200px width of a laptop. What's the fix? - [ ] Increase the font size until it fits - [x] max-width: 65ch on the text column - [ ] text-wrap: balance on the paragraphs - [ ] Justify the text *Why:* Long lines make the eye lose its place. A 65ch column keeps lines in the 45–75 character range. Balance on paragraphs would quietly narrow them; justify opens rivers. ## In the skill - https://school.agents.org.in/skill/typography/line-length-tracking.md - https://school.agents.org.in/skill/typography/line-behavior.md --- # When text runs out of room > Decide per field whether text wraps, truncates at the end or the middle, or stays whole; stop long words breaking boxes; and hold the size and contrast floors. Module: Typography · Level: intermediate · 7 min · https://school.agents.org.in/design/typography/when-text-runs-out Three files, all named almost the same. Narrow the column with end-truncation on, and try to tell which is which. *[Interactive demo: End, middle, or wrap. Tap a row to see the full name.]* With end-truncation they all become `Q3-board-report-fi…`. Identical. Switch to middle-truncation and the part that differs, the end, survives. ## Truncation deletes information Truncation (Cutting text off with an ellipsis (…) when it doesn't fit. Only allowed when there is a way to see the full text, such as a tooltip or detail view) means cutting text with an ellipsis (…). The skill treats it as deleting information, so it is only allowed **with a route back** to the whole string: a tooltip that also opens on keyboard focus, an expand control, or a detail view. A clipped ID with no way to read it is data loss wearing CSS. Choose per field, never one rule for the whole app: | Field | Do this | |---|---| | What identifies the thing (a name, a page title) | **Wrap.** Two lines is fine; four means the column is too narrow. | | Secondary info whose start matters (a role, a message preview) | **End-truncate.** | | Things that differ at the end (file names, paths, hashes, emails on one domain) | **Middle-truncate.** CSS can't; split the string in code and keep the tail. | | Card previews | **Clamp at 2 lines** with `line-clamp` (CSS that cuts text after a set number of lines, adding an ellipsis. Used to keep card previews the same height) so cards stay one height. | | Prices, counts, dates, IDs | **Never cut.** Widen the column or truncate the label beside them. | The CSS for the two common cases: ```css .one-line { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } .preview { display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2; overflow: hidden; } ``` ## Guard against overflow both ways Two opposite failures, each with one line of CSS. **A long word punches out of its box.** A URL, a hash or a user's 40-letter username has nowhere to break, so it pushes past the card edge. Add `overflow-wrap: anywhere` (CSS that lets a very long word, like a URL or a code, break onto the next line instead of punching out of its box) wherever user text, links or codes can appear. *(Not `break-word`: it looks the same but leaves the element's minimum width alone, so a flex item still overflows.)* **A short phrase breaks where it shouldn't.** A badge that wraps to "In / review", or a button label split over two lines, reads as a bug. Those get `white-space: nowrap`. **Before (avoid):** A comment card with `https://example.com/projects/acme/issues/4821?view=board` running straight off its right edge. **After (do this):** The same card with `overflow-wrap: anywhere` on its body: the URL breaks onto a second line inside the card. ## Casing and punctuation are presentation - **Store copy in sentence case.** If a label should look uppercase, use `text-transform: uppercase`. ALL-CAPS in the source gets rewritten at the next redesign and some screen readers spell it out. - **Type real punctuation.** Curly quotes in prose (“like this”), an en dash for ranges (Mon–Fri), an em dash for asides, the single ellipsis character …, and a non-breaking space between a number and its unit (`12 MB`) so they never split. Code keeps straight quotes. ## Underlines that look designed Default underlines often slice through descenders and sit at a random thickness. Take the metrics from the font: ```css a { text-decoration-thickness: from-font; text-underline-position: from-font; text-decoration-skip-ink: auto; } ``` A dotted underline means "there's more here", which is why the glossary terms in this course have one. Never underline something that isn't a link. And if you want an animated underline, only its *color* animates reliably; a growing line is a separate element. ## The floors A few numbers you never go under: - **Inputs at 16px or more on phones.** Below that, iPhone Safari zooms the whole page when you tap the field. Don't "fix" it with `maximum-scale=1`; that removes zoom for everyone, an accessibility failure. - **Body 16px, dense controls 14px, captions 13px.** Under 12px needs an unusual excuse. - **Contrast 4.5:1 for body, 3:1 from about 24px**, as in the surface module. - **Direction-neutral CSS**: `text-align: start` and `padding-inline-start` instead of left, and a `lang` on the page, so the layout mirrors for right-to-left languages. **A typography fix should be the smallest diff.** It never restructures markup unless an expandable truncation or an animated underline needs an element. **Handle long and short text (paste into your agent):** ```text Review how text fits in these components: - Per field, choose: wrap (names, titles), end-truncate (secondary metadata), middle-truncate (file names, paths, hashes) or line-clamp: 2 (card previews). Never cut prices, counts, dates or IDs. - Every truncation needs a way to the full string (tooltip that also opens on focus, expand, or detail view). - overflow-wrap: anywhere wherever URLs or user text appear; white-space: nowrap on badges and button labels. - Inputs at least 16px on mobile; never maximum-scale=1. - Sentence case in source, text-transform for caps; real quotes, dashes and … in copy. ``` **Check yourself:** A list shows file paths that share a long common prefix. How should they be shortened? - [ ] End-truncate with an ellipsis - [x] Middle-truncate, keeping the end where they differ, with a way to see the full path - [ ] Shrink the font until they fit - [ ] Hide the paths *Why:* End-truncation makes them identical. Middle-truncation keeps the distinguishing tail, and the full path stays reachable. ## In the skill - https://school.agents.org.in/skill/typography/line-behavior.md --- # Numbers, features and faces > Line numbers up with tabular figures, reach the extras inside a font file, and choose a typeface that doesn't read as the default. Module: Typography · Level: intermediate · 7 min · https://school.agents.org.in/design/typography/numbers-and-faces Watch the right-hand column of this price table for a few seconds. Then flip the switch. *[Interactive demo: Proportional digits jiggle as they tick. Tabular digits hold still.]* Most fonts draw a "1" narrower than an "8", which looks lovely in a sentence and terrible in a column. Every update shifts the number sideways and nothing lines up. ## Tabular figures for anything that changes Tabular figures (Digits that all take the same width, so numbers line up in columns and a ticking counter doesn't wiggle. Turned on with font-variant-numeric: tabular-nums) give every digit the same width. Columns align, and a ticking timer only moves the digits that actually changed. ```css .price, .timer, td.number { font-variant-numeric: tabular-nums; } ``` Use them on timers, prices, counters, scores, table columns of figures, anything live. Leave running prose on the default figures, which read more naturally in a sentence. Numbers people compare also right-align, so the decimal points stack. ## What's hidden in a font file A good font carries far more than one set of letters. These extras are called OpenType features (Optional extras hidden inside a font file: tabular digits, a slashed zero, real fractions, small caps, alternate letters. CSS switches them on), and CSS switches them on. Try a few on Inter, the face this demo uses: *[Interactive demo: A slashed zero for codes, real fractions, and a weight axis that takes any number.]* The useful ones: - **`slashed-zero`** wherever 0 and O can be confused: order codes, serial numbers, coupons. - **`diagonal-fractions`** for ½-style fractions in recipes and specs. - **Real small caps (Capital letters drawn at about lowercase height, designed to match the weight of the text. Shrinking normal capitals instead makes them look thin)** with `font-variant-caps: small-caps`, never shrunken capitals, which come out too thin. - **Real superscripts** (m², CO₂) with `font-variant-position: super | sub`, instead of the default `^{`, which is too big and pushes lines apart.
- **Stylistic sets** (`ss01` to `ss20`) are numbered slots whose meaning differs in every font. Read the font's specimen, then comment what the slot does: `font-feature-settings: "ss02" 1; /* single-storey a */`.

> **Features fail silently.** If the font doesn't contain the feature, nothing happens and nothing warns you. Check that the glyphs exist, and prefer the named CSS property over raw four-letter codes, because properties fall back sensibly.

## Variable fonts and their axes

A variable font (One font file that holds a whole range of a style, usually weight, so any value like font-weight: 473 is real instead of only 400 and 700) is one file holding a whole range of a style. Weight is the common one, which is why the slider above accepts 430 or 610, not just 400 and 700. Each range is an **axis**:

| Axis | Varies | Set it with |
|---|---|---|
| `wght` | weight | `font-weight` |
| `wdth` | width | `font-stretch` |
| `opsz` | optical size (Versions of a typeface tuned for a size: sturdier and looser for small text, finer and tighter for big headlines. Some fonts adjust it automatically) | `font-optical-sizing: auto` |
| `slnt` / `ital` | slant, italic | `font-style` |

A font exposes only the axes it was built with. One or two weights usually ship lighter as separate static files; many weights or an optical-size axis favour the variable file. Measure rather than assume.

Some families ship separate cuts for size, like Text and Display versions of one design: sturdier and looser for paragraphs, finer and tighter for headlines. Pick the cut for the size you set.

## Choosing a face that isn't the default

Now the human part. Flip between these three versions of the same hero.

*[Interactive demo: The default, a pair across categories, and one family doing everything.]*

Inter and SF Pro are excellent, neutral and on nearly every generated page. That ubiquity is the problem: on a landing page, the stock face at stock weights signals "default" before anyone reads a word.

The skill's advice:

- **On marketing pages, pick something with character.** Foundries worth knowing include Pangram Pangram, Displaay, Grilli Type and Vercel's Geist. Pair across categories when you use two (a serif display over a sans text face), never two lookalikes.
- **Inside the product, Inter or SF Pro are fine.** They were built for screens and stay legible at 12px. But then you have used your one default: don't also ship the default colors and the default icons.
- **The single-weight rule.** For a first version, use **one weight** of one face for everything and get hierarchy from size and space. It's cheaper, faster and usually cleaner. Add weights when a real need shows up.

**Test the face at every size you actually use.** Geometric faces that look great at 16px can turn to mush at 11px, which is when Inter's boring legibility wins. *(A typeface is a tell only on surfaces where people judge the brand. In a dense settings screen, legibility is the brand.)*

**Numbers and fonts (paste into your agent):**

```text
Typography details pass:
- font-variant-numeric: tabular-nums on every price, timer, counter and number column; right-align compared figures.
- Use named CSS properties for font features (font-variant-numeric, font-variant-caps, font-variant-position, font-weight); font-feature-settings only for stylistic sets, with a comment saying what the slot does in this font.
- slashed-zero on order codes and serials.
- Marketing pages: propose two typefaces that aren't Inter/SF Pro, paired across categories, and start with a single weight. Keep Inter for dense product UI.
```

**Check yourself:** A dashboard counter updates every second and the number shivers sideways. What's the one-line fix?

- [ ] letter-spacing: -0.01em
- [x] font-variant-numeric: tabular-nums
- [ ] font-weight: 600
- [ ] text-align: center

*Why:* Tabular figures give every digit the same width, so only the digits that change move and nothing shifts.

## In the skill

- https://school.agents.org.in/skill/typography/opentype-features-and-axes.md
- https://school.agents.org.in/skill/typography/typography-humanity.md

---

# Grouping by space

> Show what belongs together with space before lines or boxes, keep controls looking like controls, and line everything up on a few shared edges.

Module: Layout and pages · Level: beginner · 7 min · https://school.agents.org.in/design/layout/grouping-by-space

This form has two groups, and right now you can't tell. Every gap is 16px. Drag the second slider to 32px.

*[Interactive demo: Same fields, same boxes. Only the gaps changed.]*

Suddenly there are two sections, and you never added a line, a card or a heading color. That's grouping by space (Showing which things belong together just by putting them closer to each other than to anything else. The gap between groups is at least twice the gap inside one), and it's the cheapest structure in design.

## Space, then shape, then line

Our eyes read things that sit close together as one group. Designers call it proximity (The tendency to read things that sit close together as one group. It is the cheapest structure in design: no lines or boxes needed). A divider, a card and a tinted background all say "these belong together"; space says it without adding a single pixel of ink.

The skill's order, from Jakub Krehel's layout rules:

**Step: Space.** The gap **between** groups is at least **2×** the gap **inside** one. 8px inside means 16px or more between.

**Step: A background shape.** Only when space alone is ambiguous: a sunken well, a raised card.

**Step: A line.** Last, where neither works: a dense table, a long settings list. A divider that space could carry is a deletion.

Turn on the divider switch in the demo with the ratio already at 2×. It adds nothing; the space had already done the job.

> **More padding is not grouping.** "Add more whitespace" makes every gap bigger and equal. Equal gaps say nothing belongs together. **The ratio is the point, not the size.**

## Controls look like controls

Clean screens sometimes strip buttons down until they look like plain text. Every interactive thing needs something that says "press me": a background shape, a border, an underline, or a consistent home such as a toolbar.

**Before (avoid):**

"Edit · Share · Delete" in the same gray text as the paragraph above them. They read as a sentence.

**After (do this):**

Three small buttons with a quiet background shape, in a toolbar row. They read as things you can press.

## A few shared edges

Pick a small set of alignment edges (An invisible vertical line that several elements start from. Fewer edges make a page look calm; text starting on many different lines looks ragged) and put everything on them. Text that starts on six different vertical lines looks ragged even when every element is fine on its own.

Use one spacing step per level of nesting (16px is a useful default), and take your steps from a spacing scale (A short list of allowed gaps (for example 4, 8, 12, 16, 24, 32px) that every margin and padding picks from, so spacing stays consistent) if the project has one. If it does, use its steps; the numbers in this lesson are starting points for projects that don't.

## Clearance between controls

How far apart should two buttons be? It depends on whether you can see their edges.

| Between | Starting gap |
|---|---|
| Bordered or filled controls (buttons, inputs) | **12px** |
| The visible glyphs of borderless text or icon buttons | **24px** |
| Unrelated groups of controls | **24px** or more |

With borderless buttons nothing marks where one ends, so the space *is* the boundary. Tap areas can be bigger than the visible glyph, but they never overlap.

## Edges, bleeds and the one primary action

- **Inset buttons from the screen edge.** A full-width button on a phone sits about 16px in from each side, with the bottom safe area added below it. Glued to three edges, it looks like system chrome and clips on curved corners.
- **Content bleeds, controls float.** Backgrounds and images can run to the edge of the screen (full bleed (A background or image that runs right to the edge of the screen, past the margins. Content can bleed; text and controls stay inside the margins)); text and buttons stay inside the margins.
- **One primary action (The one thing you most want people to do on a screen, usually the one filled, strongest button. A screen should have one) per view.** Past three secondary actions, the rest go behind a menu.

A full-bleed image inside an article, in one line of grid:

```css
.article { display: grid; grid-template-columns: 1fr min(65ch, calc(100% - 48px)) 1fr; }
.article > * { grid-column: 2; }
.article > .full-bleed { grid-column: 1 / -1; }
```

*(Before reaching for a card or a border, try doubling the gap. It's usually enough.)*

**Group by space (paste into your agent):**

```text
Rework the spacing on this screen:
- Group with space first: gaps between groups at least 2× the gaps inside a group (e.g. 8px inside, 16–24px between). Use our spacing scale's steps.
- Remove dividers and cards that space already carries; keep lines only for dense tables and long lists.
- Every control must look interactive: a background shape, border, underline or a toolbar zone.
- 12px between bordered controls, 24px between borderless text/icon buttons.
- Put text on a small number of shared left edges. One primary action per view.
```

**Check yourself:** Fields inside each form section are 12px apart, and sections are 12px apart too. What's the smallest fix that makes the sections readable?

- [ ] Add a divider line between sections
- [x] Raise the gap between sections to 24px or more
- [ ] Put each section in a card
- [ ] Make the section headings bigger

*Why:* Space groups first. With between-group gaps at least twice the inside gaps, the sections separate without any extra ink.

## In the skill

- https://school.agents.org.in/skill/layout/MOC-layout.md
- https://school.agents.org.in/skill/layout/grouping-by-space.md

---

# The page frame, on every screen

> Get the frame readers judge first right (equal margins, no holes, a first screen that says what this is) and design each screen size on purpose.

Module: Layout and pages · Level: beginner · 8 min · https://school.agents.org.in/design/layout/page-frame

This little landing page has four faults that readers notice before they read a single word. The pink marks show where. Fix them one switch at a time.

*[Interactive demo: Lopsided margins, a half-empty section, a hole, and a headline that says nothing.]*

Before anyone notices a typeface or a shadow, they judge the frame (The overall shape of a page that readers judge before any detail: its margins, how the width is used, the gaps between sections, and whether the first screen says what this is). Their complaints sound vague ("everything is shifted to one side", "big random blank spaces", "I can't tell what this is"), but each one is measurable.

## Five measurable rules

taste-skill measured 97 award-winning sites in October 2026, and the strong pages agree on these:

| Rule | Fails when |
|---|---|
| **One pair of equal margins** | The left and right distances differ, or the header sits on one inset and the page on another. |
| **Text never touches the edge** | Under 16px on desktop, under 12px on a phone. |
| **Use the width you set up** | A text section sits in one half with nothing in the other. Give the empty half the section's picture, a second column or a list. |
| **No holes** | Over about half a screen holds nothing, or the gap between two sections passes about 40% of a screen. |
| **Say what this is, first** | The first screen's headline is missing, or only a slogan. 15 of the 97 sites never said what the product was, and lost marks for it. |

And: give every section of 30+ words a heading, and start most text on the same few left edges.

Spacing that holds the frame: sections about **120–240px apart on desktop** and **72–112px on a phone**, the gap between sections clearly larger than any gap inside one, and at least twice as much space above a heading as below it.

## A rest is not a hole

Empty space is fine when something frames it: a picture with the type docked to its edge, a headline big enough to span it. When nothing closes it off, it's a hole (A stretch of a page with nothing in it and nothing closing it off, like a giant gap between sections. Different from a deliberate rest, which something frames). Holes usually come from stretched section gaps, text in one half of the width, or content waiting on a scroll animation to appear.

**When a section looks empty, make its main element bigger or cut it.** Adding a decoration is almost never the fix. *(Scroll-triggered reveals cause holes: until they fire, that section is bare ground.)*

## Each screen size gets its own design

Responsive (Making a layout work on every screen size. Done well, each size gets its own composition, not a squeezed copy of the desktop one) doesn't mean "squeeze the desktop layout until it fits". It means each size gets a composition designed for it. Drag the frame's handle below; the layout answers to the frame, not your window.

*[Interactive demo: Wide: sidebar and a three-card grid. Narrow: a bottom tab bar and a row of cards that peeks so you know it scrolls.]*

Typical swaps from the skill:

| Desktop | Phone |
|---|---|
| Sidebar + content | Bottom tab bar + full-width content |
| 3-column card grid | A swipeable row, or a stack in a different order |
| Wide hero, image right | Stacked hero, image full width below |
| Dense table | One card per row with the key fields first |

What stays the same: the **components**. A button looks the same on every screen; the screen it's on changes.

That demo uses a container query (CSS that lets a component change its layout based on the width of the box it sits in, rather than the whole window. A card can then work in a sidebar and in a wide grid), so the component adapts to the box it sits in. Its breakpoints (The width at which a layout changes, for example from one column to two. Good breakpoints come from where the content stops fitting, not from a device list) are where the content stops fitting, not a device list.

## Narrow columns are valid

A common mistake is making content full-width because the screen allows it. A 2,400px paragraph is unreadable, so reading content keeps a narrow column (about 65ch) even on a huge monitor, as in the demo.

For everything else, a 12-column grid (A page divided into 12 equal columns. 12 splits into halves, thirds, quarters and sixths, so it fits most layouts) is the flexible base: 12 divides into halves, thirds, quarters and sixths. On marketing pages you can then break the grid on purpose (a pull quote that hangs into the margin, a bento of different-sized tiles). Inside the product, hold the grid; forms stay single-column, dashboards stay symmetric.

**Check the page frame (paste into your agent):**

```text
Review this landing page at 1440, 768 and 390 wide:
- One pair of equal left/right margins at each width; header and body share the same inset; no text closer than 16px (12px on phones) to the edge.
- No section with text in one half and nothing in the other; no empty run over half a screen; section gaps 120–240px desktop, 72–112px mobile.
- The first screen's h1 says what the product is, readable on first paint. Every section of 30+ words has a heading.
- Design the 390 layout on its own (tab bar, peeking card row, stacked hero) rather than shrinking desktop. Reading columns max 65ch.
```

**Check yourself:** A feature section has two lines of text on the left half and nothing on the right. What does the skill suggest?

- [ ] Add a decorative blob on the right
- [x] Give the empty half the section's picture, a second column or a list, or make the main element bigger
- [ ] Center the text
- [ ] Increase the section's padding

*Why:* Use the width you set up. An empty half reads as a hole; fill it with real content or enlarge the main element. Decoration is almost never the fix.

## In the skill

- https://school.agents.org.in/skill/layout/page-frame.md
- https://school.agents.org.in/skill/layout/viewport-custom-design.md

---

# Layouts that survive real content

> Stress-test a layout with long words, translations and big text, fix the classic overflow traps, and write CSS that mirrors itself for right-to-left languages.

Module: Layout and pages · Level: intermediate · 8 min · https://school.agents.org.in/design/layout/growth-and-overflow

This card looks finished. Now feed it real-world content: switch on German, a long URL, and 200% text. The CSS is live, so it breaks for real.

*[Interactive demo: Fits the mockup, fails the world. Then apply the fixes.]*

A layout that fits the copy in the mockup has been tested exactly once. Translations lengthen text, readers zoom, names are long and APIs return surprises. **Design for the worst content, not the sample.** That's a stress scenario (One realistic but hostile input for a component: the longest real name, zero items, a 320px box. You render them side by side to see what breaks before users do).

## Grow, don't clip

- **Size text containers with `max-width` and `min-height`**, never a fixed `width` or `height`. A `width: 96px; overflow: hidden` button is fine in English and cut in German.
- **Let rows wrap**: `flex-wrap: wrap; gap: 12px`.
- **If a box must cap its height**, pair `max-height` with `overflow-y: auto`, so the content scrolls instead of vanishing.
- **Short strings are the riskiest.** A one-word button can double in length in translation.
- **Never park a critical action where clipping can reach it**: the bottom of a modal taller than the screen, or anything the on-screen keyboard covers.

Test with pseudo-localization (Replacing interface text with longer, accented fake text (like [Ŝéţţîñĝš ~~~]) to see what breaks when real translations arrive): fake text like `[Ŝéţţîñĝš ~~~~]` that runs 30–40% longer, plus one long real language such as German.

## The overflow traps

Most "why is there a sideways scrollbar" bugs are one of these:

| You see | Fix |
|---|---|
| A grid column or flex child with long text pushes off-screen | `minmax(0, 1fr)` on the track, `min-width: 0` on the child |
| `width: 100vw` scrolls sideways on desktop | `width: 100%` (100vw includes the scrollbar) |
| `height: 100vh` panel cut off on a phone | `100dvh` (next lesson) |
| A modal taller than the screen | `max-height: 100dvh`, a scrolling body, the buttons outside the scroll area |

The first one has a name: min-content blowout (When a grid column or flex item refuses to shrink smaller than its longest word or widest table, pushing the layout off the side of the screen. minmax(0, 1fr) and min-width: 0 fix it). Grid tracks and flex items refuse to shrink below their longest unbreakable thing, so one URL can push a whole layout off the side.

```css
.layout { display: grid; grid-template-columns: 240px minmax(0, 1fr); }
.row > .text { min-width: 0; overflow-wrap: anywhere; }
```

> **overflow: hidden is not a fix.** Clipping the parent hides the sideways scrollbar and the content with it. Find the child that refused to shrink.

## Breakpoints and containers

Break where the layout stops fitting, not at 768px because a preset says so. Write queries in `rem`, so a reader with a larger default font gets the narrow layout sooner.

A reusable component should adapt to its container, not the window: `container-type: inline-size` on the parent, `@container (width < 400px)` on the child. Two traps: a container query can only style the container's children, never the container itself; and a container with no definite width (a shrink-to-fit flex item) collapses to zero.

## Hint at what scrolls

A row of cards that ends exactly at the screen edge looks complete, and nobody scrolls it. Let the next card **peek 16–32px**. A "Show more" button names what it hides: "Show 12 more results". Content scrolling under a sticky header uses `scroll-padding-block-start` so focused fields and anchor targets aren't hidden under it.

## Start and end, not left and right

Arabic and Hebrew read right to left. A layout written in `left` and `right` has to be rewritten for them; one written in *start* and *end* mirrors itself. Switch the direction below.

*[Interactive demo: Physical CSS stays put. Logical CSS mirrors, arrow included.]*

Logical properties (CSS written as start and end instead of left and right (margin-inline-start, text-align: start), so the layout mirrors by itself for right-to-left languages) are the start/end versions of every physical one:

| Physical | Logical |
|---|---|
| `margin-left`, `padding-right` | `margin-inline-start`, `padding-inline-end` |
| `left`, `right` (positioned) | `inset-inline-start`, `inset-inline-end` |
| `text-align: left` | `text-align: start` |
| Tailwind `ml-4`, `pl-4` | `ms-4`, `ps-4` |

Rules for RTL (Languages like Arabic and Hebrew that read from right to left. The whole layout should mirror for them, except things like logos, clocks and play buttons) from Jakub Krehel's work:

- **Keep visual order equal to DOM order.** Moving things with `order` or `row-reverse` makes keyboard and screen-reader order disagree with what's on screen.
- **Mirror only icons that point along the reading direction**: back and forward arrows, reply, progress chevrons. Never a play button, a clock, a checkmark or a logo.
- **Physical stays physical where the glass is physical.** Safe-area insets are about the phone's real left and right edges, so they need an RTL override.
- **Wrap mixed-direction values in `` (An HTML tag that isolates a piece of text whose direction may differ from its sentence, such as an English name inside Arabic, so punctuation lands on the right side)**, like the English company name inside the Arabic sentence above, so punctuation lands on the correct side.

*(Flipping `dir` in devtools checks the layout, not the content. Test with real RTL text and an English name inside it.)*

**Stress-test and fix (paste into your agent):**

```text
Stress-test this component and fix what breaks:
- Try pseudo-localized strings (+40%), German labels, a 120-character URL, a 40-character username and 200% text.
- Text containers use max-width/min-height, never fixed width/height; rows flex-wrap with gap.
- Grid tracks minmax(0, 1fr); flex children with text min-width: 0; overflow-wrap: anywhere on user text.
- width: 100% instead of 100vw; no overflow: hidden used to hide a scrollbar.
- Convert left/right to logical properties (margin-inline-start, text-align: start, ms-/ps- in Tailwind). Mirror only direction-bearing icons; wrap mixed-direction values in .
```

**Check yourself:** A two-column grid uses grid-template-columns: 240px 1fr, and a long URL in the main column makes the page scroll sideways. What's the fix?

- [ ] overflow: hidden on the body
- [x] grid-template-columns: 240px minmax(0, 1fr), plus overflow-wrap: anywhere on the text
- [ ] width: 100vw on the grid
- [ ] Shrink the font

*Why:* A 1fr track won't shrink below its min-content width. minmax(0, 1fr) lets it, and overflow-wrap lets the URL break inside it.

## In the skill

- https://school.agents.org.in/skill/layout/growth-and-overflow.md
- https://school.agents.org.in/skill/layout/logical-properties-rtl.md

---

# The phone's platform layer

> Make a web app feel installed on a phone with the right viewport tag, dvh and svh, safe areas, keyboard handling and overscroll, and know why each one exists.

Module: Layout and pages · Level: intermediate · 7 min · https://school.agents.org.in/design/layout/mobile-layer

Here's a web app on a phone, built edge to edge. Watch the title and the tab bar.

*[Interactive demo: Without insets the title hides under the Dynamic Island and the tabs sit on the home indicator. One line of CSS pads them back.]*

Most "it feels like a website on my phone" complaints aren't design problems. They're a handful of platform defaults (the address bar, the notch, the keyboard, the rubber-band bounce), each fixed by one declaration. Emil Kowalski's rule: reach for a media query or meta tag before JavaScript, and know the reason for every line.

## The baseline, before any component

```html

```

```css
html { -webkit-tap-highlight-color: transparent; -webkit-text-size-adjust: 100%; }
```

In Next.js these live in the root layout's `viewport` export. This course's own layout sets exactly these.

> **Never block zoom.** `user-scalable=no` and `maximum-scale=1` take zoom away from everyone who needs it. If an input zooms the page on tap, the input is under 16px: fix the input.

## Safe areas

`viewport-fit=cover` in that viewport tag (The line that tells a phone how to size the page. viewport-fit=cover lets the page paint under the notch so safe-area insets work) lets your page paint under the notch and the home indicator. Then `env(safe-area-inset-*)` tells CSS how big each covered edge is, so you can pad content back into the safe area (The part of a phone screen not covered by the notch or Dynamic Island, the rounded corners or the home indicator. env(safe-area-inset-*) tells CSS how big those edges are).

```css
.header { padding-top: env(safe-area-inset-top); }
.tabbar { padding-bottom: env(safe-area-inset-bottom); }
.fab { bottom: calc(16px + env(safe-area-inset-bottom, 0px)); }
```

Headers take the top, tab bars and sheets take the bottom, sidebars take left and right in landscape. **Without `viewport-fit=cover`, every inset is 0px**, which is why "I added safe-area padding and nothing happened" is so common.

## 100vh lies on phones

`100vh` is the screen height with the address bar *hidden*. On load the bar is showing, so a 100vh panel runs past the bottom, and its button is out of sight. Toggle the bar and the units below.

*[Interactive demo: vh assumes the bar is gone; dvh follows it; svh is the small, steady height.]*

The dynamic units (Viewport height units that understand phone browser bars. 100dvh changes as the address bar shows and hides; 100svh is the smaller, steady height. Plain 100vh assumes the bar is hidden):

- **`100dvh`** follows the bar as it shows and hides. Use it for app shells and anything pinned to the bottom.
- **`min-height: 100svh`** is the small, steady height. Use it for a hero, because a `dvh` hero re-lays-out mid-scroll and jumps.

Tailwind's `h-screen` carries the old bug; use `h-dvh` and `min-h-svh`. *(dvh everywhere is the overcorrection. Shells track the browser bar; first screens don't.)*

## The keyboard

iPhone shrinks the visible area when the keyboard opens; Android Chrome lays the keyboard over the page. `interactive-widget=resizes-content` makes Android resize too, so a chat composer at the bottom of a `100dvh` column rides up above the keyboard with no script.

Two more rules: a fixed bottom button hides the last form field, so pad the scroll area by the button's height plus the bottom inset; and never autofocus an input on a touch device, which throws the keyboard up uninvited.

## Scrolling and bounce

- **`overscroll-behavior` (CSS that controls what happens when you scroll past the end: the bounce, pull-to-refresh, or the page behind scrolling instead. contain keeps it inside a panel): `none` on the root** stops pull-to-refresh and the page bounce inside an app. Leave it off on a document where pull-to-refresh is welcome.
- **`contain` on inner scrollers** keeps their own bounce without dragging the page along.
- **Scroll lock behind a sheet** goes through a dialog primitive (Base UI, Radix, vaul). `overflow: hidden` on `body` is ignored by iPhone touch scrolling.
- **Never `touchmove` + `preventDefault()`**: it blocks scrolling and makes the listener slow.
- **Anchor links** clear a sticky header with `scroll-margin-top` equal to its height.

## The status bar

One `theme-color` per color scheme, matched to the top of your page (the header), not your brand color. If the theme can be toggled, update the tag too. An installed web app's manifest colors are the same decision.

## Prove it on a real phone

Emulators reproduce none of this. Serve your dev server on your network, open it on a phone by its LAN address, and debug through Safari's Develop menu (iPhone) or `chrome://inspect` (Android). Use a phone a few years old, open the keyboard, turn it to landscape once, and install it as a web app if you ship one.

**Phone platform pass (paste into your agent):**

```text
Make this web app feel native on phones:
- Viewport: width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content. No user-scalable=no or maximum-scale.
- Safe areas: header padding-top env(safe-area-inset-top), tab bar/sheets padding-bottom env(safe-area-inset-bottom, 0px), sidebars left/right in landscape.
- Heights: app shell 100dvh, hero min-height 100svh, never 100vh (h-dvh / min-h-svh in Tailwind).
- overscroll-behavior: none on html for the app, contain on inner scrollers; scroll lock through our dialog primitive.
- One theme-color per scheme matched to the header. Inputs 16px+. No autofocus on touch.
Tell me what to check on a real device.
```

**Check yourself:** You added padding-bottom: env(safe-area-inset-bottom) to the tab bar, but it still sits on the home indicator. What's missing?

- [ ] A bigger padding value
- [x] viewport-fit=cover in the viewport meta tag
- [ ] position: fixed
- [ ] A media query for iPhone

*Why:* Without viewport-fit=cover the page doesn't extend under the system areas, so every safe-area inset resolves to 0px.

## In the skill

- https://school.agents.org.in/skill/layout/mobile-platform-layer.md

---

# The URL, structure and scroll position

> Keep what the user sees in the URL so links and the back button work, arrange screens the way people think, and stop lists jumping when content loads.

Module: Layout and pages · Level: intermediate · 8 min · https://school.agents.org.in/design/layout/url-and-structure

Pick a tab, filter to "Assigned to me", change the sort. Then press "Open link in a new tab". Try it in both modes.

*[Interactive demo: State in memory resets when shared. State in the URL is the view.]*

When the view lived in component state, the new tab forgot everything. When it lived in the URL, the link *was* the view: same tab, same filter, same sort. And Back stepped through your changes.

## The URL is the source of truth

The rule from Vercel's interface guidelines: **anything a user can see right now should be rebuildable from the URL.** Paste it in a new tab and you land on the same view. That's URL as state (Keeping what the user is looking at (tab, filters, sort, open panel) in the web address, so a link, a bookmark or the back button brings back exactly the same view).

| State | Where | Example |
|---|---|---|
| The page | path | `/projects/acme/issues` |
| Tab | query parameter (The part of a URL after the ?, like ?tab=closed&sort=created. It is where page state such as filters lives) | `?tab=closed` |
| Filters | query | `?status=open,blocked&assignee=me` |
| Sort | query | `?sort=-updated_at` |
| Pagination | query | `?cursor=eyJpZCI6...` |
| Open panel or modal | query | `?modal=invite` |
| Search | query | `?q=auth+bug` |

What does **not** go in the URL: form drafts (local storage), login state (cookies), whether a toast is showing, hover and focus.

> **In plain words.** If you could send someone a screenshot of what you're looking at, the link should take them to the same thing. A link you can share, bookmark and go back to is a feature you get almost for free.

Three rules make it work:

- **Deep-link every modal.** `?modal=invite-team` should open the invite dialog straight from the link. That's a deep link (A link that opens a specific view inside an app, such as one open modal or one filtered list, instead of the home page).
- **One source.** Read state from the URL (`useSearchParams` in Next.js) and write through the router. Copying URL state into `useState` creates two versions that drift.
- **Back restores scroll.** Normal links and most routers do this; a custom scroll lock or an intercepted click often breaks it. Check yours.

## Structure the way people think

Information architecture (How a product's screens and features are grouped, named and connected, so people can find things. It is decided before any pixel is styled) decides what people can find before any pixel is styled. The rule under all of it: arrange and name things the way users think about them, not the way the code or the org chart is split.

- **Long settings get sections.** Past about a dozen options, split them under a side nav with named groups (Account, Billing, Notifications), each a short page.
- **Progressive disclosure (Showing what most people need first and revealing advanced options only when asked or when they become relevant)**: show what most people need; put rare options behind "Advanced", or reveal a feature when it becomes relevant. Benji Taylor describes how Family kept the basics at hand and revealed the rest by context.
- **Name by the user's words.** "Send messages in the background", not "Enable async relay mode".
- **Tabs are views of one thing** (this week / month / year), not unrelated destinations.
- **Two levels of menu, then stop.** Deeper than that, use pages with breadcrumbs and a URL.
- **Search logs are rename requests.** If people keep searching "invoices" and the nav says "Billing", rename it.

**Dead end (avoid):**

"Something went wrong." and a Back button.

**A way forward (do this):**

"That link expired. Request a new one." with the button that does it.

**Renaming beats restructuring.** Before redrawing the sitemap, check whether the labels are the problem; a label is a one-line fix.

## Keep the reader's place

One more way a page loses people: you're reading a chat log, older messages load above, and the message you were on jumps away. Try it with anchoring off, then on.

*[Interactive demo: Load older messages with anchoring off, then on. The highlighted message is where you were reading.]*

Scroll anchoring (Keeping the row you are reading in the same spot on screen when content above it loads or changes size, instead of letting the page jump) means tying the view to a row, not to a pixel offset. Cheng Lou's pattern:

**Step: Pick an anchor when the user scrolls.** The first row whose bottom is below the top of the view. Record how far it is from the top of the view.

**Step: When content changes, restore that distance.** After the new rows render, set the scroll position so the anchor row sits exactly where it was.

**Step: Detect user scrolling by value.** Compare the scroll position with the one you stored. Don't trust "a scroll event fired": your own scroll fires one too.

**Step: Store what the browser actually set.** Read the scroll position back after setting it, because browsers round. Storing the value you asked for makes the next frame think the user scrolled.

If you anchor in code, set `overflow-anchor: none` on that scroller so the browser's built-in anchoring doesn't move it a second time. For a simple page, the browser's own `overflow-anchor` is the cheaper option. *(A chat that was showing the latest message should keep showing it after a new one arrives.)*

**URL state and stable lists (paste into your agent):**

```text
Refactor this list page:
- Tab, filters, sort, search, pagination cursor and any open panel or modal live in URL query params. Read with useSearchParams, write through the router; no mirrored useState.
- Every modal is deep-linkable (?modal=...). Back must restore the previous view and its scroll position.
- When older items load above the view, keep the row in view anchored: record the first visible row's offset before the update and restore it after; set overflow-anchor: none on the scroller.
- Check the labels against what users search for and suggest renames before restructuring the nav.
```

**Check yourself:** A user filters a table and sends the link to a colleague, who sees the unfiltered table. What's the fix?

- [ ] Store the filters in localStorage
- [x] Put the filters in the URL query and read them from there
- [ ] Add a Share button that emails a screenshot
- [ ] Cache the filters on the server per user

*Why:* Visible state belongs in the URL, so a shared or bookmarked link rebuilds the same view.

## In the skill

- https://school.agents.org.in/skill/layout/url-as-state.md
- https://school.agents.org.in/skill/layout/information-architecture.md
- https://school.agents.org.in/skill/layout/scroll-anchoring.md

---

# Sticky headers and launch-ready pages

> Pick a header behaviour that isn't the generated default, never hijack the scroll, and ship public pages that load fast and preview well when shared.

Module: Layout and pages · Level: intermediate · 8 min · https://school.agents.org.in/design/layout/sticky-and-launch

Scroll the article in this frame with the default header. Then try the other three.

*[Interactive demo: Four headers. The first is on nearly every generated landing page.]*

The first one, 70% white, 12px blur, no edge, pinned on every page, has become a tell. Nothing about it is broken; it is simply what every generated site does.

## Pick a header on purpose

A sticky header (A top bar that stays pinned while the page scrolls under it (position: sticky). Useful, overused, and often given a blur that has become a tell) stays pinned while the page scrolls. The skill offers four choices:

- **Solid with a border.** The page color plus a 1px border. Calm, cheap to render, nothing to notice.
- **Hide on scroll down, show on scroll up.** It gets out of the way while you read and comes back the moment you head up toward it.
- **Not sticky.** For long reading (articles, docs), the nav can simply scroll away. The calmest option.
- **Blur, but tuned.** If you really want glass: about 6px of blur, your own page color at around 85%, a 1px bottom border, and only on marketing pages.

## Never hijack the scroll

Scroll hijacking (When a page intercepts your scroll and does something else: snapping between sections, playing an animation, or slowing down. It makes the scroll feel broken) is a page that takes your scroll and does something else with it: snaps between sections, slows down, locks until an animation finishes, or moves the background at a different speed. The same gesture behaves differently from every other page, so the scroll feels broken.

Scroll snapping is right in a few contained places: a horizontal carousel, a gallery of explicit slides, a step-by-step onboarding. **Snap the contained scroller, never the page.**

Scroll-driven animation can be fine when it follows your scroll one-to-one: a reading progress bar, a gentle parallax no slower than about 0.7× scroll speed. Wrong whenever it changes how scrolling behaves, slows it down, or plays differently going up than down.

## Marketing pages: a bigger budget, still small

A visitor sees a landing page once, not a hundred times a day, so it can afford a little more expression. Emil Kowalski's checklist keeps it honest:

- **Motion maps to input.** No scroll-triggered fade-ups, no auto-advancing carousels. If the visitor didn't cause it, cut it.
- **Intro animations play once per session**, gated with `sessionStorage` (not `localStorage`, which would kill them forever).
- **Readable on the first frame.** No preloader; the headline readable on first paint. taste-skill's capture of 99 award sites found 60 opening on a loading screen and a third still unreadable 4.5 seconds in. Design marks were the same either way; only usability dropped.
- **Pre-render content pages** and preload the fonts and hero image, so nothing shifts on load.
- **Content stays in the DOM.** Nav submenus are visually hidden, not mounted on hover, so crawlers and screen readers see them.
- **CTAs know who's looking**: "Get started" logged out, "Open app" logged in.
- **Docs are for copying**: a copy button on every snippet and every page available as markdown.

*("Marketing tolerates more motion" gets read as "marketing wants more motion". The extra is one first-run hero moment, not every section animating in.)*

## What a link looks like when it's shared

Launch day *is* people pasting your link into chats. Flip the switches to build the preview a chat app shows.

*[Interactive demo: Bare URL, framework default title, a broken image from localhost, then a real preview.]*

The preview comes from Open Graph tags (Meta tags (og:title, og:description, og:image) that chat apps and social sites read to build the preview card when someone pastes your link). The rules:

- **A real title on every public route.** One template in the root layout (`%s · Product`), a per-route title, and generated titles for dynamic pages. Take the words from the page's own `h1`; never ship the framework's default.
- **A description** from copy that already exists, like the hero's supporting line.
- **An image at least 1200×630**, with the large-image card type.
- **`metadataBase` set to the production domain.** Without it, relative image URLs resolve to localhost and the preview breaks in production.
- **Crawl rules.** A leftover staging `Disallow: /` or site-wide noindex (Instructions that tell search engines not to list a page or site. Left over from a staging site, they quietly hide your launch from search) quietly hides the whole site from search. That's a launch blocker.
- **Icons**: your own favicon, an SVG icon and an `apple-touch-icon`.
- **The paying path works end to end**: landing, button, signup or checkout, first screen. Every link resolves and the price on the page matches the price at checkout.

Then paste the production URL into two chat apps and look.

**Launch pass (paste into your agent):**

```text
Pre-launch pass on our public pages:
- Header: solid page color with a 1px border (or hide on scroll down / show on up). No default 12px/70% blur.
- No scroll hijacking, no scroll-triggered fade-ups, no auto-carousels; snap only contained carousels.
- No preloader; h1 readable on first paint; intro animation gated by sessionStorage; fonts and hero image preloaded; content pages statically generated.
- Metadata: title template + per-route titles taken from each page's h1, descriptions from existing copy, a 1200×630 OG image, metadataBase = production origin.
- Check robots/sitemap for staging leftovers, add favicon + SVG icon + apple-touch-icon, and walk landing → CTA → signup end to end. List anything you can't fix (missing images, price mismatches) for me.
```

**Check yourself:** Your OG image works locally but every shared link in production shows a broken image. Most likely cause?

- [ ] The image is too large
- [x] No metadataBase, so the relative image URL resolves to localhost
- [ ] Chat apps don't support OG images
- [ ] The page uses client components

*Why:* Relative metadata URLs need a base. Without the production origin set, they resolve to the development host.

## In the skill

- https://school.agents.org.in/skill/layout/sticky-and-scroll-tells.md
- https://school.agents.org.in/skill/layout/marketing-surface-rules.md
- https://school.agents.org.in/skill/layout/share-and-crawl-metadata.md

---

# Every list has four states

> Design the loading, empty, error and full branches of any list or page, and get an agent to build all four.

Module: Components and states · Level: beginner · 7 min · https://school.agents.org.in/design/components/four-states

Watch a list arrive. First its outline, then a problem, then a retry, then the rows.

*[Interactive demo: A skeleton in the rows' own shape, an error that offers a way out, then the content.]*

That took about five seconds and showed you three different screens. Most generated UI only ever designs the last one, because the test account always has data. **The states are the work.** Components are where people touch your product, and their states are where most interfaces get lazy.

## Four branches, every time

Every list, table, feed and dashboard has four states:

| State | When you see it | Its job |
|---|---|---|
| **Loading** | The data is on its way | Hold the shape so nothing jumps |
| **Empty** | There is no data yet | Explain what belongs here and how to add it |
| **Error** | The data could not be fetched | Say what happened and offer a real fix |
| **Full** | The data is here | The screen you actually designed |

Flip through them below, then switch to **Agent default** to see what you get when nobody asks.

*[Interactive demo: Same list, same box. The designed version keeps its height in every state.]*

*(A missing branch in the code is a finding, even if the screen looks done.)*

## Loading: delay, then a skeleton

Speed is a feeling, so the indicator depends on how long the wait will be.

| Expected wait | Show |
|---|---|
| Under about 150ms | Nothing. Delay every indicator ~150ms so fast answers never flash one |
| By 400ms | A skeleton (A gray placeholder in the exact shape of the content that is loading: circles where avatars go, bars as wide as the words. When the real content arrives, nothing moves) for a content area; a spinner only inside the button that started the work |
| 3 to 15 seconds | A progress bar with a percentage |
| Over 15 seconds | Progress, time left, and a cancel button |

A skeleton is a gray placeholder in the exact shape of the content: circles where avatars go, bars as wide as the words. Size each row from the real row (48px because the loaded row is 48px, not a guess). When the content arrives, nothing moves.

**A centred spinner as the loading state of a whole list is a defect**: the page collapses to a dot, then everything jumps when the data lands. That jump is called layout shift (When something on the page jumps because content above or around it changed size, like a list collapsing to a spinner and then expanding when the data lands), and it is the first thing that makes a screen feel cheap.

> **In plain words.** **Skeleton**: a gray outline of the content shown while it loads. **Spinner**: the rotating circle. Spinners are fine inside a button; skeletons are for areas.

## Empty: three jobs

An empty state (What a list or page shows when there is no data yet. A good one says what belongs there and offers the action that fills it, instead of just "No data") is often the very first thing a new user sees. "No data" wastes it. A good one does three things:

1. **Says what belongs here.** "No projects yet."
2. **Points to the next action.** A real button: "Create project".
3. **Optionally, adds context.** One line on why it matters, or an example.

Size it like the full state, so the first item does not shove the layout. An empty search result says what was searched and offers to clear it. And never auto-redirect from an empty state ("nothing here, taking you home..."): it feels like the app broke.

**Default (avoid):**

**No data**

**Designed (do this):**

**No projects yet**
A project keeps one client's files, notes and invoices together.
`Create project`

## Error: what happened, and a way out

An error state answers two questions: what went wrong, and what can I do now. "Something went wrong." answers neither. "Couldn't load projects. The server didn't answer. Your projects are safe." plus a **Try again** button that really refetches answers both. The framework's built-in error page and 404 count as missing states, too.

## One more state: the first paint

A theme that flashes light before going dark, a sidebar that renders open then snaps shut: both happen because a saved value was read *after* the page painted. The fix is to decide before the first paint. A tiny script in the page head sets the theme class; layout choices like a collapsed sidebar come from a cookie the server reads; anything else waits to render until its value is known.

## Getting an agent to do it

Agents build the full state because that is what their test data shows. Ask for the other three by name, with the numbers.

**All four states (paste into your agent):**

```text
For every list, table and feed in this screen, build all four states: loading, empty, error and full.
- Loading: delay any indicator 150ms; then a skeleton with the loaded rows' exact height, widths and gaps. No centred spinner.
- Empty: a title saying what belongs here, one line of why, and the primary action button. Same height as the full list.
- Error: what happened in plain words, that nothing was lost (if true), and a Try again that refetches.
- Persisted UI state (theme, sidebar) is set before first paint, not in an effect.
List any view where a branch was missing before you started.
```

**Check yourself:** A list takes about 2 seconds to load. Which loading state fits?

- [ ] A centred spinner in the middle of the empty page
- [ ] Nothing at all until the data arrives
- [x] A skeleton with the shape of the loaded rows, shown after a ~150ms delay
- [ ] A progress bar with a percentage and a cancel button

*Why:* Content areas get a skeleton by 400ms, delayed ~150ms so fast loads never flash it. A centred spinner collapses the page; progress bars are for waits over 3 seconds.

## In the skill

- https://school.agents.org.in/skill/components/MOC-components.md
- https://school.agents.org.in/skill/components/empty-loading-states.md

---

# A button has eight states

> Give every control its hover, pressed, focus, loading, done, error and disabled states, keep them from shifting the layout, and run the polish pass that makes a component feel finished.

Module: Components and states · Level: beginner · 8 min · https://school.agents.org.in/design/components/button-states

Press the Save button. Then walk through the picker, one state at a time.

*[Interactive demo: One button, eight looks. The width never changes, so nothing around it moves.]*

An agent will happily give you the resting button and a hover color. The other six states are where a button earns trust: it answers your press, tells you it is working, and confirms it worked, all in the same spot.

## The eight, in one line each

- **Rest.** A label that starts with a verb: "Save changes".
- **Hover.** One step of background. Only on devices that can hover. This is the hover state (How a control looks while a mouse pointer is over it. Good ones are subtle (one step of background, a 1px lift) and only appear on devices that can hover).
- **Pressed.** `scale(0.97)` on `:active`, through a ~150ms transition. Never below 0.95.
- **Focus.** A visible ring for keyboard users, through `:focus-visible` (A CSS selector that matches when the browser decides focus should be shown, after Tab but not after a mouse click. Use it to show a focus ring only to keyboard users). More in the keyboard lesson.
- **Loading.** The label says what is happening ("Saving…"), clicks are ignored, the width holds.
- **Done.** It confirms on itself ("Saved"), holds a beat, returns to rest.
- **Error.** It says what did not happen; the details sit beside the form.
- **Disabled.** Faded and inert, with the reason written next to it.

*(The loading label and the done label live in the same box, stacked. Swapping them never resizes the button.)*

## Hover is not lift and shadow

The reflex hover is "lift the card 4px and add a big shadow". It is dated, and it is one of the tells of generated UI. Hover over both cards:

*[Interactive demo: Real hover with a mouse; the switch shows it on a touch screen.]*

Quieter patterns read as more considered:

| Element | Hover |
|---|---|
| Rows, list items, table cells | A background shift, about `rgba(0,0,0,0.04)`, over 120ms |
| Cards | `translateY(-1px)` and one step of tint |
| Inputs | The border gets one step darker |
| Icon buttons | The icon inside scales to 1.05, not the button |

A 1px lift is felt more than seen. 4px looks bouncy.

Two rules keep hover honest. First, **gate it**: wrap hover styles in `@media (hover: hover) and (pointer: fine)`. A phone fires `:hover` on tap and leaves it stuck, which looks broken. Second, **never change layout on hover**: no margin, padding, width or font weight. Animate only `transform`, `opacity`, `background-color`, `border-color` or `box-shadow`, so the neighbors stay put.

## Pressed, by product

How much a button squishes depends on who presses it. A consumer app can press to `scale(0.96)`; it reads as delight. A tool someone uses all day stays subtler, `scale(0.98)` or just a background change, because a springy button pressed four hundred times a day gets tiring.

## Disabled, layered right

`opacity: 0.5` and `cursor: not-allowed` is fine for a simple button. On a text input, give it an explicit disabled background and muted text instead; a flat opacity on a complex element looks washed out. And the classic mistake: a submit button disabled until the form is valid tells the user nothing about *why*. Let them press it and show the errors.

## The polish pass

Once the component works, run one pass over it. Each item is invisible on its own; together they are the difference between "works" and "finished".

**Step: Hold the weight.** Never change font weight on hover or selection; bold text is wider and reflows the row. Signal with color.

**Step: Tabular numbers.** `font-variant-numeric: tabular-nums` on anything that counts, so digits stop jiggling.

**Step: No layout shift.** Skeletons, images and placeholders carry the loaded size or an `aspect-ratio`.

**Step: States that stay put.** Hover transitions only the properties that change, ~150ms ease-out. Focus rings stay neutral and never vanish.

**Step: One z-index scale.** Dropdown 100, modal 200, tooltip 300, toast 400, or `isolation: isolate`. Never `z-index: 9999`.

**Step: Hit areas and optics.** Targets of 44px on touch, grown with a pseudo-element. Nudge a play triangle 1 to 2px toward its point so it looks centred.

**Step: Decoration is inert.** `pointer-events: none` on glows and ornaments, so they never swallow a click.

Polish applied to the wrong structure gets thrown away with it. If the hierarchy or spacing is wrong, fix that first.

## Personality comes last, and sparingly

Once every state is right, a product can earn a little character in how it responds. **Personality lives in interactions, not in static screens**: a success message that names what happened ("Sent to 47 recipients" instead of "Success!"), a loading line that informs ("Fetching your last 30 days…"), a Delete that answers 100ms slower than Save because deliberation suits destruction.

Easter eggs belong where people are curious (a 404 page, Settings, a long press on the logo), never in the middle of signup or payment. And restraint wins: one well-placed surprise feels alive; ten feel exhausting. In a tool analysts use all day, skip it.

**Every state of a control (paste into your agent):**

```text
Give this button all of its states: rest, hover, pressed, focus, loading, done, error, disabled.
- Hover only inside @media (hover: hover) and (pointer: fine); one step of background, no lift, no layout change.
- Pressed: scale(0.97) on :active, 150ms ease-out.
- Focus: :focus-visible ring, 2px, neutral color, 2px offset.
- Loading: label "Saving…", ignore repeat clicks, fixed width; the labels are stacked layers that crossfade.
- Done: "Saved" on the button for ~1.5s, then back to rest. Error: "Not saved", details beside the form.
Then run a polish pass: constant font weight, tabular-nums on numbers, no layout shift, no z-index above the scale.
```

**Check yourself:** A tab bar makes the selected tab bold. What goes wrong, and what is the fix?

- [ ] Nothing; bold is the clearest signal
- [x] Bold text is wider, so the tabs shift sideways; keep the weight and signal with color
- [ ] Bold is too slow to animate; use a 300ms transition
- [ ] Bold fails contrast; make it uppercase instead

*Why:* Changing weight reflows the text and shoves its neighbors. Hold the weight constant and show selection with color or an indicator.

## In the skill

- https://school.agents.org.in/skill/components/hover-states-subtle.md
- https://school.agents.org.in/skill/components/ui-polish-pass.md
- https://school.agents.org.in/skill/components/interaction-personality.md

---

# Forms that don't nag

> Validate fields at the right moment, write errors that fix themselves, and wire the dozen small behaviors every form owes its user.

Module: Components and states · Level: beginner · 8 min · https://school.agents.org.in/design/components/forms

The field below opens mid-word, already scolding you for `maya@`. Switch to **On blur**, type `maya@` again, then tap the name field.

*[Interactive demo: The same email field. One scolds you mid-word; the other waits until you are done.]*

The keystroke version shows an error after the first letter. You were not wrong; you were not finished. That is the cardinal sin of form validation: punishing someone for an action still in progress.

## The cadence

Inline validation (Checking each form field where it is, as the person moves through the form, instead of listing every error at the top after they press Submit) means checking each field where it is, as the person moves through the form, instead of one list of errors after Submit. The timing is the whole craft:

**Step: While typing: positive signals only.** No red borders, no error text. The only feedback allowed is good news: a small check when the field becomes valid.

**Step: On blur: the real check.** When the person leaves the field (blur (The moment focus leaves a form field, by tabbing or clicking elsewhere. It is the right time to check the field, because the person has signalled they are done with it)), validate. If it fails, show the error now. They said "I'm done"; tell them if it's wrong.

**Step: Once an error shows: check on every change.** From then on, re-validate on each keystroke so the error clears the moment the value is fixed. Making them leave the field again to find out reads as the form still being cross.

**Step: On submit: a final pass.** Catch what blur missed (rules across fields, server checks). If anything fails, move focus to the first invalid field.

Here it is in a real product: the error lands only when the cursor moves on to Password, and clears as the ending is typed.

*[Interactive demo: Error on blur, cleared while fixing, then the button confirms on itself.]*

## What an error looks like

Each failing field gets three things, together: a danger-colored border, a message directly under the field (13 to 14px, in its own lane that exists before the error does, so the form never jumps), and `aria-invalid` plus `aria-describedby` on the input so a screen reader reads the message with the field.

Rules that span two fields, like "passwords match" or "start date before end date", are checked when the **second** field blurs. The first one cannot be wrong on its own.

**Before (avoid):**

Invalid input.
Please enter a valid email.

**After (do this):**

Add the domain, like name@company.com

Good error copy says what is wrong and how to fix it, skips "Please", never says "Invalid", and sounds like a person.

## When not to validate

- A single search box: just search.
- A comment or chat message: there is no wrong answer.
- An inline rename: validate on Enter, not on blur, since the person may click away with the value intact.

And mark only the fields that are truly required; label the rest "Optional".

## Everything else a form does

Validation is one job. A form owes about a dozen more, and every one is easy to forget.

| Behavior | The rule |
|---|---|
| Labels | Every input has a real ``, so clicking it focuses the field. A placeholder is not a label |
| Input types | `type="email"`, `tel`, `url`, `password`: the right phone keyboard and autofill come free |
| Font size | Inputs at 16px or more on phones, or iOS zooms the page in |
| Enter | Wrap fields in a `` so Enter submits; a textarea submits on Cmd or Ctrl+Enter |
| Submitting | Disable the button while the request runs and change its label ("Saving…"); re-enable it in `finally`, or one failure locks the form |
| Failure | A failed submit says so and **keeps every value**. Never make anyone retype |
| Icons in the field | Positioned over the input with padding reserved, never a sibling the click misses |
| Autofocus | First field in a desktop dialog, never on touch, where it throws the keyboard up |
| Prefill | Anything you already know: the current username, the `?email=` from an invite link |
| Accidents | Long forms warn before leaving, or keep a draft, so a stray back-swipe costs nothing |

**`fetch` does not throw on a server error.** An agent's `try { await fetch() } catch {}` treats a 500 as success. Check `response.ok`, and never call `reset()` before you know it worked.

> **Autocomplete, curated.** Keep `autocomplete` on for names, addresses and payment. Turn it and spellcheck off for usernames, codes and search. Use `inputmode="numeric"` and `autocomplete="one-time-code"` on verification codes, and `current-password` vs `new-password` so password managers do the right thing.

*(Auto-advancing code boxes feel clever until someone needs to fix one digit.)*

**Validation cadence (paste into your agent):**

```text
Rework this form's validation:
- While typing: no errors; show a small check inside the field once it is valid.
- On blur: validate and show the error under the field in a reserved message lane (no layout shift).
- Once a field has shown an error, re-validate on every change so it clears as soon as it is fixed.
- On submit: run everything, focus the first invalid field. Cross-field rules run when the second field blurs.
- Error copy says what is expected ("Add the domain, like name@company.com"), no "Please", no "Invalid".
- Inputs have , the right type, 16px font, aria-invalid and aria-describedby.
- The submit button disables with "Saving…" while in flight, re-enables in finally; a failed submit keeps every value and checks response.ok.
```

**Check yourself:** When should an email field first show 'Add the domain, like name@company.com'?

- [ ] As soon as the first character is typed
- [x] When the person leaves the field with an invalid value
- [ ] Only after Submit, in a list at the top
- [ ] Never; disable the Submit button instead

*Why:* Hard validation happens on blur, when the person has signalled they are done with the field. After that, it re-checks on every change so the message clears when fixed.

## In the skill

- https://school.agents.org.in/skill/components/forms-validation.md
- https://school.agents.org.in/skill/components/forms-behavior.md

---

# Instant actions, undo and toasts

> Make likely-success actions feel instant, choose between undo and a confirmation for destructive ones, and use toasts (and Sonner) without the usual bugs.

Module: Components and states · Level: intermediate · 9 min · https://school.agents.org.in/design/components/optimistic-and-undo

Both hearts get tapped once as they scroll in. Same server, same 700ms delay; tap them again yourself.

*[Interactive demo: Left waits for the server. Right updates now and only rolls back if the server says no.]*

The right one feels instant because it *is* instant, as far as you can tell. That is an optimistic update (Changing the screen right away as if an action succeeded, sending the request in the background, and rolling back only if it fails. It makes likes and toggles feel instant): change the screen immediately, send the request in the background, and undo the change only if it fails. Tick "Make the server fail" to watch the rollback.

It is the single biggest speed win available without touching the servers.

## When to be optimistic

```ts
const previous = liked;
setLiked(!liked); // update now
try {
await api.toggleLike(post.id); // confirm in the background
} catch {
setLiked(previous); // roll back
toast.error("Couldn't update the like. Try again.");
}
```

| Be optimistic | Don't |
|---|---|
| Toggles: like, bookmark, follow, mute | Payments and bookings: the confirmation *is* the design |
| Marking a to-do complete | Anything only the server can validate, like "is this username free?" |
| Renaming with client-side checks | Sign-up and login, where a failure is information |
| Reordering a list | Destructive actions **without** undo |

If the server creates an id, give the new item a temporary client id and swap it when the response lands. And test the rollback path on purpose: a rollback that yanks the page somewhere else is worse than a 200ms spinner.

## Undo or confirm?

Now the scary actions. Archive a project below, then try deleting the whole workspace.

*[Interactive demo: Archive acts at once with undo. Delete workspace can't be undone, so it asks you to type its name.]*

A confirmation on every delete trains people to click through it, so the one that matters gets clicked through too. Decide first:

| The action | Pattern |
|---|---|
| Reversible and frequent: archive, move, delete to trash | Do it now; offer **Undo** in the result |
| Irreversible, one item | Confirm |
| Irreversible, many items | Confirm, with the count |
| Affects other people | Confirm, and say who: "The 8 members lose access" |
| An account, workspace or repository | Type its name to confirm; the button stays disabled until it matches |

Undo is cheaper for the user and more honest. It is also the optimistic pattern: remove the row now, and let the real delete run during the undo window.

## A confirmation you can answer without reading the body

**Before (avoid):**

**Are you sure?**
This action cannot be undone.
`OK` `Cancel`

**After (do this):**

**Delete workspace "acme-web"?**
This permanently deletes 4 projects and their 212 files.
`Cancel` `Delete workspace`

- **Title** names the action and the object. Never "Are you sure?".
- **Body** says what is lost, with counts.
- **Buttons** are verb plus object, never Yes and No.
- **Focus starts on Cancel**, so a reflexive Enter does no harm.
- **Only destruction is red.** If the brand itself is red, give destruction a different treatment (outlined, with an icon).

*(Delete sitting in a menu right under Rename, with no gap, no color and no undo, is the most common unguarded delete there is.)*

## The undo toast is not a normal toast

A toast (A small message that slides in at the edge of the screen to confirm something ("Changes saved") and leaves on its own. One with an Undo button has to stay longer and pause while you look at it) is a small message that slides in at the edge of the screen and leaves on its own. The undo toast carries an action, so it plays by stricter rules: at least 5 seconds, **paused while hovered or focused**, and announced politely without stealing focus. An undo link that vanishes on a timer is data loss on a schedule.

Try the stack: fire a few, then hover or tap it.

*[Interactive demo: Newest in front. The stack spreads and every timer pauses while you look.]*

A plain "Changes saved" can leave after 4 seconds. An error that needs action stays until dismissed. Reading time scales with the words (about 200 to 250 words a minute), never a flat 2 seconds.

## Sonner in practice

Sonner, by Emil Kowalski, is the toast library most React apps reach for. It needs exactly two pieces: **one** `Toaster` component mounted once near the root (the root layout in Next.js), and `toast()` called from client code.

| Need | Call |
|---|---|
| A message with a second line | `toast("Saved", { description })` |
| A typed icon | `toast.success`, `.error`, `.info`, `.warning` |
| Tied to a promise | `toast.promise(p, { loading, success, error })` |
| Update a toast later | `const id = toast.loading("…")`, then `toast.success("Done", { id })` |
| A button | `action: { label: "Undo", onClick }` |
| Your own design | `toast.custom((t) => …)` |

The bugs are almost always one of these:

| Symptom | Cause |
|---|---|
| Nothing appears | No Toaster mounted, or `toast()` ran on the server |
| Appears twice | Two Toasters (layout and page), or a React effect ran twice; fire from the click handler or pass a stable `id` |
| Hidden behind a modal | An ancestor created a stacking context; mount the Toaster at the document root |
| Stuck on loading | The promise never settles |
| "Dark mode is broken" | `theme` defaults to `"light"`; pass `theme="system"`. Colors stay gray until `richColors` is set |

**Optimistic with undo (paste into your agent):**

```text
Make archiving instant: remove the row immediately, then call the API. Show a Sonner toast "Archived 'NAME'." with an Undo action that restores the row at its old position and cancels the request.
- The toast stays at least 6s, pauses on hover and focus, and does not take focus.
- If the API fails, restore the row and toast.error("Couldn't archive. Restored.").
- Move focus to the next row's action (or the previous one) when the focused row disappears.
- One Toaster, with theme="system" and richColors, in the root layout only.
For deleting the workspace, use our dialog: title "Delete workspace 'NAME'?", counts in the body, Cancel focused, "Delete workspace" disabled until the name is typed.
```

**Check yourself:** Which action should get an undo toast instead of a confirmation dialog?

- [ ] Deleting a whole workspace and its repositories
- [x] Archiving one email from the inbox
- [ ] Charging a customer's card
- [ ] Removing every member from a team

*Why:* Archiving is frequent and reversible, so act at once and offer undo. Irreversible or many-item actions, and anything involving money, get a confirmation.

## In the skill

- https://school.agents.org.in/skill/components/optimistic-updates.md
- https://school.agents.org.in/skill/components/destructive-actions.md
- https://school.agents.org.in/skill/components/sonner-usage.md

---

# Keyboard, focus and touch

> Make every control reachable by keyboard and thumb, show focus without showing it to mouse users, and give custom widgets the key maps people expect.

Module: Components and states · Level: intermediate · 9 min · https://school.agents.org.in/design/components/keyboard-and-touch

Focus is already on one of these buttons. Can you tell which? Click into the toolbar and press Tab a few times in both modes. (On a phone, use Step.)

*[Interactive demo: With outline: none, focus is still moving. You just can't see where.]*

`outline: none` is one of the most common lines an agent writes, because the default focus outline looks a little clumsy after a mouse click. The fix is not to delete it. It is to show it only to the people who need it.

## Focus you can see, only when it helps

`:focus-visible` (A CSS selector that matches when the browser decides focus should be shown, after Tab but not after a mouse click. Use it to show a focus ring only to keyboard users) is a CSS selector that matches when the browser decides focus should be shown: after Tab, not after a mouse click. So:

```css
button:focus { outline: none; } /* no ring on click */
button:focus-visible {
outline: 2px solid currentColor; /* ring for the keyboard */
outline-offset: 2px;
}
```

Even simpler: keep the browser's own ring and add only `outline-offset: 2px`. It already adapts to the platform and to high-contrast modes. A custom ring is fine if it clears 3:1 against every color it sits on, and the focused element is never hidden under a sticky header.

## The floor below taste

Accessibility is below polish and below brand. A screen that fails it is broken, whatever it looks like. The baseline every component passes:

- **Everything works by keyboard**, reached by Tab in source order. The DOM order is the visual order; never reorder with CSS, never use a positive `tabindex`.
- **Real elements.** `}