This is phy's house style: one voice and one look for everything phy makes, from pages, slides and posters to READMEs, hobby projects and code. Hand it to anyone, or any agent, making something for phy. A paper's text has its own guide; from a paper, this one covers only the main diagram (§8).

The idea behind all of it is to work in pencil: graphite on paper, drawn rather than designed, and as easy to erase and redraw as a pencil line. Colour belongs only to what the work is about.

This guide is the standard. Where anything else disagrees with it, the guide wins; where the guide is wrong, it is corrected here. The source is STYLE.md in rareone0602/phy_friends, also at its raw address for an agent to read. Other projects copy the kit (§7) from the same commit and point to the source; a copy does not update itself. §2 is the guide in short, for a brief with no room for the rest.

1. who phy is

• phy, always lower case, even at the start of a sentence. The handle is rareone0602 on GitHub and X; a credit to phy links to LinkedIn.
• The avatar is phy, phy's fursona: an Eevee in the colours of phy's tuxedo cat, with Oreo crumbs on the ruff and tail (§9).
• Draws with code. phy noticed that Grokbot Icon's character icons have a low Kolmogorov complexity: a few ellipses, some tufts, two pill eyes and a blush. So phy's characters are made by a small program, not stored as pixels.

2. principles

1. Work in pencil. Keep the source (a spec, a script, a Markdown file) and the command that builds from it. Each thing has one folder, with its examples beside it; working output goes in a git-ignored out/, and a built file is committed only where publishing needs it, never edited by hand. When something goes, all of it goes: no leftover references, no half-renamed words, no commented-out code; git remembers. Candidates that lose are set aside in a backup/ folder until phy says otherwise. A first version is a sketch, to be redrawn once phy has looked.
2. Few rules (low Kolmogorov complexity). Derive values rather than pick them: shades from colours, every vertical measure from the rule spacing. When matching something, name the one reference and what is matched, and measure the difference at the size people will see. If special cases pile up, the rule is wrong.
3. Don't make it too artificial. Drawn, not designed: honest and quiet, with lines that wobble and spacing a little uneven (§6). No gradients, glows, glass, drop shadows, emoji, stock icons, hero copy or template layouts such as a grid of cards.
4. Graphite on paper; colour for the subject. Everything is in paper and ink tones (§4), graphite rather than black, except what the work is about: the characters on a page, the data in a figure, the things and places in a film. Red is only for an error.
5. One layer. Colour goes on in one layer: flat in a chart, in coloured pencil on a character or a thing (§9). Each colour has at most one shade, the house step darker: CIELAB L* −10 and chroma ×1.2 at the same hue, with a near-grey leaning to lavender, as shadeOf in src/phyfriends.js computes it. The shade only parts two neighbours of the same colour, such as a character's body under its head. No highlights or second steps, and nothing copied from a reference's light and shade. The pencil's texture is paper, a scale of data values (§8) is data, and light (§12) is a shape drawn on the place, never on what stands in it: none of them is shading.
6. Keep the set aligned. Within a set (a family of characters, a figure series, a deck), anything new matches what is there in look, size and structure, and in code where the set is code. When a rule changes, it changes everywhere at once.
7. Tell things apart first. If two parts can't be told apart, fix that before matching a reference any closer. Simplify only down to what makes a thing itself, never past it.
8. The owner decides. People and their characters appear only with their owners' say-so, and as the owners give them: the name in the owner's capitalisation, the species, colours and pronoun, and a credit linking to the owner. An owner's wish beats a house rule.
9. Make it cute. Characters are soft and round, with a big head on a small body. Cute comes before literal, but never at the cost of principle 7.
10. Not the mode. The most likely choice (the template, the stock phrase, the default chart, the formal tone put on for show) is the boring one; look for the way that fits this idea. phy's work stays consistent through its rules, not through sameness: inside them each piece is a fresh draw, as the face's letters are, though principle 6 still holds within a set. A piece made to delight should surprise, and then, on a second look, seem the only way it could have gone.

And the particulars:

• One hand on one dial: everything is in Shantell Sans, set by one number, 0 for a paper's diagram, 50 for a site, 100 for a hobby project (§5). Code is in the system monospace.
• British English, as The Economist writes it (§3); code in American English, formal and clean (§10).
• Show phy first, and keep private things private (§11).
• A film is cut to its music, chosen first and free to set to pictures (§12).

Fixed rules and defaults. A few things hold in everything phy makes: the owners' say (principle 8), pencil on paper, the characters as their specs draw them (§9), the one face (§5), the words in prose and in code (§3, §10), private things (§11) and whose music a film may use (§12). The rest of the look, from the ruled paper and the layout to the marks, colour, light and motion, is the house setting. A page, a chart or a deck keeps it, since there sameness is what makes it easy to use. A piece made to delight (a picture, a film, a game) may depart from whatever the idea needs, and says so: a line at the top of its source names each departure and why, and a series departs together (principle 6).

3. words

The model is The Economist: opinionated, analytical and dry. Words are few, exact and honest, like a note in the margin.

• British English, all the way down. The spelling (colour, centre, grey, programme, -ise), and the vocabulary, grammar and idiom as well: "at the weekend", "in hospital", "a fortnight", "take a decision", "have got", "sort it out". American prose in British spelling is not British English.
• Take a view, and show the working. Say which is better and why, with the evidence or the mechanism. Hedging everything is ceremony of another kind.
• The exact word, in a short sentence. A long word is welcome when it is the precise one ("orthogonal", "idiosyncratic", "a trade-off"), never to sound clever. Say how a thing is made ("each one drawn from a hundred-odd lines of code") rather than how good it is: numbers and names, not adjectives.
• No hype and no ceremony. No "magical", "seamless", "powerful", "novel", "revolutionary", "leverage" or "unlock"; no "welcome" and no calls to action ("get started", "learn more"): when the reader can do something, say what, plainly. Lead with the work and end without a sign-off. Full stops and colons; no exclamation marks and no emoji.
• English only. Another script appears only inside someone's own name or a quote of theirs.
• Case follows the dial (§5). From 50 up, the chrome (titles, headings, intros, nav, labels, notes, captions, buttons and footers) is lower case, and running prose is in sentence case. Below 50, and in plain text the face can't reach (READMEs, email), it is sentence case throughout. A chart takes the case of the work it sits in. People's and characters' names keep their owner's case; other names go lower case in lower-case chrome and keep their capitals in prose.
• Person. A page talks about the work. Where phy speaks for themself, as in a credit line, it says "me". The reader is "you", told the one thing they can do.
• Humour is dark and dry, and phy's own: understatement, irony, puns and self-deprecation; the grim or absurd thing said in the flattest official voice, like a mock disclaimer or a solemn footnote. Never explain the joke. A formal piece is the same voice with the jokes taken out: none at 0; from 50 up, a line or two per page, in the corners (a note, a caption, the footer), never in what the reader came for. Dark about the world, the work and the machine; never at the expense of a real person, their character or the reader. Never baby talk.
• Credit the owner, linked; name an artist only when you know who drew the picture. Dates go in full in prose (28 September 2026) and short in a date line (28 sep 2026).

4. paper and ink

The page is a sheet of lined notebook paper: pale blue rules, a faded red margin line on the left, and a little paper tooth. Everything is written on the rules: every vertical measure is a whole number of rules, and text sits on them. The values are tokens in site/notebook.css, on the paper and on the dark sheet:

• The rules and the margin line are decoration: nothing that carries meaning is drawn in them.
• The paper tooth is a fine fractal noise at 40%, multiplied over everything.
• The dark sheet. Where the reader's system asks for dark, the paper and the ink swap: the sheet is graphite, and the words are in the paper's colour, like white pencil on black paper. Every other ink keeps its hue, and its contrast with the sheet, as the table's numbers say; python3 tools/dark_sheet.py derives them again and writes them, and the marks, into the kit. The tooth shows through the graphite as light specks, and the graphite lies in strokes rising to the right. A page opts in by declaring both schemes (<meta name="color-scheme" content="light dark">); one made for paper alone says light, and a print is always on paper. The system's setting decides, and a page never offers a switch. Nothing is inverted: a character keeps its own paper (§9), and a scan its own white (§7).
• On a dark host the page doesn't control, a slide say, lay a sheet of paper on it. A piece's night is a darker sheet (§12).

5. type

One hand on one dial. Everything is written in one face, Shantell Sans: a hand drawn with one even line, like a fine pen held lightly. The pencil is in the rest: the ink, the paper, the marks and the filter over the title. The face's informality axis lets the same hand be neat in a diagram and loose in a toy, so formality is a setting of the one voice, never another voice; above the neat end, a letter that repeats comes out a little differently each time. Only code (the system monospace) and words in a host that sets its own type (a paper's text and maths, a README on GitHub) are in anything else.

The dial. Each work has one number, --informal, set by what the work is, not where it appears: 0 for a paper's diagram and for charts (matplotlib can't turn it), 50 for a site, notes, slides and posters, and 100 for a hobby project, its site included. A work may sit anywhere between; these are the usual stops.

The print and the hand. Running words, the print, sit at the work's number d (INFM d) and never bounce. The few words written rather than set, the hand (titles, headings, notes, captions, table heads and names), are never neater than 50 and bounce in the top half: INFM max(d, 50), BNCE max(d − 50, 0). A chart's words are all at 0 (§8).

• Past 50 a lower-case s grows towards a capital. A site stops there, so "saved" still reads as "saved"; a hobby project goes all the way.
• Bounce stops at 50: any more lifts a p or an s to capital height, and "phy" reads "Phy".

Weight is pressure. Everything is Light (300); bold is 600, the pencil pressed harder. There are no other weights and no italics, not even for the title of a book.

Sizes step by 1.2 from the 18px print. On a phone the hand and the intro step down one (in brackets); the rest of the print keeps its size.

• The line height is a whole number of rules. A line moves down by --sit so its baseline lands on its rule: half a rule, less the rule's 1px, less 0.35em (half the face's ascent, 1.02em, minus its descent, 0.32em). No nudge is picked by eye.
• The hand is for a few words; anything longer than a line goes in the print. A title is about 12 letters, what fits on a phone's line. It sits on the first rule, with the rule under it left blank for its tails; too long for a phone, it shrinks rather than wraps.
• Loading it: https://fonts.googleapis.com/css2?family=Shantell+Sans:wght,BNCE,INFM@300..800,-100..100,0..100&display=swap, about 170 KB for Latin. site/notebook.css sets the dial; a page changes only --informal, and marks its hand text with .hand. Files for LaTeX, matplotlib or a design tool are in figures/fonts/. The SIL Open Font License allows any use, embedding in a PDF included; keep the licence file beside any copy of the font.
• CJK text adds 'LXGW WenKai TC' (Google Fonts, a pencil-like hand) after the face, loaded only on pages that need it, with the text marked by lang.

6. hand-drawn marks

Every mark is a single pencil stroke: an SVG path with round caps, 1.1–1.5px wide, in an ink, never filled. A page has nine:

• a ground line along a rule, for a character to stand on, or in --ink-2 going over a rule (under a table's head, under a field);
• a ring, one loose loop that doesn't quite close, round "this one": the current page, or the one thing that matters;
• an arrow from a note to what it's about;
• a squiggle for a break, or while loading; in red, the wave under a field in error;
• a side line down a quote;
• a box round the one primary button;
• a tick;
• a cross, in red, for errors;
• a caret on a select.

If a page needs a tenth mark, write a word instead; a piece (§12) draws whatever it needs, rain or speed lines, by the rule above. A mark may turn to point somewhere or grow to hold its own; it is still the same mark.

• Focus is a dashed pencil outline, 1.5px in --ink-2, 3–4px clear of the thing.
• Tilts are anticlockwise and never more than 2°: the title −1°, a margin note −2°, the button's box −0.8°.
• The graphite filter goes over the title, the ground line and the arrow, never over small text or a figure. Paste it once into each page:

<svg width="0" height="0" style="position:absolute" aria-hidden="true">
  <filter id="graphite" x="-2%" y="-20%" width="104%" height="140%">
    <feTurbulence type="fractalNoise" baseFrequency="1.1" numOctaves="2" seed="7" result="n"/>
    <feColorMatrix in="n" type="matrix" values="0 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 -2.4 2.1" result="grain"/>
    <feComposite in="SourceGraphic" in2="grain" operator="in" result="g"/>
    <feTurbulence type="fractalNoise" baseFrequency="0.04" numOctaves="1" seed="2" result="w"/>
    <feDisplacementMap in="g" in2="w" scale="1.5" xChannelSelector="R" yChannelSelector="G"/>
  </filter>
</svg>

7. parts of a page

The kit, to copy from rareone0602/phy_friends: site/notebook.css (the paper), site/pencil.css (everything drawn on it; its opening comment lists the classes), site/icon.svg (the favicon), figures/ (§8) and the graphite filter (§6). specimen.html shows every part below at work, on the rules, with the dial to turn. A page is put together as the specimen is: <html lang="en-GB"> with the colour-scheme meta (§4); in the head the face, then notebook.css, then pencil.css, and --informal on :root where the work is not at 50; the graphite filter first in the body; and a main holding a header (the title, the intro and any nav), the writing inside .doc, and a footer.

Layout. One column, 42em at most, left-aligned against the margin line: a title in the hand, one line of intro, the content and a small footer. Nothing else is required.

Small print, in --ink-2: the nav, a date line, a contents line and the footer.

• The nav sits on the rule under the intro: plain words spaced apart, underlined only while hovered, with the ring round the current page. No menus and no hamburgers; a page in one part needs no nav.
• A date line, a contents line and the footer split their items with middle dots: "28 sep 2026 · pencils · paper". Tags are plain words: no pills and no #. A long page opens its writing with a contents line of its headings, each a link.

Links are the text itself, underlined like a pencil line (1px, 3px below), darkening to --ink when hovered.

Lists, quotes and code. A list item starts with a dash in --ink-3, and a numbered one with its number in the hand. A quote is indented, in --ink-2, with the side line. Code is one line to a rule; a block is indented like a list, with no box, and wraps rather than scrolls.

Pictures are a whole number of rules tall, with top and bottom on rules, no frame, no rounded corners and no shadow, and are scaled to fit, never cut: a chart loses nothing on a phone. A photo stays a photo. A scan or a line drawing on white is laid in with multiply, so its white becomes the paper, and keeps its white on the dark sheet (§4); a character or a chart is drawn on paper or on nothing. The caption is a note on the next rule. Never put words over a photo.

Tables. The rules are the rows: no borders, stripes or vertical lines. The head is in the hand in --ink-2, with the rule under it gone over in pencil, and a cell that wraps takes whole rules. A phone fits three columns: fold the rest into a label, or split the table.

Controls:

• One primary button per view: the word in the pencil box. Hovering goes over the box again, and pressing moves it down 1px. Every other button is quiet: the word alone, underlined like a link.
• A text field has its label on its own rule, in --ink-2, and the field on the next, with no box: the rule under it is gone over in --ink-2. No placeholders: put an example in the label. A select is the same, with the caret; its open list is the system's.
• A checkbox is a pencil box with a tick that overshoots it. There are no switches. Disabled things are in --ink-3.

States:

• An error turns the field's line into a red wave, and a red note on the next rule says what to do: "that needs to be a number, like 250".
• A result is written in the hand with the arrow pointing at it, numbers and all.
• Loading shows the squiggle drawing itself and one plain word: "counting…". Under reduced motion it stays still.
• An empty state is one note, "nothing saved yet.", then a few blank rules. No picture, no "oops".

A portrait. An about page may have one character standing beside the title, a rule taller than it. It stands on the title's rule, reaches up into the blank band, and may watch the cursor.

Other places:

• Favicon: phy's head on everything phy makes, unless the work is about another character.
• Link preview: the page itself, photographed at 1200×630; not a designed card, with no extra text and no logo.
• README: GitHub strips CSS, so the style lives in the words, in sentence case (§3): a title, one honest line, the preview picture and short plain sections. No badges, no emoji and no feature lists.
• Print: plain paper. The rules, margin line, tooth, nav and portrait drop out; the ink stays.

8. charts, slides and a paper's diagram

Charts and diagrams wear the same pencil, and the data plays the characters' part as the only saturated thing (principle 4). The matplotlib styles in figures/ carry these rules; stack an overlay for the medium:

plt.style.use(['phy.mplstyle', 'phy-slides.mplstyle'])  # Slides and the web.
plt.style.use(['phy.mplstyle', 'phy-print.mplstyle'])   # Print: white, in the host document's typeface.

Data colours come from phy's characters: each is a character's colour taken down in the house shade step (principle 5) until it holds 3:1 on the paper, and where two still sat too close, one took another step. python3 figures/palette.py derives them again and prints the tests.

• Every pair stays apart under protanopia, deuteranopia and tritanopia (CIEDE2000 13.9 at the closest), but the five fall into only two tiers of grey: a figure that may be printed in grey needs direct labels or marker shapes as well.
• Five at most. Fold the rest into "other" in --ink-3, or split the figure into small panels. Take the colours in order; a series keeps its colour from figure to figure, never its rank.
• Data on a scale takes the blue in steps: #e4f3ff #abdafe #83c0ea #55a6d7 #0c8dc3 #09729f #06587c. The lightest four fall short of 3:1 on the paper, so they are for fills only; a line or a small mark takes one of the last three. Data either side of a middle takes the blue and the red, with the paper in the middle.

Charts:

• Words are in --ink; axes, ticks and numbers in --ink-2.
• Two spines, short ticks, no box and no grid. Where a grid helps, pale rules (#cfdbe8, 0.6pt) run across y only, under the data.
• Lines are 1.2pt with round caps. Fills are flat, and a band of spread is the series colour at 16%.
• Label lines at their ends. A legend goes only where labels would collide, and has no frame.
• The face is at 0, which is the font file's default, so matplotlib needs no dial; but register it before plotting, or matplotlib falls back to Helvetica Neue without a word: font_manager.fontManager.addfont('figures/fonts/ShantellSans-Variable.ttf'). A chart inside a document with its own typeface takes that typeface instead (the print overlay).
• No wobble and no graphite filter: on a chart they look bent, not drawn.
• A caption says what is shown, then what it shows: "build time for four versions: the last one halves it". Never just "results".

Slides. A slide is the notebook page ×1.5: at 1280×720 the rules are 48px apart, 15 to a slide, and the title is 96px. A chart on a slide takes the slides overlay's sizes instead.

• The title states the point, not the topic.
• A chart sits on blank paper, since rules behind it would read as gridlines; the overlay's paper-toned figure covers them.
• One note with an arrow may point at the one thing to see.
• The bottom line, in small print, gives the source and what is missing: "one run each; no error bars".

A paper's main diagram, the teaser or method overview that people remember the paper by and redraw in their own talks, is where the pencil shows; the paper's text keeps the venue's type. figures/phy-diagram.sty carries it for TikZ, and figures/diagram.tex is an example.

• Build it as its own file with lualatex diagram.tex and include the PDF, so the paper builds as usual, arXiv included, without the font. Only LuaLaTeX can turn the dial; XeLaTeX stops with a message.
• It sits on white, with no title: the caption carries it. Its words are in the face at 0, in sentence case; a box holds a noun or two, and the caption does the explaining. A diagram for a site or slides takes that work's number: \usepackage[informal=50]{phy-diagram}.
• Symbols and values are maths in the paper's own type, so the z_t in the diagram is the z_t in the text: load the paper's text and maths packages (newtxtext and newtxmath for Times) before phy-diagram.
• One note in the hand, at 50, with an arrow, may point at the new part.
• Draw it at the size it prints, 6.75in across both columns or 3.3in in one, so words come out at 8pt and none is smaller than 7pt.
• Lines are graphite, 0.7pt, with round caps and open arrowheads, and wobble a little from a fixed seed, so a rebuild draws the same lines.
• Boxes are outlined, not filled. Colour goes only to the new part, or to the few things the reader must follow: a data colour on the line and at 16% inside, the same in every figure of the paper.

9. the avatar and characters

• phy's mark is phy (§1): the head alone for a favicon or avatar, the whole character where there is room. It is drawn by src/phyfriends.js from characters/phy/phy.js, never by hand, so every copy matches.
• Every character is a small spec, about 100 lines, that a factory draws in coloured pencil: soft round shapes coloured in without an outline, pill eyes in the character's own eye colour, a soft blush, and no nose and no mouth by default. Each has exactly one shade layer (principle 5), which its body, under the head, always wears. The rules for drawing one, and the references a reviewer needs, are in FWIENDS.md, next to the factory. However free a piece is (§12), it stages its characters and never redraws them.
• The pencil is one texture over the whole character: strokes rising to the right, the paper's tooth, and patches where the hand pressed more lightly, with the paper, rules and all, showing through. The texture belongs to the paper: it stays put while the character breathes, turns or hops on the spot, and travels with it about a page, as a figure cut out of paper would. On a background of its own, such as a dark close-up or the dark sheet (§4), a character is drawn on paper cut to its outline, so the pencil shows paper, never the background. An icon too small to hold the texture, such as a favicon, is drawn flat.
• Motion is calm and alive: eyes that follow the pointer, smoothed so they never jitter, over breathing, irregular blinks and a slow sway. Nothing bounces all the time. Under prefers-reduced-motion only the eyes move, and a page whose characters move of their own accord offers the same as a checkbox, "keep still".

10. code

Code is a language of its own: American English, formal, and clean in the sense of Robert C. Martin's Clean Code. The dial, the lower-case chrome and the humour stop at its edge.

• American English in identifiers, comments, docstrings and commit messages: color, center, gray, normalize, behavior, license, labeled, toward. Words the code puts in front of people (a page's text, a label, an error message) are copy, and follow §3.
• Formal. Comments and docstrings are full sentences in sentence case, plain and precise: no jokes, no asides and no metaphors.
• Plain names: no cute names, no puns, and no abbreviations beyond the field's own (rgb, L*).

11. working with phy

• Discuss before building anything big: say what you'll make and wait for a yes.
• Show, don't describe. Render the options and put them side by side. Looks are settled by looking; once one is settled, write it down here, at the source.
• phy reviews before anything is published. Pushing, posting and sharing are phy's call, each time.
• Fanning out is welcome: a big job may go to several agents in parallel. Visual work then goes to an adversarial reviewer who knows the references. A review, whoever writes it, is a reference rather than an order: check each finding against the work, adopt what holds, and say what was rejected and why.
• Three ideas first. For a piece, think first of what the viewer will enjoy, and sketch three ideas before choosing; an ideas agent is briefed with the fixed rules (§2) alone. The first idea to come is presumed the mode (principle 10), and stays only if it beats the other two. Then draw the best in the house style, departing from a default rather than dropping the idea (§2).
• Private stays private. Personal references (photos of a real pet, say) live in a git-ignored folder and never reach a public page. Quote phy's own words only where a piece needs them.

12. pictures, films and sound

A piece made to delight (a picture, a film, a game) is looked at before it is read. Everything above holds in it, except where this section, or a departure it declares (§2), says otherwise.

The picture. A frame is composed, not filled:

• One thing to look at first, and everything else quieter than it.
• Scale does the work: something large against something small, rather than everything at one size.
• The paper is part of the picture, and a frame may be mostly empty when the idea is small.
• Off centre and uneven. A row facing us, evenly spaced, is the gallery's picture; a piece needs its own.
• Turned grey (CIELAB L* alone), a frame still shows its one thing.

The characters stay as drawn; the world is free. As in cel animation, the characters are drawn as they always are (§9), and the place around them takes its own colours (principle 4) and its own light:

• Light is drawn, never filtered: a beam, a lit window or a pool of lamplight is a pale shape in coloured pencil, laid on the set. It falls on the place, never on a character or a thing (principle 5).
• Night is a darker sheet of paper, not a filter over the light one. On it the inks turn over, as on the dark sheet (§4), and each character keeps its own paper (§9).

References, each for the one thing to take from it (principle 2), never its whole look:

• The Snowman (Raymond Briggs's book and the 1982 film): soft coloured pencil throughout, almost no words, and the pace set by Howard Blake's score.
• Ernest & Celestine (2012): colour that stops short of the frame's edges, so the paper shows round every scene.
• Jon Klassen's hat books (2011–16): eyes without mouths doing all the acting, and menace stated flatly.

Sound and pace:

• Music first. Choose the track before the story. Measure it once, into data beside the film (its bars and beats, or, where the tempo is free, its moments), and write every cue against that data, never by ear.
• The pace is the music's. Motion lands on phrases, not on every beat, and a film may cut, pan and push in on the music's lifts, where a page stays calm (§9).
• Whose music. Never music that the agent making the film composes or generates; music someone else made with AI only where it is good. The licence must let a hobby film set it to pictures: public domain in the US, where the site is served (the recording as well as the score), CC0, CC BY or CC BY-NC. CC BY-SA only where phy alone is on screen, since the other characters are not phy's to license; never ND. Credit the composer even where nothing requires it. A commercial song goes only through a platform's own library, never on a page.
• Credits once, large. A link in a picture cannot be clicked, so a video names the people and characters in it once, written large, and the post that carries it links them.

phy's fwiends: the gallery and its characters

This file adds what only this project needs to phy's style guide (STYLE.md): the gallery page, the rules for drawing a friend with src/phyfriends.js, and the rules for putting friends together in films and games. Where the two disagree, STYLE.md wins unless this file says why. The site's style.html shows both, one after the other, and section N of STYLE.md stays at style.html#sN. Run python3 tools/pf.py style after editing either.

the gallery page

index.html (the gallery), style.html (the guides) and specimen.html (the kit at work) all wear the kit, and turn to the dark sheet where the reader's system asks for it (STYLE.md §4). The paper is design C of the mockups in design/; A and B are kept in design/backup/. The specimen sits at 50, and its dial turns the face, never the case, to 0 or 100 until a reload. The gallery is a hobby project, so it sits at 100 (STYLE.md §5).

The page has five parts, in this order:

1. The title, phy's fwiends, in the hand: the project's name wherever people read it (phy_friends is only the repository's and the code's).
2. One line of intro: "a few fwiends in coloured pencil, each one drawn from a hundred-odd lines of code."
3. The nav, as on the other two pages: fwiends, style guide, specimen.
4. The stage, a group photo: the fwiends stand together on pencilled ground and all watch the cursor.
5. The footer: "characters belong to the people named under them"; a credit to Terry's owner, who tuned the fwiends' proportions by eye on the tuning page; the style guide; and the source.

The stage:

• It is the one centred and the one wide thing on the page, as the subject of a group photo is; the rest keeps to the margin line. Beside the margin line it runs to the paper's edge, and the page stops growing where every friend fits in one row.
• Every friend is drawn at one scale, in a box 270 head units tall whose bottom edge is its ground (PhyFriends.groundOf): 5 rules, or 4 below 360px, so that two still stand side by side. Ears and tails may reach out of the box, as in a photo. A body or tail that sticks out at ground level widens the friend's slot (--reach-left, --reach-right, measured on load), so neighbours stand close but never tread on a tail; below 420px a pair stands a whole box apart instead, so that two long species never run together.
• Narrower than one row, they stand eight to a row, then five, four and three, and in pairs on a phone, never a mix of pairs and threes, so that the same friends always share a row. In rows of eight or five the second row's rule is 768px down, so a window that tall shows two rows. python3 tools/pf.py pages works out from the reaches (neighbours overlap by 0.06 of a box) how wide each split is and where the page stops, and writes them into the page; python3 tools/pf.py test fails while they are stale.
• The order is phy's. Howdi, YuanYuan and phy come first, side by side at every width; Fruit stands next to Yuda; K3V1N, BarDell, WeiWei, mosing and Yawei come between mumuyou and cowosus in that order; Raze stands between cowosus and tanyuan, and Alfie, Teni, WhiteDeer and jiaoyue follow tanyuan in that order; on a phone Yuda shares a row with Terry, Brian with mumuyou, and WeiWei with mosing. Claude stands last, so a new fwiend goes before it, and any change of order is checked at every width.
• A phone held sideways, if at least 390px tall, shows the first row and its names on the first screen: the gallery gives up the blank rule above the title, and the note the one below it.
• Each friend's ground is its own patch of rule, gone over in pencil (a seeded wobble, PhyFriends.rng(5), ink at 70%, 1.4px, through the graphite filter). Each friend is drawn on the page (bg: 'page'): on the dark sheet and in forced colours, on paper cut to its outline instead (STYLE.md §9). In forced colours its ground is in the system's text colour.
• A spotlight comes on, on the dark sheet, over the friend you point at, tap or focus: a beam from the tips of its ears and a pool on its ground, in warm light drawn in pale coloured pencil (STYLE.md §12). It is the one light on the site's pages, since the gallery is a stage, and it lights one friend at a time, so that the page still has one thing to look at. It stays within the friend's slot, clear of the words above and below.
• The ring circles the host's name, phy's: "this one" is the one whose page it is.
• Two winks, both in corners of the stage (STYLE.md §3). A pencilled note on the rule under the nav, over the right end of the row, says what to do: "psst: they watch your cursor. click one to say hi" (only "click one to say hi" where fewer than five stand in a row, and "tap" on touch screens). Being one long line, it takes the title's tilt, −1°, since at −2° its far end would climb half a rule. And a mock disclaimer about the last fwiend, Claude, the machine that made the page, in small print a blank rule under the last row's labels: "this work was generated entirely by this machine", then "human intelligence was confined to the characters and the corrections." Its first line ends in the kit's arrow, turned to point up at Claude's middle (measured on load); where Claude stands alone, the disclaimer is centred under it and the arrow points up and in.
• At the left of the note's rule, a small-print checkbox, "keep still", keeps the fwiends as still as reduced motion does and skips the opening. It starts as the system's setting, is remembered on the device, and on a phone held sideways moves up to the nav's rule. Without JavaScript it is hidden, and the stage reads "the fwiends are drawn live, so they need JavaScript to appear."
• Each fwiend has a link of its own to send its owner, index.html#yuda, its name in lower case (#k3v1n): it skips the opening, brings the fwiend into view and focus, and the fwiend says hi.

Labels, three rules tall: the name in the hand, 31px (26px on phones, 22px on the smallest), a step above an h3, since it is read from further away; the species in small print, two or three lower-case words ("tuxedo eevee"); and the owner's handle in small print, linking to their page (phy's reads "that's me · linkedin"). On the smallest phones a long species or handle wraps onto a second rule rather than run into a neighbour.

Each friend is a button with a short name (aria-label), "say hi to Terry", so that a screen reader or a voice gets to the point; what it looks like is a hidden description (aria-describedby): "a yellow plush toy with huge floppy ears, a fluffy bib and dark felt soles". The specimen's portrait is named and described the same way.

The cast (characters/cast.js) is the source of each name, species, credit and consent. The page repeats them by hand (the labels, the aria-labels, the host, the footer's credit and the link preview's alt text); python3 tools/pf.py test names the friend and field wherever the two disagree, and fails any friend whose owner has not agreed to the gallery. Every page that loads all the friends loads them in the cast's order, and python3 tools/pf.py pages writes their script tags.

Saying hi, and how they take it. src/live.js, which any page can use, brings the fwiends to life, and their feelings come from the emotion library:

• Hovering over a friend, or tabbing to it, perks it up: ears in, eyes a touch wider. Kept there a moment, it grows curious and tilts its head one way, then the other.
• A click, a tap, Enter or Space says hi, with the hop for joy: happy eyes, a small mouth, two bounces, while the others glance at it. A friend in mid-air ignores another hi until it lands, since starting the hop again would drop it to the ground in one frame, and a key held down says hi once.
• A third hi within six seconds makes it shy instead: it blushes, ducks and looks away, and takes no notice of another hi until it recovers.
• Stroking makes it content: it shuts its eyes happily, and a ♪ shows once. The pointer or a finger moved back and forth strokes it, as do ← and → pressed in turn on a fwiend tabbed to, and a finger held still on it for half a second (the tap that ends a long press is not a hi).
• Left alone for 30 seconds, the fwiends grow sleepy one by one and fall asleep, a z drifting up now and then. Any input wakes them, with a "!", nearest the pointer first.
• Claude shows no feelings and stays awake. It perks up, watches and hops like the others, and returns a hi with the same smile, which is manners rather than a feeling. Its third hi, where the others go shy, plays the routine of Claude Code's animated mascot, timed as the mascot's GIF times it: a wink as it steps aside, its laptop swung up and set down open beside it, a hop round to type at it side-on, then the laptop folded away. Meanwhile it ignores a hi and the others watch it. Under reduced motion it only winks.
• A hidden status line tells a screen reader what happened in one flat sentence: "Howdi hops twice." ("Howdi smiles." under reduced motion), "Howdi goes shy.", "Howdi looks content.", "Claude gets out its laptop and types.", "Everyone but Claude falls asleep." (once a visit) and "Everyone wakes up.", which is not said when the reader only moves about the page, so that it never talks over the screen reader's own account.
• A double-click or a long press selects nothing and opens no menu, and a quick second tap doesn't zoom the page. The labels stay selectable, so a handle can still be copied.

The opening. The first time the page opens in a tab, the title writes itself and the fwiends come in by roll call. A reload, a step back through the history, a link to a fwiend, reduced motion, "keep still" and the link preview show everything in place.

• The title is written stroke by stroke, in the order a hand writes each letter, in just under three seconds, slowing at each end of a stroke and lifting between strokes. src/pen.js writes it; python3 tools/title_pen.py derives the strokes (site/title-pen.js) from the title as the page sets it, and must run again if the title or its face changes. If the face is slow or doesn't match the strokes, or colours are forced, the title simply shows.
• As the pen reaches "fwiends", the friends hop in along their row's rule from the nearer edge of the screen, row by row, the one farthest from its edge first, so that nobody hops past anybody standing. The hops are a little lower than a scene's, so that ears clear the labels above, and neighbours watch each one land. The labels are there from the start, so the empty places read as the names still to be called.
• A row is called once any of it is in view; one just below the fold comes in with only its ears showing, which draws the eye down, and on a phone the lower rows come in as they are scrolled to. A row scrolled past unseen is simply there, as are the rows still to come once the fwiends doze off. A click, a tap, Escape, a change of width or tabbing to a fwiend still to come brings everyone in at once; scrolling does not.

The favicon and link preview come from python3 tools/site_assets.py, run after any character changes: the favicon is phy's head, and the preview (1200×630) is the page photographed in the narrowest window where every friend stands in one row, then scaled down.

drawing a friend

The factory (src/phyfriends.js) encodes these rules. A friend is a spec of about 100 lines, a palette plus shape parameters, not a traced path. Before turning someone's picture into one, ask the owner how the character is written (the name's capitalisation, the species and the pronoun, "they" until told), take one picture as the colour standard and say which, and keep private references in a git-ignored private/ folder.

Coloured pencil (STYLE.md §9):

• The one texture is the factory's pencil, which render and mount lay over the whole friend; a spec never draws a texture of its own. pencil: false draws the flat shapes alone, for an icon too small to hold the texture or to match a flat reference picture (pf.py compare).
• Clothes take their thickness from how they are made, never from a texture: a band standing a few units proud of the body (YuanYuan's sash, the roll of tanyuan's hood), or cloth lying over cloth (a crossed collar, a front over its hem). Painted on to the body's ellipse, clothes read as a print on a ball.
• Every colour is one the character really has: fur, hair, markings, accessories. A band the owner counts as a marking (phy's crest) is a colour, not shading.
• A few colours, 6–13, each with a named role in palette. Every fwiend but Claude opens with the same roles in the same order, one for each part of the house figure: fur, head, face, hair, ear, earInner, iris, ink (the mouth), blush, tongue, body, tail, arm, paw, leg and foot, with earRight, irisRight or pawRight where a pair differs. Each is a colour or the name of the role it shares (paw: 'face'). Markings and clothes follow, named for what they paint, and bg (#1c1d21) is the same for all.
• Exactly one shade layer (STYLE.md, principle 5). <name>Shade is derived from <name> by PhyFriends.shadeOf, so shades match across fwiends, and nothing comes from a reference's lighting: no pale rim along an ear, no darker far side, no highlights.
  • The body sits under the head, so every body is in its fur's shade, or its clothes' shade where it is dressed. A layer of the clothes lying over it takes the clothes' own colour, such as the front of a hoodie.
  • Elsewhere the shade goes only on a part behind a neighbour of the same colour: Terry's ears behind his face, the back layer of a ruff, locks behind the mop, the inside of a hood past its rim.
  • One part in front takes it instead: a raised paw, as far as it has come in front of the head or face (fading in as it crosses their edge), so that a paw the colour of the face still shows against it.
  • A spec sets a shade by hand only where the derived one looks wrong, and says so in a comment (mumuyou's gold hair). Where a shade lands on a neighbouring colour, the neighbour moves, not the shade: phy's crumb went a step darker, away from the shaded hip.
• A pale colour that would vanish on paper takes one slightly deeper tint wherever it appears: most whites become #efeef3, and phy's warm white #f5ede6. A dark colour whose shade would read as black takes the lightest tint its pictures give it (Fruit's navy, #283e74). Judge it on the page, not on a flat render, since the pencil lets the paper through.

Proportions, in head space: a big head on a small body.

• The origin sits between the eyes. The head is widest around eye level, about 140–190 units across the cheeks. Ear tips reach about −155 (floppy ears less), and the paws reach the ground (PhyFriends.groundOf), about +140. The eyes are about 13 × 32 units, centred 31–35 either side.
• One figure sits and stands. Standing, a friend keeps its seated body on two short plush legs that show 30 units below it, with arms hung high and well out from its sides; its feet touch stand.ground, and the rig lifts it so that they stand where its seated paws did. Seated, the same arms hang straight down in front as forelegs, to its seated paws (stand.seat), and the legs fold into its feet, so it stands up and sits down through every height between, with nothing appearing or vanishing.
• From the back: the body and its clothes, the scarf (a ruff or bib of fur, or a scarf), the head, whose chin lies over the scarf and collar, then the arms, except at the shoulder, which tucks under the scarf and head. A hood is clothing, so it lies under the arms, and a sleeve takes its cloth's shade, so that it shows against the garment's front.
• A reference in the house template (a 1254px close-up, head tipped 20°, as in the Grokbot Icon prompt's examples, which reviewers should know) is matched at scale: 5.5 with the view {w: 1254, h: 1254, x: 450, y: 835, scale: 5.5, rotate: 20}.

Shape vocabulary, layered ears, head, face mask, blush, eyes, mouth, then hair on top (bangs may cross the face):

• fluffy ellipses for the head, face mask and chest, whose outlines grow small curved tufts;
• a star hair mop of broad, curved, flame-like locks, some hanging over the face;
• rounded-triangle ears, with an inner ear and stripe bands only where the character really has them;
• pill eyes, one flat colour each, from the art (iris, and irisRight through eyes.right for a second colour): no whites, no highlight and no rim, which reads as an outline. Where the art draws dark eyes, as Terry's does, they are near-black. A colour that would be faint at gallery size goes a house step deeper, or further until it holds (phy's green; mumuyou's pale sky, to a blue), and on a dark face the step goes the other way (Raze's eyes take the cyan and lavender that rim them). An eye its owner draws in two colours keeps both, flat, the second a mark clipped to the eye (shine) that glances and blinks with it, as the lower half of K3V1N's does; it keeps its picture's own tint, since the colour above it holds the eye's shape. The palette's eye, a near-black, is for the open mouth;
• soft blush ovals, in the owner's colour if they have one (Yuda's is blue);
• no nose, and no mouth by default.

Turning round comes from the spec, not from new drawings. Every fwiend but Claude turns as South Park's cut-outs do, a quarter turn at a time (pose.facing): side-on to either side, or its back to the viewer, by rules that every fwiend shares (PhyFriends.TURN), so a change to the body plan turns with it. Where the true turn looks worse than a cheat, the cheat wins.

• Side-on, the face slides forwards and narrows, keeping a pale patch wide enough to read, with only its near eye (drawn over the hair), mouth, cheek and markings; the hair bends from the crown to the face, which a fringe follows; the ears close up and stand straighter, the far one in its shade; the body narrows, the far limbs go behind, and the tail grows from the back. Whatever lies on one side wraps round the near side and hides on the far one.
• From behind, a fwiend is its own mirror image: anything one-sided changes sides, the face hides but the chin keeps the head's outline, the ears show their backs in their shade, hair that covers the crown lies over the head, the arms hang beside it, and the tail is drawn over everything.
• A marking or a garment turns as its feature does (ANATOMY.turns): a bib goes to the front and hides from behind, a hood or wings go to the back, horns and antlers move with the ears, and glasses are left out once a fwiend turns, as is the custom in a side view. Name a feature for what it is and it turns rightly (the anchor on WhiteDeer's hat is a badge, which faces forwards); give an extra its own turn only where it lies otherwise (the pale lock on phy's forehead faces forwards). Teni's spec lights his back (backLit), so the back of his bob takes its own colour.
• A part that shows only from behind is drawn from the owner's own picture of the back (WhiteDeer's sailor-collar flap, the knot of Brian's bandana), and lies under the body facing the viewer, so the front is unchanged.
• A fwiend's own turn numbers (turn in its spec) are a last resort: a difference that several share belongs in the rules. The tuning page shows the side and the back.

Feelings come from the pose, not from new drawings. The emotion library (src/emotion.js) has twenty-three, each made of parts every fwiend on the house template has: the eye shapes (happy, closed, squint and the dizzy swirl), a lid over the open eyes (lid, slanted by lidTilt for a sad or cross look), the blush spreading (flush), a mouth (w, smile, frown, o, flat, wobble, open), the ears, the tail and the posture, and, standing, the arms and a gesture (paws on the hips when proud, a shrug when confused). Each shape is drawn from the eye's or the mouth's own size and colour, so a spec needs nothing for its feelings, and a new fwiend has them all. Body language follows from how pleasant and how alert a feeling is, so feelings that sit close look alike. eyes.arc and eyes.stroke set how wide and thick the happy and closed strokes are.

Keep the spec small. Tune the fluffy, star and ear parameters rather than writing raw nodes, and match the set in the spec's structure as well as in its look.

Claude, the exception. The last fwiend is Claude, the model that drew the others, as Claude Code draws it on its welcome screen: three lines of block characters. It keeps every rule above but the shape, which comes from the glyphs. A terminal cell is about twice as tall as it is wide, so a quadrant pixel is one unit wide and two tall, drawn 16 head units to the unit, which makes the eyes as tall as the house's: a terracotta block whose body is its head, pill eyes where the glyphs cut their notches, a stub of an arm on each side and four short legs.

• Being made of blocks, it is drawn in raw nodes, rounded as a pencil rounds them: soft top corners and nearly square bottom ones, so its sides run straight into its outer legs. Its arms take the place of ears, in its own colour, each turning about a shoulder inside the block so that they rise as it hops. Its legs are its body, in its one shade.
• It shows no feelings (emotions: false): a feeling gives it the movement without the face, and it smiles only to greet, with the happy eyes and mouth and without the blush. Its blush is a soft rose, since a pale pink on terracotta reads as a highlight, and its eyes look a whole unit aside (16 head units, where the house's move 6), as the glyphs move the notches.
• Having no tail, it does not sway. It is short, so its legs meet the ground at 112 rather than about 131, and standing already on four legs, it never stands up (stand: false).
• Its laptop, for its routine, is a grey base and screen drawn only on cue (an extra's show): on its arm while held, then on the ground (on: 'ground'), where it stays while Claude hops. Set down, it reaches a little into the space after the last fwiend of a row, and while it is out the page clips sideways, as during the roll call.
• Its species is "language model", its pronoun "it", and its credit Anthropic's.

Motion, on the page and in a scene (STYLE.md §9):

• Idle, the library's clip plays underneath: breathing, blinks at irregular intervals, a slow sway of the head and tail, a glance about now and then and an occasional ear flick, on an 8-second loop that each fwiend starts at a different point. A fwiend standing also breathes with its arms and shifts its weight slowly from foot to foot. The pencil boils: its texture is redrawn 8 times a second, through three versions, as in hand-drawn animation.
• Each friend works out the direction from its own head to the pointer, so the group converges on it: the eyes take the whole offset (lookX/lookY), the head about half (turnX/turnY, drawn as layer parallax), and the glances give way whenever there is something to look at. When the pointer leaves or rests a while, they drift back to centre or glance about, unless one has been tabbed to: then the others look at it. A pen is followed like a mouse, and a finger while it touches; there is no gyroscope.
• The stage stops drawing while none of it is in view or the page is hidden, to spare a phone's battery. Its clock stops with it, so everything picks up where it left off.
• Under prefers-reduced-motion, or with "keep still" ticked: eyes only, no idle motion and a still pencil; a hi or a feeling changes just the face (the eye and mouth shapes, the lids and the blush), and marks neither pop nor drift. The stage draws only as often as the pencil would boil. A fwiend that stands stays standing, since its stance belongs to the story rather than the motion.

scenes: films and games

Beyond the gallery, the fwiends appear in scenes built with film/scene.js: short films, listed in demo/index.html, and in time games. A scene is a sheet of ruled paper measured in head units, a rule every 54, so a seated fwiend is five rules tall, as in the gallery. Everything happens at a time on the scene's clock, so a film plays in a page and is filmed frame by frame (pf.py film) from the same script.

Who knows whom. Every fwiend belongs to someone, and not every owner knows every other one. phy, the host, knows everyone; any other two are strangers until phy says their owners know each other (characters/cast.js). The scene checks these rules and refuses to break them.

• Strangers keep a strip of paper between them, 40 head units between outlines (ears apart); fwiends who know each other may stand side by side. Choreograph so that nobody hops past anybody.
• Only phy speaks in words, said or written on the sheet. The others speak in marks, since only their owners know how they talk: ! ? !? … z ??, and drawn ones, a ♪, a heart, a bead of sweat, a sparkle, a light bulb and a swirl. A mark is a drawing over a fwiend's head, not punctuation, so the calm punctuation of STYLE.md §3 doesn't apply to it. It is written in the hand pressed harder, bold (600) in --ink-2, so that it reads at a glance; a drawn mark is a line as thick as that hand's stem, never filled, on the same baseline (the hand has no ♪, so the ♪ is drawn too). Likewise, nobody is given a personality, a birthday or any other fact its owner didn't give it. A film made for one owner alone (madeFor) may draft a few short lines and traits for that owner's fwiend, used sparingly and written as its marks are (write(text, { by })); nobody else sees them until the owner has kept, changed or struck each one.
• Feelings are reactions, not temperaments. A feeling answers something that happens in the scene (actor.feel('surprised', { at }), with its mark); nobody is shy, cross or sleepy by nature. Aimed at another fwiend, it follows the table: a heart or a fond look needs the two owners to know each other, and a wink or a laugh at another fwiend is teasing, which needs both to opt in. Aimed at a thing in the scene, any feeling will do.
• Nobody is hurt, frightened for a laugh or beaten by another fwiend. Games are won against the clock or the page; a miss ends with a fwiend sitting down, not falling over, nobody is blamed for it, and each fwiend keeps its own best score.
• The owners are credited where a viewer can follow the link. A page links each owner in its small print, and a frame may credit the owners of the fwiends in it on the bottom rule. A video credits them once, large (STYLE.md §12), in a roll call, say. Without the credits, recompose the frame, so that the bottom rule is not left as dead space.
• Consent is per medium. An owner who agreed to the gallery has not thereby agreed to films or games (agreed in characters/cast.js). Until they do, work that shows their fwiend carries the word "draft" in a corner, and pf.py film refuses to film it without --draft.
• Getting about. Seated fwiends hop. Standing ones walk: facing us, the foot on the side they go to steps out and the other closes up, and the body glides on up to twice as far as the feet, at a little under half a hop's speed. They turn with turnX, never with a mirror image, which would swap two-coloured eyes and reverse K3V1N's mark. Each is on its own paper, cut to its outline (STYLE.md §9).
• Films boil as the gallery does, 8 times a second (film/film.js). Under reduced motion a scene plays as the motion rules above say; travel becomes a glide, a fwiend stands up or sits down in a cut, and a film shows its last frame and waits to be played.

Props and sets. Everything in a scene that is not a fwiend is drawn as a fwiend is, so that the sheet keeps one hand.

• A prop is a spec (film/props.js): a palette of the colours the thing really has, a box in head units whose bottom centre stands on the ground, and a few of the factory's shapes, coloured in with the fwiends' pencil, with no outline. Never a traced path or a picture. A prop that films share lives in props/, one to a file; one that a single film needs stays in its folder. A set (rock, soil, grass) is props too, laid on the sheet, whose rules show through the pencil.
• A prop takes a fwiend's colour by override (palette: { paper: PF.get('yuda').palette.scarf }), never by copying the value, and its shade follows (STYLE.md principle 5).
• Light is a pale shape: a flame, a beam or a lit window is a prop like any other (STYLE.md §12), never a glow or a halo.
• Ink is a stroke: a wick, a string, a vein or a rib is one pencil line in an ink, at STYLE.md §6's width, never filled.
• A prop changes by its states, parts shown or hidden on cue (the candles lit, the needle down), never by a second drawing, and it may be drawn in, coloured in or rubbed out from the bottom or the left, as handwriting writes itself (reveal, recolor, erase).