agentleFS
gpustackgpustack/gpustack-ui/.claude/skills/design-review/SKILL.md

design-review

Skill100 starsChanged 39 days agoApache-2.0View on GitHub

Review a page, drawer, or form in the gpustack-ui (open source) codebase against the product's design principles (semantic color, system feedback, focus/density, accessibility, consistency, destructive actions). Use when the user asks for a design/UX review, a "design 体检", or wants to check a screen against the design system before shipping. Reports ranked findings, not a rewrite.

167 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use team-level, team-audio and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • CoralGameSkill

    team-level

    Orchestrate level design team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester for complete area/level creation.

    Also in 13 projects that use this

  • CoralGameSkill

    team-audio

    Orchestrate audio team: audio-director + sound-designer + technical-artist + gameplay-programmer for full audio pipeline from direction to implementation.

    Also in 14 projects that use this

  • lilangMaxSkill

    asset-spec

    Generate per-asset visual specifications and AI generation prompts from GDDs, level docs, or character profiles. Produces structured spec files and updates the master asset manifest. Run after art bible and GDD/level design are approved, before production begins.

    Also in 11 projects that use this

  • lilangMaxSkill

    create-control-manifest

    After architecture is complete, produces a flat actionable rules sheet for programmers — what you must do, what you must never do, per system and per layer. Extracted from all Accepted ADRs, technical preferences, and engine reference docs. More immediately actionable than ADRs (which explain why).

    Also in 11 projects that use this

  • julianoczkowskiSkill

    brief-to-tasks

    Break a design brief into an ordered checklist of independently buildable tasks using vertical slices. Saves as a markdown checklist. Use when user wants to break down work, create tasks from a brief, plan implementation order, or mentions "tasks" or "breakdown".

    Also in 7 projects that use this

  • +4 more from lilangMax
  • +3 more from CoralGame

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 139 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read the target file(s). If given a module, read index.tsx, its components/, forms/, and the columns hook.

    line 14
  2. Very specific:

    Delete/remove goes through DeleteModal and is visually distinct from the primary action (never the same color/weight as a benign confirm).

    line 67
  3. Distinctive:

    After each review, before finishing, ask: did I rely on a rule, core-ui primitive, or violation class that isn't already in the checks …

    line 88
  4. Very specific:

    If yes, propose a concrete one-line addition to the relevant check (name the component/prop/path, keep it grounded in code that exists — …

    line 90
  5. Distinctive:

    If the user corrects a finding ("that's not a real issue" / "you missed X"), treat that as the highest-value signal: fold the correction …

    line 91
  6. Very specific:

    Keep both copies in sync — this open-source copy and the monorepo copy at .claude/skills/design-review/SKILL.md (repo root).

    line 92

“Common” is measured: kept by at least 6 in 10 of the 139 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

Design Review

Review one screen (a page module, a drawer, a form, or a component) against GPUStack UI's design principles and report concrete, ranked findings. This is a review, not a refactor — do not edit unless the user asks. Point at file:line, say what's wrong, propose the fix.

The principle layer below is adapted from Apple's Human Interface Guidelines (semantic color, always-visible system state, focus, accessibility), narrowed to a data-dense desktop admin web app. Skip HIG's touch/gesture/whitespace-maximalism — it doesn't apply here. What applies is already encoded in the core-ui component conventions; most findings are "a core-ui primitive exists for this and wasn't used."

How to run

  1. Read the target file(s). If given a module, read index.tsx, its components/, forms/, and the columns hook.
  2. Walk each check below against the code.
  3. Report findings ranked most-severe first. For each: file:line, one-sentence problem, the principle it violates, and the concrete fix (name the core-ui component/prop). If a screen is clean, say so — don't invent findings.

Checks

1. Consistency — reuse core-ui, don't hand-roll (highest priority)

Most design defects here are a hand-rolled version of something core-ui already standardizes. Flag any of:

  • Raw display: flex in new code — compose layout with Ant components instead: 1D flex → Flex; inline sequence → Space; page/grid columns → Row/Col. Drive spacing with the theme scale, not scattered px literals.
  • A hand-built drawer instead of FormDrawer (forms) or the drawer primitives; a custom search/bulk bar instead of FilterBar; a bespoke delete confirm instead of DeleteModal; a raw icon glyph instead of IconFont.
  • A hand-rolled list-add UI instead of the schema-matched field (LabelSelector for object / ListInput for string[] / MetadataList for object[] — see CLAUDE.md "Dynamic add-item form fields").

2. Semantic color — pick the tag by MEANING, never a generic antd Tag

Colors carry meaning; different meanings must not share a color, and one meaning must not change color between screens. Flag:

  • Tag from antd used for a status/category. Route to the right of the four core-ui components by what the value means:
    • semantic status with dynamic text (error message, detail) → StatusTag
    • semantic status, fixed enum, no message → StatusDot
    • standalone category label (scope, model name) → ThemeTag
    • annotation trailing another text (name [custom]) → TextAttribute (ref src/pages/api-keys/hooks/use-keys-columns.tsx)
  • Hardcoded hex/rgb for a semantic state instead of StatusColorMap (error/warning/transitioning/success/inactive) or var(--ant-color-*) tokens.
  • colorTextTertiary on resting body text (descriptions, captions): 3.36:1 in light, under AA's 4.5:1 — use colorTextSecondary (7.00 / 7.69). Tertiary stays legal for graphics at the 3:1 bar.
  • A business status value (running, pending) passed straight to StatusTag.status instead of being mapped through StatusMaps (see the "Status display" section of create-crud-page). Ref src/pages/llmodels/components/table-list.tsx.

Token source of truth (look up values here, don't memorize them): StatusColorMap / StatusMaps are defined in src/config/index.ts; spacing/color primitives are the antd theme var(--ant-*) tokens. Never hardcode a value the theme already names.

3. System state & feedback — the user must always know what's happening

  • Async actions (deploy, delete) must show loading state; a submit button that can double-fire needs useSubmitLock.
  • A failed/errored row must surface its message — use StatusTag with message, not a silent color.
  • Table/list loading and empty states present: page lists → NoResult; simple tables → Empty with image={Empty.PRESENTED_IMAGE_SIMPLE}.

4. Focus & information density

  • Drawer/modal open-close uses useBodyScroll. Widen a drawer only when content needs it — flag a wide drawer with sparse content.
  • A form cramming many ungrouped fields — suggest ScrollSpyTabs or sectioning only when the schema genuinely has grouped sections (don't add tabs gratuitously).
  • Long text in a table cell must be single-line via AutoTooltip, not wrapped.
  • An expanded row / detail panel restating a field the parent row already shows (state, counts, name) — an expansion earns its space by adding what the row could not fit, not by repeating it. Count the renderings before accepting one: in the PD group expansion Prefill 0/1 appeared in the parent's replicas column, again in a group summary bar, and again in the role heading — three statements of one fact, in three different visual languages. The summary bar was dropped and the heading reduced to the role label; compare src/pages/llmodels/components/pd/pd-replicas-cell.tsx (which prints the counts) against role-group-header.tsx (which does not).

5. Accessibility (usually the weakest area — look hard here)

  • Icon-only buttons (IconFont / antd icon as the only child) need an accessible label (aria-label / title).
  • Form fields need associated labels (Form.Item label / labeled Input), not a bare placeholder as the only cue.
  • Interactive elements must be real buttons/links (keyboard-focusable), not onClick on a div/span.
  • Focus each custom clickable element and diff outline / box-shadow / border-color before vs after: all three unchanged → class B (focusable but invisible), document.activeElement can never reach it → class A (fix with a real element or tabIndex+key handler, not with a ring). Coverage must be 100%. A focus glow does not count — this theme's is 1.13:1.
  • A role from a composite widget (radio / tab / option) without the rest of its pattern — the group container (radiogroup/tablist) with an accessible name, roving tabIndex (active ? 0 : -1), and arrow-key movement — is an incomplete widget: Tab walks every item and arrows do nothing.
  • Drawers/modals must retain focus management and follow their component's dismissal contract. FormDrawer defaults to dismissible={false} (Escape and mask dismissal disabled); DeleteModal also disables them. Do not flag those defaults as defects or enable dismissal globally. When dismissal is explicitly enabled for a surface, verify Escape and mask behavior.

6. Destructive actions

  • Delete/remove goes through DeleteModal and is visually distinct from the primary action (never the same color/weight as a benign confirm).

7. Permissions & i18n

  • Admin-only UI gated with Access / useAccess (ref src/pages/access/index.tsx), not just hidden by absence.
  • Select options needing i18n: label set to the message key with locale: true on the option (ref src/pages/benchmark/config/index.ts). Don't ship raw English strings inline.

Output format

Ranked list, most-severe first:

1. [semantic-color] table-list.tsx:82 — status rendered with antd <Tag color="red">.
   Principle: semantic color / consistency.
   Fix: use StatusTag with status mapped through StatusMaps.error and the state message.

End with a one-line verdict (e.g. "3 findings: 1 color, 2 a11y; layout & feedback are clean").

Self-improvement (evolve this skill as you use it)

After each review, before finishing, ask: did I rely on a rule, core-ui primitive, or violation class that isn't already in the checks above?

  • If yes, propose a concrete one-line addition to the relevant check (name the component/prop/path, keep it grounded in code that exists — verify the symbol before citing it). Show the user the proposed diff and let them approve; do not silently edit the skill.
  • If the user corrects a finding ("that's not a real issue" / "you missed X"), treat that as the highest-value signal: fold the correction into the checks (or drop the false-positive rule) once approved.
  • Keep both copies in sync — this open-source copy and the monorepo copy at .claude/skills/design-review/SKILL.md (repo root). When you add a rule to one, add the path-adjusted equivalent to the other.

Growth comes only through the user's approval — never auto-mutate the skill unreviewed.

Related

  • create-crud-page — the module structure and status-display setup this review checks against.
  • form-patterns — cascading/dependent form fields.
  • dataviz — for screens with charts, review color/legend/axis there instead.

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.