Stop guessing UI components. Choose them from user intent, real constraints, and evidence.
Choose UI is a Claude skill that decides which interaction pattern fits a product flow, explains why, rejects the closest wrong alternative, and names the states and accessibility behavior an implementation needs.
Exact excerpts from two fresh Claude Code runs with the same prompt and model. Read the prompt, run conditions, and unedited outputs.
In the baseline run, Claude recommended preserving a single radio button for future consistency. With Choose UI loaded, Claude instead recognized that one available value is not a choice and recommended readable confirmation text backed by a submitted value.
It starts with a deliberately sharp rule:
If there is only one available option, do not render a dropdown. Apply the value and present it as readable text.
The useful part is everything around that rule: actions are not selections, navigation is not a segmented control, short comparable choices should not be hidden, and a mobile picker is not merely a smaller desktop dropdown.
Illustrative UI mockup—not the output of a live prompt benchmark.
Illustrative UI mockup—not the output of a live prompt benchmark.
AI can produce polished interfaces while choosing the wrong interaction model. Design systems document good components, but product teams still have to decide which component represents the user's actual task.
Choose UI turns that decision into a repeatable workflow:
- Classify intent: input, filter, view switch, action, navigation, or setting.
- Evaluate current and credible option count, value kind, comparison need, frequency, effect timing, platform, and accessibility.
- Inspect the project's component inventory and translate the generic pattern into its real design-system name.
- Choose one pattern, reject the closest mismatch, and include production states.
flowchart LR
A["User intent"] --> B["Real data constraints"]
B --> C["Canonical rule baseline"]
C --> D["Product design-system adapter"]
D --> E["One justified decision"]
E --> F["States and accessibility"]
Prompt Claude:
Use choose-ui to review this checkout form. The shipping-method dropdown
currently has one available option, and the value is submitted with the order.
For a narrow question, the skill stays brief:
Recommendation: static value
Why: One fixed option creates no meaningful user choice.
For implementation, audits, or ambiguous decisions, it returns the full record: confidence, rejected alternative, required states, accessibility, assumptions, and evidence.
Inside Claude Code, add this repository as a marketplace and install the plugin:
/plugin marketplace add ProgWon/choose-ui
/plugin install choose-ui@ui-ux-skills
/reload-plugins
The installed skill is available as /choose-ui:choose-ui, and Claude can also invoke it automatically when the request matches its description. Update it later with:
/plugin marketplace update ui-ux-skills
/plugin update choose-ui@ui-ux-skills
The Claude plugin also recognizes broad product-building requests such as Build a booking service from scratch, even when the user does not name a form, filter, or component. A local, zero-package UserPromptSubmit hook checks only the submitted prompt for product-build phrases and adds a private reminder for Claude to load Choose UI before choosing interactive components. It does not send data anywhere, modify the prompt, block the request, or activate for backend-only and visual-only work. The hook requires python3, which is also used by the optional rule and eval tools in this repository.
The hook is included only in the Claude plugin installation. Agent Skills installations still support Claude's normal description-based automatic invocation, including the expanded end-to-end build triggers, but do not install the plugin hook.
npx skills add progwon/choose-ui@choose-uiCopy .claude/skills/choose-ui into the same path in your project:
cp -R .claude/skills/choose-ui /path/to/your-project/.claude/skills/Claude discovers the skill from its name and description. Invoke choose-ui explicitly when you want a visible decision record.
The optional agents/openai.yaml is bonus metadata for Codex and other Agent Skills clients. Claude ignores it; the Claude skill itself is fully defined by SKILL.md and its bundled resources.
The skill includes a zero-dependency Python rule interpreter for structured prompts, CI checks, and bulk audits:
python3 .claude/skills/choose-ui/scripts/recommend.py \
--intent input \
--options 3 \
--expected-max-options 9 \
--selection single \
--platform mobileUse explicit semantics for a Boolean answer:
python3 .claude/skills/choose-ui/scripts/recommend.py \
--intent setting \
--options 1 \
--value-kind boolean \
--effect submitJSON input and --format json are available for automation. Other decision flags include --frequency, --comparison, --search, --custom-value, and --rich-options.
The interpreter performs ordered table lookup; it does not attempt to replace product judgment. Claude handles research, content complexity, localization, and justified design-system overrides.
selection-rules.json is the canonical ordered rulebook. Both the recommender and the human-readable matrix derive from it.
selection-rules.json
├── scripts/rule_engine.py # generic first-match interpreter
├── references/selection-controls.md # generated human reference
└── scripts/rules_tool.py # schema/source/staleness checks
After changing a rule, regenerate and verify the matrix:
python3 .claude/skills/choose-ui/scripts/rules_tool.py --write
python3 .claude/skills/choose-ui/scripts/rules_tool.py --checkThis prevents the documentation and executable baseline from silently recommending different controls.
- Empty, loading, and one-option states
- Boolean switches and submitted checkboxes
- Buttons, action menus, links, tabs, navigation lists, and searchable navigation palettes
- Radios, radio cards, checkboxes, and comparison groups
- Segmented controls and selection chips
- Selects, text inputs, editable comboboxes, and tokenized multi-select comboboxes
- Mobile view, radio, and checkbox sheets
- Credible option growth rather than fixture-only cardinality
- Existing design-system inventory and SEED component mapping
- Accessibility and required UI states
- Quick answers and full audit records
- Choose behavior before appearance.
- Do not render interaction without agency.
- Keep choices visible when comparison matters.
- Add search only when it reduces retrieval cost.
- Design for credible production data, not fixture data.
- Prefer existing product components and native semantics.
- Explain overrides instead of pretending thresholds are universal laws.
The framework synthesizes guidance from SEED, GOV.UK Design System, Carbon, Apple HIG, WAI-ARIA APG, and WCAG.
The wording and decision framework are original. Sources are paraphrased and linked rather than copied. See sources.md for provenance notes.
Run the public regression suite:
python3 -m unittest discover -s tests -vevals/cases.json covers deterministic boundary decisions. evals/skill-cases.json covers skill activation, non-activation, output discipline, ambiguous judgment, and design-system adaptation in fresh Claude sessions.
Run the six trigger cases against authenticated Claude Code. Every prompt gets a fresh, non-persistent session, and activation is measured from the actual Skill tool call:
python3 evals/run_skill_evals.py --suite triggerRun behavior and output-shape cases as well, or repeat cases to estimate a less noisy rate:
python3 evals/run_skill_evals.py --suite all --repeats 3 --model sonnetAutomatic scoring is language-tolerant for Korean and English field labels and component terms. Judgment items under semantic_checks are printed for human or model-judge review rather than treated as brittle substring assertions. Live model evaluations are intentionally not part of CI because they require Claude authentication, spend budget, and can vary between runs.
The runner verifies its required flags against claude --help before spending model budget. If Claude Code is not installed as a direct executable, pass a command prefix such as --claude "npx -y @anthropic-ai/claude-code@2.1.222". Trigger cases expose Skill plus the non-mutating Read, Grep, and Glob tools so implementation-shaped negative prompts have a realistic alternative to forced skill use. Behavior cases expose only Skill unless a case opts into project inventory inspection. User-enabled plugins are disabled by default so their skill-selection policies cannot contaminate activation rates; use --keep-user-plugins only when intentionally measuring that environment.
Measured on 2026-08-05 with Claude Code 2.1.221, the sonnet model alias, three fresh sessions per case, sequential execution, a 120-second timeout, and user plugins isolated:
| Measure | Result |
|---|---|
| Positive activation | 9/9 (100%) |
| Negative false positives | 0/9 (0%) |
| Trigger-suite automatic checks | 18/18 (100%) |
| Behavior/output automatic checks | 17/18 (94%) |
| Manual semantic checks | 23/24 (96%) |
The complete campaign reported $3.47 in model cost. Its single behavior miss was an underspecified prompt that the model sometimes treated as form input instead of recognizing unknown intent. After the case explicitly stated that intent was unresolved, the targeted regression passed 3/3. A separately strengthened explicit-search regression also passed 3/3 after manual response review. These targeted results are reported separately rather than retroactively presenting the complete run as perfect.
The best contribution is a concrete product situation where the current recommendation is wrong or underspecified. Include user intent, constraints, expected pattern, and a primary source or research finding when possible.
Read CONTRIBUTING.md before opening a pull request. New design-system adapters, platform conventions, evaluation cases, and accessibility corrections are welcome.
- Selection controls — current
- Actions, confirmation, and undo
- Navigation, tabs, disclosure, and hierarchy
- Forms, validation, and progressive disclosure
- Feedback, loading, empty, and error states
- Framework-specific implementation checks
- Source-code and screenshot audit modes