Design, from other people's skill files
Designers are writing their standards down so a model will follow them. Six units that turn those files into a course, with the reasons they leave out.
10 public files from 5 collections · about 1,983 lines of reading · 6 units
The claim A skill file is a working designer's non-negotiables, in the imperative, with the numbers in them, in public — and it teaches you nothing if you read it before you have tried the work yourself.
Something useful happened by accident. To hand a piece of your job to a model you have to write down what you would otherwise just do, and the model fails visibly when a step is missing, so the author keeps adding steps until it stops failing. What comes out the other end is not a blog post and not a course. It is a professional's working standard, in the imperative, with the numbers still in it, published for free because it was written to be executed rather than sold.
That artefact is rare, and the reason it is rare has a literature. Experts are not able to produce it on request: the standard estimate in the cognitive-task-analysis field is that they are unaware of about 70% of their own decisions, because the decisions became automatic on the way to becoming good. When six expert programmers were recorded solving problems and then asked to explain what they had done, no single one of them could report more than 41% of their own diagnostic actions — and pooling all six accounts raised it to 87%. So the file in front of you is not the method. It is one practitioner's partial account of the method, and the way to use that fact is to read three of them and treat the disagreements as the interesting part.
The optimistic half is that instruction built from this kind of elicited procedure measurably outperforms instruction built the usual way — an overall effect of g = 0.871 across domains, from a small enough set of studies that the authors say so themselves, and in surgical training a standardised mean difference of 1.36 on procedural knowledge. A skill file is an informal, self-administered, unreviewed version of the interview those studies are built on. The claim here is not that it is as good. It is that it is the same kind of artefact and it costs nothing.
The trap is that these files read beautifully. A good one is dense, confident and specific, and reading it produces a strong feeling of getting better, which is the feeling that predicts nothing. A rule is a compressed failure, and the compression throws away the failure. Someone who reads always 0.96 has acquired a number; the person who wrote it has watched a hundred buttons at 0.9 look broken. Only one of those two can apply it to a case the rule does not cover.
So every unit below inverts the obvious order. You make the artefact first, unaided, in a fixed time box, and only then open the file and grade yourself against it. The contribution of this page is the column the file does not have — why. And the last move is one no book has ever offered a learner: you can run the skill on your own work, and get the practitioner's review applied to the thing you actually made.
The method, and it is the same every unit
Six moves. The order is the whole thing: reading a rule before you have attempted the work turns it into an answer you cannot unsee, and you lose the only measurement of where you actually were.
- 1
Make the thing first, unaided, in a fixed time box. No reference open, no model, and write down the decisions you made as you make them.
WhyA rule read before an attempt is an answer you cannot unsee, and you lose the only measurement that matters — where you actually were before. The list of decisions is what you will grade; without it you will remember agreeing with everything.
- 2
Read the file once, as a rubric, and mark every rule you broke. Count them.
WhyThis turns reading into grading. The count is a number you can watch move across units, and it is the difference between studying a checklist and being measured by one.
- 3
For each rule you broke, write the reason the file leaves out — one sentence, from your own head, before looking anything up.
WhyExplaining why a rule is true, in your own words, is what turns it into knowledge you can apply to a case the rule does not cover. Where you cannot construct a reason, mark it: sometimes the honest answer is that one practitioner decided, and knowing which rules those are is most of the skill.
- 4
Read a second file on the same topic and diff it against the first.
WhyA single expert's account of their own work is radically incomplete, and pooling accounts is what recovers the rest. Where two unrelated authors agree on a number, you have a convention worth adopting. Where they disagree, you have found the judgement, which is the part you came for.
- 5
A week later, remake the artefact from memory with every file closed.
WhyPulling it back out of your own head is worth more than reading it again, and the delay is doing work rather than wasting time. The gap between the graded version and this one is the only honest measure of what stuck.
- 6
Only now run the skill on your work, and read its findings against the ones you already wrote.
WhyThis is the apprenticeship loop that stopped running when production got cheap: expert feedback on the specific thing you made. It is worth exactly as much as the file behind it, so grade the grader — every finding you disagree with is either a rule you have not understood or a rule that does not apply here, and deciding which is the exercise.
What you will be reading
Every file below is public, readable without an account, and written by a named person for their own use. Licences are what each repository states. Line counts are there because they are the honest way to say how much there is — two of these are an evening, one is a reference you will never read end to end.
interfaces MIT
- better-typography 162 lines
Type scale, weight, line height, measure, wrapping and OpenType detail, with a numeric threshold in most rules. Six further reference files sit beside it. The densest single file in this corpus for values you can apply tonight.
- better-layout 81 lines
Grouping, alignment, reading order and progressive disclosure. Short, and most of it is about spacing as the carrier of structure rather than as decoration.
- better-colors 105 lines
Palette structure, token naming and contrast. Notable for drawing the line between the parts of colour that have an exact answer and the parts that do not, which is the distinction most colour advice blurs.
- better-accessibility 111 lines
Focus, keyboard, hit areas, semantics and forms, each tied to the WCAG criterion it comes from. Reads as a checklist because it is one.
- better-ui 112 lines
Motion, surfaces, icons, optical alignment and press feedback, every value given exactly rather than as a range. The best file here for learning what a specified decision is.
Vercel MIT
- web-interface-guidelines 190 lines
A flat review checklist covering accessibility, forms, interaction, layout and performance. Terse to the point of being telegraphic, which makes it the fastest one to audit against and the weakest one to learn from alone.
impeccable Apache-2.0
- craft-floor 44 lines
Forty-four lines splitting a minimum standard from a banned list. Short enough to read in one sitting and the single best page here for calibrating against generated defaults.
- critique 806 lines
A full scoring rubric built on Nielsen's ten heuristics, with an explicit honesty protocol about what the reviewer did not look at. Long; read the scoring guide and the reporting rules and skip the rest until you need it.
Anthropic Apache-2.0
- frontend-design 71 lines
Mostly a calibration list of the tells that mark a page as generated, written by the people with the clearest view of what a model produces by default. Almost no positive instruction, which is the point.
Microsoft MIT
- vscode-accessibility 301 lines
Not a general guide: the accessibility requirements a real engineering organisation imposes on its own contributors, living in the product's own repository. Read it for the shape of an internal standard, not for portable rules.
The units
In order. Each one starts with something you make before you read anything, because that artefact is what the file is going to grade.
-
1 Type and space, where the numbers are
Find out how many of your values you invented on the spot, and learn that most of what reads as polish is two scales applied without exceptions.
Do this first, with everything closed In 45 minutes with nothing open, set one screen with real content: a heading, two paragraphs, a list of six settings rows and one button. Then write out every font size, weight and gap you used, as a flat list, before you read a word of the files.
Then read better-typography, better-layout
-
Below
18px, stay at weight400or heavier. Weights under300are display-only at28px+; they disappear at text sizes.The reason the file does not give you Stroke width and contrast trade against each other, and the accessibility standard says so out loud: WCAG allows large text a 3:1 ratio instead of 4.5:1 on the grounds that text which is larger and has wider strokes is easier to read at lower contrast. A light weight at a small size is the opposite corner of that same trade — thin strokes and small size together — so it is the one combination where legibility falls off from both directions at once. It does not look delicate at 14px. It looks faded.
-
The gap between groups must be at least 2× the gap within one (
8pxintra-group to16px+ inter-group), or the grouping reads as noise.The reason the file does not give you Proximity is a grouping cue the eye applies before you have decided to read anything, and it works on relative distance rather than on absolute size. That is why the rule is a ratio and not a value — it survives being scaled, and a spacing scale that does not hold the ratio has stopped grouping anything. A 12-to-16 pair is not weaker grouping than 8-to-16; it is ambiguous grouping, which costs the reader a conscious decision on every row. Doubling is the point at which the comparison stops needing to be made.
You are done when Your list of values collapses onto one type scale and one spacing scale with nothing left over, and you can name which scale every number on the screen came from. Keep the count of values you had before — it is your baseline, not a verdict.
-
-
2 Colour, and the part of it with an exact answer
Separate the colour decisions that are measurable from the ones that are taste, and stop guessing at the measurable half.
Do this first, with everything closed Give the screen from unit one a palette: a background, two text colours, one accent, one border. Before measuring anything, write down what you think the contrast ratio of your body text is, to one decimal place.
Then read better-colors, craft-floor
-
Never report a contrast value you did not measure, and never estimate a color you could compute.
The reason the file does not give you Contrast ratio is a defined function of two relative luminances. There is a right answer, it takes two seconds to get, and your eye is not the instrument that produces it: what you perceive is pulled around by hue and by whatever surrounds the text, in a direction you cannot predict from looking. This is the rare interface question with no judgement in it at all, which makes guessing at it purely a loss.
-
Contrast: body and placeholder text ≥4.5:1, large text ≥3:1.
The reason the file does not give you These are not this author's preference, they are the WCAG AA thresholds, and the standard explains where they come from: 4.5:1 is set to compensate for the contrast loss of roughly 20/40 vision, which is typical around age 80. Large text is allowed 3:1 because wider strokes stay legible at lower contrast — the same trade as the weight rule in the previous unit, seen from the other side. Referenced in accessibility law in much of the world, and a floor rather than a target.
You are done when You predicted a contrast ratio and then measured it, five times. Write both columns down. The size and the direction of your error is now a thing you know about yourself, which is more useful than any single ratio.
-
-
3 The floor, as two organisations actually wrote it down
Discover that the accessibility baseline is more concrete and lower than it sounds, and that your screen is under it.
Do this first, with everything closed Push the mouse away. Reach your screen's every control with Tab, activate each one with Enter or Space, and write down every place you got stuck or could not see where focus was. Do this before opening any file.
Then read web-interface-guidelines, better-accessibility, vscode-accessibility
-
<button>for actions,<a>/<Link>for navigation (not<div onClick>)The reason the file does not give you The native element is not a style choice, it is a bundle: focusability, keyboard activation on the right keys, the correct role for assistive technology, the platform's own focus ring, and the disabled and active states. Rebuilding that on a div takes five attributes that you will get right the first time and forget on the fourth component.
-
WCAG 2.5.8's Level AA baseline is a 24×24 CSS-pixel target, or one of its spacing, equivalent-control, inline, user-agent and essential exceptions. Aim for 44×44px on touch and 40×40px on desktop where density permits.
The reason the file does not give you Two numbers answering two different questions. 24 is what a conformance audit will accept; 44 is the size Apple's platform guidance has specified for a finger target for over a decade, which is a claim about hands rather than about compliance. The gap between them is the entire difference between passing and being usable, and noticing that one rule quietly contains both is the thing this unit is really teaching.
-
When adding a new interactive UI surface to VS Code — a panel, view, widget, editor overlay, dialog, or any rich focusable component the user interacts with — you must provide three accessibility components
The reason the file does not give you Read this one for its existence rather than its content, which is specific to one editor. A product with tens of millions of users keeps its internal contributor requirements in its own repository, addressed to a machine, in public. That is an apprenticeship document, and until recently you would have had to be hired to read it.
You are done when Your keyboard-only list from before, next to the findings after reading. Every item you missed is a rule you can now give the reason for, and every item you found unaided is evidence the previous units worked.
-
-
4 Specified values, and the difference between a number and a vibe
Learn what it means for a decision to be specified rather than approximated, and why that matters more than which value was chosen.
Do this first, with everything closed Add press feedback to your button and one entrance animation to your list. Write down the duration, the curve and the scale you picked, and one line each on why you picked them.
Then read better-ui
-
Every duration, curve, scale and blur below is a specific value, not a range to approximate.
cubic-bezier(0.2, 0, 0, 1)is notcubic-bezier(0.4, 0, 0.2, 1), and0.96is not0.95. Use what is written.The reason the file does not give you The most instructive sentence in this corpus, and its reason is not that 0.96 is objectively correct. A design system is a set of decisions you have agreed to stop re-making, and the value of that agreement is consistency across a hundred surfaces built by people who never met. An approximated value is a new decision, so approximating is how a system quietly becomes a suggestion.
-
A
scale(0.96)on click gives a button tactile feedback. Always0.96; anything below0.95feels exaggerated.The reason the file does not give you Here the honest answer is that this is one practitioner's calibration, not a measured threshold, and no study is going to tell you where exaggerated starts. That does not make it worthless — it is a default from somebody who has looked at far more buttons than you have. Adopt it, ship it, and find out whether anyone notices. Deriving it from first principles is the one response that is definitely a waste of your evening.
You are done when You can point at every duration on your screen and say what it is feedback for. Any you cannot name a purpose for is decoration, and deleting it is the exercise.
-
-
5 Calibration: what the median page looks like
Learn the defaults you reach for without noticing, from the people with the clearest view of what a generator produces.
Do this first, with everything closed Write down five things you believe make a page look machine-generated. Five, specifically, before you read anything. Then look at the last landing page you built and count how many of your own five it has.
Then read frontend-design, craft-floor
-
template chrome that appears whatever the subject: a tracked-out ALL-CAPS eyebrow label above every heading; meta strings joined with middle dots ('A · B · C'); labels built as 'WORD — fragment' with a spaced em dash; tinted near-black (#0B0B0B, #111) standing in for black; a monospace face for small data labels; a '→' appended to link and button text.
The reason the file does not give you None of these are ugly, which is exactly why they are a problem. They are frequent. A generator reproduces the middle of what it was trained on, so the median of the web becomes the default of every new page, and a reader who sees the same six devices everywhere stops reading them as choices. The list is not a ban on the devices; it is a warning that using one now costs you something it did not cost in 2022.
-
A kicker or eyebrow above a heading. This one is a ban, not a default: no brief earns it back. The heading carries its own weight; delete the label and let the heading speak.
The reason the file does not give you The content of the rule matters less than the coincidence. Two authors with no shared lineage, writing for different tools, independently single out the same small element and one of them escalates it to a ban. Agreement like that across unrelated files is the closest thing this corpus has to evidence, and learning to notice it is how you use a corpus rather than a file.
You are done when Your five against their list. The tells you did not have are the ones you are still producing without seeing them, and you should be able to find one in your own last three projects.
-
-
6 Being graded, and grading the grader
Close the loop — score your own work, have the rubric score it, and account for every disagreement.
Do this first, with everything closed Score your screen yourself against Nielsen's ten usability heuristics, 0 to 4 on each, and write the total down before you run anything or read the scoring guide.
Then read critique
-
Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32 out of 40.
The reason the file does not give you The second sentence is the valuable one and it is doing something no heuristic list does: it gives you a distribution. A self-assessment with no anchor is unreadable, because you have no idea whether 30 is good. Being handed the range a practitioner expects turns your own number into information, and if you scored yourself 36 the useful conclusion is about your scoring, not your screen.
-
A silent degraded critique is a failed critique.
The reason the file does not give you Written about a tool that could not complete its own review, and it generalises past design entirely. A review that does not say what it failed to look at cannot be acted on, because you cannot tell a clean bill of health from an empty one. Demand it of the tools you run, and of yourself when you hand someone a critique.
You are done when Your total and the rubric's differ by four points or fewer, and you can explain every heuristic where you disagreed. A disagreement you cannot explain means one of the two scores was a feeling.
-
Where this approach fails you
Nobody peer-reviewed any of the files above. A section that recommends unvetted material owes you a louder account of the failure modes than of the promise.
- Nobody reviewed these. A skill file is one named person's account of their own practice, published because it was useful to them, and some of what is published under the name is marketing with a checklist stapled on. Before you take a corpus seriously: find out who wrote it, whether the commit history shows it being used and corrected over time, and whether its rules carry numbers or adjectives. A file made entirely of adjectives has nothing to teach you that you cannot already say.
- They are written for a reader that never gets bored, never forgets and does not need to understand anything. That shapes the ordering: a skill file is arranged for lookup at the moment of use, not as a path from not knowing to knowing. It is a reference. The sequence has to be imposed from outside, which is the only thing the units above really are.
- A rule is a compressed failure and the compression discards the failure. You can satisfy every rule in this corpus and produce something correct, consistent, accessible and completely dead, because not one of these files can tell you what the screen is for or whether anybody needed it. That question belongs to the page on learning design itself, and no amount of craft substitutes for it.
- Reading them is pleasant and feels like progress, and that feeling is the one the research says does not predict retention. Fluency while reading is a property of the text, not of your memory. If you finish a unit having read carefully and made nothing, you did not do the unit — and you will believe you did, which is the expensive part.
- They are snapshots, and they age unevenly. The parts tied to a framework, a platform version or a specific tool go stale fastest; the parts about how people read and where their fingers land barely age at all. Check when the file was last touched before you trust anything version-specific in it, and prefer the human half when the two disagree.
Doing this in a field we have not written up
The method above is not about design. It is about what to do with somebody else's written-down practice, and most fields now have some.
- Look inside product repositories, not app stores. The strongest file in this corpus is the one Microsoft keeps in the VS Code repository, because it governs work that actually ships and gets corrected when it is wrong. A standard that is applied beats a standard that is published, and you can usually tell which you are holding by whether anything in it sounds inconvenient.
- Read the history, not just the file. A skill file under version control shows a professional changing their mind, with dates and reasons in the commit messages, and the diff where a rule acquired an exception is worth more than the rule. No course contains that, because no course admits to having been wrong in public.
- Never let one file be the field. The research here is explicit that a single expert's account of their own work recovers less than half of it, and that pooling accounts recovers most of the rest. Three files on one topic, read in a row, will show you the same advice with different reasons attached, and the disagreements are where the judgement lives.
- Judge a candidate file by whether it is falsifiable. Numbers, thresholds, named exceptions and outright prohibitions are the parts written by somebody who has been burned. Anything that would read identically in any other field is filler that survived because the model does not complain.
- If your field has no such files yet, write one. Writing down what you would otherwise just do is the exercise — the agent is only the reason you will finally do it, and the first draft failing is how you find the steps you did not know you were taking.
The evidence
These support the method, not the files. Nothing here measured a skill file, because nobody has: what has been measured is what happens when you build instruction out of an expert's elicited procedure, and how incomplete one expert's account of themselves is.
- Clark, Feldon, van Merriënboer, Yates and Early (2007) Peer-reviewed
The standard reference chapter on cognitive task analysis, in the Handbook of Research on Educational Communications and Technology. States that experts are not aware of about 70% of their own decisions and mental analysis of tasks, and so cannot fully explain them even when they are deliberately trying to help someone design training.
-
Six expert programmers were recorded doing troubleshooting tasks and then asked to explain their procedures by several elicitation methods. No single expert reported more than 41% of their diagnostic actions, 53% of their debugging actions or 29% of their interpretations. Aggregating all six accounts raised those figures to 87%, 88% and 62%.
-
Meta-analysis of instruction built from cognitive task analysis against instruction built by other means: the overall effect is large, Hedges's g = 0.871, though effect sizes vary substantially by CTA method and training context and the authors note the number of studies is relatively small.
-
Meta-analysis of randomised trials of CTA-based surgical training: a standardised mean difference of 1.36 (95% c.i. 0.67 to 2.05) on procedural knowledge across four studies, and 2.06 (95% c.i. 1.17 to 2.96) on technical performance across four trainee studies, both favouring training derived from an expert-elicitation procedure.
The learning science underneath
The order of the method is a claim about how people learn, and it is not original to this page. Each of these sets out the evidence for one part of it.
Learning the skill itself
None of the files above can tell you what the thing you are making is for. That question has its own pages.