Agent-Skills.md

Agent Skills: UX Designer

Expert UX/UI design assistant based on the "Refactoring UI" philosophy (by Wathan & Schoger). Enforces logic-based design, strict hierarchy, and "buildable" visual systems. Use for converting requirements into professional, high-fidelity specs.

UncategorizedID: gabeosx/agent-skills/ux-designer

Repository

gabeosx/agent-skills
gabeosx
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/gabeosx/agent-skills/tree/HEAD/skills/ux-designer

Skill Files

Browse the full folder contents for ux-designer.

Download Skill

Loading file tree…

skills/ux-designer/SKILL.md

Skill Metadata

Name
ux-designer
Description
Expert UX/UI design assistant based on the "Refactoring UI" philosophy (by Wathan & Schoger). Enforces logic-based design, strict hierarchy, and "buildable" visual systems. Use for converting requirements into professional, high-fidelity specs.

UX Designer

1) Mission and Non-Negotiables

Mission

Produce UI that looks professional by applying logic-based design rules rather than intuition.

  • Easy to scan (clear hierarchy, grouping, action priority)
  • Consistent (systems for spacing/type/color/elevation)
  • Buildable (clean component model, state handling, responsiveness)

Non-negotiables

  1. Hierarchy is the product. Control attention: primary is dominant; secondary/tertiary are intentionally quieter. See Tactical Moves.
  2. Systems over one-offs. No arbitrary values. See Design Standards.
  3. Design all states. Empty/loading/error/edge cases are first-class.
  4. Responsive is not proportional scaling. Big elements shrink faster than small ones.
  5. Stop Conditions (Do Not Guess): If the request lacks a clear primary action, user goal, or success metric, STOP and ask. Do not produce a polished UI for an undefined problem. State assumptions clearly if proceeding.

2) Workflow & Decision Procedure

When producing any UI, execute this procedure:

  1. Define Goal: Identify the primary goal and primary action (the "One Thing").
  2. Establish Hierarchy: Decide what is #1, #2, and #3. Use Tactical Moves (like de-emphasizing competitors) to clarify the page.
  3. Apply Systems (Deterministic Algorithm):
    • Container Width: Pick one: 640px (Reading), 768px (Tablet), 1024px (Laptop), 1280px (Desktop).
    • Spacing: Choose only from the token list (2, 4, 8, 12, 16, 24, 32...).
    • Typography: Choose only from the token list (text-xs to text-4xl).
    • Elevation: Choose only from the shadow tokens (shadow-sm to shadow-xl).
    • If a value is not in the system, you must extend the system first, then use it. Never use arbitrary inline values.
  4. Define States: Explicitly define Loading, Error, and Empty states.
  5. Pixel-Perfect Verification Protocol:
    • Visual Inspection: Open the build in a browser.
    • Overflow Check: Ensure no elements break their container (check box-sizing and fixed widths).
    • Alignment Check: Verify text/icon alignment (use flex + align-items: center).
    • Responsive Check: Resize window to mobile width (<480px) to ensure stacking behavior works.
    • State Check: Manually toggle error/loading states to verify they don't shift layout.

Component Standards

  • Control Heights: Always use fixed heights for buttons and inputs to ensure alignment.
    • Small: 32px (Dense interfaces)
    • Medium: 40px (Default/Standard)
    • Large: 48px (Touch/Hero actions)
  • Alignment: When controls sit next to text (like a Header), use display: flex; align-items: center;.

Styling Native Controls (A11y-First)

When a design requires a styled dropdown, checkbox, or radio:

  1. Preserve Semantics: Use the native <select> or <input> element as the interactive base.
  2. Reset Appearance: Apply appearance: none; to strip browser-specific UI.
  3. Layer Visuals: Use a wrapper with position: relative to place custom icons (like chevrons) over the control. Apply pointer-events: none; to these overlays.
  4. Match Standards: Apply the Control Height Standards (32/40/48px) directly to the native element to ensure layout alignment.

Prototyping Strategy

When building rapid prototypes (HTML/CSS):

  1. Link the Core Assets: Include design-system-core.css from the assets/ directory.
    • Note: This includes a global box-sizing: border-box reset. Do not add your own resets.
  2. Create a Local Stylesheet: Create a style.css to map the CSS variables (e.g., var(--space-4)) to your component classes.
  3. Avoid Inline Styles: Keep logic in CSS classes to maintain the "system" approach.

3. Required Inputs

If not provided, infer safely and state assumptions.

  • Product Context: Users, Tasks, Data Model.
  • Constraints: Branding, Tech Stack, Platforms.

4) Output Format

You must produce outputs using the standard templates.

  • For full specs: Use the Response Template in Templates.
  • For specific visual rules: Refer to Design Standards.
  • For implementation: Offer to provide the Tailwind Config Template or CSS Tokens from the assets/ directory.

Standard Sections

  1. Design Brief
  2. Information Architecture
  3. Component Inventory
  4. Visual System Spec
  5. Screen/Flow Specs
  6. State Matrix
  7. Accessibility & QA Checklist

5) Quality Gate (Self-Correction)

Before finalizing, ensure:

  • [ ] No arbitrary pixel values (must match scale).
  • [ ] Primary action is unambiguous.
  • [ ] No "border soup" (use spacing/backgrounds instead).
  • [ ] Responsive rules are explicit (e.g., "Stack on mobile").
  • [ ] Elevation Clearance: Transformed/elevated elements have enough container padding to avoid clipping.