Syllabus Module 10 · Laboratory: interfaces for people and for agents
NSW 3011 / 31
Software Engineering with Language Models

Module 10 · Laboratory: interfaces for people and for agents

Class time
60 minutes
Slides
31, each with teacher’s notes
Goes with
Laboratory 5; Assignment 6 (Part IV)
Module 102 / 31

Where this module sits

  • In Module 9 you built a game and proved it with replays and frame times.
  • In Module 7 you learned the reference audit prompt, which you reuse in Laboratory 5.
  • Today's subject is interface code that uses the current web platform and reads as designed.
  • The page has a second audience: software agents that read it.
  • In Module 11 you recover behaviour from someone else's artifact.
Module 103 / 31

Objectives

  • Explain why an agent's default front end is dated, and supply the context that corrects it.
  • Apply the foundation rules and name the failure each one prevents.
  • Write colour, theme, size and layout rules in their current form.
  • Apply the interaction and motion rules, including the decision not to animate.
  • Use four remedies for generic design output.
  • Make a page's facts readable with scripts off and by a text-only fetch.
Module 104 / 31

Agenda

  • 4 min: where this sits, objectives
  • 6 min: why agents write dated front ends (10.1)
  • 20 min: foundations and further rules (10.2)
  • 9 min: interaction and motion (10.3)
  • 13 min: giving an agent taste (10.4), pages agents can read (10.5)
  • 8 min: mistakes, hand-ins, recap
Module 105 / 31

Why agents write dated front ends

  • Older code dominates the training data.
  • A model's default is the pattern that was common five years ago.
  • The signs are scripts where the platform has a native feature, pixel values and physical directions.
  • A further sign is animation on everything.
  • A model that knows a modern API has still seen few dense examples of it.
  • The remedy is context: a reference the agent retrieves before it writes.
Module 106 / 31

References built for a model

  • One public pack holds 47 CSS practices and installs as a skill.
  • A second public pack gives guidance for the whole platform.
  • The second pack keeps a tiny description always loaded.
  • The second pack offers local search over some 200 guides.
  • Both packs write every entry in the same shape.
Module 107 / 31

The shape of a reference entry

  1. When to use it.
  2. The code.
  3. Why it works.
  4. The rules and failure modes.
  5. Browser support, with version numbers.
Module 108 / 31

Foundations for every element and the root

*, *::before, *::after {
  box-sizing: border-box; min-width: 0;
}
:root {
  color-scheme: light dark;
  scrollbar-gutter: stable;
  text-wrap: pretty;
  overflow-wrap: break-word;
  -webkit-text-size-adjust: 100%;
}
Module 109 / 31

Foundations for the body and for media and form fields

body { margin: 0; min-height: 100svh; }
img, svg, video {
  display: block;
  max-width: 100%;
  height: auto;
}
input, select, textarea {
  font-size: max(16px, 1rem);
}
Module 1010 / 31

The failure each foundation line prevents

DeclarationApplied toFailure it prevents
min-width: 0every elementChildren cannot shrink; page overflows sideways
scrollbar-gutter: stablerootPage shifts sideways
min-height: 100svhbodyContent hidden behind phone toolbars
max-width: 100%images, SVG, videoMedia wider than its container
font-size: max(16px, 1rem)form fieldsiOS zooms in on focus
Module 1011 / 31

Ask the room: the missing foundation line

  • Symptom A: the page scrolls sideways at 320 pixels wide.
  • Symptom B: the layout moves sideways when a scrollbar appears.
  • Symptom C: a phone zooms in when the search field is tapped.
  • Symptom D: the last line of a full-height screen sits under the phone's toolbar.
  • Name the foundation line missing in each case.
Module 1012 / 31

Logical properties and OKLCH colour

  • Write the logical properties padding-inline and margin-block-end.
  • With logical properties, right-to-left layouts mirror without extra code.
  • Define one base colour in OKLCH.
  • Derive hover states and tints with color-mix(in oklch, ...).
  • OKLCH lightness is perceptual, which makes scales and contrast predictable.
  • Write greys with hue none, because a hue of zero is red.
Module 1013 / 31

Theme tokens and fluid sizes

  • One token per colour serves both themes through light-dark(a, b).
  • Switch a theme by changing color-scheme.
  • Never switch a theme by redefining tokens.
  • Fluid sizes use clamp(min, rem + vw, max).
  • The preferred value always includes a rem term.
  • The maximum of a type size is at most 2.5 times its minimum.
Module 1014 / 31

Worked example: tokens for one small page

:root {
  --brand: oklch(55% 0.18 250);
  --grey: oklch(60% 0 none);
  --hover: color-mix(in oklch,
    var(--brand), black 15%);
  --surface: light-dark(white,
    oklch(20% 0 none));
  --title: clamp(1.5rem,
    1rem + 2vw, 3rem);
}
Module 1015 / 31

Grid and container layout with clipping and spacing

  • Write an intrinsic grid as repeat(auto-fit, minmax(min(100%, 16rem), 1fr)).
  • The intrinsic grid needs no media query.
  • A container query sizes a component by its slot.
  • overflow: clip replaces hidden, which breaks sticky positioning.
  • The parent sets spacing through gap.
  • Do not use spacer elements.
Module 1016 / 31

In-class exercise: a dated rule to modernise

.card {
  width: 320px;
  margin-left: 16px;
  overflow: hidden;
  color: #777;
  transition: all 0.3s ease-in;
}
.card:hover { background: #eee; }
.card:focus { outline: none; }
Module 1017 / 31

Interaction

  • Never remove the focus outline.
  • Use :focus-visible with a visible ring.
  • Apply hover styles only inside @media (hover: hover) and (pointer: fine).
  • Give touch feedback with :active.
  • A pseudo-element extends small targets to a 44-pixel hit area.
  • Prefer native behaviour to script.
Module 1018 / 31

Motion rules

  • First decide whether the animation is warranted at all.
  • An animation exists to give feedback and make a state change understood.
  • Do not animate keyboard-triggered actions or repeated tooltips.
  • Write the state change first.
  • Add transitions only inside @media (prefers-reduced-motion: no-preference).
  • Entering and leaving elements ease out. Never use ease-in or transition: all.
Module 1019 / 31

Motion durations

What movesDuration
A press100 to 160 ms
Small popovers125 to 200 ms
Menus150 to 250 ms
Dialogs and drawers200 to 500 ms
Module 1020 / 31

Worked example: a menu transition

.menu { opacity: 0; }
.menu[open] { opacity: 1; }
@media (prefers-reduced-motion:
    no-preference) {
  .menu {
    transition: opacity 200ms
      ease-out;
  }
}
Module 1021 / 31

Four remedies for generic design output

  1. Reference components as source: the agent copies them into the repository and adapts them to your tokens.
  2. Reference screens: real shipped screens to compare against, critique, then delete.
  3. Design skills: one skill per narrow job.
  4. Named failure modes: faults with names the agent can check for.
Module 1022 / 31

Named failure modes and the hand-over gate

  • One marketing-interface skill names five faults: too much, wireframe, boxed, flat, bland.
  • The skill sets a word budget of three to seven real strings per screen.
  • The skill requires design at the displayed size.
  • A script films the running result at two widths.
  • The skill hands nothing over until a gate has passed.
Module 1023 / 31

Page content that agents can read

  • Name every icon button, label every form field and describe every image.
  • Never put essential information only in an image.
  • Put the price, the specification and the proof in the HTML the server delivers.
  • Use semantic elements (nav, header, button) for functional parts.
  • State in plain sentences what is offered, who it is for and what it does.
  • Put a date on facts that change.
Module 1024 / 31

Published files that agents can read

  • Publish an llms.txt index.
  • Publish documentation as Markdown as well.
  • robots.txt and the sitemap are public.
  • Listing a path as disallowed tells every reader where that path is.
  • Add og:video alongside og:image where a link preview should play.
  • Functions offered to an in-browser agent as tools are a public API.
Module 1025 / 31

Worked example: the page a text-only reader gets

  1. Take a toy product page with a name, a price, three specifications and a review score.
  2. Load it with scripts disabled and list the facts present.
  3. Fetch it as text only and list the facts present.
  4. The price and the review score are absent, because a script filled them in.
  5. Move those facts into the HTML the server delivers.
  6. Repeat both loads and record the result.
Module 1026 / 31

Ask the room: the disallowed path

  • A site's robots.txt lists a staff rota page as disallowed.
  • State what a stranger learns from reading that file.
  • State what stops the stranger from opening the page.
  • Name two measures that keep the page from being found.
Module 1027 / 31

Common mistakes

  • Accepting the agent's default CSS. Fix: give the agent a reference to retrieve first.
  • Using pixel sizes and physical directions. Fix: use clamp() sizes and logical properties.
  • Writing transition: all with ease-in. Fix: name one property, ease out, and stay inside the reduced-motion query.
  • Removing the focus outline. Fix: put a visible ring on :focus-visible.
  • Filling in facts by script. Fix: deliver the facts in the server's HTML.
  • Hiding a page with robots.txt. Fix: use authentication or noindex.
Module 1028 / 31

Laboratory 5: what is due

  • Start from an existing page of your own.
  • (a) A reference audit against a modern CSS reference, and the five most valuable changes applied.
  • (b) The page passing at 320, 768 and 1440 pixels, with the keyboard only and with reduced motion.
  • (c) A record of facts missing with scripts disabled and through a text-only fetch.
  • (d) Screenshots before and after at each width, plus the list of unchecked items.
Module 1029 / 31

Assignment 6 · A search engine served securely: what is due

  • A search engine for a few hundred text files that are yours to use.
  • The warm-up is in_both(first, second), with its examples written first.
  • You score two engines, one on exact words and one on embeddings, on 20 queries with expected answers.
  • A small web server offering a single page and a single search endpoint.
  • Step 4 belongs to this module: the results are readable with scripts off and by a text-only fetch.
  • Each result has a stable address.
Module 1030 / 31

Recap

  • An agent's default front end is about five years old. A retrieved reference corrects it.
  • The foundation block prevents most layout defects; 10.2 names four of the failures.
  • The current forms are logical properties, OKLCH, light-dark(), clamp(), intrinsic grids, container queries and overflow: clip.
  • For motion, decide whether to animate, write the state change first, ease out and stay within the duration ranges.
  • Generic design output has four remedies, and each one is context.
  • Facts go in server HTML, and robots.txt protects nothing.
Module 1031 / 31

Before next class

  • Run the reference audit of Laboratory 5 on your page and keep the ranked list.
  • Take the before screenshots at 320, 768 and 1440 pixels.
  • Read Module 11, on reverse engineering.
  • Choose a Laboratory 6 target from the three kinds the laboratory allows.
  • Write one question about that target's behaviour.