ui-conventions
Skill2 starsChanged 59 days agoMITView on GitHub
Use when writing or changing any UI in todox — a page, a component, Tailwind classes, or CSS. Covers the helpers to reach for before inventing one, and the layout rules that keep the app usable on a phone.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- ericwood8/skillstheir own version, first seen Nov 1, 2026
- willdady/platypustheir own version, first seen Oct 13, 2026
- Autonoma-AI/autonomatheir own version, first seen Oct 9, 2026
- foru17/neko-mastertheir own version, first seen Oct 8, 2026
- foru17/clash-mastertheir own version, first seen Oct 8, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- foru17/clash-master★ 4.4ksame name
- foru17/neko-master★ 4.4ksame name
- Autonoma-AI/autonoma★ 242same name
- willdady/platypus★ 130same name
- ericwood8/skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- add-rpc-methodSkill
- db-changeSkill
- i18n-stringsSkill
The file
We split this skill into the rules it gives an agent
1 rule. 0 are common, 0 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 113
Colour never carries meaning alone: Every status, kind and badge has a text equivalent — see StatusDot and Chip for the pattern — and every …
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
UI conventions
Tailwind v4, CSS-first: there is no tailwind.config. Tokens and helpers live
in app/globals.css under @theme inline.
Reach for what exists first
| Helper | For |
.sticker / .sticker-flat | the card, and the quieter card inside it |
.btn / .btn-quiet | buttons |
.pill | nav, report period and language pills |
.link-more | the wavy-underline text button |
.lift | hover raise |
.pop | entry animation, staggered with an inline animationDelay |
.row-action | an action that appears on hover and on touch |
.searchbox | the search field frame |
.on-fill | dark text on a bright fill |
.display / .mono | the two non-body typefaces |
.prose | 68ch measure for body copy |
Components: app/components/ (Panel, Empty, Chip, Counter, Field,
StatusDot, Blob) via the barrel app/components/index.ts. Client-side
pieces: app/features/.
Mobile rules
These are written down because every one of them was a bug on a real phone.
- Every flex row that holds more than two controls needs
flex-wrap. The header, the panel header and the status rows each shipped without it and each made the page scroll sideways. flex-1is a basis of zero, so a box withflex-1 min-w-0will squeeze to one word per line rather than let the row wrap. If it should wrap, give it a realmin-w-[…]. If it should not shrink, give the siblingsshrink-0.- No bare fixed widths.
w-[210px]belongs behindsm:; on a phone usew-full min-w-0orflex-1 min-w-0. - Touch targets are 44px.
.btn,.link-moreand.pillgetmin-heightundermax-width: 640pxinglobals.css— use those classes rather than restyling a control from scratch.min-heightand not padding, because several call sites override padding with!py-[3px]. - Hover is not available. Anything revealed on
:hovermust also be revealed under(hover: none);.row-actionalready is. - Inputs are 16px on mobile. Below that, iOS Safari zooms on focus and does not zoom back.
- Long unbroken text breaks or truncates. Paths, e-mails, tokens and model
ids:
truncatewith atitle, orbreak-all. Prose in a<pre>getsbreak-words, notbreak-all. html, body { overflow-x: clip }is inglobals.cssas a net for the entry animation's rotation. It is not a licence to leave an overflow unfixed — find the element and fix it there.
To check a page, at 320px and 390px:
[...document.querySelectorAll('*')].filter(e => e.getBoundingClientRect().right > document.documentElement.clientWidth + 1)It should be empty — with one exception, so nobody "fixes" a correct one.
A deliberately scrollable block (a code sample, a wide table) sits inside an
overflow-x: auto box, and the check reports its content, because the
content's own rectangle really does reach past the viewport. The box is what
has to stay inside it. When something shows up, measure the wrapper:
const w = el.closest('[class*="overflow-x-auto"]') ?? el.parentElement;
w.getBoundingClientRect().right <= document.documentElement.clientWidth + 1 // in bounds
w.scrollWidth > w.clientWidth // and scrollingBoth true means it is working as intended. Either one false is the bug.
Contrast and the type floor
Two greys: text-muted is for sentences, text-faint for metadata (a
timestamp, an id, a path, a slug) — and nothing goes under text-meta
(12px). Sizes come from the scale (text-meta, text-small, text-body,
text-lead), not from text-[11px]. The dashboard once had a hundred and
twenty nodes at 11–13px in the metadata grey and read as texture.
To check a page, on the real thing (the tokens are runtime CSS variables, so the dev server is the same):
const ch=c=>c.match(/\d+/g).slice(0,3).map(v=>{v/=255;return v<=.04045?v/12.92:((v+.055)/1.055)**2.4});
const lum=c=>{const[r,g,b]=ch(c);return .2126*r+.7152*g+.0722*b};
const okL=c=>{const[r,g,b]=ch(c);const l=.4122214708*r+.5363325363*g+.0514459929*b,m=.2119034982*r+.6806995451*g+.1073969566*b,s=.0883024619*r+.2817188376*g+.6299787005*b;return .2104542553*Math.cbrt(l)+.793617785*Math.cbrt(m)-.0040720468*Math.cbrt(s)};
const cr=(a,b)=>((Math.max(lum(a),lum(b))+.05)/(Math.min(lum(a),lum(b))+.05)).toFixed(2);
const bg=e=>getComputedStyle(e).backgroundColor, paper=bg(document.body), card=bg(document.querySelector('.sticker')), row=bg(document.querySelector('.sticker-flat')||document.querySelector('.sticker')), line=getComputedStyle(document.querySelector('.sticker')).borderColor;
const m=new Map();for(const e of document.querySelectorAll('main *')){if(![...e.childNodes].some(n=>n.nodeType===3&&n.textContent.trim()))continue;const s=getComputedStyle(e);const k=s.fontSize+' '+s.color;m.set(k,(m.get(k)||0)+1)}
({stepCardOverPaper:(okL(card)-okL(paper)).toFixed(3), stepRowUnderCard:(okL(card)-okL(row)).toFixed(3), outlineOnPaper:cr(line,paper), under12px:[...m].filter(([k])=>parseFloat(k)<12), rows:[...m].sort((a,b)=>b[1]-a[1]).slice(0,10).map(([k,n])=>n+'× '+k+' → '+cr(k.match(/rgb.*/)[0],card))})The surfaces are near black, and the WCAG ratio is near-useless there (it
reports 1.17:1 for a step the eye sees fine), so the surface steps are
measured in OKLab lightness: stepCardOverPaper stays at or above 0.08,
stepRowUnderCard at or above 0.05 (a .sticker-flat row is a well cut
into the card, so it sits a step below it), and the sticker outline reads at 2:1 or
better against the paper, because on this paper the outline is what cuts a
sticker out — the hard shadow does not show. under12px is empty, and any
row that is a sentence (not .mono) reads at 6:1 or better against the
card. The --on-fill rows (dark text on chips) will show a low number
against the card — they sit on a bright fill, not on the card, and are fine.
Accessibility
- Colour never carries meaning alone. Every status, kind and badge has a
text equivalent — see
StatusDotandChipfor the pattern — and every control has a real label. - A control that is the current state stays focusable. Do not
disabledit just because it is active;aria-currentsays that, and a disabled control gives a touch user no feedback at all. - Anything that changes without a navigation needs
role="status"andaria-live="polite"(app/features/token-form.tsx). - Server Actions stay in a real
<form action={…}>so they work without JavaScript; if you need a pending state, split just the button into a client component and useuseFormStatus(app/features/lang-button.tsx).
Full rules: CONTRIBUTING.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

