UI/UX - transversal design system (START HERE)

Single home for everything UI/UX (CLAUDE.md File Routing rule, 2026-07-03). Any session producing HTML for Frank reads this folder first.

Visual front door → index.html - the thumbnailed gallery of the whole library: the rules (compendium, digest, Kennedy shelf, kit) + the formats library (vision paper, teaching compendium, one-pager, poster, leaflet, deck, simple table). This README is the text spine behind it. Open index.html to browse; each format thumbnail is a live preview of a real page.

Current catalogue, 5 September 2026

The visual library and full search now share catalogue/catalogue.json. Four primary media domains are UI, Voice, Video and Images; Workflows, References and Principles are supporting views. Compare tools within tasks at compare/voice.html, compare/images.html, and compare/video.html. Do not reintroduce an independent hand-written search index or global tool ranking. Stars mean editorial task fit, never measured output quality. New records need meaningful previews, role, input/output, limits, official evidence and a review date.

Two modes

Mode A, DOCUMENT (the default). A teaching page, a one-pager, a specification, a manual: something read calmly, often printed, often long. Every rule in this folder applies, unchanged. This mode is right most of the time and is not the problem.

Mode B, PIÈCE. A page whose job is to make someone feel something in the first three seconds: a concept page, a presentation, a public page, a venture pack cover, anything shown to a room. In mode B the following are explicitly suspended, and a page is not judged against them:

What still holds in BOTH modes, and is not negotiable: the Teletubbies principle (understood before it is read, adult, never childish) · light theme, no dark mode, ever · the reader's dignity for the audience in question · accessible contrast, keyboard reach, works on a phone, readable with motion off · one self-contained file, nothing fetched from outside · no invented facts or numbers.

The skeleton to break. Independently of any rule, every page we make repeats the same bones: a sticky top nav, a .wrap with max-width around 1200px, a .meta line of breadcrumbs and a date, h1, a .dek, then h2 sections of prose. A new page copied from an old page inherits all of it. In mode B, that skeleton is forbidden: decide the structure from the reference, not from our last page.

How to work in mode B. Name the real reference site before designing, open it, read how it is really built, and say in the delivery which three things were copied and what was refused. A pièce that cannot name its reference is house style wearing a new colour.

Adding something to the studio, the tidy rule (Frank, 12-08-2026)

Every addition reorganises. Frank: "Since studio has a lot of things now, you need to reorganize every time you put something else. It has to be very simple for me to see and for AI to get ideas. I like for AI to browse this all the time I ask for a good UI." The studio has two readers and both must stay served: Frank's eye on index.html, and a session hunting for ideas when he asks for good UI.

So, in the same turn as any addition: 1. Put it in the family it belongs to, not in a new one. A new card is only justified when a genuinely new kind of thing appears. Logos and illustration joined the existing inspiration card; dictation and two-way voice earned a card because speaking to the machine is a direction the studio had never held. 2. Feed the search words. Every card carries a data-find list, that string is what a session greps and what the find bar matches. A thing that is not in a data-find is invisible however good the page is. Add the words Frank would say and the words a session would search. 3. Say plainly what is not worth using. A row that says skip, and why is worth as much as one that recommends. It stops the same thing being re-proposed in a month. See the "not to be re-proposed" table in ~/Claude/kit.md. 4. Never let a category grow past what the eye can scan. If a category passes about eight cards, split it or merge its weakest members before adding another. 5. EVERY link carries a picture, and anything we made is COPIED here, not linked away (Frank, 01-09-2026, on the globes page living only at smartrules.ai/space-registry/globes/: "all links must have a thumbnail... or rather copying into the studio repo since this link might disappear"). Two halves, both required. The picture (Frank, 15-08-2026: "systematically put thumbnails when you refer to a site or an image"). A link with no picture beside it is a name the eye cannot judge and the hand does not want to click. Capture it (node ~/.claude/skills/page-review/review.js <url> --out <dir>), shrink it (sips -s format jpeg -s formatOptions 60 -Z 1200), file it under assets/thumbs/, and put it AT the link. Sites go in assets/thumbs/sites/, card art in assets/thumbs/cards/. A vector page can be its own card art: assets/thumbs/cards/card-globes.svg is the drawing itself, no capture needed. The copy. Anything WE made that the studio points at is copied INTO the studio, with the files that rebuild it, and the outside address becomes a second link labelled as the published copy. A link to our own work on a server is a promise somebody else can break. Worked example: diagramas/globes/ holds the page, its seven drawings, the maths and the coastline file; the live address is one link inside it. The exception, stated plainly: somebody else's site is linked and pictured, never copied.

1. Nothing in the folder may be unreachable by clicking. After adding a page, run python3 build-index.py, it relists every file not carded anywhere into the "Everything else" band of all.html. --check reports without writing.

2. Explaining prose becomes cards, and a card that names a site carries its picture (Frank, 15-08-2026). A paragraph telling the reader how to use the page is a wall; the same content as three or four cards is read in a glance. And a card about a site shows the site, with the text laid over the picture, it is what makes the row worth looking at. Captures live in assets/thumbs/sites/.

3. Name the skill where the page tells the reader to ask (Frank, 19-08-2026: "they all have their own Claudes. The Claude will not understand if I give him this"). A page that says « say: put a speaker on this page » is useless to a colleague whose Claude has never heard of the recipe. So the FIRST box says both moves in order: give your Claude the recipe (the skill's name, the one command, the download) then ask (the sentence to say). Naming the skill only at the bottom of the page is too late. And the page must speak of Claude in the third person: "Claude declares the domain", never "I do it", because the actor is the reader's own session, not ours. Shape to copy: mail/branded-mail.html, the box under the drawing.
4. A page whose capability is a skill carries that skill, on the page (Frank, 19-08-2026: "in each page where a skill is needed it should be downloadable there"). A colleague reading the page must be able to take the thing away without hunting: a Give it to a colleague section with the one install command (npx skills add gfrankgva/studio-skills), a download link to the skill file: the public copies live in assets/skills/, refreshed from the pack, and the GitHub link. Say plainly that they use their own accounts, nothing of ours, and that the method still works by hand without the skill. The shape to copy: mail/branded-mail.html §Give it to a colleague.
5. Sections fold, but never as ruled bars (Frank, 19-08-2026, asked three times). Keep <details>; give the summary no border, no rule, no filled band: the title and a quiet chevron, and leave it open, so the reader sees the content before clicking anything. A column of thick lines with triangles and empty space says nothing.
6. A list of documents is a row of pictures, and a card never lands on markdown (Frank, 18-08-2026, on the motion page's filename table and the galleries page's first card). Two faults, one rule: a reader is never shown a filename, and a card whose picture invites a click must open a page he can read, a .md link belongs beside its HTML view, never as the main click. Every page that can be photographed carries its picture; the ones that cannot (private, Mac-only, a code repository) become a short text list under the pictures. Crop with Python/PIL, not sips --cropOffset: that flag crops from the centre and silently gives mid-page thumbnails.
7. Nothing tall may freeze. .page-header is sticky because it was written for one slim line. A header carrying a title and paragraphs uses .page-intro instead and scrolls away: a frozen block eats the screen and hides what the reader came for.

One tool, one home for its measured facts (Frank, 31-08-2026: "you must have one doctrine"). Two files describe tools and they must never both describe the same thing. ~/Claude/kit.md holds what Frank owns: the tool on his Mac or his servers, its keys, its traps, and what it really gives when we run it. The studio holds what a page can be made of and what Claude can drive to build one. So a studio page states the capability and points at the kit for the tool's measured behaviour; it never restates a figure or a promise from a product page. The fault this fixes: the voice page claimed VibeVoice returned who spoke and when, while the kit already recorded, from a run on his own machine, that it returns plain text with no labels and no timings. When the two disagree, the measured line wins and the other side becomes a link.

And the register outside the studio. Tools installed on Frank's Mac or servers go in ~/Claude/kit.md, not here. The studio holds what a page can be made of; the kit holds what he owns.

The three layers (in order - this order IS the method)

1. ① GOAL - the Teletubbies principle (Frank's philosophy, unchanged): every page understood BEFORE it is read; appetite - the eye must WANT to stay; reading easy and pleasant, ALWAYS. Adult, dignified, deep-simple. Memory: user-teletubbies-principle.md (5-second test, state-by-color, drawn gestures, numbers with mass).
2. ② METHOD - the Kennedy method (Erik D. Kennedy, learnui.design - adopted 2026-07-03 after Frank rejected the rules-first demo): start from the ONE job of the screen (per 100 visits, what happens ~95 times?); hierarchy by DE-EMPHASIS - silence everything that is not the point (pop/un-pop, one most-prominent element); design in GRAYSCALE first, colour last as scarce accent on the actionable; double your whitespace; locality laws + ABD control table for anything interactive; ≥16px inputs, two body regimes (reading 18–24px / dense 14–20px); text over images only by method. Shelf: kennedy/_index.md, seven sourced digests: hierarchy and spacing · colour · typography and fonts · intuitive UX · practice methods · tools · against systems. The method section in the system doc is the operating body of the rules.
3. ③ NET - tokens + auditors (consistency enforcement ONLY, explicitly insufficient for design): scale 1.25 × 5 steps + 2xl hero (rationale: "corral attention" - a step must be visibly a step; may flatten below 480px), spacing by duplication, plain figures, baseline alignment, committed column. python3 token-audit.py <file> + composition-audit.js in the live page. A page can pass every audit and still be bad - the audits catch regressions, they never steer the design.

The families, one line each

Each family page is the source for its subject. This README is the spine, not a second library.

How a document reads → documentation-design.md. Reading measure, two body regimes, the on-this-page rail, and the block vocabulary written on house tokens: segment, callout, steps, statistic, description list, divider, label, code block, comparison. Any session producing a teaching page reads this alongside the Kennedy shelf.

How the text sounds → register. Eight registers, one default per document type, chosen before writing. Seven habits forbidden in all eight.

The document formats → formats. Vision paper, simple table, proposal note, concept note, implementation plan, and the formats whose recipe lives in a skill. Copy one and fill it.

Putting a page online → publishing. Three roads: a link now, the studio itself, Frank's two servers. The page says which, and what to check before any of them.

Motion, video and people in the page → motion. Video under a calm UI rather than animation code, four motion moments, the speaker in four sizes. The whole capability has one door: the motion topic file. Motion applies to public and venture pages; documents keep the calm rules.

Show a body, and put it straight → body. A fault shown in place, then put right in the same frame. Three ways to make one.

Screens, manuals and reviews → the user manual and the UI review. Software shown in a page, and a page judged against the rules.

What Frank refused and approved → taste. Read before producing anything meant to be good rather than merely correct.

The self-check (new order)

Before delivering ANY page, in this order: (1) state the page's ONE job in writing + verify everything else was de-emphasized (squint test) · (2) grayscale check - hierarchy must carry without colour · (3) locality + ABD if interactive · (4) composition audit (live) · (5) token audit (static) · (6) the pleasure gate - reading every part easy and pleasant, or that part fails. Full checklist: «Autocontrol antes de entregar» in the system doc.

Impeccable execution companion

Impeccable is installed globally for Codex as the execution companion to this system. It contributes focused commands, implementation discipline, and production checks; it does not replace the Teletubbies principle, Kennedy method, document layer, or incumbent project truth. Read impeccable-integration.md for the authority order, project-context boundary, command routing, and combined verification sequence.

Reference implementations

• 3 - Projects/marketplace-showcase/index-v2-proposal.html - the Kennedy-first pilot (one job, one prominent element, grayscale-first, colour last)
• 2 - eR services/countries/Cuba/torre/index-teletubbies.html (Cuba tower - happy path drawn, solid cylinder)
• 2 - eR services/countries/Jamaica/boards/tower-teletubbies.html (Jamaica tower - the ∅ empty-registry gesture)