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)
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.
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.
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
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.
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.
The shape of a reference entry
- When to use it.
- The code.
- Why it works.
- The rules and failure modes.
- Browser support, with version numbers.
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%;
}
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);
}
The failure each foundation line prevents
| Declaration | Applied to | Failure it prevents |
|---|---|---|
min-width: 0 | every element | Children cannot shrink; page overflows sideways |
scrollbar-gutter: stable | root | Page shifts sideways |
min-height: 100svh | body | Content hidden behind phone toolbars |
max-width: 100% | images, SVG, video | Media wider than its container |
font-size: max(16px, 1rem) | form fields | iOS zooms in on focus |
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.
Logical properties and OKLCH colour
- Write the logical properties
padding-inlineandmargin-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.
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
remterm. - The maximum of a type size is at most 2.5 times its minimum.
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);
}
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: clipreplaceshidden, which breaks sticky positioning.- The parent sets spacing through
gap. - Do not use spacer elements.
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; }
Interaction
- Never remove the focus outline.
- Use
:focus-visiblewith 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.
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-inortransition: all.
Motion durations
| What moves | Duration |
|---|---|
| A press | 100 to 160 ms |
| Small popovers | 125 to 200 ms |
| Menus | 150 to 250 ms |
| Dialogs and drawers | 200 to 500 ms |
Worked example: a menu transition
.menu { opacity: 0; }
.menu[open] { opacity: 1; }
@media (prefers-reduced-motion:
no-preference) {
.menu {
transition: opacity 200ms
ease-out;
}
}
Four remedies for generic design output
- Reference components as source: the agent copies them into the repository and adapts them to your tokens.
- Reference screens: real shipped screens to compare against, critique, then delete.
- Design skills: one skill per narrow job.
- Named failure modes: faults with names the agent can check for.
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.
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.
Published files that agents can read
- Publish an
llms.txtindex. - Publish documentation as Markdown as well.
robots.txtand the sitemap are public.- Listing a path as disallowed tells every reader where that path is.
- Add
og:videoalongsideog:imagewhere a link preview should play. - Functions offered to an in-browser agent as tools are a public API.
Worked example: the page a text-only reader gets
- Take a toy product page with a name, a price, three specifications and a review score.
- Load it with scripts disabled and list the facts present.
- Fetch it as text only and list the facts present.
- The price and the review score are absent, because a script filled them in.
- Move those facts into the HTML the server delivers.
- Repeat both loads and record the result.
Ask the room: the disallowed path
- A site's
robots.txtlists 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.
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: allwithease-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 ornoindex.
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.
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.
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 andoverflow: 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.txtprotects nothing.
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.