UX Semantics Audit

What it does

When your agent uses it

• The user asks to review
• Frontend codebase for UX quality
• Design problems
• Confusing labels

Example prompts

• “t say the word”
• “. Also use it when a coding agent”
• “is this a good design?”
• “/ux-semantics-audit”

Requirements

• Node.js

Workflow steps

7 steps, taken from the step headings in SKILL.md.

1. 1Scope the audit
2. 2Load the ruleset
3. 3Build a per-view inventory
4. 4Run Tier 1 (mechanical) checks
5. 5Run Tier 2/3 (semantic and judged) checks
6. 6Self-review pass (false-positive sweep)
7. 7Emit the report

What it can do on your machine

Read from SKILL.md and the folder at commit f187f45. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships script files (JavaScript, from the files we listed), which the agent can run.

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

UX Semantics Audit loads about 2.1k tokens when it runs, and up to ~7.8k if it reads all its reference files. Until then it costs about 178 tokens; SKILL.md has 760 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~178

When it runs · the whole SKILL.md, loaded when a task matches

~2.1k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~7.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from rome-os/rome at commit f187f45, republished under its MIT licence (© rome-os). 760 words, ~2,120 tokens.

name

ux-semantics-audit

description

Audit an existing UI/UX design (React/JSX/TSX components, HTML, or generated app code) against a tiered ruleset of verifiable UX principles, and produce structured, evidence-cited findings that a coding agent can act on to fix the design. Use this skill whenever the user asks to review, evaluate, critique, audit, or lint a UI, screen, view, form, dialog, dashboard, or frontend codebase for UX quality, design problems, redundancy, confusing labels, missing states, or accessibility of status indicators — even if they don't say the word "audit". Also use it when a coding agent's generated UI needs a quality check before shipping, or when the user asks "is this a good design?" about code.

# UX Audit: <scope>

## Summary
<2-4 sentences: overall assessment, count of block/warn findings, the single highest-leverage fix.>

## Findings

### [BLOCK|WARN] <rule-id>: <one-line title>
- **View**: <view/component name>
- **Evidence**: `<file>:<lines>`
  ```<lang>
  <minimal quoted snippet>

Order findings: all `block` first, then `warn`, each group ordered by leverage (user impact × fix cheapness). If there are zero findings, say so plainly and fill in "Passes worth keeping" — a clean audit is a valid result, not a failure to try hard enough.

### Step 8 — Build the shareable report (Rome surfaces)

When the audit covers a Rome surface and the user wants something to look at, share, or triage — rather than findings in chat — build it with the report app in **`report/`**, beside this file. Do not hand-author an HTML page: the chrome, filtering, triage and prompt export already exist and are the same every time.

The whole job is two files:

1. **`findings.tsx`** — rewrite it against the `AuditReport` type in `types.ts`. Prose fields take Markdown inline syntax (`` `code` ``, `**bold**`), because the same strings render on the page *and* serialize into the hand-off prompt.
2. **`repros.tsx`** — one component per finding, built from real `@rome-os/ui` primitives.

Then `node .claude/skills/ux-semantics-audit/report/build.mjs` emits a single self-contained `dist-report/index.html`.

Read **`references/report-app.md`** before writing either file — it carries the authoring contract and the rules that keep reproductions honest.

## Interaction with the consuming coding agent

The report is designed to be handed to a coding agent as-is. Findings are independent work items: each contains everything needed to fix it (location, evidence, fix). Do not bundle multiple rule violations into one finding. If two findings share a root cause (e.g., a missing design-token discipline causes both an emphasis-budget and a color-not-sole-channel violation), note the shared root cause in the Summary rather than merging the findings.

## What this skill does NOT do

- Aesthetic judgments (spacing taste, color palette beauty, typography pairing) — out of scope.
- Full WCAG conformance — only color-not-sole-channel (1.4.1) is in the ruleset; recommend axe-core for the rest.
- Information architecture / navigation-model critique — the rules operate at view level, not sitemap level.
- Rewriting the UI itself — emit findings; the consuming agent makes the changes.

© rome-os, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 26 other files (references) in .claude/skills/ux-semantics-audit of rome-os/rome.

• SKILL.md
• references/report-app.md
• references/rules.md
• report/.gitignore
• report/Report.tsx
• report/build.mjs
• report/findings.example.tsx
• report/fonts.css
• report/fonts/LICENSE
• report/fonts/funnel-sans-latin-400-normal.woff2
• report/fonts/funnel-sans-latin-500-normal.woff2
• report/fonts/funnel-sans-latin-600-normal.woff2
• report/fonts/ibm-plex-mono-latin-400-normal.woff2
• report/fonts/ibm-plex-mono-latin-500-normal.woff2
• report/fonts/petrona-latin-500-normal.woff2
• report/fonts/petrona-latin-600-normal.woff2
• report/index.html
• report/main.tsx
• … and 9 more

Open the folder on GitHubat commit f187f45