# 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`](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.

## 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 showcase): 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` (6 sourced digests + `adoption-proposal.md` + `against-systems.md` + validated cheat sheet). 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.**

## For animated sites, video and people in the page → `motion/motion-design.md`

Opened 2026-07-31 (Frank's new direction: animated sites, avatar videos, 3D-looking motion). **The whole capability — recipes, factory, applications — has one door: the [motion topic file](/Users/unctad/Claude/5 - Handovers/topics/motion.md) (`/pickup motion`).** The heart of it: the cinematic feel is AI-generated VIDEO under a calm UI, not animation code; four motion moments (entrance, scroll, ambient, hover); the speaker in four sizes (face · half bust · bust · full body). Front door [`motion/index.html`](motion/index.html); references: the [Higgsfield MCP tutorial](motion/reference-viktoroddy-tutorial.html), the [NovaAI scroll-video prompt](motion/reference-novaai-prompt.md), the [Marcus person-on-top prompt](motion/reference-marcus-prompt.md), the [motionsites.ai decode](motion/reference-motionsites-analysis.md). Asset pipeline: the `photo-avatar-video` skill. Motion applies to PUBLIC and venture pages; documents keep the calm rules below.

## For didactic HTML documents specifically → `documentation-design.md`

Kennedy's rules (layer ②) is about **app screens**. Frank's pages are mostly **didactic documents** - teaching pages, one-pagers, explainers for UN partners and government teams. `documentation-design.md` is the missing layer: how a *document* reads well (reading measure, two body regimes, on-this-page rail, hover anchors) plus a native-CSS block vocabulary (segment, callout, steps, statistic, description list, divider, label, labelled code block, comparison) stolen from Semantic UI's grammar but hand-written on house tokens - no framework, one file. Captured 2026-07-19 from four sources Frank gave. **Any session producing a teaching page reads this alongside the Kennedy shelf.**

## 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`](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)

## History

Born 2026-07-03 from the typography specialist's adversarial diagnosis of the first Teletubbies towers ("twenty font sizes and no hierarchy"). Restructured the same day after Frank's verdict on the rules-first showcase ("no hierarchy, not pleasant, not easy - adopt Erik Kennedy's rules"): the token system was demoted from method to net, and Kennedy's rules adopted as layer ②. The typographer's reflection ("I designed for the system and not for the reader") is section 1 of the system doc.