agentleFS
beydemirfurkanbeydemirfurkan/todox/.claude/skills/ui-conventions/SKILL.md

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

  • Other versions5 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 5

    1. foru17/clash-master★ 4.4ksame name
    2. foru17/neko-master★ 4.4ksame name
    3. Autonoma-AI/autonoma★ 242same name
    4. willdady/platypus★ 130same name
    5. 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.

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
  1. Very specific:

    Colour never carries meaning alone: Every status, kind and badge has a text equivalent — see StatusDot and Chip for the pattern — and every …

    line 113

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

HelperFor
.sticker / .sticker-flatthe card, and the quieter card inside it
.btn / .btn-quietbuttons
.pillnav, report period and language pills
.link-morethe wavy-underline text button
.lifthover raise
.popentry animation, staggered with an inline animationDelay
.row-actionan action that appears on hover and on touch
.searchboxthe search field frame
.on-filldark text on a bright fill
.display / .monothe two non-body typefaces
.prose68ch 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-1 is a basis of zero, so a box with flex-1 min-w-0 will squeeze to one word per line rather than let the row wrap. If it should wrap, give it a real min-w-[…]. If it should not shrink, give the siblings shrink-0.
  • No bare fixed widths. w-[210px] belongs behind sm:; on a phone use w-full min-w-0 or flex-1 min-w-0.
  • Touch targets are 44px. .btn, .link-more and .pill get min-height under max-width: 640px in globals.css — use those classes rather than restyling a control from scratch. min-height and not padding, because several call sites override padding with !py-[3px].
  • Hover is not available. Anything revealed on :hover must also be revealed under (hover: none); .row-action already 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: truncate with a title, or break-all. Prose in a <pre> gets break-words, not break-all.
  • html, body { overflow-x: clip } is in globals.css as 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 scrolling

Both 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 StatusDot and Chip for the pattern — and every control has a real label.
  • A control that is the current state stays focusable. Do not disabled it just because it is active; aria-current says that, and a disabled control gives a touch user no feedback at all.
  • Anything that changes without a navigation needs role="status" and aria-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 use useFormStatus (app/features/lang-button.tsx).

Full rules: CONTRIBUTING.md.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.