ux-laws-reviewer 1.0.0

package/README.md

@@ -0,0 +1,49 @@
+# ux-laws-reviewer
+
+A Claude Code skill that provides a rigorous framework for evaluating UI code and designs against established psychological principles and UX laws.
+
+## What is this?
+This is an installable skill for [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) (or compatible agents). Once installed, your AI agent will be able to critique front-end code, HTML, CSS, React components, and design mockups using the **Laws of UX** (like Hick's Law, Fitts's Law, Cognitive Load, Gestalt Principles, etc.).
+
+## Installation
+
+You can install this skill directly into your Claude environment using `npx`:
+
+```bash
+npx ux-laws-reviewer
+```
+
+This will automatically copy the necessary `SKILL.md` and reference files into your `~/.claude/skills/ux-laws-reviewer` directory.
+
+## Usage
+
+Once installed, just ask Claude to review your UI!
+
+Examples of prompts that will trigger this skill:
+- *"Review this React component against UX laws."*
+- *"Critique my pricing page design."*
+- *"How is the UX of this form?"*
+- *"Audit this layout for cognitive load."*
+
+Claude will respond with a structured breakdown:
+1. **Summary:** Overall assessment.
+2. **Key UX Findings:** Identification of UX Law applications and violations (e.g., `❌ Hick's Law (Violation)`).
+3. **Actionable Improvements:** Concrete code suggestions to fix the issues.
+
+## Included UX Laws Reference
+The skill includes a comprehensive reference document covering:
+- Aesthetic-Usability Effect
+- Choice Overload
+- Chunking
+- Cognitive Bias & Cognitive Load
+- Doherty Threshold
+- Fitts's Law
+- Flow & Goal-Gradient Effect
+- Hick's Law & Jakob's Law
+- Gestalt Principles (Proximity, Common Region, etc.)
+- Miller's Law, Occam's Razor, Pareto Principle
+- Peak-End Rule, Postel's Law
+- Von Restorff Effect, Zeigarnik Effect, and more.
+
+## License
+ISC

package/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ux-laws-reviewer
+description: Use this skill whenever the user asks you to review, critique, audit, or improve a UI, frontend component, layout, or design mockup. Also trigger if they ask about UX best practices, user experience, cognitive load, or if a design is user-friendly. This skill provides a rigorous framework for evaluating UI code/designs against established psychological principles and UX laws.
+---
+
+# UX Laws Reviewer
+
+You are an expert UX/UI designer and frontend engineer. When invoked, your job is to review the user's provided UI code, component, or design description through the lens of established psychological principles of UX design.
+
+## Review Framework
+
+When critiquing a UI, follow this process:
+
+### 1. Read the Reference (If Needed)
+If you are not already deeply familiar with the Laws of UX, immediately read `references/laws.md` located in this skill's directory. This file contains the definitions and takeaways for heuristics like Hick's Law, Fitts's Law, Jakob's Law, Cognitive Load, and various Gestalt principles.
+
+### 2. Analyze the UI
+Examine the user's provided code (HTML/CSS, React, Vue, etc.) or design description. Understand its primary goal, the user flow, and the visual hierarchy.
+
+### 3. Identify UX Law Applications & Violations
+Evaluate the design against the Laws of UX. Specifically look for:
+- **Violations:** Areas where the design creates unnecessary friction, cognitive load, or violates user expectations.
+- **Good Applications:** Areas where the design successfully leverages psychology (e.g., good chunking, clear visual hierarchy, progressive disclosure).
+
+### 4. Provide Concrete Recommendations
+Do not just point out theoretical flaws. You must provide specific, actionable recommendations on how to fix them in the code or design.
+
+## Output Structure
+
+Format your response to the user using the following structure:
+
+### Summary
+A brief 1-2 sentence assessment of the overall user experience and primary areas for improvement.
+
+### Key UX Findings
+Use bullet points. For each finding, explicitly name the relevant UX Law in bold, explain how it applies to the specific UI element, and state whether it's a violation or a positive application.
+
+**Example:**
+* **❌ Hick's Law (Violation):** The main navigation contains 15 equally weighted links. This choice overload will increase decision time. Consider grouping these into 3-4 primary categories with a dropdown menu.
+* **✅ Fitts's Law (Positive):** The primary "Checkout" button is large and placed prominently at the bottom of the screen, making it easily accessible for mobile users.
+* **❌ Law of Proximity (Violation):** The form labels are spaced equally between the input field above them and the input field below them, making it difficult to scan which label belongs to which field.
+
+### Actionable Improvements / Code Suggestions
+Provide the exact code changes or structural design changes needed to resolve the violations. If the user provided code, output the refactored code blocks showing the improvements. Explain *why* the code change improves the UX.
+
+## Guidelines for Success
+- **Be direct and specific:** Instead of saying "improve the layout," say "group the billing and shipping address fields into distinct visual cards (Law of Common Region)."
+- **Prioritize impact:** Focus on the 2-3 most critical UX issues that will have the biggest impact on usability. (Remember the **Pareto Principle**).
+- **Consider the platform:** Apply Fitts's Law differently for mobile (touch targets) vs. desktop (mouse cursor).
+- **Accessibility is UX:** Remember that laws like the Von Restorff effect require that you don't rely solely on color to isolate elements (consider users with color vision deficiency).

package/install.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const skillName = 'ux-laws-reviewer';
+const claudeSkillsDir = path.join(os.homedir(), '.claude', 'skills', skillName);
+const agentsSkillsDir = path.join(os.homedir(), '.agents', 'skills', skillName);
+
+// Determine which directory exists, prefer .claude
+let targetDir = claudeSkillsDir;
+if (!fs.existsSync(path.join(os.homedir(), '.claude')) && fs.existsSync(path.join(os.homedir(), '.agents'))) {
+    targetDir = agentsSkillsDir;
+}
+
+console.log(`Installing ${skillName} skill...`);
+
+// Ensure target directory exists
+fs.mkdirSync(path.join(targetDir, 'references'), { recursive: true });
+
+// Copy files
+const sourceDir = __dirname;
+fs.copyFileSync(path.join(sourceDir, 'SKILL.md'), path.join(targetDir, 'SKILL.md'));
+fs.copyFileSync(path.join(sourceDir, 'references', 'laws.md'), path.join(targetDir, 'references', 'laws.md'));
+
+console.log(`\n✅ Skill successfully installed to: ${targetDir}`);
+console.log(`\nYou can now use this skill in Claude by asking it to "review my UI against UX laws" or "critique this design".`);

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "ux-laws-reviewer",
+  "version": "1.0.0",
+  "description": "A Claude Code skill for reviewing UIs against UX Laws",
+  "bin": {
+    "install-ux-laws-reviewer": "install.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs"
+}

package/references/laws.md

@@ -0,0 +1,170 @@
+# Laws of UX Reference
+
+## Aesthetic-Usability Effect
+Users often perceive aesthetically pleasing design as design that’s more usable.
+* **Takeaways:**
+  * An aesthetically pleasing design creates a positive response in people’s brains and leads them to believe the design actually works better.
+  * People are more tolerant of minor usability issues when the design of a product or service is aesthetically pleasing.
+  * Visually pleasing design can mask usability problems and prevent issues from being discovered during usability testing.
+
+## Choice Overload (Paradox of Choice)
+The tendency for people to get overwhelmed when they are presented with a large number of options.
+* **Takeaways:**
+  * Too many options hurts users’ decision-making ability.
+  * Enable side-by-side comparison of related items and options that require a decision.
+  * Optimize for the decision-making process: avoid overwhelming users by prioritizing content, and provide tools for narrowing down choices (search, filtering).
+
+## Chunking
+A process by which individual pieces of an information set are broken down and then grouped together in a meaningful whole.
+* **Takeaways:**
+  * Enables users to easily scan content and identify relevant information.
+  * Structure content into visually distinct groups with a clear hierarchy.
+  * Group content into distinctive modules and apply rules to separate content.
+
+## Cognitive Bias
+A systematic error of thinking or rationality in judgment that influences our perception and decision-making ability.
+* **Takeaways:**
+  * We conserve mental energy by developing rules of thumb based on past experiences.
+  * Understand intrinsic biases to serve as a safeguard against fallacious reasoning or costly mistakes.
+
+## Cognitive Load
+The amount of mental resources needed to understand and interact with an interface.
+* **Takeaways:**
+  * Intrinsic cognitive load: effort required to absorb new information and keep track of goals.
+  * Extraneous cognitive load: mental processing that takes up resources but doesn't help understand content (e.g., distracting elements).
+  * Reduce extraneous load to prevent users from feeling overwhelmed.
+
+## Doherty Threshold
+Productivity soars when a computer and its users interact at a pace (<400ms) that ensures that neither has to wait on the other.
+* **Takeaways:**
+  * Provide system feedback within 400 ms.
+  * Use perceived performance (e.g., animations) to reduce the perception of waiting.
+  * Progress bars help make wait times tolerable.
+
+## Fitts’s Law
+The time to acquire a target is a function of the distance to and size of the target.
+* **Takeaways:**
+  * Touch targets should be large enough for users to accurately select them.
+  * Provide ample spacing between touch targets.
+  * Place touch targets in areas that allow them to be easily acquired.
+
+## Flow
+The mental state in which a person is fully immersed in a feeling of energized focus and enjoyment.
+* **Takeaways:**
+  * Requires a balance between the difficulty of a task and the user's skill level.
+  * Provide necessary feedback so users know what action has been done.
+  * Optimize for efficiency by removing unnecessary friction.
+
+## Goal-Gradient Effect
+The tendency to approach a goal increases with proximity to the goal.
+* **Takeaways:**
+  * The closer users are to completing a task, the faster they work towards reaching it.
+  * Provide artificial progress towards a goal to motivate completion.
+  * Provide a clear indication of progress.
+
+## Hick’s Law
+The time it takes to make a decision increases with the number and complexity of choices.
+* **Takeaways:**
+  * Minimize choices when response times are critical.
+  * Break complex tasks into smaller steps.
+  * Highlight recommended options to avoid overwhelming users.
+  * Use progressive onboarding.
+
+## Jakob’s Law
+Users spend most of their time on other sites, meaning they prefer your site to work the same way as all the other sites they already know.
+* **Takeaways:**
+  * Leverage existing mental models so users can focus on tasks rather than learning new models.
+  * When making changes, empower users to continue using a familiar version for a limited time.
+
+## Gestalt Principles of Grouping
+* **Law of Common Region:** Elements are perceived into groups if they share an area with a clearly defined boundary (e.g., borders, backgrounds).
+* **Law of Proximity:** Objects near each other tend to be grouped together. Establish relationships and similar functionality through spacing.
+* **Law of Prägnanz:** People perceive complex images in the simplest form possible because it requires the least cognitive effort.
+* **Law of Similarity:** Visually similar elements (color, shape, size) are perceived as related.
+* **Law of Uniform Connectedness:** Elements visually connected (via lines, colors, frames) are perceived as more related than elements with no connection.
+
+## Mental Model
+A compressed model based on what we think we know about a system and how it works.
+* **Takeaways:**
+  * Match designs to users’ mental models to improve their experience.
+  * Use consistent patterns and conventions (e.g., shopping carts in e-commerce).
+
+## Miller’s Law
+The average person can only keep 7 (plus or minus 2) items in their working memory.
+* **Takeaways:**
+  * Organize content into smaller chunks to help users process and memorize.
+  * Don't rigidly stick to "exactly 7" as an excuse for bad design.
+
+## Occam’s Razor
+Among competing hypotheses, the one with the fewest assumptions should be selected.
+* **Takeaways:**
+  * The best method for reducing complexity is to avoid it.
+  * Remove elements without compromising overall function.
+
+## Paradox of the Active User
+Users never read manuals but start using the software immediately.
+* **Takeaways:**
+  * Make guidance accessible throughout the product experience.
+  * Design guidance to fit within the context of use (e.g., contextual tooltips).
+
+## Pareto Principle (80/20 Rule)
+Roughly 80% of the effects come from 20% of the causes.
+* **Takeaways:**
+  * Focus the majority of effort on the areas that will bring the largest benefits to the most users.
+
+## Parkinson’s Law
+Any task will inflate until all of the available time is spent.
+* **Takeaways:**
+  * Limit the time it takes to complete a task.
+  * Leverage features like autofill to save user time and prevent task inflation.
+
+## Peak-End Rule
+People judge an experience based on how they felt at its peak and its end, rather than the total sum.
+* **Takeaways:**
+  * Pay close attention to the most intense points and final moments of a user journey.
+  * Design to delight at these moments. People recall negative experiences more vividly.
+
+## Postel’s Law (Robustness Principle)
+Be liberal in what you accept, and conservative in what you send.
+* **Takeaways:**
+  * Be empathetic, flexible, and tolerant of user inputs.
+  * Accept variable input, translate it to meet requirements, and provide clear feedback.
+
+## Selective Attention
+The process of focusing attention only on a subset of stimuli related to our goals.
+* **Takeaways:**
+  * Guide users' attention and prevent distraction.
+  * Banner Blindness: users ignore content that resembles ads.
+  * Change Blindness: significant interface changes go unnoticed without strong cues.
+
+## Serial Position Effect
+Users best remember the first and last items in a series.
+* **Takeaways:**
+  * Place least important items in the middle of lists.
+  * Position key actions on the far left and right within elements like navigation.
+
+## Tesler’s Law (Conservation of Complexity)
+For any system, there is a certain amount of complexity which cannot be reduced.
+* **Takeaways:**
+  * The burden of inherent complexity should be assumed by the system, not the user.
+  * Lift the burden from users during design and development.
+
+## Von Restorff Effect (Isolation Effect)
+When multiple similar objects are present, the one that differs from the rest is most likely to be remembered.
+* **Takeaways:**
+  * Make important information or key actions visually distinctive.
+  * Use restraint when placing emphasis so elements don't compete.
+  * Don't rely exclusively on color for contrast (accessibility).
+
+## Working Memory
+A cognitive system that temporarily holds and manipulates information needed to complete tasks.
+* **Takeaways:**
+  * Limited to 4-7 chunks, fading after 20-30 seconds.
+  * Support recognition over recall (e.g., visually differentiate visited links).
+  * Place the burden of memory on the system.
+
+## Zeigarnik Effect
+People remember uncompleted or interrupted tasks better than completed tasks.
+* **Takeaways:**
+  * Invite content discovery by providing clear signifiers of additional content.
+  * Provide artificial progress towards a goal to motivate completion.