UI/UX Consultation Guide
A style-neutral, interview-first UI/UX skill that listens to your product and brand before helping you define a design system, review an interface, or emit design rules.
No network calls, credential access, or hidden data exfiltration; side effects are limited to reading project files, writing design-spec.md to the project root, generating /tmp HTML previews, and invoking the open command. Data flow is transparent and files are easily removable for rollback. Deducted for: file writes and the open system command lack explicit confirmation gates; least-privilege declaration incomplete.
SKILL.md and references are highly self-consistent (Phase 0-5 flow, five-stage triage, contract files cross-reference correctly), with default behavior for ambiguous input and 12 behavioral assertions in evals. covering abnormal paths (overtrigger, user insistence). Deducted for: static review cannot execute; README claims 8 eval cases while evals. contains 12 (doc drift); evals are behavioral assertions only, not runnable automated tests; failure-feedback quality unverified.
Trigger and non-trigger conditions are explicitly defined in the description (narrow questions bypass consultation), three modes are clearly bounded, Chinese is explicitly supported (eval 9 tests CJK fonts and Chinese business mockups), and core function has no dependency on overseas services. Deducted for: the preview template loads fonts from Google Fonts CDN, which may be slow/blocked from mainland China; actual trigger precision rests on assertions without execution evidence.
Good layered documentation (SKILL.md → references progressive disclosure), install instructions, Apache-2.0 license, cross-tool bridging, and disclosed known limitations (Phase 4b skip scenarios). Deducted for: no version numbers or changelog, README/evals. case-count mismatch, no explicit maintenance ownership or update path.
Value proposition is clear: structured interview producing a project-specific design-spec.md, with tangible marginal value over manual work (mandatory code scan, five-stage triage, business-mockup gating). Deducted for: static review cannot verify output quality; the final artifact depends on model behavior rather than deterministic scripts; design-spec.md still needs substantial user review; no representative verified outputs.
Auditable primary material exists: full references system, 12 behavioral assertions, the business-mockup contract. Deducted for: no third-party execution evidence, no CI test workflow, assertions not independently reproducible, and the correlation between authored behavioral claims and real model behavior is unproven.
- This is a static source review; no tests were executed and the behavioral assertions in evals. are unverified in practice.
- The preview template references the Google Fonts CDN, which may fail to load from mainland China networks, though core function is unaffected.
- The skill writes design-spec.md to the project root and invokes the system open command; be aware of these side effects before use.
- README and evals. disagree on eval case count (8 vs 12), indicating documentation drift; no version numbers or changelog exist.
- The final design-spec.md is model-generated and should be human-reviewed before adoption as a team standard.
What does this skill do, and when should you use it?
This is a UI/UX consultation skill for coding agents, designed as a "patient interviewer" rather than an assistant with a fixed aesthetic. It strictly separates rules into two layers: 10 style-independent UX Hard Rules and 8 project-chosen style families, so no single taste is imposed as a global standard. It runs three modes: design (default, produces design-spec.md through dialogue), review (a P0/P1/P2 fix list), and guide (do/don't rules for a surface type). Before asking anything, it silently scans your project code for existing tokens and UI frameworks. The repo ships 8 eval test cases and an extensive set of reference documents.
In design mode, it first reads tailwind.config / theme.ts / globals.css / package. and sample UI files, classifies the project into one of five stages (blank, half-built, mature, complex legacy, uncertain), then branches accordingly. It interviews the user about product, brand references and constraints, and offers 2–3 unstarred options per token — color, typography, radius, spacing, shadow, motion, plus four extended dimensions (container strategy, icon system, decoration, locale). A config-driven HTML preview template renders candidates across 5 surface types (dashboard / marketing / content / form / pricing) with Compare mode, Full mode, dark-mode and viewport switching. After the user signs off on a business-specific mockup, it writes design-spec.md to the project root. Review mode uses HCI laws, cognitive bias and design psychology references to output a P0/P1/P2 findings list with fixes and a verification checklist. Guide mode outputs bullet-only do/don't rules. Narrow one-off questions never trigger the full consultation flow.
- A developer starting a new project who wants to settle project-specific colors, fonts, radius, spacing, shadows and motion through dialogue, producing a design-spec.md as the shared source of truth
- An engineer who inherited a half-built project with scattered tokens and inconsistent components (e.g. radius values of 4/8/16 mixed) and wants existing decisions organized before filling gaps
- A team maintaining a web admin dashboard that wants a prioritized P0/P1/P2 review of the existing UI with actionable fixes and acceptance checkpoints
- A developer who needs quick do/don't UX rules for a specific surface type such as long B2B forms, dashboards or settings pages
- A team with strong existing brand assets (logo, brand book) that wants all tokens derived from the brand rather than from a fashionable style family
- Developers using Codex / Claude Code / Cursor / Windsurf together who want design instructions shared across tools via AGENTS.md
What are this skill's strengths and limitations?
- Clear two-layer rule design: 10 cross-style UX Hard Rules kept separate from 8 opt-in style families, avoiding any single aesthetic becoming a global standard
- Interview-first interaction: silently scans code before speaking, presents equal unstarred options, and leaves decisions to the user
- Ships a config-driven HTML preview template with multi-candidate comparison, dark mode and desktop/tablet/mobile switching
- Strong cross-tool support via AGENTS.md / CLAUDE.md / Cursor rules bridging and one-command skills CLI installation
- Thorough reference corpus (interview flow, style families, HCI laws, design psychology, review template, per-surface checklists) plus 8 eval test cases
- The design flow is long (Phases 0–5, multiple dialogue turns) — a poor fit if you want a quick single answer; it deliberately refuses to run the full flow for lightweight questions
- Style-neutral means it won't decide for you — it gives no starred recommendation unless you explicitly ask
- evals. contains only 8 test cases; there is no published evidence of real-world usage or user validation in the README
- Outputs are Markdown specs and static HTML previews; it does not modify project code or generate component implementations
- The preview template requires manually refreshing a browser; there is no automated screenshot or comparison report
How do you install this skill?
Option 1 — install via the skills CLI to multiple agents:
npx skills add oil-oil/ui-ux-guide --list
npx skills add oil-oil/ui-ux-guide -a codex -a claude-code -a cursor -a windsurf
Add -g for a global install. Option 2 — manual clone:
git clone https://github.com/oil-oil/ui-ux-guide ~/.codex/skills/oiloil-ui-ux-guide
The skill body lives at skills/oiloil-ui-ux-guide/SKILL.md; the repo uses AGENTS.md as the shared cross-tool entry, bridged from CLAUDE.md and .cursor/rules/*.mdc.
How do you use this skill?
Trigger it two ways: name it explicitly ("Please use $oiloil-ui-ux-guide to help define this project's design spec") or just describe the task ("define colors and fonts for this project" / "review this dashboard" / "give me UX rules for form pages"). Without an explicit mode it defaults to design; review and guide must be requested explicitly. The README provides recommended prompt templates for all three modes, where you can state context, requirements and constraints (e.g. "scan existing design tokens before asking me questions", "don't judge us by a style family we haven't chosen").