agentleFS
FracteraFractera/web4-node-starter-kit/.claude/skills/use-widgets/SKILL.md

use-widgets

Skill68 starsChanged 2 days agoMITView on GitHub

Widgets — the unique, route-owned pieces a project is recognised by. Load this BEFORE building any screen element that is not a plain content block: a table with its own behaviour, an animated showcase, a calculator-looking panel, anything a designer handed you as finished code. Also load it when the owner says "make it look like this", "here is a section from my other site", "put a widget after the hero", or asks why an animation must not sit on the page itself. Two kinds exist — `_widgets/static/<name>` and `_widgets/dynamic/<name>` — and the folder names them out loud because the two obey different disciplines.

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    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:

    Read security-orbit before writing your own: index.tsx (server, resolves words), static.tsx (the twin), swap.client.tsx (the island), …

    line 130
  2. Distinctive:

    Keep the donor's geometry, drop the donor's palette.

    line 189
  3. Distinctive:

    No browser at hand — say so out loud and record it as a debt.

    line 207
  4. Distinctive:

    Deletion: remove the folder, run the gates, grep the tree.

    line 210

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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

use-widgets

Informational, not binding. Know a better way for the case in front of you — do it your way and say so. You are trusted with the creative work on this project.

A widget is a unit of ownership inside one route. Everything that answers "how does THIS thing look and behave" lives in its folder: markup, skeleton, behaviour, words. Delete the route folder and the widget is gone without a trace — that deletion test is the acceptance, not a metaphor.

What a widget is NOT: a reusable component. Reuse is the opposite of the point. Two widgets that look alike are two widgets, and they are allowed to drift apart tomorrow — that freedom is the whole value.

🔒 Сначала прочитай аналог — до первой строки

Обойди _widgets/ по дереву и назови, что уже построено. Затем открой ближайший по смыслу и прочитай его ЦЕЛИКОМ, а не по диагонали. Только после этого пиши свой.

find app -type d -path "*_widgets/*/*"

Что берётся у аналога:

БерётсяПочему
устройство — какие файлы, что в каком лежитuse-list · toolbar · skeleton · row · pager · ui.i18n — состав проверен работой, свой порядок изобретать не за чем
вид — ритм отступов, шапка таблицы, чередование строк, размеры кнопок и полейстраницы одного продукта обязаны выглядеть роднёй
состояния — закрыт, загрузка, пусто, отказ: какие есть и в каком порядке показываютсяпропущенное состояние обнаруживает владелец, а не гейт

Не берётся: сам файл импортом, поведение выборки, слова, колонки, действия строки.

🔒 ИЗОЛЯЦИЯ — ПРО ФАЙЛЫ, СЕМЕЙНОЕ СХОДСТВО — ПРО ВИД, И ЭТО НЕ ПРОТИВОРЕЧИЕ. Правило «четыре копии таблицы — не дублирование, а изоляция» говорит: не делите код. Оно НЕ говорит: стройте разный вид. Разойтись виджеты обязаны в том, ЧТО делают, а не в том, КАК выглядят.

Оплачено 2026-08-21. Таблица учётных записей была построена с нуля по правилу изоляции: свой ритм отступов, заголовки колонок без приглушения, поиск после раскрытия, до нажатия — голая кнопка вместо скелетона. Каждое решение по отдельности защитимо, вместе — страница из другого сайта. Владелец сказал дословно: «not similar design, copy widget design from another pages». Ни один гейт этого не поймал и поймать не мог: разметка формально верна.

Дешёвая проверка, которая ловит это до владельца: открой свою страницу и соседнюю рядом, в двух вкладках. Разница видна за секунду и не требует замеров.

Two kinds, and the folder says which

<route>/_widgets/static/<name>/    отрисован сразу и целиком   — public layer, first impressions
<route>/_widgets/dynamic/<name>/   просыпается по нажатию      — protected layer, data behind a door

The path shape is enforced by check:protected: a file under _widgets/ that sits outside static/ or dynamic/ fails the build. Nothing else is enforced — folders are not created in advance, because a folder that stands everywhere proves nothing when the deletion test comes.

Specimens in this starter: five dynamic (price-table, manage-table, catalogue-table, shop-table, product-card) and one static (security-orbit, on the homepage).

The boundary rule — the one sentence to keep

Outward goes what answers "how does the project do X at all". Inside stays everything that answers "how does THIS widget look and behave".

Outward: lib/architecture/project-api (the way this project talks to its database), toast, the primitives in components/ui/*, the entity model in lib/<entity>/, tools in _tools/. Inside: layout, columns, empty state, interactions, words — and the skeleton.

The test at the border: move a piece outward — would that force two widgets to be alike in anything? If yes, it stays inside.

🚫 Merging fragments of widgets into a shared library is forbidden (owner's direct word). Four copies of a table are not duplication, they are isolation. It would be duplication only if the tables were the same — and the whole bet is that they are not.

The skeleton is the sharp case. A shared skeleton decides in advance that every table has the same shape: while it is one for four, none of them can look different even while loading. That was caught live — the shared one drew five columns for a table that has three, and the layout jumped when the answer arrived.

Ask first whether an island is needed at all

Tabs, highlighting, reveal-on-select, a lit step — plain CSS does most of this, and then there is no island: the page works without JavaScript fully, not tolerably, and no second copy of the text "for crawlers" is required. The specimen is the section kind problemSolution: the list of cases is a group of radio inputs, and showing the selected one is a :checked rule in styles/globals.css.

Reach for an island only when browser state is unavoidable — a database call, an input, a timer. An island bought for something CSS already does costs the no-JS visitor the whole element.

One page, no repeated section kinds

A section kind appears once per page. The eye recognises a layout before it reads a word, so a second section of the same kind reads as a repeat however different the text. Caught by asking "is this shape already on the page?" before reusing a kind — no gate enforces it.

Movement: the island rule, and why it is about search, not taste

Classic use of a motion library kills SEO. The page goes dynamic, the markup ships with opacity: 0, and the crawler — like anyone with JavaScript off — sees empty space. So:

  1. The server prints stillness. A static twin, fully visible, whose letters carry their own colour. 🔒 opacity: 0 is one mechanism out of many — read "Present in the markup and still unreadable" below before you call the twin honest.
  2. An island holds the twin and swaps in the animated version. 🔒 The event is chosen by the price of the motion, not copied from the specimen. Expensive or decorative — on the first click, or when the pointer enters the area (pointerenter; a finger never fires it, so touch keeps the click). Cheap and part of the meaning — the page's own heading, a word that must be alive for everyone — right after mount, the library still lazy, because asking a person to activate a title means showing it to nobody. Name the chosen event and its reason in the file.
  3. The animated version loads lazily (lazy + Suspense), and the fallback of the swap is the twin itself — so nothing blinks while the chunk flies.
  4. Both versions share one markup file. Geometry must match 1:1 at any width; measure the bounding boxes before and after the swap and demand equality.
  5. prefers-reduced-motion is respected: the swap happens, the movement does not.
  6. Movement is declared with animate and no initial — it starts from the current state, which is what makes the swap invisible.

Read security-orbit before writing your own: index.tsx (server, resolves words), static.tsx (the twin), swap.client.tsx (the island), animated.client.tsx (motion), parts.tsx (the one markup), ui.i18n.ts (its words).

Present in the markup and still unreadable

🔒 The defect is one class, and opacity is only its most famous member: the colour and the visibility of the letters are decided by something around them instead of by themselves. curl finds the text, search indexes it, the gate stays green — and the person without JavaScript is handed a heading in the colour of a caption, or nothing at all.

The ways in, none of them exhaustive:

  • text-transparent / color: transparent with bg-clip-text — the background paints the letters;
  • clip-path, mask-image — the letters are cut out of something else;
  • visibility: hidden, content-visibility, a container of zero height;
  • text living in ::before / ::after, or in an icon font;
  • any initial style of a motion library, not only the transparent one.

🔒 Partial degradation is worse than total. A title that vanishes is noticed in a second. A title whose real colour was transparent, drawn by a second static background layer, simply looks slightly grey — no curl, no gate and no person who has not seen the intended colour will catch it. This is why the no-JS proof measures the computed colour, and why a "the text is in the HTML" answer is not an answer.

🔒 When the component comes from someone else's registry, read the technique, not the manifest. Its dependencies tell you what will be installed; how it paints the content tells you what the reader gets — and only the second one can hand you transparent letters. use-tools carries this as a rule.

Two ways a widget reaches a page

WhereHowExample
Behind authorizationthe route entry (_components/index.tsx) imports it and passes resolved wordsmanage-table
Public homepagethe afterHero slot of createContentPage — full width, right after the first screen, outside the columnsecurity-orbit

Why not a new section kind. The section catalogue is closed and every kind needs a specimen on the architect's page — a public widget would have to be rendered from the protected layer, i.e. the platform would import a route. The slot keeps ownership where it belongs.

Words

Ten languages, the page set (en ru es fr it de pt pl tr nl), in the widget's own ui.i18n.ts, and registered in scripts/check-i18n.mjs in the same commit. Eighty-two is for reusable parts of the product — the account drawer, the cart, dialogs — because those appear in any enabled language by themselves. A widget does not. Enable an eleventh language and the widget answers in English: a deliberate trade, written in the header of every widget dictionary.

Words are resolved on the SERVER and handed to the island as props. A client file that imports the dictionary ships every language to every browser.

Colour: code that arrives from outside must learn the palette

Design handed over as finished code arrives with its own hex values. Translate them to tokens — --primary and its fractions, bg-card, border-border, text-foreground, text-muted-foreground — before anything else. Two reasons, both practical: the owner changes the palette in the panel and the widget must repaint with the site; and check:contrast refuses fractions on text (text-muted-foreground/50), because a fraction reads in one theme out of two.

Keep the donor's geometry, drop the donor's palette. Layout is what was chosen; colour is what the project owns.

🔒 A widget that takes the WHOLE screen inherits a page's duties. The moment it is the page, it owes what a page owes: the markdown twin for machines, an address in the sitemap, a heading hierarchy, and honest behaviour without JavaScript — or an explicit statement that it requires it. ✗ "it is only a widget" is how a full-screen thing ends up invisible to search and to models while looking finished.

Proof

Green types prove nothing here. Four measurements, all cheap:

  1. The route stays ● in the build table. A widget that turns the page ƒ has already failed.
  2. No-JS, and the question is READABILITY, not presence. curl the page: every title of the widget must be in the HTML — and then, with JavaScript switched off in the browser, the computed colour of those letters must equal the theme's text colour and their computed visibility must be normal. 🔒 Grepping the markup for opacity: 0 is NOT this check: bg-clip-text text-transparent carries no opacity at all and still hands the reader a heading painted the colour of a caption. No browser at hand — say so out loud and record it as a debt; do not report the widget proven.
  3. The swap does not jump: bounding boxes of the cards and the centre, before the first click and a second after — identical strings.
  4. Deletion: remove the folder, run the gates, grep the tree. One line in the route entry and one in the i18n registry is the whole footprint; anything else means the widget was smeared.
  5. Foreign design knowledge has the widest room here — a widget owes nobody but its route. use-shadcn names what still holds: one dialog, one toast, colour as a token.

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.