The Kennedy method
Erik Kennedy's rules govern the screen, not the document: one job per screen, hierarchy by de-emphasis, grayscale before colour, double the whitespace, controls placed where they act. Seven rules, each shown here.
One job - the squint test
Per hundred visits, one thing happens about ninety-five times. Find it, make it the loudest thing on the screen, and quiet everything else. Kennedy's own case study cut a form from ten visible fields to five.
Ten fields, three buttons, two banners, all the same size - the eye doesn't know where to land first.
One field, one button, full size. Everything else runs smaller and quieter, or is gone.
Grayscale first
Design in black, white and grey until spacing and weight alone carry the hierarchy. Add colour last, and only where it means something. Try it on a callout already on this page:
Double the whitespace
Default markup has almost no air. Group gaps should visibly beat element gaps - not by a little, by double.
Pop and un-pop
Every text style leans up (bigger, bolder, darker) or down (smaller, lighter, greyer). Only the page's own title gets to be all the way up.
Locality, and anything but dropdowns
A control sits where it acts. The farther it sits from its effect, the more it has to shout to be found - the real fix is moving it back, not making it louder.
Dropdowns hide options and cost a tap. Replace them by option count:
| Options | Use instead |
|---|---|
| 2 | Segmented buttons, a checkbox, or a switch |
| 2 to 5 | Vertical segmented buttons, radios, or visual cards |
| Many | Typeahead search |
| Dates | Calendar for near dates, a text field for wide-spread ones |
Colour as scarce accent
One base colour, varied by brightness and saturation - never a wheel of decorative hues. The same four tags, coloured two ways:
Every tag a different hue - so none of them means anything.
New Open Late HoldGrey by default; the accent marks only the one that matters.
New Open Late HoldAlignment
Left-aligned text has a weak, ragged right edge - never hang a new element off it; align to the shared left edge instead. And the light marks - bullets, icons, punctuation - hang outside the text's left edge, as print has done since Gutenberg.
but the right edge stays uneven, on purpose.
- The bullet sits out in the margin, outside the text column.
- So the sentences themselves keep one clean, shared left edge.
- The eye follows the text, not the marks beside it.
Documentation patterns
Kennedy's rules govern the screen. A teaching document is a different shape, read top to bottom, sometimes long. Four patterns keep a long page calm.
Reading
Body text you are reading now runs at 18 pixels, line height 1.6, capped at 68 characters so the eye finds the return path on every line - this paragraph is set in .prose. Reference material is scanned, not read, so it runs smaller and tighter in .dense:
Three fonts, three jobs, set once at the top of the file: a serif for reading, a plain sans for labels and controls, a monospace for anything literal - an ID, a field name, a line of code.
:root {
--font-body: Georgia, serif; /* prose */
--font-ui: system-ui, sans-serif; /* labels, nav, controls */
--font-mono: 'SF Mono', monospace; /* code, IDs, literal values */
}serif - reading
sans - labels
mono - code
Orientation
A long page loses the reader unless it keeps answering "where am I, how much is left." Three quiet devices do this without asking for attention: the thin bar at the top of this page that stays while you scroll, the list of headings on the right that tracks your position, and the small # that appears when you rest the pointer on any heading here - try it on this one.
The rail collapses into a plain toggle on a narrow screen - the same markup, one media query, no script beyond what the browser's own <details> element already does.
The block vocabulary
Eight shapes cover almost everything a teaching page needs to say. None come from a framework - each is a dozen lines of hand-written CSS, borrowed as an idea from Semantic UI and refused as a dependency.
.segment.raisedA bordered box groups related content into a visible topic before a word is read.
The one place colour is allowed to mean something. Three tints, never more.
filter:grayscale(1).
Its job is to flag the one sentence that matters - done by quieting the rest and lifting that line out, not by making it louder:
The form has several fields and takes about ten minutes. Applicants complete it online. The deadline is 31 March, after which the service closes for the year. Supporting documents are optional. A confirmation email is sent on submission.
The form has several fields and takes about ten minutes. Applicants complete it online. Supporting documents are optional. A confirmation email is sent on submission.
A row of numbered stages turns "first, then, finally" into something scannable in two seconds:
A large number with a small caption lands the one figure a page wants remembered:
A word, then what it means, structurally paired with the real <dl> tag rather than a callout pretending to be one:
- Measure
- The length of a line of text, capped near 68 characters so the eye keeps its place.
- Regime
- A reading mode - prose for teaching paragraphs, dense for tables and specs.
A divider splits a page without a full heading - like the one just above. A label is a tiny status tag: Draft Confirmed - one grey, one accent, no dozen variants.
figure.codeA filename or language tag above the block, horizontal scroll, never wrap - wrapping destroys the code's own structure:
.callout { border-left: 4px solid var(--accent); background: #f7f7f7; }Sticky header, zebra rows, scroll in their own box on a narrow screen:
| Block | Its one job |
|---|---|
| Segment | Group a topic into a visible box |
| Callout | Flag the one sentence that matters |
| Statistic | Land the one figure worth remembering |
Wrong-way beside right-way, in matched columns with equal weight - see every "before/after" pair on this page, including the one right below.
One long paragraph, full viewport width, every fact the same size and weight, no space between ideas, a table that squeezes instead of scrolling.
A capped reading column, a segment around each topic, one callout for the sentence that matters, a table that scrolls sideways in its own box.
How to build one
The same four moves, in order, on every teaching page:
What makes a page tiring
Eight ways a document loses its reader, gathered from the same four sources:
| Anti-pattern | Why it tires the reader |
|---|---|
| Full-width body text | No measure cap - the eye loses its place on every wrap. |
| Colour-only signalling | A status or a code block told apart purely by hue, invisible without colour vision. |
| Font tourism | Three or more display fonts on one page compete instead of guiding. |
| Loud saturated callouts | Filled high-chroma boxes for routine notes - everything screams, nothing lands. |
| No local orientation | No rail, no sticky header, no anchors - a scroll of unknown length. |
| Prose and reference at one size | A paragraph and a data table fighting for one register. |
| Word-wrapped code | Long lines wrap and break the code's own structure. |
| Wiki chrome | Nav, tags and "last edited by" competing with the content for the first five seconds. |
The naming habit
Semantic UI's real contribution was never its CSS - it was the habit of a class name reading like English: raised segment, info callout, step active. Anyone opening the file later reads intent straight off the tag, no framework required.
Sources and verdicts
This kit did not invent its vocabulary. It reviewed four sources and kept what survived contact with the house rules.
| Source | Verdict | What we took |
|---|---|---|
| r/UXDesign - top documentation UI/UX | Kept - the spine | The exemplar list and the reading/orientation patterns on this page. |
| Semantic UI | Kept the idea | Segment, callout, steps, statistic, definitions, divider, label - hand-written, not the framework. The dead 2013-era jQuery build itself is skipped. |
| uibakery - HTML UI libraries | Kept three ideas | Reading measure, the prose class, the alert box. |
| screensdesign.com | Skipped | App-paywall gallery, no transfer to documents. |
Named exemplars
The doc sites that read well, and what each one is worth stealing:
- LaTeX.css
- One link tag turns plain HTML into a book-like page. Proof that typography and spacing alone, zero components, can look finished.
- MDN Web Docs
- Persistent "In this article" rail, breadcrumb above the title, soft-tinted status callouts. The page never makes you guess where you are.
- Astro Starlight
- Grouped collapsible sidebar, "on this page" control, coloured-left-border admonitions - the clean reference for the orientation kit on this page.
- GitHub Markdown CSS
- The semi-nice baseline everyone measures a documentation page against.
- Stripe docs, Vercel, Tailwind, Prisma, Supabase, Radix, Anthropic docs
- The current frontier of developer-tool documentation, competing hard on layout discipline over typeface fashion.
- Confluence
- Named only as the anti-example - wiki chrome, not a designed page. What not to imitate.
Full digests: documentation-design.md and kennedy/, both in this same folder.