Maintaining Valet
A guide for whoever looks after Valet by hand. It explains how the code fits together, how to change or add a rule, and how to check that nothing else changed by accident. You need a text editor, a browser and Node.js (any recent version). There is nothing to install and no build step.
Read this once from start to finish. After that, the checklists in sections 4 and 6 are what you will use.
1. The ten-minute tour
Valet is one page, index.html, plus plain JavaScript files that it loads in order. There are no modules, frameworks or packages, so the page also opens straight from the folder (file://). Each file is wrapped in (function () { ... })() and puts its public parts on one object on window.
| I want to change… | File | Object |
|---|---|---|
| A number that decides a verdict (a threshold) | js/rules.js, PARAMS |
VRULES |
| A rule’s name, weight, kind, section or passage | js/rules.js, RULES |
VRULES |
| What a rule checks, its score, its text, its fixes | js/engine.js, checkOutfit |
VENGINE |
| How your colouring is read, the tiers, the palette | js/engine.js, top half |
VENGINE |
| Suggestions, Choose the best colours, Keep this | js/suggest.js |
VENGINE |
| Garments, cloths, occasions, what each piece is | js/garments.js |
VGARM |
| The named colours, the demo profile | js/data.js |
VDATA |
| What a pattern looks like from a distance | js/patterns.js, js/vision.js |
VPAT |
| Colour maths (CIELAB, CIEDE2000, OKLCH) | js/colour.js |
VC |
| Body survey, proportion targets, sizes | js/body.js, js/proportion.js, js/fit.js |
VBODY, VPROP, VFIT |
| The explanation and its sources | index.html, <article id="howArticle"> |
|
| What a tab shows | js/ui/you.js, palette.js, shape.js (Proportion), fit.js, dresser.js |
VAPP |
| The “Why” and “Sources” bubbles | js/ui/why.js |
|
| Reading colour from a photo; Colours from photos and My colours | js/ui/photos.js (the window, kept photos); the strip in dresser.js |
VPHOTOS |
| Start-up, the welcome window, How it works’ contents list | js/ui/main.js |
|
| The phone layout | js/ui/mobile.js, and @media blocks in css/valet.css |
The rule is simple: files in js/ never touch the page, so the tests can run them in Node. Files in js/ui/ draw the page and call the logic.
2. How a check becomes a verdict
- Your colouring is measured once (
analyseProfileinengine.js): contrast, depth, warmth, vividness and the band of lightness steps that suits your face. It does not change while you dress. - Each piece is reduced to what is seen of it across a room (
lookinengine.js): the colour it adds up to (mean), its pattern and whether that reads as pattern or texture at 3 m (visible,texture). - Each rule inside
checkOutfitlooks at one relationship and callsadd({...})with a score:score < 0.5: fails (counted in the verdict, with a fix where there is one);0.5 ≤ score < 0.85: to note;score ≥ 0.85: passes (often added with score 1 and a short sentence, so the card can say why it passed).
- The verdict (
verdictinengine.js): no fails is “Good outfit” or “Works”; one fail is “One fix away”; two or more is “Start again”. A failing possibility rule (something that cannot be worn at all) is shown first. - Suggestions compare outfits with
penalty: the sum of(1 − score) × weightover all checks, leaving out context checks. So a rule’sweightinRULESdecides how much it counts when Valet chooses colours, not whether it fails.
A rule’s kind (in RULES) says how it counts:
perceptual: what the eye measurably does (badge A or A/B);convention: tailoring and colour convention (badge B);possibility: what cannot be worn (a pocket square with no breast pocket);context: advice about what the outfit cannot change (your frames, your build). Shown, never counted.
A check’s level ('A', 'B', 'A/B') is the badge the reader sees. If you leave it out, add uses 'B'.
3. Anatomy of a rule
Every rule lives in four places. The tests fail if they disagree.
a. The registry entry, in js/rules.js:
socks: { name: 'the socks', weight: 0.6, reason: 'takes the trousers\' colour family',
section: 'feet', kind: 'convention', how: 'r-socks' },
name: how the verdict names it (“Fails on the socks”).weight: how much it counts in suggestions (see 2.5). Most rules are 1; minor ones 0.3 to 0.6.reason: the phrase a suggestion gives when a colour mends this rule (“… takes the trousers’ colour family”), ornullwhen no colour change can mend it.section: which question of the Outfit Check card it is listed under in the Dresser (skin,temperature,contrast,frame,sheen,pattern,metal,feet,colour,proportion,formality,season; seeSECTIONSin the same file). Without one, the check’sgroupdecides.kind: see section 2.how: theidof the passage in How it works that explains it. The Dresser’s “Why” button opens it.
b. Its thresholds, in PARAMS in the same file, each with its badge and the section of How it works that explains it:
sockFamilyHue: 35, sockLoudC: 0.2, // B §10 socks in the trousers' colour family: hue within 35°; electric or neon from OKLCH chroma 0.2
Never write a deciding number straight into engine.js. Name it here, so it can be found, argued with and tested.
c. The check, in checkOutfit in js/engine.js. The function is long but flat: one block per rule, grouped under comments (/* --- colour --- */, /* --- pattern --- */, /* --- accessories --- */ and so on). Inside it you have:
L[k]: what is seen of the piece in positionk(shirt,jacket,tie,trousers,socks,shoes,square…), orundefinedif it is not worn.L[k].meanis its colour from a distance,L[k].hexits ground colour,L[k].visibletrue if its pattern reads at 3 m.K[k]: what kind of piece it is (fromgarments.js):K.tie.knotted,K.jacket.pocket,K.shirt.frameand so on.p: your analysed colouring (p.band,p.contrastLevel, andp.season, the season switch);o.occasionfor the outfit.- Helpers:
lum(hex)(lightness L*),okc(hex)(OKLCH),VC.deltaE2000(VC.hexToLab(a), VC.hexToLab(b))(colour difference),nm(k)(a piece’s name for a sentence).
A check calls add:
add({ id: 'socks', score: 0.45, slots: ['socks'], level: 'B',
fixes: [{ label: 'Socks in the trousers\' colour', slot: 'socks', set: { hex: L.trousers.mean } }],
text: 'Socks that match the shoes, not the trousers: …' });
id: the key inRULES.slots: the pieces it is about (the Dresser highlights them, and Keep this uses them).text: one or two plain sentences. Say what you see, then what to do.fixes(optional, at most two are shown): buttons the Dresser offers. Each has alabeland one action:{ slot, set: { hex: … } }changes a piece;{ slot, on: false }takes it off;{ slot, kind: 'roll' }changes its type;{ slot, pat: { type: 'solid' } }makes it plain;{ acc: 'watch', set: {...} }changes an accessory. A fix never touches a piece the user has locked.
d. The passage, in index.html, in the section of How it works the rule belongs to, as a list item with the id named in how:
<li id="r-socks"><strong>Socks</strong> take the trousers, not the shoes … <span class="cite">[<a href="#ref-50">50</a>, p. 173]</span> …</li>
State the rule, its numbers and its sources. A web source gets class="web" on its link, so it shows in a dashed box. The opening sentences are what the “Why” bubble shows, so make the first one count.
4. Checklist: changing or adding a rule
- Decide what it rests on. A (measured), B (convention, with a source you can cite, ideally a book) or A/B. If it is C (a popular system nobody has tested), it does not go in: add it to section 16 of How it works instead, saying why. If a convention contradicts a measured effect, the measurement wins.
- Write the passage first, in How it works, with its source. If you cannot write it, the rule is not ready.
- Name its thresholds in
PARAMS, with badge and section. - Add the registry entry in
RULES. - Write the check in
checkOutfit, next to the rules it belongs with. -
Add scenarios in
tests/scenarios.js: at least one outfit where it should fire and one where it should not. The helpers arebase({...})(a plain smart-casual outfit you override),P(hex, kind, cloth)(a piece) andT(name, outfit, [[/^id: /, true]])(expect a note matching the pattern, orfalsefor none):T('socks that match brown shoes, not grey trousers: fails', base({socks:P(col('Chocolate'),'socks')}), [[/^socks: .*match the shoes/,true]]); - If it has a threshold, add a line to
tests/boundaries.js(flip(...)): it measures the quantity in an outfit, moves the threshold just past it both ways and checks that the rule flips. - Run the tests:
node tests/run.js. The regression test will now fail, listing outfits whose verdicts changed. Read the list: every change should be one you meant. Then record the new behaviour withnode tests/regression.js --update. - Look at it in the browser (section 6).
- Write it down: a short entry in the revision notes, and in the commit message.
To change a threshold only: edit PARAMS and the number in its passage, then steps 8 to 10.
To remove a rule: delete its check, its RULES entry, its scenarios and boundary lines, and either delete its passage or say there why it was removed (readers may remember it). tests/rules.js reports a RULES entry that nothing emits.
5. A worked example, not yet built
Flusser gives a rule Valet does not check (How it works, section 18): a plain pocket square only with a patterned tie (Dressing the Man, p. 216). Here is how it would go in, as a gentle note.
- What it rests on: B, one writer. A note, never a failure: score 0.7.
- Passage: add a sentence to
<li id="r-square">, and take it out of the “not checked yet” paragraph in section 18. - Threshold: none needed; “patterned” is
L.tie.visible, “plain” is!L.square.visible. - Registry: none new; it is part of the
squarerule, so it reusesid: 'square'. -
Check, in the pocket-square block of
checkOutfit, after the “bought as a set” test:else if (L.tie && K.tie.knotted && !L.square.visible && !L.tie.visible && !white) add({ id: 'square', score: 0.7, slots: ['square', 'tie'], text: 'A plain square with a plain tie: Flusser keeps the plain square for a patterned tie. A patterned square, or white linen, sits better here.' }); - Scenarios: a plain burgundy square with a plain navy tie should note
square; the same square with a striped tie should not; a white square never should. - Run
node tests/run.js, read which regression outfits changed (only ones with a plain square and a plain tie should), then--update.
6. Checking in the browser
The Node tests cover the logic, not the page. After any change to index.html, css/ or js/ui/, open index.html and go through this list, on a wide window and on a narrow one (or your phone):
- the welcome window opens on a first visit (clear the site’s storage to see it again);
- Load the demo profile; each tab opens without an error in the browser console (F12);
- on the Palette, Next: try an outfit leads to the Dresser; in the Dresser, Choose the best colours, Undo and a fix button work, and Why opens its passage;
- Proportion & fit: each garment button in Fit, and a Sources button;
- How it works: the contents list jumps to each section.
If you have Python, tools/smoke.py does the clicking for you and reports console errors (see its header).
7. Releasing
node tools/release.js 1.11(your version number). It writes the version to every place it appears, including the?v=on each file so browsers fetch the new ones.node tests/run.jsmust say all tests pass.- Add an entry to the revision notes: what changed, why, and whether any verdict changed.
- Commit, with the same summary.
- To give someone a copy, make a zip without the git history (which carries every commit and your email address):
git archive --format=zip --prefix=valet/ HEAD -o valet.zip.
8. Things that are easy to break
- Text that differs on a phone. Instructions written for a mouse (“Click”, “Point at”) have a touch version:
V.say(mouse, touch)in JavaScript, ordata-touch="…"on an element in the page. Write both. - Ids the code looks for. Many elements in
index.htmlare found byid(#ovComplete,#welcomeDemo…). Search thejs/folder for an id before renaming it. - The order of scripts at the bottom of
index.html. A file can only use the objects of files loaded before it. - The “Why” and “Sources” maps in
js/ui/why.js. A new Proportion target or Fit size row needs a line there;tests/why.jstells you if it is missing. - No network. The page’s security settings forbid any connection, on purpose (privacy). Do not add fonts, libraries or images from the web; put them in the folder.
- Reference numbers. Sources in How it works, section 19, are numbered in list order and cited as
[n]. If you insert one in the middle, every later number moves: add new sources at the end of their group, or renumber all citations together.