ui-ux-master 1.1.0

package/references/ui-ux-memory-workflow.md

@@ -0,0 +1,175 @@
+# UI/UX Project Memory Workflow
+
+Use this workflow every time `ui-ux-master` is used on a project. Its purpose is to keep the UI consistent across the whole application instead of generating a different visual style each time.
+
+## Core Principle
+
+The agent must behave like an adaptive product designer who respects the product's existing identity.
+
+- If an existing product/app has branding, preserve it.
+- If a design system exists, extend it instead of replacing it.
+- If a UI/UX memory file exists, read it before making design decisions.
+- If no memory file exists, create one after inspecting the project or asking key questions.
+- Only introduce a new visual direction when the user explicitly asks for redesign, rebrand, new theme, or specific modification.
+
+## Memory File Location
+
+When working inside a project, use this priority order:
+
+1. Project-specific memory file already present:
+   - `.ui-ux-memory.md`
+   - `docs/ui-ux-memory.md`
+   - `docs/design/ui-ux-memory.md`
+   - `design/ui-ux-memory.md`
+2. If none exists, create:
+   - `.ui-ux-memory.md` at the project root.
+3. If project root is unclear, ask for the project root or create the memory file beside the main frontend app after explaining the assumption.
+
+Do not create the memory file inside the `ui-ux-master` skill folder for each app. The memory belongs to the application being designed.
+
+## Required First Step Every Time
+
+Before creating or modifying frontend, inspect for existing design memory and branding:
+
+- Read `.ui-ux-memory.md` or equivalent if it exists.
+- Search for design tokens, theme files, CSS variables, Tailwind config, Sass variables, component library config, Figma exports, Storybook, or DESIGN.md.
+- Inspect existing global CSS and representative components/screens.
+- Identify current colors, fonts, spacing, radius, shadows, layout patterns, button styles, form styles, icon style, and tone of voice.
+- Check package/dependencies before assuming any UI library.
+
+## Existing Product Behavior
+
+If the project already has UI/branding:
+
+1. Extract the existing design facts.
+2. Update/create `.ui-ux-memory.md` with those facts.
+3. Follow the existing branding as the default.
+4. Add new screens/components using the same tokens, components, and interaction patterns.
+5. If something is inconsistent, propose a normalization plan instead of inventing a new look.
+6. If the user asks for a specific visual change, update only the requested dimension and preserve everything else.
+
+## Fresh Product Behavior
+
+If the project is new and no branding exists, ask only the minimum high-value questions needed:
+
+1. What are you building and who is it for?
+2. What is the primary user action or success moment?
+3. What personality should it have: premium, playful, enterprise, technical, calm, bold, luxury, friendly, etc.?
+4. Any colors, fonts, logos, competitors, or references you want to use or avoid?
+5. Is this web, mobile, dashboard, landing page, ecommerce, SaaS, admin, or another type?
+
+If the user does not answer, proceed with clearly labeled assumptions and create `.ui-ux-memory.md` from those assumptions.
+
+## What to Store in UI/UX Memory
+
+Store stable design decisions, not temporary task notes.
+
+Required sections:
+
+- Product summary.
+- Target users and primary jobs-to-be-done.
+- Brand personality.
+- Design method blend.
+- Color tokens.
+- Typography.
+- Spacing/layout rhythm.
+- Radius/elevation/shadows.
+- Component rules.
+- Interaction/state rules.
+- Accessibility rules.
+- Content/microcopy voice.
+- Responsive rules.
+- Do/don't rules.
+- Change log for design-system decisions.
+
+Do not store:
+
+- One-off bug status.
+- Temporary implementation progress.
+- Commit hashes or PR numbers.
+- Personal secrets.
+- Credentials.
+- Raw analytics exports.
+- Anything that will be stale in a few days unless it is clearly marked as temporary and removed later.
+
+## How to Use Memory During Implementation
+
+Before editing:
+
+- Read the memory file.
+- State the existing style baseline in your working notes or summary.
+- Identify whether the user asked to preserve, extend, or change the style.
+
+During design:
+
+- Reuse stored tokens and component rules.
+- Prefer extending existing patterns over creating new variants.
+- If a new component is needed, define it in memory so future work uses the same pattern.
+- If a new color/font/spacing/radius is needed, justify it and add it as a token.
+
+After implementation:
+
+- Update the memory file if stable UI rules changed.
+- Add only durable decisions.
+- Keep the memory concise and structured.
+- Mention in the final response whether memory was read/created/updated.
+
+## Adaptive Decision Rules
+
+The skill should be intelligent, not robotic:
+
+- If existing branding is strong, prioritize consistency over trendiness.
+- If existing branding is weak or inconsistent, normalize it into a clearer token system.
+- If the user asks for "modernize" or "make it better", improve hierarchy, spacing, states, accessibility, and consistency first before changing colors.
+- If the user asks for a new style, confirm whether it is a full redesign or a local change.
+- If different parts of the app conflict, choose the pattern used by the most complete/recent/high-quality screen and document the decision.
+- If the UI library limits design choices, adapt the desired style to the library instead of fighting it.
+- If brand details are missing, infer from product category and ask only if the choice would materially change the result.
+
+## Existing Branding Inspection Checklist
+
+Look for:
+
+- Logo and wordmark usage.
+- Primary/secondary/accent colors.
+- Background and surface colors.
+- Text color hierarchy.
+- Fonts and font loading.
+- Type scale and weights.
+- Spacing scale.
+- Grid/container widths.
+- Border radius.
+- Shadows/elevation.
+- Button variants.
+- Form/input styling.
+- Cards and panels.
+- Navigation style.
+- Modal/drawer/popover style.
+- Table/list style.
+- Empty/error/loading states.
+- Icons/illustrations/images.
+- Animation/motion style.
+- Voice/tone in headings, CTAs, errors.
+
+## Conflict Resolution
+
+When a requested change conflicts with memory:
+
+1. Follow explicit user instruction.
+2. Preserve unaffected design rules.
+3. Update memory with the new rule if the change is durable.
+4. Note the change in the memory change log.
+
+When user intent is ambiguous:
+
+- Ask whether they want a local change or global design-system change.
+- If low-risk, make a local change and document it as local.
+
+## Required Final Response Note
+
+When finishing UI work, include a short note:
+
+- UI/UX memory: read / created / updated / not available.
+- Branding baseline followed.
+- Any new durable design decisions added.
+- Any intentional deviations from existing style.

package/references/usability-heuristics.md

@@ -0,0 +1,65 @@
+# Usability Heuristics and Expert Review
+
+Use this reference for heuristic reviews, cognitive walkthroughs, UX audits, and quick diagnosis when user testing is unavailable.
+
+## Nielsen's 10 Usability Heuristics
+
+1. Visibility of system status: show loading, progress, saved state, errors, sync, and feedback.
+2. Match between system and real world: use user language and natural task order.
+3. User control and freedom: undo, cancel, back, edit, exit, and recover.
+4. Consistency and standards: consistent labels, components, locations, platform conventions.
+5. Error prevention: prevent destructive mistakes and invalid input before they happen.
+6. Recognition rather than recall: visible options, defaults, examples, history, and contextual help.
+7. Flexibility and efficiency: shortcuts, saved preferences, bulk actions, power-user paths.
+8. Aesthetic and minimalist design: remove irrelevant content and reduce competing hierarchy.
+9. Help users recognize, diagnose, and recover from errors: specific messages and next steps.
+10. Help and documentation: accessible help where users need it.
+
+## Norman Interaction Principles
+
+- Affordances: controls suggest what they do.
+- Signifiers: labels, icons, shape, and placement communicate action.
+- Feedback: every action has a visible, timely response.
+- Mapping: control placement matches outcome.
+- Constraints: the UI prevents impossible or dangerous actions.
+- Conceptual model: users can predict what happens next.
+
+## Practical Cognitive Rules
+
+- Reduce cognitive load with grouping, defaults, progressive disclosure, and plain language.
+- Prefer recognition over memory.
+- Use Fitts's Law pragmatically: important targets should be large and easy to reach.
+- Use Hick's Law pragmatically: too many equal choices slow decisions.
+- Use serial position: important actions belong at memorable start/end positions.
+- Avoid change blindness by making important changes explicit.
+
+## Severity Rating
+
+Rate each issue:
+
+- Critical: blocks task, causes data loss, legal/security/accessibility failure, or deceptive outcome.
+- High: many users fail or require support; severe accessibility or conversion issue.
+- Medium: creates confusion, delay, avoidable errors, or inconsistent behavior.
+- Low: polish issue that reduces confidence but does not block completion.
+
+## Heuristic Review Output
+
+For each finding include:
+
+- Location.
+- Violated heuristic.
+- Evidence or rationale.
+- Severity.
+- User impact.
+- Recommended fix.
+- Acceptance criteria.
+
+## Common Agent Fixes
+
+- Add one primary CTA and demote secondary actions.
+- Add clear loading, empty, error, success, and permission states.
+- Replace vague labels with task-oriented labels.
+- Add undo or confirmation for destructive actions.
+- Preserve form data after errors.
+- Make current location and next best action obvious.
+- Use consistent component variants, spacing, and terminology.

package/references/ux-measurement-quality-gates.md

@@ -0,0 +1,58 @@
+# UX Measurement and Quality Gates
+
+Use this reference to make UX measurable and deployment-ready.
+
+## Metric Selection
+
+Choose metrics based on goal:
+
+- Task completion: success rate, error rate, time on task, support contact rate.
+- Conversion: CTA click-through, signup completion, checkout completion, qualified leads.
+- Activation: first successful action, onboarding completion, time to value.
+- Retention: repeat usage, feature adoption, churn, saved work, returning users.
+- Comprehension: first-click success, content comprehension, reduced confusion/support.
+- Trust/safety: consent comprehension, refund/cancel success, security perception, complaint rate.
+- Accessibility: WCAG 2.2 AA pass, keyboard completion, screen-reader smoke test.
+- Performance perception: Core Web Vitals, skeleton stability, perceived latency, no layout shift.
+
+## Common UX Measures
+
+- Task success rate.
+- Time on task.
+- Error rate.
+- System Usability Scale (SUS).
+- Single Ease Question (SEQ).
+- UMUX-Lite.
+- HEART: Happiness, Engagement, Adoption, Retention, Task success.
+- Funnel/drop-off by step.
+- Qualitative severity themes.
+
+## Quality Gate Template
+
+A UI/UX deliverable is ready only when:
+
+- Primary task and success metric are explicit.
+- All required states exist: loading, empty, error, success, disabled, permission, offline if relevant.
+- WCAG 2.2 AA acceptance criteria are listed.
+- Responsive behavior is specified for mobile, tablet, desktop, and wide.
+- Component states and tokens are documented.
+- Content is final enough to implement or flagged as placeholder.
+- Analytics events are named for key decisions and outcomes.
+- Risks, assumptions, and validation plan are documented.
+
+## Frontend Performance Gates
+
+For web implementation, aim for:
+
+- No avoidable layout shift in core flows.
+- Interactive controls respond immediately or show progress.
+- Images are sized and lazy-loaded appropriately.
+- Critical flows work on low-end mobile and slow network where relevant.
+- Errors are recoverable without data loss.
+
+## Experimentation Guardrails
+
+- Define hypothesis before A/B tests.
+- Do not optimize conversion with dark patterns.
+- Track guardrail metrics such as refunds, complaints, accessibility, support load, and retention.
+- Avoid declaring success from underpowered or biased data.

package/references/ux-research-methods.md

@@ -0,0 +1,99 @@
+# UX Research Methods for Agents
+
+Use this reference when a UI/UX task requires evidence, discovery, validation, or uncertainty reduction. Research output must distinguish observed evidence from assumptions.
+
+## Source-Grounded Baseline
+
+Align research work with these authoritative bodies of knowledge:
+
+- Nielsen Norman Group UX research guidance and UX Research Cheat Sheet.
+- GOV.UK Service Manual user research practices.
+- ISO 9241-210 human-centred design and ISO 9241-11 usability definitions.
+- Interaction Design Foundation UX research and human-computer interaction learning materials.
+- W3C/WAI accessibility research and testing guidance when users include disabled people.
+
+## Research Decision Tree
+
+1. If the problem, audience, or jobs are unclear: use stakeholder interviews, user interviews, analytics/support review, and competitive scan.
+2. If users cannot find things: use IA audit, card sorting, tree testing, search-log review, first-click testing.
+3. If a flow is confusing: use task analysis, usability testing, cognitive walkthrough, funnel/drop-off review.
+4. If copy or labels are unclear: use comprehension testing, preference testing, plain-language review.
+5. If accessibility risk exists: use WCAG audit, keyboard testing, screen-reader smoke test, disabled-user research where possible.
+6. If launching high-risk health, finance, minors, legal, or safety UX: require consent, privacy, ethics review, and human expert review.
+
+## Research Plan Template
+
+- Research goal: what decision will this inform?
+- Known facts: evidence already available.
+- Assumptions: what may be wrong.
+- Participants/users: segment, criteria, exclusions.
+- Method: interview, survey, contextual inquiry, diary, usability test, analytics, card sort, tree test, heuristic review.
+- Tasks/questions: neutral, non-leading prompts.
+- Consent/privacy: what data is collected and how it is handled.
+- Success metrics: task success, time on task, error rate, confidence, SEQ, SUS, qualitative themes.
+- Output: findings, evidence, confidence, design implications.
+
+## Core Methods
+
+### Stakeholder Interview
+Use to learn business goals, constraints, risks, and internal assumptions. Do not treat stakeholder opinion as user evidence.
+
+### User Interview
+Use for goals, motivations, workflows, language, pains, trust concerns. Ask about past behavior, not hypothetical preferences.
+
+### Contextual Inquiry
+Observe users in their real environment. Capture tools, interruptions, workarounds, handoffs, data sources, and failure recovery.
+
+### Survey
+Use for quantifying known questions with enough respondents. Avoid using surveys to discover unknown needs without qualitative follow-up.
+
+### Diary Study
+Use for repeated behavior over time: habits, emotional changes, frequency, reminders, retention, and lifecycle journeys.
+
+### Competitive and Comparative Analysis
+Compare task models, IA, copy, trust signals, onboarding, pricing, checkout, and accessibility. Extract patterns; do not copy UI.
+
+### Analytics and Support Synthesis
+Review search terms, funnel drop-off, rage clicks, error logs, support tickets, chat transcripts, refunds, cancellations, and feature requests.
+
+### Task Analysis
+Break a task into trigger, user intent, decisions, inputs, system responses, success criteria, and recovery path.
+
+### Card Sorting
+Use open card sorting to discover grouping models and closed card sorting to test existing taxonomy.
+
+### Tree Testing
+Test whether labels and hierarchy help users find content before investing in visual design.
+
+### First-Click Testing
+Validate whether the first click or tap points users toward success.
+
+### Usability Testing
+Test realistic tasks with representative users. Capture success, errors, confusion, workarounds, comments, confidence, and severity.
+
+## Evidence Confidence Levels
+
+- High: repeated findings across representative users or triangulated quantitative + qualitative evidence.
+- Medium: consistent evidence from limited research, analytics, or expert review.
+- Low: plausible assumption, stakeholder opinion, synthetic user model, or single observation.
+
+Label low-confidence findings as assumptions and recommend validation.
+
+## Research Ethics
+
+- Get consent before recording or collecting personal data.
+- Minimize data collection.
+- Avoid manipulative tasks and leading questions.
+- Do not invent user quotes or claim research was performed when it was not.
+- Protect vulnerable users and sensitive domains.
+- Mark AI-generated personas or journeys as synthetic assumptions.
+
+## Deliverables
+
+- Research plan.
+- Interview or test script.
+- Recruiting screener.
+- Findings table: finding, evidence, confidence, impact, recommendation.
+- Persona/proto-persona or JTBD if useful.
+- Journey map or service blueprint if useful.
+- Design changes and validation plan.

package/references/wcag-aa-quick-reference.md

@@ -0,0 +1,85 @@
+# WCAG 2.2 AA Quick Reference for Agents
+
+This is a practical accessibility reference for UI/UX work. Treat WCAG 2.2 AA as the default minimum unless the user specifies another standard.
+
+## Core Principles
+
+1. Perceivable: users can perceive content.
+2. Operable: users can operate controls.
+3. Understandable: users can understand interface and content.
+4. Robust: content works with assistive technology.
+
+## Contrast
+
+- Normal text: at least 4.5:1.
+- Large text: at least 3:1.
+- UI components and graphical objects: at least 3:1.
+- Do not use color as the only way to communicate status.
+
+## Keyboard
+
+- All interactive controls must be reachable by keyboard.
+- Focus order must follow the visual/task order.
+- Focus indicator must be visible and high contrast.
+- No keyboard trap unless there is an obvious escape method.
+- Modals must trap focus while open and return focus when closed.
+
+## Semantic Structure
+
+- Use real buttons for actions and links for navigation.
+- Use headings in logical order.
+- Use lists, tables, labels, fieldsets, and landmarks semantically.
+- Use ARIA only when native HTML cannot express the behavior.
+- If ARIA is used, names, roles, values, and states must be correct.
+
+## Forms
+
+- Every input needs a programmatically associated label.
+- Required fields must be clear.
+- Error messages must identify the field and explain the fix.
+- Do not rely only on placeholder text.
+- Use autocomplete attributes when helpful.
+- Use fieldsets/legends for grouped radio/checkbox inputs.
+
+## Motion and Timing
+
+- Respect prefers-reduced-motion.
+- Avoid flashing content.
+- Give users control over time limits where relevant.
+- Animation should support orientation, feedback, or continuity, not distract.
+
+## Images and Media
+
+- Informative images need alt text.
+- Decorative images should be hidden from assistive technology.
+- Icons used as buttons need accessible labels.
+- Videos need captions; audio-only content needs transcript when relevant.
+
+## Touch and Pointer
+
+- Aim for 44x44 px touch targets.
+- Do not require complex gestures without alternatives.
+- Hover-only content must also work on focus/tap.
+
+## Common Agent Fixes
+
+- Add visible labels instead of placeholder-only fields.
+- Replace clickable divs with buttons or links.
+- Add focus states to custom components.
+- Add aria-expanded and aria-controls to disclosure controls.
+- Add aria-current to current nav item.
+- Add aria-live polite for async success/status updates.
+- Add role="alert" or associated error text for validation errors.
+- Ensure disabled controls have explanation if their disabled reason is not obvious.
+
+## Accessibility Acceptance Criteria
+
+For final handoff, include:
+
+- Keyboard path for all major tasks.
+- Focus behavior for modals, drawers, menus, popovers.
+- Contrast requirement for text and UI elements.
+- Screen reader labels for icon-only controls.
+- Error association for forms.
+- Reduced-motion behavior.
+- Touch target requirements.

package/scripts/build_deployment_zip.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import zipfile
+
+src = Path(__file__).resolve().parents[1]
+out = src.parent / "ui-ux-master-deployment.zip"
+if out.exists():
+    out.unlink()
+exclude_dirs = {".git", "graphify-out", "__pycache__", "node_modules", "coverage", ".nyc_output"}
+exclude_suffixes = {".pyc", ".tgz"}
+exclude_names = {"npm-debug.log"}
+
+with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as z:
+    for path in src.rglob("*"):
+        rel = path.relative_to(src)
+        if set(rel.parts) & exclude_dirs:
+            continue
+        if path.suffix in exclude_suffixes:
+            continue
+        if path.name in exclude_names or path.name.startswith("npm-debug.log"):
+            continue
+        if path.is_file():
+            z.write(path, Path("ui-ux-master") / rel)
+
+print(out)
+with tempfile.TemporaryDirectory() as td:
+    with zipfile.ZipFile(out) as z:
+        z.extractall(td)
+    pkg = Path(td) / "ui-ux-master"
+    res = subprocess.run(
+        [sys.executable, "scripts/validate_skill.py", "--release"],
+        cwd=pkg,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+    print(res.stdout)
+    raise SystemExit(res.returncode)