ui-kit-review
Skill501 starsChanged 18 days agoApache-2.0View on GitHub
Review a diff or pull request for @epam/ai-dial-ui-kit adoption — hand-rolled markup the kit already provides (ErrorText, CaptionText, StateScreen, Notification, LinkButton, Dropdown, Spinner, …), legacy Dial* components, ErrorText/CaptionText a11y wiring, icon stroke, and typography that does not come from the kit dial-*-text scale (raw Tailwind sizes, font CSS, unknown classes). Use when reviewing an MR/PR or local changes for UI kit usage, or as the UI-kit pass of code-review-and-quality.
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/a11y.mdcCursor rule
- nx-generateSkill
- nx-importSkill
- nx-pluginsSkill
- nx-run-tasksSkill
- nx-workspaceSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- address-current-branch-reviewSkill
- api-designSkill
- celebration-scene-ideasSkill
- code-review-and-qualitySkill
- create-ticketSkill
- dep-scanSkill
- dep-triageSkill
- dial-docsSkill
- extract-to-libSkill
- figmaSkill
- fix-cve-backportSkill
- git-shipSkill
- i18n-stringsSkill
- lean-verificationSkill
- lib-themingSkill
- monitor-ciSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- proactive-security-monitorSkill
- refactoring-auditSkill
- chat-release-notesSkill
- responsive-designSkill
- security-monitor-triagerSkill
- snyk-jira-ingestSkill
- snyk-scan-stubSkill
- snyk-triageSkill
- nx-generateSkill
- nx-pluginsSkill
- nx-run-tasksSkill
- nx-workspaceSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- nx-generateSkill
- nx-importSkill
- nx-pluginsSkill
- nx-run-tasksSkill
- nx-workspaceSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 27
Collect candidates: Run the scanner over the added lines:
- Very specific: line 37
Pin the kit version: Read @epam/ai-dial-ui-kit in the root package.json, and skim the matching section of …
- Very specific: line 46
Verify every candidate: Read the surrounding code, then confirm the replacement with the ai-dial-ui-kit MCP tools (getEntityDetails, …
- Very specific: line 78
Every font size, weight, line height and letter spacing comes from a kit dial-*-text class — in JSX, in a lib's *ClassName default, and in …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.
Files
UI kit review
Find the places in a change where code re-implements something
@epam/ai-dial-ui-kit already ships, or uses the kit in a way the installed
version no longer supports. Report verified findings only — a regex hit is a
candidate, not a finding.
Inputs
| Mode | Diff source |
| Local | uncommitted changes (git diff HEAD) — the default |
| Branch | the branch against its base, --base origin/development |
| Pull request | only when the user gives a PR number or URL — --pr <n> (uses the gh CLI) |
| Whole repo | an audit of all code, not a change — --all (every tracked line at HEAD; commit or stash first, uncommitted edits are not seen) |
Review comments on GitHub are written in English, and are posted only when the user explicitly asks; otherwise the report goes to the chat.
Workflow
Collect candidates. Run the scanner over the added lines:
node .claude/skills/ui-kit-review/scan-diff.mjs [--base <ref> | --pr <n> | --all]It groups hits by signal (table below) and flags any
dial-*-textclass that the installed kit CSS does not define. It only reads added lines inapps/*/srcandlibs/*/src; it never decides anything.- Pin the kit version. Read
@epam/ai-dial-ui-kitin the rootpackage.json, and skim the matching section ofnode_modules/@epam/ai-dial-ui-kit/dist/CHANGELOG.mdfor behaviour the diff relies on (a dev versionx.y.z-dev.Nmaps to releasex.y.z). Theai-dial-ui-kitMCP server readsdist/components-manifest.jsononce, when it starts: after a kit bump in the same session, reconnect it (/mcp) before trusting a "not found" — a stale process still answers for the old version. - Verify every candidate. Read the surrounding code, then confirm the
replacement with the
ai-dial-ui-kitMCP tools (getEntityDetails,searchEntity) — never grep the kit. A replacement counts only when the kit component keeps the behaviour, the theming hooks and the a11y semantics of the hand-rolled code. If it cannot, it is a kit gap, not a finding. - Report with the format below.
Signals and what to check
| Signal | Usually means | Before flagging, check |
error-text-markup | dial-tiny-text text-error span/p → ErrorText | 14px+ screen-level messages (dial-small-text) are not field errors — consider ErrorMessageNotification instead |
caption-text-markup | dial-tiny-text text-secondary → CaptionText | a *ClassName prop default in a lib is API, not markup; CaptionText merges classes, a prop that replaced them changes behaviour |
error-text-wiring | ErrorText/CaptionText has no live-region role since kit 0.16 | field error: id + the control's aria-describedby + aria-invalid (2.0 Input/Textarea/Select do it through their own error/caption/ariaDescribedBy); submit failure: announce={LiveRegionPoliteness.Assertive} (kit 0.16.0-dev.55+) — the scanner skips a tag that carries announce |
live-region | role="alert"/aria-live added | it must be mounted before its text appears; a region rendered together with the message is not read reliably. Check every early-return branch (loading → error must keep the same node) and whether it sits inside an error boundary, which remounts its children. A raw role="status"/"alert" on an HTML element also fails no-restricted-syntax lint |
dropdown-overlay-role | renderOverlay with no overlayRole nearby | the overlay is role="menu" by default; free-form content or menu rows plus a button footer → DropdownOverlayRole.Dialog + overlayAriaLabel; content with its own role (a dialog card, a tree) → None. Pure menu-item overlays are fine |
spinner-name | <Spinner> with no ariaLabel or aria-hidden | it announces English 'Loading'; inside an element that already names the state wrap it in <span aria-hidden>, otherwise pass ariaLabel (lib: from a *Labels prop; app: t()) |
alert-role-assumption | a test queries getByRole('alert') | if it targets an ErrorText, it passes only through a kit mock — the real component has no role |
legacy-dial-component | 1.0 Dial* component | MCP "Use instead"; DialPagination, DialFileName, DialInputPopup and the file-manager package have no 2.0 replacement |
raw-control | raw <button>/<select>/<textarea>/checkbox/radio/<mark> | underline link → LinkButton; styled button → Button/IconButton; deliberately unstyled rows, drop targets and full-row overlays are fine; search matches → Highlight; an on/off aria-pressed chip → ToggleChip |
hand-rolled-popover | document/window pointerdown/keydown listeners | Dropdown with renderOverlay gives positioning, collision, outside press, Escape and focus return; a non-menu panel takes overlayRole (DropdownOverlayRole.Dialog / None); selection-anchored UI cannot use it |
state-screen-layout | centred icon + heading + text + button | StateScreen renders an h1 in a section — only for a whole screen; inside a panel use ErrorMessageNotification or NoDataContent |
notification-markup | sunken rounded box with an alert glyph | Notification / *MessageNotification; warning and error variants default to role="alert" — pass role="status" for state that must not interrupt; a neutral sunken banner → surface={NotificationSurface.Neutral} |
widget-role | custom tabs, tooltip, switch, progress, dialog, menu | the matching kit component, unless the role describes content the kit does not draw |
inline-width-bar | track/fill bar | ProgressBar; a capacity or quota gauge → role={ProgressBarRole.Meter} |
loading-placeholder | animate-spin / animate-pulse | Spinner / Skeleton |
icon-stroke | Tabler icon without stroke={DIAL_KIT_ICON_STROKE} | filled glyphs and 48px+ empty-state art are exempt; multi-line JSX is not scanned, so read the props |
unknown-typography | a dial-*-text class the kit CSS lacks — it renders unstyled | lib-owned public class names (dial-ci-*, …) are not typography; otherwise look the name up with getEntityDetails("typography") |
Typography: the kit scale only
Every font size, weight, line height and letter spacing comes from a kit
dial-*-text class — in JSX, in a lib's *ClassName default, and in every
value an app passes to a lib. Look the name up with
getEntityDetails("typography"); never write one from memory.
| Signal | Flags | Fix / exemption |
custom-typography-class | text-xs…text-9xl, text-[13px], font-semibold/font-bold/…, font-mono/font-serif/font-sans, leading-*, tracking-* in TS/TSX | the matching dial-*-text class — font-mono → dial-code-text, serif formula symbols → dial-*-italic-text; a raw utility carries no line height from the scale. Colour/alignment text-* pass |
custom-typography-style | fontSize / lineHeight / fontWeight / fontFamily / letterSpacing with a value (a *Typography interface field is skipped) | a class; the only exception is the caller-driven CSS-var channel (.claude/rules/libs.md) for surfaces that cannot take a class |
custom-typography-css | font-size, line-height, font-weight, font-family, letter-spacing, font declared in .scss/.css | move it to a class (a monospace block → dial-code-text); only em-relative sizing of a ::before/::after glyph may stay, with a comment saying why |
redefined-kit-typography | a local .dial-*-text { … } rule | delete it — it shadows the kit and drifts on the next upgrade; a missing step is a gap to raise in the kit |
typography-important | !important on a typography property | delete it — it silently beats the class the caller passed |
lead-text-double-case | uppercase, tracking-* or .toUpperCase() next to a *-lead-* class | drop them: *-lead-* classes uppercase and track themselves, and a pre-uppercased string is spelled out by screen readers |
unknown-typography | a dial-*-text the installed kit CSS lacks | see the table above |
Declarations that read var(--…) are skipped by the scanner: they are the
CSS-var channel, which is allowed only when the lib also exposes a
*ClassName prop defaulting to a scale class — check that by hand.
Also look, without a scanner signal, for:
- the same helper or hook copied into several libs — it belongs in
@epam/ai-dial-chat-shared(for exampleuseControlErrorAssociation, which links an error to a control that takes noaria-describedby); - a hardcoded English string passed to a kit prop — apps use
t(), libs expose a prop with an English default; - a code comment that justifies avoiding a kit component with behaviour the
installed kit no longer has (the "CaptionText renders
role="alert"" comment survived the 0.16 change).
Known kit gaps — report as gaps, not as defects
Confirm each still holds in the installed version before repeating it.
Notification's own close button has a fixed English name — pass a lib-ownedCloseButtoninstead ofclosable.MarkdownEditortakes noaria-describedby/aria-invalid— bridge withuseControlErrorAssociationfrom@epam/ai-dial-chat-shared.CalendartakesariaDescribedBysince kit 0.16 — pass it instead of the hook.
Accepted exceptions — do not report
apps/chat/src/pages/NotFound/— the 404 hero numeral is sized above the kit's biggest step (dial-display1-text, 32/48) on purpose. The scanner skips its typography signals (TYPOGRAPHY_EXEMPT_PATHS).apps/chat/src/components/NewConversationComposer/NewConversationComposer.tsx— the welcome greeting (welcomeClassName) isfont-light text-4xl, light 36px/40px by design. Every kitdial-display*-textstep is semibold, so no scale class matches;dial-display1-textmade it bold and 32px. Keep the raw classes until the kit ships a light display step.
Report format
Group verified findings by severity, most severe first:
- Must fix — a11y regressions (an error nobody announces or links), a
dial-*-textclass that does not exist, custom typography outside the kit scale, a legacy component with a drop-in 2.0 replacement. - Should fix — hand-rolled markup with a kit component that preserves behaviour.
- Kit gap — what the kit would need; suggest raising it in the kit repo.
Each finding: path:line, what is hand-rolled or wrong, the kit replacement
(with the props that matter), and anything that changes visually. End with
the candidates you rejected and why, in one line each, so the author can see
they were considered.
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.

