Learn it.
Make it. Keep it.

Start with decisions, not components

A design system is a collection of shared decisions. Components are how those decisions become visible.

Find the repetition

Take three screens from the same product. List the repeated decisions: text sizes, spacing, surfaces, and actions. Start with the rules that recur; a huge component library is not the goal.

Name the intent

A name like color-action communicates a role. A name like green-500 communicates a value. Keep both layers: primitive values define the palette, and semantic tokens describe how the product uses it.

Try it

Choose a familiar app and write down five recurring decisions. Give each a semantic name. If two elements play the same role, they should usually use the same token.

:root {
  --color-surface: #f3f4ed;
  --color-ink: #20251d;
  --color-action: #c8f27c;
  --space-unit: 8px;
}

Build a visual hierarchy

Hierarchy helps a reader decide where to look, what to understand, and what to do.

Choose three levels

Start with a title, body text, and supporting label. Make the difference between levels obvious without relying on color alone. Keep paragraphs at a comfortable line length.

Use a spacing rhythm

Try a small scale of 4, 8, 16, 24, and 40 pixels. Related elements sit closer together. Unrelated groups need more separation. A spacing scale supports judgement rather than replacing it.

Try it

Arrange a title, description, price, and button inside a card. Blur your eyes: the title and primary action should still be easy to find. Test the design at a narrow width.

Make components resilient

A useful component survives long text, missing images, keyboard input, and a small screen.

Design the states

Write down default, hover, focus, disabled, loading, and error behavior before polishing the default appearance. Only include states that the component needs.

Define the contract

Decide which parts are content and which are structure. Let a card accept a title and description while preserving its spacing and hierarchy. Avoid arbitrary variations without a real use case.

Your project

Build the reading-app kit described in the project brief. Test a long title, a missing image, and keyboard navigation. Document what changed after those tests.

Model the interface as state

An interface is a view of the data a person is working with. Start with that data before writing components.

Keep the source small

Store the source items, selected filter, and search query. Calculate the filtered items from those values. Keeping a second copy of the filtered list creates opportunities for the copies to disagree.

Name the transitions

A save button changes a saved-ID collection. A search field changes a query. Writing these transitions in plain language makes event handlers easier to understand.

Try it

Sketch the data for a reading list. Separate what the user changes from what you can calculate. Count and filtered results are usually calculated values.

const visibleBooks = books.filter(book =>
  book.title.toLowerCase().includes(query.toLowerCase())
);

function toggleSaved(id) {
  setSaved(current => current.includes(id)
    ? current.filter(value => value !== id)
    : [...current, id]);
}

Design component boundaries

Good boundaries make change local. Split components around responsibilities rather than arbitrary visual boxes.

Follow the responsibility

A FilterBar collects choices. A BookCard presents one item and exposes actions. A ReadingList coordinates the data. Each name tells you why that component exists.

Keep state near its owner

If multiple siblings need the same selection, let their nearest shared parent own it. Pass data down and events up. Move to a broader state solution only when that model stops being clear.

Try it

Write the props for a BookCard without implementing it. If the props describe the whole application, the boundary is probably doing too much.

Ship the states between screens

People experience the transitions and edge cases, not only the happy path.

Treat empty as useful

An empty search should name the active query and offer a way to clear it. An empty saved list can explain how saving works. Neither is an error.

Make actions perceivable

Use real buttons, accessible names, visible focus, and status messages for changes that happen without navigation. Preserve keyboard focus when content updates.

Your project

Build the reading-list app. Try a query with no matches, save an item twice, reload persisted data, and navigate entirely with Tab and Enter. Record what those checks reveal.

Write a brief that makes decisions

A useful prompt starts with a useful brief. Describe the person, the task, and what a successful result lets them do.

Make the goal concrete

“A beautiful website” leaves the important decisions open. “A booking page where a first-time visitor can compare three workshops and reserve a time” creates a clear task.

Supply the constraints

State the content, required interactions, layout boundaries, and accessibility expectations. Explain what you admire about a reference instead of asking for an unexamined copy.

Try it

Write a brief in four parts: audience, primary action, content, and constraints. Remove adjectives that do not change an implementation decision.

Audience: first-time workshop visitors
Primary action: compare topics and choose a session
Content: title, outcome, prerequisites, time, price
Constraints: keyboard access, mobile layout, no fabricated proof

Critique one dimension at a time

Specific criticism is actionable. A general feeling is a starting point, not a useful change request.

Separate the concerns

First check whether the page does the right job. Then examine hierarchy, spacing, typography, and motion. Make the smallest change that tests your hypothesis.

Explain the evidence

Instead of “make it premium,” say “the price and primary button compete with six equally bold labels; reduce the label emphasis and keep the action visually distinct.”

Try it

Review a generated section and write three observations. Connect each observation to a user task and an explicit proposed change.

Verify before you trust

An assistant can produce a plausible-looking result that does not behave correctly. Verification belongs in the workflow.

Test the critical path

Exercise the exact flow the page promises. Test inputs, empty results, small screens, keyboard navigation, and reloads. Check claims and assets against their sources.

Keep an iteration record

Record the intention, the change, and the observed result. This makes future prompts more precise and helps you distinguish real improvement from novelty.

Your project

Build your landing page and keep a three-entry iteration log. For each revision, include one concrete test and its actual outcome. Do not describe a planned check as a passed check.

Give every movement a reason

Motion can show where an element came from, where it went, or what just changed.

Start with the change

Choose one event: a panel opens, an item is saved, or a selection changes. Decide what information motion adds. If it adds no useful information, leave the transition out.

Keep it brief

Try a short duration around 160–240ms for small interface transitions, then adjust to the distance and complexity. This is a starting point, not a universal rule.

Try it

Pick a button and a panel. Describe their state change without using animation terminology. That sentence is the purpose your animation should serve.

.card {
  transition: transform 180ms ease-out;
}
.card:hover { transform: translateY(-4px); }
@media (prefers-reduced-motion: reduce) {
  .card { transition: none; }
}

Shape the rhythm with easing

Two transitions with the same duration can feel very different because their speed changes differently over time.

Consider the destination

An element entering view often benefits from slowing as it reaches its resting point. A linear transition moves at a constant rate and can feel mechanical in the wrong context.

Avoid accidental choreography

Many independent animations competing at once create noise. Make one action dominant and let supporting elements respond quietly. Never delay essential interaction for a flourish.

Try it

Apply linear, ease-out, and ease-in-out to the same small transform. Compare them at the same duration and explain which best supports the state change.

Make motion optional

The interface must remain understandable when animation is reduced or removed.

Respect the preference

Use prefers-reduced-motion to remove nonessential movement. Keep the resulting state visible through text, color, or structure. Reduced motion should not mean reduced functionality.

Test interruption

Click rapidly and change direction halfway through a transition. The interaction should remain responsive and settle into the correct state.

Your project

Build the three interactions from the brief. Test both motion preferences, keyboard use, and rapid input. Explain how the final state communicates the change without animation.

Find the one thing to say

A first-time visitor should quickly understand what this is, who it is for, and why the next step is useful.

Begin with the reader

Write down the situation that brought someone to the page. Use the words they would use to describe the problem. The headline should connect that situation to a concrete outcome.

Choose a primary action

A page can offer multiple routes, but the main action should be visually clear. Name what happens next. “Explore workshops” is more informative than “Get started” in a workshop catalog.

Try it

Write three headlines for the same offer. Remove vague praise and compare how clearly each explains the outcome. Choose the one a new visitor can understand without context.

Build a page with rhythm

A page is a sequence of answers. Each section should earn its place by resolving a real question.

Order the questions

Start with what the offer is, then what the visitor gets, what it requires, and how to take the next step. The order can change when the audience brings different doubts.

Vary the pace

Alternate concise statements with useful detail. Use spacing and scale to express relationships. Avoid repeating the same card grid simply because it is easy to build.

Try it

Write a one-sentence purpose for each section. Merge sections that answer the same question. Remove a section that adds no useful information.

Make the small screen deliberate

A mobile layout is a fresh composition with the same priorities, not a desktop page squeezed narrower.

Preserve the priority

Keep the headline, explanation, and action in a natural reading order. Reduce decorative complexity before reducing text to an uncomfortable size.

Check the constraints

Test long labels, touch targets, line lengths, and horizontal overflow. Make sure imagery does not hide information that the copy depends on.

Your project

Build both layouts for the creative workshop. Ask someone to describe the offer after a short look. Use their uncertainty to improve the page rather than merely changing its style.

Let the browser share the work

Responsive CSS works best when you describe constraints and let the browser distribute the available space.

Start with the container

Use a maximum reading width, flexible side padding, and content that can shrink. Fixed widths are useful for some details but fragile as a default layout strategy.

Use a flexible grid

A grid with auto-fit and minmax can change column count based on available space. Set a sensible minimum, and ensure it never exceeds the container width.

Try it

Create three cards in the playground. Change the minimum column width and resize the preview. Notice how the layout responds without a separate breakpoint for every screen.

.grid {
  display: grid;
  grid-template-columns:
    repeat(auto-fit, minmax(min(100%, 240px), 1fr));
  gap: 24px;
}

Build a small visual vocabulary

A few well-chosen variables make an expressive composition easier to understand and maintain.

Give repeated values names

Use custom properties for surface colors, spacing, and border radii. Prefer names that describe their role. A change to one value can then update the composition consistently.

Keep the hierarchy distinct

Let display text be expressive while body text stays comfortable. Use a deliberate range of sizes and weights. Decoration should support the reading order.

Try it

Create a second theme by changing only five variables. If you need to rewrite many selectors, look for values that should have been shared.

Polish the edges

Craft becomes visible when the content or device stops matching your ideal example.

Stress the content

Try a very long heading, a short description, and an absent image. Use overflow-wrap where necessary and avoid hiding important content just to preserve a shape.

Test the interaction

Use real links and buttons. Give keyboard focus a visible outline and make hover effects optional. The card must communicate its purpose before anyone points at it.

Your project

Build the editorial grid from the brief. Test at 390px and 1280px, tab through every action, and make a second theme from your custom properties.

Choose a voice before a typeface

A journal about quiet places should not sound like a sports scoreboard. Begin with the reading situation.

Design the role

Write three attributes for the publication and translate each into a visible decision. “Reflective” might suggest generous leading and a steady text rhythm. “Precise” could mean a clear numeral set and disciplined labels. These are hypotheses, not rules about serif versus sans. Compare actual words; a font preview alphabet cannot show how your headline breaks.

Worked example

Interval needs a large opening line, a 300-word essay, and short place captions. Try a high-contrast display face only for the opening. Set the essay in a face whose small counters and punctuation remain clear at the intended size. Compare both pairings with “Between arrivals” and a caption containing 11:45, an em dash and parentheses. The quieter pairing may make the photograph more prominent.

Make a specimen

Create two versions using identical content, size and layout. Change only the pairing. Read a paragraph aloud while following the text and note where the eye loses its place. Annotate three specific differences: rhythm, character width and punctuation clarity. Record the font license before committing to distribution.

Common mistake

Choosing two unusual display faces can produce a striking title and an exhausting article. Reserve expressive treatment for one role, then check whether a neutral companion creates enough contrast without looking unrelated.

Make hierarchy visible without decoration

A reader should distinguish an article title, section heading and caption before reading every word.

Build a small scale

Start with roles rather than a long list of sizes: display, title, body, caption and label. Specify size, weight, line height and spacing for each. A mathematical scale is useful scaffolding, but an actual line break can justify moving a size. Keep related roles close enough to belong together and different enough to recognize.

Worked example

Use a 48px title, 24px section heading, 18px body and 13px caption on the desktop specimen. At 390px, try a 36px title while leaving body text comfortably readable. If title and section heading seem equally loud, first reduce heading weight or increase the space above it. Adding a border to every section would obscure the hierarchy you are trying to test.

Practice

Lay out a title, deck, two paragraphs, subheading and caption in black and white. Remove the photograph. Ask a reader which element begins the article and which introduces a new idea. Adjust one role at a time, then write your final values beside the specimen.

Check the edge

A short title can disguise weak hierarchy. Replace it with “A room between one arrival and the next” and let it wrap naturally. Avoid a fixed height that cuts off the third line.

Tune the line, not just the font size

Reading comfort emerges from the relationship between letter shape, line length and vertical rhythm.

Set constraints

Use a maximum text measure and responsive side padding. A range around 55–75 characters is a useful starting experiment for continuous prose, not a universal pass mark. Narrow measures may need different line height; wide text can make finding the next line harder. Evaluate with the actual language and font, including punctuation and long words.

Worked example

An 18px essay stretches across a 1000px content area. Limiting it to 65ch creates a calmer central column, while the image can retain the full width. At 390px, padding becomes the effective constraint. The ch unit follows the zero glyph, so 65ch does not guarantee exactly 65 characters on each line. Inspect the output rather than counting the declaration as evidence.

Practice

Render the same paragraph at 45ch, 65ch and 85ch. Compare how quickly you find the next line. Test 200% zoom, a narrow window and a long URL. Keep the variant that balances reading comfort with the publication’s rhythm; explain why the other two are weaker in this context.

Common mistake

Tightening tracking to force a paragraph into a decorative box changes every word to solve one layout problem. Change the container or content structure before damaging the text texture.

.article-copy {
  max-width: 65ch;
  font-size: 1.125rem;
  line-height: 1.65;
  overflow-wrap: anywhere;
}
.article-title {
  font-size: clamp(2.25rem, 5vw, 4rem);
  line-height: 1.05;
}

Deliver a specimen someone can use

A type system is finished when another person can apply it to unfamiliar content.

Describe the contract

For each role, name its purpose, values and permitted exceptions. Show a good example and a failure. Include font file sources, licenses and a fallback stack. A fallback may wrap differently, so check the initial loading state as well as the final font. Reserve layout space where possible and avoid hiding content while fonts load.

Worked example

Interval uses the display face for article openings but never for navigation. Its caption rule allows two lines and follows the image rather than aligning every caption to a forced height. The specimen includes a three-line title and a missing-image state so a future editor sees the boundaries rather than only the ideal example.

Capstone practice

Finish the two Interval pages. Mark the first, second and third visual priorities. Run the long-title and zoom checks, then capture one revision with its reason. Use the project checklist to assess the result; a decorative cover alone does not demonstrate the article system.

Review criterion

Have another person compose a new caption and subheading from your notes. If they must invent a size or ask what belongs together, add the missing rule or simplify the system.

Extract principles, not appearances

A reference can teach you about hierarchy without becoming a layout to copy.

Separate the layers

Describe a reference through composition, scale, contrast, image treatment and pacing. Then name the job each decision performs. “Large empty margin isolates the date” is transferable; “put the same object in the same corner” is a surface imitation. Collect contrasting sources so a single work does not silently become your entire direction.

Worked example

Afterlight is an evening exhibition of small luminous objects. One architectural reference teaches you to use darkness as space. A timetable teaches concise information order. A printed invitation contributes a quiet edge detail. Combine those principles into a new composition with an original light study and a clear date block; do not reuse the referenced artwork without permission.

Practice

Choose three legally accessible references. For each, write one observed design decision, the effect it has, and a different way you could achieve that effect. Make a small black-and-white sketch using only those translated principles. Credit the references in your working notes.

Common mistake

“Premium, bold, clean” does not tell a collaborator what to do. Replace each adjective with a decision and a tradeoff: generous margins emphasize the object but leave less room for explanatory copy.

Write a visual thesis you can test

A direction should explain how the page will feel and how it helps the audience act.

Connect promise and form

Use one sentence linking audience, idea and visual behavior. Then choose three constraints that make the sentence visible. Constraints narrow the range of possible decisions; they do not specify every pixel. Include the information the campaign must communicate before deciding how much room can be atmospheric.

Worked example

“Afterlight invites first-time visitors to notice small objects through dramatic scale changes and precise captions.” Rules: one object dominates each composition, captions sit in a consistent type system, and the date/action remain outside the image. A dense collage violates the first rule even if it looks exciting. A tiny date violates the visitor’s task.

Practice

Build two routes for the same exhibition: an intimate editorial route and a graphic poster route. Keep the title, date, venue and action identical. Show both at thumbnail size and actual reading size. Explain which route better serves someone deciding whether to attend.

Common mistake

Judging only at presentation scale favors large decorative gestures. Also inspect a small phone crop and a distant poster view, because those are different encounters with the same idea.

Keep the identity; change the composition

Consistency comes from recognizable relationships, not identical layouts at every size.

Define invariants

Choose what stays stable: palette, type roles, image behavior, mark placement logic and tone. Allow columns, crop and spacing to change with context. A poster can hold a short statement while a landing page needs explanatory evidence. Each format must perform its own job without abandoning the campaign’s visual thesis.

Worked example

The Afterlight poster uses a tall image and large title. The mobile invitation places a tighter crop below the date so the action appears early. Both share a dark field, fine caption rules and the same title voice. The object is recropped, not squeezed; a narrow screen should not force unreadable type simply to mimic the poster.

Practice

Apply your chosen route to all three capstone formats. Add one stress case to each: a longer venue name, a portrait photograph and a translated title. Change the composition while keeping the rules recognizable. Note which rule needs an explicit exception.

Review criterion

Cover the logo. The three pieces should still feel related through image logic and hierarchy. If they only match because of the logo, strengthen one shared relationship rather than adding more repeated decoration.

Critique a decision, then revise it

A critique is useful when it names an observable problem and a testable change.

Structure the feedback

Describe what you see, identify which reader task it affects, and propose a small experiment. Keep preference separate from evidence. “I like blue” is preference; “the date has less contrast than the caption and is missed in a quick scan” identifies a hierarchy problem. Record the before/after result so revisions accumulate knowledge.

Worked example

A five-second review of Afterlight leaves readers with the exhibition name but no idea it happens in the evening. You test moving the time alongside the date, keeping its type size. If the time becomes easy to identify without overpowering the title, the hierarchy improved. Changing the entire palette would make the cause of improvement difficult to isolate.

Capstone practice

Ask a peer to identify the offer, time and next action in each format. Do not coach them. Revise the weakest composition, then repeat the same questions. Deliver the three final pieces alongside two concise critique entries and source credits.

Common mistake

A unanimous preference is not the same as a usable result. Keep the campaign’s audience and information requirements in view, and describe any uncertainty your small review cannot resolve.

Start with the decision at risk

Research becomes easier to scope when you know which decision it could change.

Frame the uncertainty

Name the proposed action, the assumption behind it and the consequence of being wrong. A broad goal such as “understand productivity” cannot guide a short study. A focused question such as “what context do people need when returning to an unfinished project?” suggests specific recent episodes to investigate.

Worked example

A team proposes daily reminder notifications. Its assumption is that people forget projects. A different explanation is that people remember but cannot reconstruct the next step. Interviews should investigate returning to work, rather than ask whether reminders sound useful. The two explanations suggest different product responses and different evidence to seek.

Practice

Write a decision statement for a personal-project tool. List two competing explanations for stalled work and the observations that would weaken each. Recruit based on recent experience of the situation, not enthusiasm for your proposed solution. Use a peer rehearsal if recruitment is not possible and label its limits.

Common mistake

A small convenience sample cannot establish market prevalence. It can expose a mechanism or challenge an assumption. Phrase findings as observations from the study rather than percentages about all users.

Ask for the episode, then follow it

The most informative detail often appears after the first general answer.

Use a neutral sequence

Ask what happened, what the person did next, and what information they used. Follow their wording rather than supplying a preferred explanation. Ask permission before recording; written notes may be enough. Explain how notes will be used and avoid collecting identifying or sensitive material that the decision does not require.

Worked example

A participant says, “I lost track.” Instead of asking “So a notification would help?”, ask “What did you do when you opened the project?” They describe searching three documents for the last decision. That episode suggests a context-recovery issue, while their original phrase could have meant several things. Preserve the distinction in your notes.

Practice

Write a six-question guide: introduction/consent, recent episode, sequence, obstacles, workaround and closing. Rehearse it with a peer for ten minutes. Note every question that assumes a motive or includes your feature. Rewrite those prompts, and leave room to follow an unexpected answer.

Common mistake

Filling silence with your own explanation can turn an interview into a sales conversation. Pause, then ask a short follow-up. Accept “I do not remember” as data about the limits of the account.

Keep evidence and interpretation separate

A tidy theme is persuasive; traceability helps you decide whether it is justified.

Build an evidence table

Use columns for episode, observation, interpretation, counterexample and open question. Keep a source reference that you can trace without exposing unnecessary personal details. Themes should summarize recurring relationships, not merely reuse the most memorable quote. Look for disagreement and conditions under which a pattern changes.

Worked example

In a fictional rehearsal, P1 searches for a previous decision; P2 restarts easily using a checklist; P3 remembers the next step but lacks time. “Everyone needs reminders” ignores two different mechanisms. A narrower theme is that a visible next action may help reconstruct context, while time constraints remain a separate problem. This is a hypothesis to test, not a measured population claim.

Practice

Code six observations from your notes. For every proposed theme, attach supporting episodes and one uncertainty. Rewrite any theme that cannot be traced. Keep direct quotations exact; use paraphrases when the original words were not recorded accurately.

Common mistake

Frequency in a tiny sample is not the only indicator of importance. A single severe barrier can matter, but describe its severity and source instead of inflating how common it is.

Write a decision with an expiry condition

A useful research brief says what to try and what evidence would make you reconsider.

Make the reasoning visible

State the decision, strongest observations, competing explanation and next experiment. Keep scope proportional to the study. Distinguish what you learned about behavior from what remains unknown about feasibility or demand. An explicit revisit condition keeps a tentative decision from becoming permanent folklore.

Worked example

The project tool tests a “last decision / next action” note with five returning users. Success means they can identify a next step without reopening old documents; the team also observes whether writing the note is burdensome. This experiment addresses context recovery. It does not establish retention improvement or justify a forecast of paid conversion.

Capstone practice

Write your one-page brief with a source reference for each major claim. Include one recommendation you rejected and why. Ask a peer to trace the recommended experiment back to an observation. If the chain has a missing link, label the inference or gather more evidence.

Review criterion

A reader should understand what changed your mind and which future result would change it again. Remove unsupported certainty before polishing the presentation.

Name what happens after the click

A button label is a small contract about the next state.

Start with the action

Use a verb and a meaningful object when the destination is not obvious. “Review reservation” prepares someone for another step; “Confirm reservation” implies commitment. Decide what the system actually does before writing the label. Keep the terminology stable between the card, form and confirmation.

Worked example

A workshop page says “Get started,” then opens a date picker. Replacing it with “Choose a session” reduces ambiguity. The final action becomes “Confirm free reservation” only if no payment occurs. When payment is required later, the interface must describe that sequence accurately rather than borrowing reassuring language from another product.

Practice

List six actions in your booking flow. Beside each, write the next visible state and whether anything is committed. Rewrite labels whose meaning differs from their effect. Read them without nearby body copy to check that they still give a useful clue.

Common mistake

A playful label can work when its meaning remains clear. “Let’s do this” on a consequential action forces the user to infer the effect from context. Put personality into supporting copy while keeping the action precise.

Build a vocabulary that survives the flow

Inconsistent nouns make people wonder whether two screens refer to the same thing.

Choose canonical terms

Define the product’s important nouns and verbs in a short terminology sheet. Include the meaning, preferred term and a sentence in context. Avoid internal implementation language when it does not help the user decide. Do not vary a term simply to make the writing sound less repetitive.

Worked example

A booking tool uses “class,” “event,” “workshop” and “session” interchangeably. Define workshop as the topic and session as its dated occurrence. Then “Choose a workshop” and “Choose a session” refer to different decisions. A session card should repeat its workshop name so the distinction remains visible.

Practice

Write a terminology sheet for five concepts. Apply it to a card, confirmation and cancellation message. Ask a peer to explain the difference between a workshop and a session. If your definitions are not reflected in the interface, simplify them rather than adding a glossary users must study.

Common mistake

Removing every repeated word can make a flow harder to follow. Repetition is useful when it confirms that the same selected session persists across steps. Vary sentence structure before varying core terms.

Turn an error into a next step

An error message should identify the problem at the level where someone can fix it.

Explain and recover

Name the affected item, describe the problem in ordinary language, and provide a possible next action. Preserve entered data when safe. Avoid blaming the person for a system failure. Place field-specific feedback beside the field and provide a summary when several errors need attention.

Worked example

“Invalid input” does not help someone who typed a date in another format. “Enter a date as day/month/year, for example 18/09/2026” supplies a concrete repair. If the server is unavailable, a different message is needed: “We could not check availability. Your details are still here. Try again.” Do not claim the reservation succeeded when only the request was sent.

Practice

Write messages for a missing email, full session, lost connection and duplicate submission. For each, state what the system knows and what it does not know. Draw the recovery action and the information that remains on screen.

Common mistake

“Something went wrong” can be honest but insufficient. When the exact cause is unknown, say what failed and give a safe next step. Avoid invented explanations that would mislead support or the user.

Review the journey as a reader

A sentence can be clear in isolation and confusing beside another sentence.

Test comprehension

Walk through the flow with someone unfamiliar with the project. Ask what they think happened and what they expect the next action to do. Avoid asking only whether they like the tone. Record hesitation and mismatched expectations, then identify the wording or missing context that caused them.

Worked example

The review screen says “Almost there” while the button says “Done.” A participant believes the reservation already exists. Replacing the heading with “Review your session” and the action with “Confirm reservation” makes the pending state explicit. The success screen then includes the selected date and a clear confirmation statement.

Capstone practice

Deliver the main booking flow and five edge states. Include an empty saved list and an unavailable session. Stress every action label at a narrow width. Record two observed misunderstandings and show the revised copy alongside the original.

Review criterion

Someone should be able to identify the current state, the available action and the consequence without reading a help article. Check accuracy before adding charm.

Start with the element’s job

A visually convincing control can still be impossible to operate without a pointer.

Choose native semantics

Use links for navigation and buttons for actions. A button supplies keyboard activation and a role; adding a click handler to a generic box does not supply the same contract. Labels connect fields to their purpose. Headings and landmarks organize the page beyond its visual appearance.

Worked example

A book card contains a title link and a separate Save button. The button uses aria-pressed to communicate saved state and changes its visible text to “Saved.” The card itself is not a nested button around other controls. A result message reports the updated count without moving focus away from the action.

Practice

Build one card using a title link, description and Save button. Tab through it. Verify that Enter follows the link and Space activates the button. Check that the accessible name still identifies the action when the visual icon is hidden.

Common mistake

Adding ARIA to every element can replace useful native meaning with incorrect claims. Prefer the element that already performs the job, then add only the state or description it genuinely needs.

<button type="button" aria-pressed="false">
  Save The Quiet City
</button>
<p role="status" aria-live="polite"></p>

Make focus follow the task

Keyboard focus is the current place in an interaction, not a decorative outline.

Plan the sequence

Keep DOM order aligned with the reading order. Use a visible focus indicator with enough separation from nearby edges. When opening a modal dialog, choose an initial focus target inside it; for long content a focusable heading can be appropriate. Closing should return people to the control that opened it when that control still exists.

Worked example

A details button opens a native dialog. The heading explains the selected book, the close button remains available, and Escape dismisses the modal. After closing, focus returns to the details button. If the user removed the item inside the dialog, choose a sensible neighboring item instead of focusing a deleted node.

Practice

Sketch the focus sequence for open, inspect, close and remove. Implement the first three using dialog.showModal() and dialog.close(). Verify forward and reverse tabbing. Test the actual browser rather than assuming that the presence of a dialog tag guarantees a complete experience.

Common mistake

Removing outlines because they do not match the design leaves keyboard users without a position marker. Restyle the indicator with :focus-visible and review it against every surface.

:focus-visible {
  outline: 3px solid #244fc4;
  outline-offset: 4px;
}
button { min-height: 44px; }

Report changes without creating noise

A changed screen is not automatically a perceivable state change.

Choose meaningful feedback

Use a concise status region for updates such as saved confirmation or result counts. Keep the live region in the DOM before changing its text. Avoid announcing every keystroke in a complex interface. Error text should identify the field and the repair, and aria-describedby can connect the explanation to that field.

Worked example

Searching for “coast” produces “3 books found.” A zero-result state repeats the query and offers Clear search. Submitting an empty required title marks that field invalid and displays “Enter a title.” The interface does not move focus to the result count on every search update, because doing so would interrupt typing.

Practice

Add search feedback and one recoverable validation error to the reading list. Inspect the accessibility tree and try a screen reader if available. Record exactly what you tested; a markup inspection alone does not establish how every assistive technology announces the result.

Common mistake

A rapidly changing live region can become a stream of interruptions. Report the result of an action and let people continue working. Keep essential feedback visible as well as announced.

Review a complete journey

Accessibility is experienced through tasks and states, not a score on one screen.

Combine checks

Automated scans can find some structural defects. Manual keyboard use reveals order and traps; zoom exposes layout constraints; assistive-technology checks reveal announcements and names. Use all available evidence and describe the limits. Focus this course on a small flow so you can inspect its states carefully.

Worked example

The reading list passes a scan but the dialog closes after saving and sends focus to the top of the page. The task becomes tedious for keyboard users. Fix the return target, then repeat the original journey. A passing scan did not make that interaction correct, and one corrected flow does not certify the entire application.

Capstone practice

Complete search, open details, save and close using only the keyboard. Repeat at 200% zoom and with a long book title. Record failures with the triggering action, expected behavior and observed behavior. Fix the highest-impact barrier and rerun that exact sequence.

Review criterion

Deliver the working page and a short evidence log. List any browser or assistive-technology combination you could not test. Clear scope makes the review useful to the next person.

Write the question above the chart

A dashboard becomes useful when the reader knows which comparison matters.

Define the decision

Start with who will act, what they can change and the time window. List the measures needed for that decision. More metrics are not automatically more context; unrelated figures compete for attention. Keep the data’s unit explicit so a large number is not mistaken for a good outcome.

Worked example

The organizer asks which workshop needs an attendance follow-up. Fictional data: Print has 18 attendees from 20 bookings; Clay has 12 from 30; Light has 8 from 10. Counts alone rank Print highest, but rates reveal Clay at 40% compared with Print at 90% and Light at 80%. The organizer needs both capacity context and the attendance denominator.

Practice

Create a three-row table with workshop, bookings, attendees and rate. Write one sentence explaining the decision. Sketch a layout that makes the rate comparison visible while retaining the counts. Label these as fictional teaching data rather than real business results.

Common mistake

A chart titled “Performance” hides the meaning of its measure. “Attendance among booked places, week 1” gives the reader a denominator and a period before they interpret the values.

Choose an encoding that preserves comparison

Position and length are usually easier to compare than decorative area or perspective.

Match form to task

Use aligned bars for category comparisons and lines for ordered change over time. Keep bar baselines at zero when length encodes magnitude. A line chart can use a narrower range if the axis is explicit and the context justifies it. Avoid decorative three-dimensional depth that changes apparent sizes without adding information.

Worked example

Three horizontal bars show attendance rates of 90%, 40% and 80% on a shared 0–100% scale. Direct labels provide the exact rates and counts. Sorting by rate helps identify Clay quickly; alphabetical ordering may be better if readers repeatedly locate known workshops. Choose the order based on the task and keep it stable during comparison.

Practice

Draw the same data as bars and circles with area encoding. Ask which makes the difference between 80% and 90% easier to judge. Keep the useful chart and write down why. Add a label that still works when colors are removed.

Common mistake

Starting a bar axis at 35% makes a 40% bar look nearly empty compared with 90%. The visual length then exaggerates the difference. A clear scale is part of the message, not an optional technical detail.

Keep missing data visible

A blank measurement and a measured zero describe different events.

Audit before styling

Check units, time windows, duplicate rows and denominators. Represent missing observations explicitly. When a denominator is zero, a percentage is undefined rather than 0%. If a value is estimated, label that fact close to the chart. Do not interpolate a missing point merely because a continuous line looks better.

Worked example

Clay’s week-two attendance is missing because the count was not recorded. Its bookings are known, but that does not justify a zero attendance rate. Show a gap and “Not recorded.” For a canceled Light session with zero bookings, show “No session” rather than a percentage. These choices prevent the organizer from investigating an invented collapse.

Practice

Add one missing row and one canceled session to the four-week dataset. Define the text, chart mark and table value for each. Check that a reader can distinguish all three cases: zero attendees, no session and unknown attendance.

Common mistake

A smooth trend line can imply more precision than the collection process supports. Show the observations first and explain any transformation, including how you aggregate weeks with different booking counts.

Deliver the decision and its limits

A good data story helps the reader act without claiming more than the observations support.

Layer the information

Put the question and principal observation first, then the comparison, supporting table and methodological notes. Write a chart summary that names the pattern in words. Interactive tooltips can add detail, but essential values must remain available to keyboard and touch users. Provide a table for precise inspection.

Worked example

The page says “Clay needs follow-up: 12 of 30 booked places attended in week 1.” It does not say the instructor caused low attendance. A note proposes checking reminder delivery and cancellations before changing the programme. The chart supports where to investigate; it does not establish the cause.

Capstone practice

Build the attendance review with the supplied fictional values and your missing-data cases. Include a plain-language summary and table. Test at 390px: the question, critical comparison and units should remain visible without a hover action. Ask a peer what decision the page supports and what remains unknown.

Review criterion

Every prominent statement should trace to a displayed value or be labeled a hypothesis. Remove a chart if it adds no new evidence to the decision.

Let content reveal the breakpoint

A component’s narrow state should work before you decide when it can become wider.

Begin with flow

Use a natural document order: image, title, description and action. Let blocks grow with their content. Grid children sometimes need min-width: 0 so long content can shrink within the track. Use overflow-wrap for genuinely unbroken strings rather than truncating meaningful titles.

Worked example

A story card fits in a 280px sidebar until the title becomes “An unexpectedly long afternoon in the city.” A fixed 42px heading height clips it. Removing the fixed height solves the content problem without a new breakpoint. The action follows the description naturally, and the card grows; equal-height catalogue alignment can be handled by the parent grid.

Practice

Create the narrow card with a short title, a five-line title and an absent image. Test each in the same 280px container. Record which rules prevent overflow and which merely hide it. Keep the reading order understandable without CSS.

Common mistake

Adding a media query for every awkward word treats symptoms as device sizes. First fix the sizing contract; introduce a breakpoint when a different arrangement becomes more useful.

Query the space the card actually gets

A wide browser can still contain a narrow sidebar. Local layout needs local information.

Establish the container

Set container-type: inline-size on a wrapper and give it a name when the page has several candidates. Descendants can query that wrapper’s inline size. The query styles a descendant, not the queried container itself. Keep the wrapper in normal layout with a sensible width supplied by its parent.

Worked example

The story-card wrapper receives its width from either a sidebar or a grid track. Below 30rem the card remains stacked. Above that available width, the image and text become two columns. Moving the same component between parents changes its layout without changing the browser width or passing a “sidebar” class through the application.

Practice

Place two copies on a wide page, one in a 260px column and one in the remaining space. Resize the parent tracks while leaving the viewport unchanged. Confirm that only the wide card changes arrangement. Inspect which ancestor provides the query context when a nested container is added.

Common mistake

A query can silently bind to an unintended ancestor. Naming the container helps express which space the component is responding to, and a useful base layout protects readability if an enhancement is unavailable.

.story-slot { container: story / inline-size; }
.story-card { display: grid; gap: 1rem; }
.story-card > * { min-width: 0; }
@container story (min-width: 30rem) {
  .story-card { grid-template-columns: 2fr 3fr; }
}

.story-slot { container: story / inline-size; }
.story-card { display: grid; gap: 1rem; }
.story-card__text { min-width: 0; overflow-wrap: anywhere; }
@container story (min-width: 30rem) {
  .story-card { grid-template-columns: minmax(0, 2fr) minmax(0, 3fr); }
}

Separate page rules from component rules

The parent decides where a component lives; the component decides how its content fits.

Keep responsibility local

Use viewport queries for page-level decisions such as navigation layout. Use container queries for a card’s internal arrangement. Avoid allowing the child to demand an arbitrary page width. Treat decorative crop, text measure and action alignment as internal choices, while the parent controls track count and gaps between cards.

Worked example

A catalogue switches from one to three columns as the page gains space. Its cards still decide whether image and text can sit beside one another. On a very wide grid, a three-column page may give each card less space than a two-column page. A viewport-only rule would incorrectly assume every card is wide.

Practice

Build three placements for your card. Change the catalogue from two columns to three without editing card CSS. If the component breaks, identify a rule that assumed its surroundings. Add an image with a different aspect ratio and decide whether to crop or preserve it based on the story’s content.

Common mistake

Visual reordering can make keyboard and reading order disagree. Prefer a source order that works in every layout, and use grid placement for modest composition changes rather than rearranging the meaning.

Prove the component travels

A reusable component needs evidence from more than its original screenshot.

Build a stress matrix

Use widths around the actual transition, not only familiar phone and desktop presets. Include long text, missing media, browser zoom and translated labels. Check that the action remains reachable and that focus is not clipped by an overflow rule. Preserve a readable base presentation before applying enhancements.

Worked example

The card looks correct at 390px and 1280px but overflows at a 479px container width because a long action label cannot shrink. Allowing the label to wrap and removing a fixed minimum width fixes the boundary. This is a component defect that the two common viewport screenshots would have missed.

Capstone practice

Deliver the three placements and a short matrix of tested widths and content. Capture one failed boundary case and the change that fixed it. Use the project checklist to review semantic order, missing media and keyboard access.

Review criterion

Another developer should be able to insert the wrapper into a new grid without knowing your original page dimensions. Document the minimum viable width and any genuine content limits.

Make the requirement visible before the error

A form is easier to complete when the field explains what it needs before rejecting an answer.

Use the platform

Choose suitable input types, labels, autocomplete tokens and required constraints. Place examples and hints before submission, especially when a format is unfamiliar. Placeholder text is not a persistent label. Native validation offers a useful baseline, but its messages and timing still need review in your intended browsers.

Worked example

The reservation form labels an email field “Email for your reservation” and uses type="email" with autocomplete="email". The name field accepts ordinary punctuation and spaces rather than an overly restrictive letters-only expression. A session select has a clear unselected option. These choices reduce preventable errors before any custom JavaScript runs.

Practice

Build the three fields without custom validation. Tab through them, submit with missing values and use a valid address containing a plus sign. Record where the browser’s behavior is helpful and where your task needs additional explanation.

Common mistake

An elaborate regular expression can reject valid names and addresses. Validate the minimum structure needed by the task and leave domain-specific acceptance to the appropriate service. Client validation alone is never a trusted server boundary.

<label for="booking-email">Email for your reservation</label>
<input id="booking-email" name="email" type="email"
       autocomplete="email" required>

Validate at the moment someone can act

Feedback is useful when it helps repair an answer instead of interrupting the act of typing it.

Choose timing deliberately

Do not show an error merely because a newly focused field is empty. Validate on submission and, where helpful, revalidate a field after it has already failed. Keep the message next to the control and connect it with aria-describedby. Use aria-invalid only while the value is invalid, and remove stale error text after correction.

Worked example

A person types the first characters of an email address. The form waits rather than repeatedly announcing an incomplete address. On submission, it identifies the email field and preserves the name and chosen session. Once the address is corrected, the error state clears; the form does not require a full page reload.

Practice

Add one custom rule: the chosen session must still be present in the available-session list. Simulate its removal before submission. Show the problem beside the select and offer another choice. Keep the previous user-entered values in the other fields.

Common mistake

Color alone cannot explain which value failed or how to fix it. Pair the visual treatment with a specific message and ensure the focus indicator remains distinct from the error border.

Model submission as a state machine

A request being sent is not the same as a reservation being confirmed.

Name the states

Use idle, submitting, success and error. A transition to submitting should prevent duplicate attempts while preserving the values on screen. Only confirmed success should produce success copy. A network failure returns the form to a retryable state. On a real service, an idempotency mechanism is also needed to handle uncertain or repeated requests safely.

Worked example

The local simulation waits one second, then either returns a reservation object or throws. While pending, the button says “Checking reservation…” and cannot start another request. On failure, the form explains that the check did not finish and offers Try again. It does not invent a reservation number to make the flow look complete.

Practice

Write the four-state transition table before implementing it. Test double-clicking, a rejected promise and success after a retry. Log the number of handler calls so duplicate prevention is observable. Label the simulation clearly because it does not reserve a real seat.

Common mistake

Disabling the button forever after an error protects against duplicates by removing recovery. Restore a usable state after failure, and communicate whether the outcome is known or uncertain.

Test the uncomfortable paths

A form earns trust when a mistake or slow connection does not destroy the work already entered.

Create a journey matrix

Test empty submission, malformed input, unavailable session, slow completion, failure and retry. Use the keyboard and a narrow viewport. Ensure feedback does not move the page unexpectedly or hide the input beneath a fixed header. Inspect the actual submitted values, including unchecked or disabled controls.

Worked example

A disabled session select is omitted from FormData. The mock request therefore lacks the selected session even though the screen displays it. Keep essential data in your state model or build the payload deliberately before disabling controls. The visible interface and submitted payload must agree.

Capstone practice

Finish the form and add a development-only switch for success, slow and failure scenarios. Document each expected outcome and compare it with the actual UI. Include one screenshot of recovery after an error, with the earlier name and email still present.

Review criterion

A peer should be able to make a mistake, understand it, correct it and reach the local success state without re-entering unrelated information. Keep the simulated nature of the result visible.

Replace combinations with named states

Three independent booleans create combinations that your product may never intend to support.

Find the contradictions

Consider loading, hasError and hasData. If all three are true, which screen should appear? A discriminated union gives each meaningful state a name and its own required data. It does not eliminate design decisions; it forces you to make them explicit instead of hiding them in nested conditions.

Worked example

A resource is idle, loading, ready with books, or error with a message. The ready variant always contains the books array, including an empty one. Loading does not pretend to contain usable data. If you want stale data during refresh, add a deliberate refreshing variant rather than accidentally mixing flags.

Practice

Write the union below and create one value of each variant. Try to construct an error without a message and a ready value without books. Run your type checker and inspect the errors. Then decide whether empty success deserves a separate variant or can be derived from an empty array.

Common mistake

Optional properties on one broad object allow many incomplete combinations. A discriminant ties the available fields to the state in which they have meaning.

type Book = { id: string; title: string };
type LoadState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "ready"; books: Book[] }
  | { status: "error"; message: string };

type Book = { id: string; title: string };
type LoadState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'ready'; books: Book[] }
  | { status: 'error'; message: string };

Let narrowing guide the renderer

Checking the discriminant tells both you and the compiler which fields are available.

Render one variant at a time

Use a switch or conditional that checks the shared discriminant. Inside the ready branch, access the data guaranteed by that variant. Avoid non-null assertions that silence a useful warning. Use an exhaustive final branch so adding a future state requires a presentation decision.

Worked example

The loading branch returns a progress message, ready returns the item count, and error returns its message. A never assignment in the default branch fails type checking if a new “refreshing” variant is added without updating the renderer. This connects the model’s evolution to the screens that must support it.

Practice

Add a refreshing variant with existing books. Run the type checker before changing the renderer. Use the resulting error to locate the missing behavior, then decide whether old content stays interactive during refresh. Write that decision alongside the model.

Common mistake

Casting every branch to the desired type defeats the model. An assertion tells the compiler to trust you; it does not prove that the value has the required shape.

function label(state: LoadState): string {
  switch (state.status) {
    case "idle": return "Choose a list";
    case "loading": return "Loading";
    case "ready": return `${state.books.length} books`;
    case "error": return state.message;
    default: { const missing: never = state; return missing; }
  }
}

Treat outside data as unknown

A type annotation describes your expectation; a network response can still violate it.

Validate before promoting

Start external JSON as unknown and check the properties your application depends on. A validator can be handwritten for a small shape or provided by a schema library. Either way, it must execute at runtime. Keep a useful error path when the data is malformed instead of allowing a later render to fail mysteriously.

Worked example

The loader expects a book with string id and title. A response containing title: null is not a Book merely because the fetch call is followed by “as Book.” A small guard checks that the value is a non-null object and the required fields are strings. The application can then enter an error state with a truthful message.

Practice

Test a valid book, null, a number, an object with a numeric id and an object with missing title. Decide whether empty strings are permitted by your domain. Type structure and business rules are related but distinct checks; document both.

Common mistake

JSON parsing only proves syntactic validity. It does not prove that the object is suitable for your application. Place validation close to the boundary so the rest of the code can rely on a smaller set of assumptions.

Keep selection consistent with the collection

A valid item ID can become invalid when the collection changes.

Design the invariant

Decide what selection means when an item disappears after refresh. You might clear the selection or move to a neighboring item. Store an ID rather than an entire duplicate object when the collection is authoritative, then derive the selected item from current data. Types help express the model, but transitions must still preserve its invariants.

Worked example

Book B is selected before a refresh removes it. Looking up B now returns undefined. The transition checks the new collection and clears selection if the ID is absent. The detail panel returns to its empty prompt rather than showing stale title data from a copied object.

Capstone practice

Implement the loader and selection transitions. Test ready-to-loading-to-error, successful empty data, malformed data and removal of the selected item. Deliver the state diagram, the typed implementation and a short record of which invalid combinations the model prevents.

Review criterion

A new developer should be able to add a state and see which presentation and transition decisions need attention. Keep assertions rare and explain any unavoidable ones.

Separate the query from the result

The text being typed and the data currently visible are related but not identical values.

Model the states

Store the current query, the request status and the data associated with a completed query. A loading state can retain old results if the interface labels them clearly. Empty success means the request finished with no matches; error means the request could not establish a result. Do not use one generic empty screen for both.

Worked example

A person searches “coast,” then types “coastal.” While the second request is pending, the previous results can remain with a small updating message. When the new result arrives, the label and list change together. If it fails, the interface can explain that the update failed while retaining the previously identified results.

Practice

Draw the state sequence for first load, update, empty success and error. Write the exact status sentence for each. Include the query that produced visible data, so an old list is not silently presented as the answer to a new search.

Common mistake

Clearing everything as soon as a request begins can create unnecessary flicker. Keeping old data without a label creates a different problem: the page appears to answer a query it has not completed.

Let the latest request own the screen

Requests do not necessarily finish in the order they started.

Guard the commit

Assign a monotonically increasing request ID. Capture it when starting work and check it before committing either data or an error. This protects the UI even if the underlying work cannot be canceled. A stale request may finish, but it no longer has permission to change the current screen.

Worked example

Search A starts first and takes 900ms. Search B starts later and takes 100ms. Without an ownership check, A overwrites B after B has already appeared. Checking the captured ID against the latest ID prevents both stale results and stale failures from replacing the current state.

Practice

Create a fake search function with two controlled delays. Start A and B quickly, then confirm that only B is rendered. Reverse which request fails. Test the error branch as carefully as the success branch; a stale rejection must not show an error over fresh results.

Common mistake

Debouncing reduces how often requests start, but it does not prove that responses arrive in order. Keep correctness separate from the strategy used to reduce work.

let latest = 0;
async function search(query) {
  const request = ++latest;
  try {
    const items = await loadBooks(query);
    if (request === latest) renderResults(items);
  } catch (error) {
    if (request === latest) renderError(error);
  }
}

Cancel work without confusing failure

Cancellation describes work you no longer need, not necessarily a failure the user must repair.

Use the lifecycle

Create an AbortController for a request and pass its signal to APIs that support cancellation. Abort the previous request when it becomes obsolete and clean up when the owning view is removed. Handle an intentional abort differently from a network error. Keep an ownership guard because cancellation may arrive after useful work has already completed.

Worked example

A search view starts fetch with a signal. Typing a new query aborts the old request, and leaving the view aborts the current one. The interface does not flash “Something went wrong” for those intentional aborts. A genuine server failure, however, enters a visible retryable error state.

Practice

Add cancellation to the delayed-search exercise. Count started, aborted and committed requests. Navigate away before a response completes. Confirm that removed UI is not updated and that cancellation does not leave a permanent loading indicator when the view returns.

Common mistake

Creating a controller without passing its signal changes nothing. Follow the signal through the actual API call and verify the resulting behavior rather than trusting the presence of the constructor.

Make retry repeat the intended operation

A retry button needs a clear relationship to the failed request.

Capture the intent

Decide whether retry uses the last failed query or the currently edited query. Make the label and implementation agree. Prevent uncontrolled duplicate submission, but restore the action after a failure. Check response.ok before treating a fetch response as successful, because HTTP error status does not automatically reject the promise.

Worked example

The failed query is “coast,” but the input now reads “mountain.” A button labeled “Retry coast” should retry coast, not silently use mountain. Alternatively, “Search again” can use the current input if that contract is clear. For a 503 response, show the error state even though fetch resolved to a Response object.

Capstone practice

Complete the search and run a table of scenarios: empty query, zero matches, HTTP failure, reordered completion, cancellation and retry after editing. Use a deterministic service so each case is repeatable. Record the query and data shown at the end of every test.

Review criterion

The final screen must belong to a clearly identified user intent. Smooth loading animation does not compensate for data attached to the wrong query.

Translate promises into observations

“Saving works” is too vague to tell you what should be checked.

Write a behavior contract

Describe a starting state, an action and an observable result. Include the thing that must remain unchanged. Test at the smallest useful level: a filtering function can prove data selection, while a browser journey proves that a control calls it and presents the result. Neither replaces the other.

Worked example

Given three books and no saved items, saving Book A should add exactly A to the saved set, update the button and make A appear in the saved view. Saving it again should remove it if the control is a toggle. The original book catalogue must retain its order. These are distinct claims that deserve distinct evidence.

Practice

Write five contracts for the reading list. Include a zero-result search and a save action while a category filter is active. Label which contracts belong to pure logic tests and which require the rendered interface.

Common mistake

A test that merely checks whether a function was called can pass while the user sees incorrect output. Prefer meaningful state or visible-result assertions when they capture the actual promise.

Test boundaries and combinations

Many defects appear where individually correct features meet.

Build a compact matrix

Test empty input, normal input, repeated input and boundary values. Add combinations that share state, such as search plus category or saved plus sort. Use small fixtures where the expected result is obvious. Keep the source array unchanged so one test cannot silently alter the next.

Worked example

A price sort mutates the global catalogue in place. Search tests still pass individually, but the default curated order changes after using the sort menu. Copying before sort preserves the catalogue contract. A test should compare the original ID sequence before and after filtering, not only inspect the sorted result.

Practice

Create four fixture books with two categories and distinct prices. Test a combined query/category filter, a query with no matches, and ascending price order. Then assert that the fixture’s original ID sequence is unchanged. Add a duplicate saved ID to test normalization.

Common mistake

Huge realistic fixtures can make expected behavior difficult to see. Begin with the smallest set that demonstrates the rule, then add a specific fixture only when it exposes a real edge.

Exercise the actual interface

The browser adds focus, layout, timing and storage behavior that a pure function does not contain.

Follow the user’s route

Find controls by role and accessible name when possible. Operate search, open details, complete the free lesson and inspect the library. Wait for a meaningful state rather than an arbitrary long delay. Include keyboard navigation and Escape behavior for dialogs, then verify the state after reload.

Worked example

A lesson completion test clicks “Mark lesson complete,” observes the completed label and checks the library count. After reload, the count remains. It also checks that a locked lesson cannot be opened before demo enrollment. Merely seeing a progress bar would not establish either persistence or access behavior.

Practice

Run the journey once manually and write down the exact visible labels. Automate the stable steps with your chosen browser-testing tool. Use a separate test storage key or isolated browser context so the test does not clear someone’s real notes or enrollments.

Common mistake

Forcing clicks through overlays can hide a usability failure. If the control cannot be reached normally, inspect why before weakening the test. A passing test should reflect a possible user action.

Keep a regression test worth maintaining

A good regression check protects a behavior that mattered enough to fail.

Reproduce before fixing

Record the trigger, expected result and actual result. Make a test fail for that reason, apply the fix, and verify the same test passes. Avoid asserting every CSS class or internal helper call unless that is the contract. Visual judgment still belongs in a separate review of hierarchy, clipping and readability.

Worked example

A saved item disappears from the catalogue when the saved filter is cleared because the implementation replaced the source list. A four-item fixture reproduces it. The fix derives the visible list instead. The regression test checks the restored IDs, while a browser check verifies that the Clear filters control actually reaches that state.

Capstone practice

Introduce a deliberate source-array mutation, observe your test fail, and then restore the correct implementation. Deliver a short report listing automated outcomes, manual observations and untested environments. Keep one screenshot of a meaningful state, not a folder of unexplained captures.

Review criterion

Another developer should understand which promise each test protects. Remove assertions that only mirror implementation and do not distinguish a correct result from a plausible-looking failure.

Choose the moment that feels slow

A fast initial render does not guarantee a responsive search or a stable page.

Separate the concerns

Loading, interaction latency and layout stability describe different experiences. Core Web Vitals currently include LCP, INP and CLS, but a local lab run is not a field distribution. Define the journey you are investigating and the device/network conditions. A metric is a signal to inspect, not a replacement for understanding what the user was doing.

Worked example

A catalogue displays its title quickly but its large hero image arrives late. Search is responsive until every keystroke rebuilds dozens of complex cards. A late image without reserved space pushes the filter bar downward. These are three different problems; minifying one stylesheet may not solve any of their main causes.

Practice

Record opening the page, typing a query and scrolling to the first card. Note the visible delay and inspect the relevant network or performance trace. Choose one moment to improve and write a hypothesis about the work causing it.

Common mistake

Comparing a cached desktop run with an uncached mobile run produces an impressive but meaningless difference. Keep conditions consistent and state what the measurement covers.

Give the important image a sensible budget

Image quality is a design decision constrained by display size, crop and delivery cost.

Match asset to use

Export images near the sizes actually displayed and provide responsive candidates when appropriate. Reserve width/height or aspect ratio so the layout knows the space before decoding. Prioritize genuinely important above-the-fold media and defer offscreen media thoughtfully. Evaluate the compressed result at its actual size, including gradients and fine edges.

Worked example

A 4000px photograph is displayed in a 360px card. A smaller candidate reduces transfer and decode work without visibly changing the card. The hero still receives a larger source because its crop fills a wide display. Supplying one tiny image for every placement would improve bytes while damaging the design’s central material detail.

Practice

Export three candidate sizes for one photograph. Compare file size, rendered sharpness and decode behavior at the intended placement. Add dimensions and verify that the filter bar no longer shifts when the image loads. Keep your choice and its reason in the budget notes.

Common mistake

Lazy-loading the largest immediately visible image can delay the main content. Decide priority from the actual opening composition rather than applying one attribute to every image.

Reduce work on the interaction path

The fastest task is often the work you can avoid doing on every input.

Inspect the cost

Profile a concrete interaction before optimizing it. Look for repeated layout reads/writes, expensive synchronous computation and unnecessary rebuilding. Batch reads before writes where possible. Schedule visual updates with the browser, but remember that requestAnimationFrame does not make expensive work free. It only aligns a callback with rendering opportunities.

Worked example

Dragging a slider reads every card’s dimensions and then changes each style in alternating order. The trace shows repeated layout work. Read the needed geometry once, calculate the values, then write the updates together. If the effect is offscreen or motion is paused, stop scheduling it rather than continuing invisible work.

Practice

Instrument the number of updates during a five-second interaction. Remove one redundant computation or DOM reconstruction and repeat the same input sequence. Compare the trace and inspect the final visual state. Test rapid input to ensure skipped intermediate work still settles correctly.

Common mistake

An arbitrary delay can make the interface feel smoother by postponing work while making it less responsive. Preserve immediate feedback and move or reduce the expensive work deliberately.

Write a budget that protects the experience

A useful budget connects a measurable limit to something the product should preserve.

Define a scenario

State the page, task, device class, viewport, network and cache conditions. Choose a small number of limits you can measure repeatedly, such as image transfer or long tasks during a specific interaction. Keep visual and accessibility checks beside the performance evidence so an optimization cannot quietly remove essential content.

Worked example

The catalogue budget limits offscreen card image work during the opening view and checks that search remains responsive with all 26 entries. The before/after report includes the same viewport and input sequence, multiple runs and representative screenshots. It describes the measured change without claiming that one local browser predicts every visitor’s experience.

Capstone practice

Deliver the baseline trace, one targeted change and repeat measurements. Record the median and the range across several comparable runs. Explain what became cheaper, what stayed visually equivalent and what you did not test. Add a regression check for the specific waste you removed.

Review criterion

A reviewer should be able to repeat your scenario and understand the tradeoff. A score without conditions is weaker evidence than a modest, well-explained improvement.

Place the camera before adding effects

A 3D scene becomes understandable when you can explain what is being viewed and from where.

Three responsibilities

The scene holds objects. The camera describes a view. The renderer draws that view into a canvas. Begin with a plain material so lighting is not another unknown. Create a one-unit box at the origin and position the camera several units away. Look toward the origin and render once before introducing an animation loop.

Worked example

For a small sculpture, place a sphere at x = -1.4, a box at the origin and a ring at x = 1.4. Put the camera at (0, 1.5, 6). The lateral spacing makes the three silhouettes readable. A camera accidentally inside the box produces a confusing view that brighter lights will not fix.

Practice

Use the starter below as your module entry in a local bundled project with three@0.186.0 installed. A bare browser import needs an import map; this example assumes your bundler resolves the npm package. Change only camera position, then only object position. Explain the difference in a sentence. Add a nearby HTML description of the sculpture.

Common mistake

When nothing appears, inspect canvas size, camera direction and object placement before adding effects. Reduce the scene to one object to isolate the missing relationship.

import * as THREE from "three";
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
camera.position.set(0, 1.5, 6);
camera.lookAt(0, 0, 0);
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshNormalMaterial();
scene.add(new THREE.Mesh(geometry, material));
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(480, 480);
document.body.append(renderer.domElement);
renderer.render(scene, camera);

Group objects around a useful pivot

Transforms become easier to control when the hierarchy matches the movement you intend.

Local and shared movement

Each object has a transform relative to its parent. Put the three sculpture pieces in a Group and rotate the group to turn the whole composition. Move a child to change its place within that composition. Choose the group origin as the pivot you actually want; a misplaced pivot makes an apparently simple rotation orbit around a distant point.

Worked example

The ring should spin around its own center while the garden turns slowly as a whole. Give the ring its own rotation and the parent group a separate rotation. Moving the parent changes the complete arrangement; changing the ring does not disturb its neighbors. Draw this hierarchy as a small tree before coding.

Practice

Create a garden group with three children. Add native buttons for front and side views. Set absolute target positions on reset rather than subtracting earlier movements; repeated reset must give the same result.

Common mistake

Applying the same movement independently to every child scatters one intention across several places. Use a shared parent when the objects genuinely belong to one moving assembly.

Fit the canvas without stretching the world

The canvas has a layout size and a drawing-buffer size. Treat them as related, separate decisions.

Measure the host

Measure the container that owns the canvas, not an assumed full browser width. Update the perspective camera aspect ratio from width divided by height, call updateProjectionMatrix, and update the renderer size. Guard against zero height when the container is hidden. Limit pixel ratio if necessary so a dense display does not create an unreasonable rendering workload.

Worked example

A square preview becomes a wide panel on desktop. Resizing only the CSS stretches the rendered sphere into an ellipse. Updating the camera projection as well as the renderer preserves its shape. A ResizeObserver can report changes caused by a sidebar opening even when the browser itself has not resized.

Practice

Place the scene in a resizable panel. Test square, wide and tall hosts, then hide and restore the panel. Compare a circle silhouette before and after each resize. Record the pixel-ratio cap you chose and the visual tradeoff.

Common mistake

Rendering at the maximum device pixel ratio everywhere spends pixels before establishing whether the extra detail is visible or useful. Measure on the intended device class.

Give the scene a lifetime

An embedded scene should start, pause and stop as deliberately as any other interface component.

Control the loop

Use elapsed time for rotation rather than adding a fixed amount per frame. Provide a visible pause control and respect reduced-motion preferences with a static initial presentation. Keep native controls outside the canvas. Track the resources and listeners created by the scene so teardown can release them.

Worked example

Navigating between two previews mounts the garden repeatedly. If each mount leaves an animation loop behind, hidden scenes continue working. A destroy function stops the animation loop, disconnects observers, removes listeners and disposes the geometry, material and renderer that this instance owns. Shared resources need a separate ownership policy.

Capstone practice

Finish the garden, then mount and remove it three times in your development page. Verify that pause and reset still behave correctly and that the number of active callbacks does not grow. Include a text fallback for unavailable WebGL.

Review criterion

The scene is complete when it behaves well inside the page, including after resizing, pausing and removal. A beautiful first frame alone is not the acceptance test.

Change one variable at a time

A convincing material study starts with a controlled comparison.

Establish a reference

Use the same geometry and camera for every specimen. Give the object enough curvature to reveal a highlight and a broad face to reveal color. Begin with a neutral background and one clear key light. Record the starting values before changing the mood; otherwise every attractive result becomes difficult to reproduce.

Worked example

Three identical rounded objects are labeled ceramic, metal and rubber. When their shapes and framing differ, it is impossible to tell whether the impression comes from the surface or the silhouette. Reusing one geometry turns the comparison into a useful experiment. Keep an unedited reference specimen beside each variation.

Practice

Make a three-column study using one mesh geometry. Change only roughness across the columns, then make a second row changing only base color. Describe the visual evidence for each difference without using “more realistic” as the entire explanation.

Common mistake

Changing light intensity, exposure and material color simultaneously can make a pleasant image, but it does not teach you which parameter caused the improvement.

Read the highlight, not just the color

The shape and spread of a reflection communicate a surface’s character.

Surface controls

MeshStandardMaterial uses metalness and roughness. Begin non-metal specimens at metalness 0 and a metal specimen at 1. Adjust roughness while observing the highlight. A metal needs something useful to reflect; a dark appearance may be an environment problem rather than a reason to increase base color indefinitely.

Worked example

The ceramic specimen has a relatively concentrated highlight while the rubber specimen spreads it. Both remain non-metallic. The metal specimen reflects the lighting environment differently. These are art-directed interpretations, not measurements of real manufactured materials. Keep your labels honest about that distinction.

Practice

Use the code values as starting hypotheses. Move the light without changing the surface, then restore it and change roughness. Save a comparison sheet describing which visual cue helped you distinguish the changes.

Common mistake

Using metalness as a general “shininess” slider confuses two different properties. Start from the type of surface, then tune its reflection spread.

const ceramic = new THREE.MeshStandardMaterial({
  color: 0xd9bda4, metalness: 0, roughness: 0.3
});
const rubber = new THREE.MeshStandardMaterial({
  color: 0x343d38, metalness: 0, roughness: 0.85
});
const metal = new THREE.MeshStandardMaterial({
  color: 0xaaaaaa, metalness: 1, roughness: 0.35
});

Keep color roles explicit

A texture can represent visible color or numerical surface information; those are different inputs.

Audit the pipeline

Label every texture by its role before loading it. Color images and roughness data should not be treated interchangeably. Check the renderer output configuration and any postprocessing output step. Avoid adding a second color conversion simply because the result looked brighter. Keep a plain reference render to compare against the processed version.

Worked example

A material changes appearance after adding a postprocessing chain. Before retuning all its colors, compare the output conversion and tone-mapping steps. If the discrepancy belongs to the pipeline, changing every material creates compensating errors that will reappear in another scene.

Practice

Write a small asset table: filename, role, color-space setting and owning component. If you use no textures, document the output path instead. Compare a neutral reference and a saturated patch with and without your effects chain.

Common mistake

A correction made only by eye in one scene can hide a pipeline inconsistency. Fix the source of the discrepancy, then return to the creative material decision.

Light a story with a budget

Lighting should guide attention while remaining practical for the page that contains it.

Choose a visual intention

Name the intended mood in observable terms: a crisp silhouette against a quiet background, or a broad soft highlight that reveals curvature. Build two setups from that intention. Introduce shadows only where they clarify contact or depth; review their cost and artifacts at the actual display size.

Worked example

The gallery setup uses a restrained background and broad readable highlights. The evening setup introduces a warm key and darker surroundings, but the object’s edge remains legible. A “dramatic” version that hides the subject fails the purpose of a material comparison.

Capstone practice

Finish the three specimens and two lighting presets. Add keyboard-operable preset buttons and a static fallback image or description. Compare rendering cost and visual quality at the intended canvas size, then document a lower-cost setting.

Review criterion

A viewer should see both the difference between materials and the intention behind each lighting setup. Include the reference configuration so another developer can reproduce the comparison.

Make the coordinate system visible

Before drawing a complex effect, draw a map of the space in which it will exist.

Normalize deliberately

gl_FragCoord describes the fragment in drawing-buffer pixels. Divide by a resolution uniform to obtain a normalized coordinate. Center it around zero, then compensate for aspect ratio so equal distances remain equal on screen. Keep the resolution uniform synchronized with the actual drawing buffer, especially on dense displays.

Worked example

A circle calculated directly in 0–1 coordinates becomes an ellipse on a wide canvas. Scaling the horizontal centered coordinate by width divided by height makes a distance of 0.2 correspond to the same screen distance in either direction. This defines a useful unit based on canvas height.

Practice

First output the normalized coordinates as red and green channels. Identify the corners and center. Then draw a circle at the center and test square, tall and wide canvases. Describe exactly what a unit means after your aspect correction.

Common mistake

Using CSS dimensions for a shader that reads drawing-buffer pixels can introduce a mismatch. Inspect the actual buffer dimensions and pass those to the uniform.

A shape is a distance decision

A signed distance field gives you more than a binary inside-or-outside mask.

Measure from the boundary

For a centered circle, length(p) minus radius is negative inside, zero at the edge and positive outside. Use this value to create a fill, an outline or a soft boundary. Keep softness tied to the intended display scale; an arbitrary large feather can erase the character of the shape.

Worked example

The fragment shader below uses a circular field and a narrow smooth transition. It is a WebGL 1 style fragment shader for a compatible host; the host must supply u_resolution and a full-screen triangle. It is not a complete HTML application. A Three.js ShaderMaterial can supply the surrounding vertex stage.

Practice

Change the radius, then turn the filled circle into a ring using abs(distance). Compare a thin outline at two canvas sizes. Inspect shader compile logs after each structural edit, and keep the last working version.

Common mistake

Reversed smoothstep edges are not a portable way to invert a mask. Keep the lower edge first and subtract the result from 1 when you want the opposite mask.

precision mediump float;
uniform vec2 u_resolution;
void main() {
  vec2 p = gl_FragCoord.xy / u_resolution - 0.5;
  p.x *= u_resolution.x / u_resolution.y;
  float d = length(p) - 0.28;
  float ink = 1.0 - smoothstep(-0.004, 0.004, d);
  vec3 paper = vec3(0.94, 0.88, 0.75);
  vec3 color = mix(paper, vec3(0.85, 0.18, 0.09), ink);
  gl_FragColor = vec4(color, 1.0);
}

precision mediump float;
uniform vec2 u_resolution;
void main() {
  vec2 p = gl_FragCoord.xy / u_resolution - 0.5;
  p.x *= u_resolution.x / u_resolution.y;
  float radius = 0.28;
  float thickness = 0.02;
  float d = length(p) - radius;
  float edge = 1.0 / u_resolution.y;
  float fill = 1.0 - smoothstep(-edge, edge, d);
  float ring = 1.0 - smoothstep(thickness - edge, thickness + edge, abs(d));
  // Use fill instead of ring below to compare the filled shape.
  vec3 paper = vec3(0.94, 0.88, 0.75);
  gl_FragColor = vec4(mix(paper, vec3(0.85, 0.18, 0.09), ring), 1.0);
}

Repeat a rule, then break it intentionally

Repetition creates a system; controlled variation gives that system a point of view.

Separate frequency and phase

A repeating stripe can depend on a coordinate multiplied by frequency and shifted by phase. Frequency changes how many bands appear; phase moves the pattern without changing its density. Keep these controls independent so you can explain a visual revision. Very dense patterns may shimmer when sampled by the screen.

Worked example

The poster places broad bands behind a circle. Increasing frequency from six to sixty creates distracting interference near the edge. Reducing density improves the composition more effectively than adding blur everywhere. A single interrupted band creates a focal event while the rest of the field establishes rhythm.

Practice

Make three still studies with identical colors but different band frequency. Choose one based on hierarchy and legibility at the smallest display size. Add a labeled phase control and confirm that it changes position rather than accidentally changing scale.

Common mistake

More mathematical complexity does not automatically produce a stronger image. Keep a plain version available so each new rule has to justify its contribution.

Give time a compositional purpose

An animated poster needs a coherent still frame as well as a pleasant loop.

Animate a meaningful parameter

Choose one main change, such as the phase of the bands or the radius of a shape. Use elapsed time in seconds, not frame count. Define a static phase that preserves the composition when motion is paused or reduced. Controls should remain normal HTML so keyboard users can operate them.

Worked example

The circle stays fixed while the bands move slowly behind it, revealing a contrast between stability and flow. Animating every property at once removes that relationship. A pause button freezes a deliberate composition, while reset restores the same parameter values every time.

Capstone practice

Deliver the poster with two parameter controls, a static mode and a short description of its rules. Test shader compilation, resize and a context failure path. Capture a still at the narrowest intended size and explain the strongest compositional decision.

Review criterion

The result should remain recognizable as the same design across sizes and motion preferences. Treat a shader error as a visible fallback state, not an empty unexplained rectangle.

Design the field before increasing the count

A particle system is a composition made from a rule, not simply a large number.

Choose the distribution

Decide where objects are allowed to begin and what larger shape they create together. Store initial positions separately from current positions so reset and return forces have a stable target. Use a seeded generator when you need the same arrangement for debugging or art direction.

Worked example

Four hundred objects occupy a gently bent grid. Small seeded offsets soften the rows without destroying their structure. The grid supplies visual order; the offsets supply variation. Starting from unconstrained randomness makes it harder to see whether an interaction returns the field to a coherent state.

Practice

Sketch a field with twenty points before writing the full system. Compare a grid, ring and clustered distribution. Choose one and state the rule precisely. Save its seed and verify that reloading reconstructs the same coordinates.

Common mistake

Regenerating random positions every frame creates flicker rather than a simulation. Randomness should usually establish stable properties that evolve through a separate movement rule.

Share the geometry; vary the transform

Repeated shapes can share rendering resources while retaining individual positions and scales.

Instance the repetition

InstancedMesh stores many transforms for shared geometry and material. Use a temporary Object3D to compose each transform, update its matrix, then pass that matrix to setMatrixAt. After changes, mark instanceMatrix.needsUpdate. Recompute bounds when transforms change enough to invalidate them; incorrect bounds can cause unexpected disappearance.

Worked example

The snippet creates a regular field using a supplied THREE import and scene. Every object shares one low-detail sphere and one material. The temporary transform object is reused instead of allocating a new one per particle per frame. The simulation can remain plain arrays independent of the mesh.

Practice

Render 400 instances and compare draw calls with 400 separate meshes in the same scene. Keep geometry, camera and material identical for a fair comparison. Record the actual result; fewer draw calls do not guarantee that every other cost disappears.

Common mistake

Instancing reduces repeated draw setup, but an expensive shader or excessive pixel coverage can still dominate. Measure the bottleneck you actually have.

const count = 400;
const field = new THREE.InstancedMesh(
  new THREE.SphereGeometry(0.035, 8, 6),
  new THREE.MeshNormalMaterial(), count
);
const transform = new THREE.Object3D();
for (let i = 0; i < count; i++) {
  transform.position.set((i % 20) * 0.12 - 1.14, Math.floor(i / 20) * 0.12 - 1.14, 0);
  transform.updateMatrix();
  field.setMatrixAt(i, transform.matrix);
}
field.instanceMatrix.needsUpdate = true;
field.computeBoundingSphere();
scene.add(field);

Bound the force and the time step

An attractive field should not explode when the pointer approaches a particle or a frame arrives late.

Separate the simulation

Keep position, velocity and home position in data. A return force points toward home; damping removes energy. If a pointer force divides by distance, impose a minimum distance and cap the force. Use a bounded time step or substeps so a delayed frame does not produce one enormous jump.

Worked example

A pointer lands exactly on a particle. Dividing by zero distance creates an invalid velocity and the particle disappears. A minimum radius and a zero-distance direction policy prevent this. When a tab resumes after being hidden, cap the elapsed step rather than integrating the entire absence at once.

Practice

Inject a 250ms delayed frame and place the pointer exactly on a particle. Observe whether every position remains finite. Add a keyboard button that triggers the same bounded disturbance at the field center.

Common mistake

Clamping the displayed position while leaving an enormous velocity in the model hides the failure for one frame. Bound the cause and let damping dissipate energy.

Measure the illusion at two quality levels

The strongest system preserves its character when the device cannot afford every detail.

Define the essential image

Decide whether density, silhouette or response softness makes the field recognizable. Reduce a less important cost first: object detail, pixel ratio or count. Compare the same seeded scene and interaction under the same conditions. Report the device, viewport and measured metric alongside the result.

Worked example

A lower-density mode uses 200 objects but preserves the overall bent-grid shape and disturbance radius. It still feels like the same piece. Randomly removing half the field on every frame would reduce count while destroying continuity. A static mode retains the composition without running the simulation.

Capstone practice

Deliver the field with two density settings, a seeded reset, pause and keyboard disturbance. Record frame-time samples for both modes, including your measurement conditions. Verify that changing density releases unused resources and does not accumulate listeners.

Review criterion

Explain one measured tradeoff and one preserved visual intention. Avoid claiming a universal frame rate from a single computer.

Write the page before animating it

A scroll story needs a sequence of ideas that works even when every frame is still.

Assign each chapter a job

Write the question a chapter answers and the new information it adds. Avoid three sections that repeat the same promise at increasing scale. Place the essential text in the document, with meaningful headings and links. Motion can reveal a relationship, but should not be the only way to obtain the information.

Worked example

The seed-library story begins with collecting varieties, moves to exchanging them, then ends with the next season’s growth. One seed becomes many packets and later a living pattern. Each transformation corresponds to a real change in the story, rather than an arbitrary visual trick between unrelated paragraphs.

Practice

Write three chapter summaries of no more than forty words each. Underline the new idea in each. Build a plain HTML version and ask someone to retell the sequence without seeing any animation. Revise unclear transitions before opening a timeline editor.

Common mistake

A page that only makes sense when read at one precise scroll speed is fragile. The reader may skip, reverse, use search or arrive at a deep link.

Map a local interval into progress

Each scene needs an explicit beginning and end rather than a vague relationship to the whole page.

Normalize the interval

Choose scroll positions start and end for the scene, then map the current position into a 0–1 value. Clamp values outside the interval. Guard against a zero-length interval. Recalculate the geometry when layout changes, including image loading or viewport resizing, and separate measurement from per-frame visual updates.

Worked example

A packet opens between scroll positions 600 and 1400. At 1000, the local progress is 0.5. Scrolling backward naturally closes it because the visual state derives from progress rather than a one-time “play” event. The mapping below is a pure function you can test independently.

Practice

Write expected values before running the function: before start, at start, halfway, at end and beyond end. Test an invalid interval. Then map the value to a single transform and inspect reversal at every point.

Common mistake

Accumulating a transform on every scroll event makes the result depend on how many events fired. Derive the current state from current progress instead.

function progressAt(y, start, end) {
  if (end <= start) return 0;
  return Math.max(0, Math.min(1, (y - start) / (end - start)));
}

Stage the transition around attention

A transition should help the eye follow the idea that changed.

Choose an anchor

Keep one element or position stable while another changes. Introduce, transform and settle rather than moving every layer continuously. Reserve enough reading space after the transition so the audience can inspect the result. Avoid pinning so much content that a phone viewport becomes a cramped animation stage.

Worked example

The seed remains near the center while its surrounding packet opens. The next chapter introduces exchange lines after the packet has settled. Delaying the lines makes the causal sequence legible. On a narrow screen, the illustration sits above the text and uses a simpler fade or static state.

Practice

Storyboard five still frames: before, anticipation, change, arrival and rest. Label the element the viewer should notice first in each. Build the transition with transforms and opacity where suitable, then inspect the page while scrolling quickly and backward.

Common mistake

Long animation does not create narrative depth by itself. A reader waiting for an oversized transition to finish may lose the thread of the story.

Let the reader interrupt

The story belongs to the reader’s pace, device and motion preference.

Test alternate arrivals

Open a chapter link directly, resize halfway through a scene and switch to reduced motion. Ensure focusable controls are not hidden in off-screen decorative layers. Use normal anchors for the chapter index. A static mode should show complete information rather than leaving objects transparent because their entrance animation never ran.

Worked example

A deep link lands on Exchange before the opening animation executes. The chapter heading and copy must already be present. If the decorative packet needs a state, derive it from the current scroll position immediately; do not require the reader to revisit the top of the page to initialize the story.

Capstone practice

Finish the three-chapter seed-library page. Test keyboard navigation, direct links, quick reverse scrolling, resize and disabled JavaScript. Capture the static version and explain how the same narrative relationships remain visible.

Review criterion

The reader can choose the route and pace without losing information. Document any simplified mobile choreography as a deliberate composition, not an unfinished desktop effect.

Separate the target from the current position

A spring is a relationship between where an object is and where it is being asked to go.

Name the state

Track current position, velocity and target. Stiffness pulls toward the target; damping resists velocity; mass affects acceleration. Begin in one dimension so the response is easy to inspect. Draw position over time and describe overshoot, settling time and interruption without relying on a library’s preset names.

Worked example

A thumb currently sits at x=20 while its target is x=100. It accelerates toward the target, then damping reduces its energy. Increasing stiffness makes the pull stronger; increasing damping changes how the motion settles. Changing both at once makes it harder to understand the response you are designing.

Practice

Draw three desired responses: calm arrival, lively overshoot and a nearly immediate control. Choose which one fits a small settings switch and explain why. The switch’s semantic on/off state should update from the user’s action, not wait for the decorative thumb to finish moving.

Common mistake

Using visible animation completion as the only source of product state makes a slow or interrupted effect delay the actual interaction.

Integrate with a bounded step

A numerical spring is an approximation whose stability depends on how time is handled.

Step the model

The example uses semi-implicit Euler integration: update velocity from acceleration, then position from the new velocity. This is an educational integrator, not a universal physics solver. Feed it small bounded time steps, use positive mass, and choose parameters within the stable range you have tested. Subdivide long elapsed intervals rather than taking one huge step.

Worked example

A frame arriving after 200ms should not be passed directly to an aggressively stiff spring. Several small steps or a capped catch-up policy avoids a sudden numerical explosion. Capping time deliberately sacrifices perfect elapsed-time simulation to preserve a useful interface response. Document that tradeoff.

Practice

Run the step function with the same total duration using 1/60 and 1/120 second steps. Compare the resulting trajectories within a reasonable tolerance. Then inject one long delay and test your chosen subdivision policy.

Common mistake

A mathematically plausible force equation can still become unstable when integrated poorly. Test the numerical behavior, not only the appearance at your monitor’s normal refresh rate.

function springStep(x, velocity, target, dt, stiffness=170, damping=26, mass=1) {
  const acceleration = (-stiffness * (x - target) - damping * velocity) / mass;
  const nextVelocity = velocity + acceleration * dt;
  return { x: x + nextVelocity * dt, velocity: nextVelocity };
}

Retarget without restarting the object

Interruption is the ordinary case for a control that someone can operate quickly.

Preserve continuity

When a new target arrives, keep the current position and velocity. Replace the target and let the simulation respond. Resetting velocity to zero on every click creates an unnatural stop. For direct dragging, distinguish the pointer-controlled phase from the released spring phase and decide how release velocity enters the model.

Worked example

The panel is moving open when the user closes it. Its existing velocity may carry it slightly farther before the spring reverses direction. That continuity makes the object feel coherent. Snapping back to a predefined start point breaks the relationship between the pointer action and the visible object.

Practice

Toggle the target five times at irregular intervals. Log position immediately before and after each target change; it should remain continuous. Repeat with keyboard activation. Decide whether the movement is appropriate for the product, then tune the response rather than removing interruption support.

Common mistake

Queueing every requested animation makes the interface replay obsolete intentions. A control should move toward the latest target, not perform a history of earlier clicks.

Define rest and respect preference

A finished motion system knows when to stop doing work.

Use two thresholds

Consider the spring at rest when both distance to target and velocity are small. Snap the final tiny remainder to the target and stop requesting frames. Distance alone can be misleading when the object passes the target at high speed. Reduced-motion mode can update the visual position immediately or use a much smaller nonessential transition.

Worked example

The thumb crosses the target while still moving rapidly. Stopping because the position is momentarily close produces an abrupt cutoff. Requiring low velocity as well allows a natural settle. When the user requests reduced motion, the control remains fully functional with the thumb placed directly at the selected end.

Capstone practice

Deliver the control, parameter notes and interruption tests. Verify the loop stops at rest, restarts after a new action, and is removed on teardown. Test rapid keyboard activation and a delayed frame as well as ordinary pointer clicks.

Review criterion

Explain why the chosen response fits this control. A spring is successful when it clarifies the interaction and survives interruption, not when it bounces as much as possible.

Decide what never changes

A generative identity needs constants that make different outputs feel related.

Write the grammar

List the fixed rules before choosing randomness: margin, grid, palette, title zone and one family of shapes. Then name the variables, such as position within a cell, rotation or density. Keep the information hierarchy independent of chance so every output remains usable as a poster.

Worked example

The listening festival uses a warm paper ground, black circular arcs and a narrow lime accent. Every poster reserves the lower quarter for the event name and date. The artwork changes above that zone, but the margins and typography hold the family together.

Practice

Draw one poster without randomness. Write five rules another person could follow to create a related version. Identify which rule protects the title from being obscured. If the identity only exists in one lucky composition, refine the grammar before automating it.

Common mistake

Randomizing every property creates unrelated images rather than a visual system. Start with a small possibility space that you can understand and art-direct.

Make chance reproducible

A seed turns an interesting accident into a design you can revisit.

Use a deterministic sequence

The small generator below produces the same sequence from the same unsigned 32-bit seed. It is suitable for visual variation, not security or scientific simulation. Create it once for a render and consume values in a consistent order. Reinitialize it when regenerating a poster from a saved seed.

Worked example

Seed 42 gives a useful arrangement of arcs. Saving only a screenshot loses the ability to revise it at another size. Saving the seed, parameter values and generator version lets you reconstruct the composition. Changing the order of random calls can still change the result, so version the rule set when it evolves.

Practice

Generate five numbers twice from the same seed and compare them. Then draw a grid using those values for bounded rotations. Reload the page and verify that the same seed reproduces the same output.

Common mistake

Reading fresh Math.random values during export produces a different poster from the preview. Render both from the same saved design state.

function seededRandom(seed) {
  let value = seed >>> 0;
  return () => {
    value = (Math.imul(1664525, value) + 1013904223) >>> 0;
    return value / 4294967296;
  };
}

Bound the variation, then curate it

A useful generator produces a range you can explain, not a stream you hope will occasionally work.

Choose distributions deliberately

Uniform random placement can create clusters by accident. A grid with bounded jitter preserves rhythm while allowing local differences. Limit the allowed angles or palette combinations if those constraints strengthen the identity. A density control should have a meaningful minimum and maximum, not simply expose an arbitrary loop count.

Worked example

Each grid cell contains one arc, shifted by at most a tenth of the cell width. This keeps a recognizable scaffold. Three curated seeds demonstrate quiet, balanced and dense compositions without changing the title zone. The designer can explain why each belongs to the same festival.

Practice

Render a contact sheet of twelve seeds at the lowest and highest density. Identify recurring failures, such as collisions with the title or large accidental voids. Change the rule that causes the failure instead of deleting only the unlucky seed.

Common mistake

Manual curation is useful, but it should not hide a generator whose ordinary outputs violate the design requirements. Test the range as well as the favorite example.

Export the design you actually previewed

The export is part of the product, with its own dimensions and quality checks.

Separate design space and output size

Define the composition in a logical coordinate space, then scale the drawing context for the export dimensions. Render from the same seed and parameters used by the preview. Wait for any fonts or images before drawing. Use canvas.toBlob for a PNG and release temporary object URLs after download.

Worked example

The preview is 600 by 800 CSS pixels, while the export is 1800 by 2400 pixels. Scaling the same logical composition preserves margins and relationships. Increasing only the canvas dimensions without scaling the drawing coordinates leaves the artwork stranded in one corner.

Capstone practice

Deliver the generator and three curated seeds with their settings. Export each, inspect its pixel dimensions and compare the content with the preview. Include a text summary of the generated design for users who cannot inspect the canvas.

Review criterion

Someone else can reproduce a chosen poster, change one parameter and export the expected composition. Record any limits, such as raster output or fonts required by the local project.

Start with consent and a signal path

A sound interface should explain what will happen before it makes noise.

Draw the graph

An oscillator creates a signal, a gain node controls its amplitude, and the destination sends it to the output. Create or resume the AudioContext from a user action and handle a failed resume visibly. Begin at a conservative gain. Offer a persistent stop or mute control rather than relying on closing the page.

Worked example

A button says “Enable sound” before the three note buttons become available. The page explains that the instrument is optional. When the context is ready, the status changes to Sound ready. A text label and visual pulse communicate activation for someone who cannot or does not want to listen.

Practice

Sketch the signal graph and the interface states: disabled, enabling, ready and stopped. Implement the enable button first, then one short note. Test keyboard activation and a browser where audio starts suspended.

Common mistake

Creating sound during page load surprises the listener and may be blocked by the browser. Treat audio availability as an explicit state, not an assumption.