UX Optimization Skill

Languages: English | 简体中文 | 繁體中文

ux-optimization is a production-minded Codex Skill for improving user experience, visual quality, accessibility, interface states, forms, dashboards, and mobile/web interfaces without breaking existing product behavior.

It is built for coding agents that need more than generic design advice: the Skill turns UX work into evidence-backed, implementation-ready decisions with explicit risk, recovery, verification, and visual-quality gates.

Why This Exists

Most UX prompts are good at saying “make it better” and weak at protecting working software. This Skill focuses on the hard parts of real product work:

• preserve current behavior unless the user asks to change it;
• tie every UX recommendation to an implementable code or interaction change;
• handle loading, empty, error, disabled, validation, recovery, keyboard, and responsive states;
• separate static inspection from runtime proof;
• prevent generic “AI-looking” polish from overriding task completion, trust, accessibility, or evidence.

What It Covers

• Modes: quick, full, delta, and verify-only.
• Visual depth: off, standard, and deep.
• Intents: audit, critique, polish, redesign, clarify, layout, form, onboard, harden, adapt, taste, repair, verify, and init.
• Scenarios: Universal plus 12 scenario checklists covering landing pages, e-commerce product pages, dashboards, admin systems, data tables, forms, onboarding, mobile screens, error states, empty states, settings, and checkout flows.
• Evidence labels: AUTOMATED_PASS, RUNTIME_PASS, STATIC_ONLY, UNVERIFIED, and BLOCKED.
• Risk levels: L1/L2/L3 recovery-point guidance for low, medium, and high-risk edits.

Quick Start

Use the Skill by explicitly naming the mode and intent when you want deterministic behavior:

Use $ux-optimization audit full to review this dashboard. Do not modify files.

Use $ux-optimization quick to fix this form validation state. Output: Problem -> Change -> Verification.

Use $ux-optimization redesign full deep to improve this existing UI. Preserve current behavior, data flow, and framework. Do not rewrite the app architecture. Verify rendered states where possible.

For verify-only checks:

Use $ux-optimization verify verify-only to inspect the changes without modifying files.

Repository Layout

SKILL.md                         # Self-contained core Skill instructions
agents/openai.yaml               # Agent-facing metadata
references/                      # Deep references loaded selectively
examples/                        # Audit examples and before/after code examples
scripts/                         # Standard-library validation and context estimators
tests/                           # Structural, routing, budget, and behavior fixtures
companion-skills/
  ux-visual-directions/          # Optional deep visual direction Skill
  ux-visual-review/              # Optional rendered visual review Skill

Validation

The main validation scripts use Python standard library only.

python scripts/validate_skill.py
python scripts/estimate_context.py audit full
python scripts/estimate_context.py redesign full deep
python scripts/estimate_context.py polish full standard
python scripts/estimate_context.py repair delta
python scripts/estimate_context.py verify verify-only
python scripts/estimate_context.py audit quick

Expected result:

• validate_skill.py reports VALID;
• every estimate_context.py route reports WITHIN_BUDGET;
• SKILL.md remains within the configured line and word limits;
• ux-core.md remains a deep reference rather than a duplicate of the inline core.

Installation Notes

This repository is the source suite for the Skill, not an application package.

For a local Codex-style runtime, place the main Skill files in a skill directory named ux-optimization. If you use the optional visual workflow, install the two companion skills as sibling skill folders named ux-visual-directions and ux-visual-review.

Before replacing an installed runtime copy, create a timestamped backup and verify the copied files. Do not install repository-only maintenance files such as AGENTS.md unless your runtime explicitly expects them.

Design Principles

The inline core in SKILL.md is the primary authority. Deep references extend it; they do not replace it.

The most important rules are:

• safety, accessibility, privacy, trust, and task completion outrank visual novelty;
• evidence outranks convention and personal taste;
• high-risk actions require confirmation and recovery paths;
• form and network failures must preserve user input and context;
• static source inspection is never runtime proof.

Examples

The examples/ directory includes both audit-style examples and runnable before/after code examples for:

• form validation that preserves input and exposes field-level errors;
• loading, error, retry, and empty states around fetch flows;
• semantic controls, tabs, roving tabindex, and Arrow-key navigation.

Project Status

Current status: v2.4 candidate / public beta.

The Skill has passed its structural validator and context-budget routes in the local source suite. It is ready for real-project trial use, especially through quick, audit full, and redesign full deep workflows.

Contributing And Security

• Contribution guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• GitHub Actions validation: .github/workflows/validate.yml

GitHub Publishing Assets

• Repository description, topics, and social-preview upload notes: .github/REPOSITORY_SETTINGS.md
• Launch posts and directory copy: .github/PROMOTION_COPY.md
• Social preview image: assets/social-preview.png
• Editable social-preview source: assets/social-preview.svg

License

Licensed under the Apache License 2.0.