ui-ux-master 1.2.1 → 1.5.0

package/README.md

@@ -1,169 +1,121 @@
-# UI/UX Master 🎨✨
+# UI/UX Master
 
-[![npm version](https://img.shields.io/npm/v/ui-ux-master?logo=npm&label=npm)](https://www.npmjs.com/package/ui-ux-master)
-[![npm downloads](https://img.shields.io/npm/dm/ui-ux-master?logo=npm&label=downloads)](https://www.npmjs.com/package/ui-ux-master)
-[![License: MIT](https://img.shields.io/npm/l/ui-ux-master)](https://github.com/Seance1723/UI-UX-Skills/blob/main/LICENSE)
-[![GitHub stars](https://img.shields.io/github/stars/Seance1723/UI-UX-Skills?style=flat&logo=github)](https://github.com/Seance1723/UI-UX-Skills/stargazers)
-[![Last commit](https://img.shields.io/github/last-commit/Seance1723/UI-UX-Skills?logo=github)](https://github.com/Seance1723/UI-UX-Skills/commits/main)
+[![npm](https://img.shields.io/npm/v/ui-ux-master?logo=npm&label=v1.5.0&color=6366f1)](https://www.npmjs.com/package/ui-ux-master)
+[![downloads](https://img.shields.io/npm/dm/ui-ux-master?logo=npm&label=downloads&color=10b981)](https://www.npmjs.com/package/ui-ux-master)
+[![License: MIT](https://img.shields.io/npm/l/ui-ux-master?color=f59e0b)](https://github.com/Seance1723/UI-UX-Skills/blob/main/LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
 
-**The ultimate UI/UX skill for AI coding agents.** Turn your AI into a Senior Product Designer, UX Researcher, and Frontend Lead in seconds.
+**Turn your AI coding agent into a Senior Product Designer, UX Researcher, and Frontend Lead — in one command.**
 
-Author: Rupak Biswas.
-
-Use it with a normal prompt plus one trigger:
+One trigger. Every agent. Full design lifecycle from discovery to developer handoff.
 
 ```text
-/ui-ux-master audit this dashboard and give me implementation-ready fixes
+/ui-ux-master build a SaaS landing page for my project management tool
 ```
 
-If `/ui-ux-master` is not present, the installed rules tell agents not to use the skill. That keeps your normal coding workflow clean and makes UI/UX mode explicit.
-
-## Why Use UI/UX Master?
-
-Most AI UI prompts produce pretty screens but miss the hard parts: research assumptions, information architecture, accessibility, responsive states, design-system consistency, platform conventions, localization, ethics, and developer handoff.
-
-UI/UX Master is built to make agents behave like a senior product designer, UX researcher, accessibility reviewer, design-system lead, and frontend handoff partner in one workflow.
+---
 
-## 🚀 Supercharge Your AI Workflow
-
-AI agents are great at writing code, but they often struggle with **Information Architecture**, **Accessibility (WCAG)**, and **Design Systems**. `ui-ux-master` bridges this gap. 
+## Install with npm
 
-By installing this tool, you instantly give **Claude**, **Cursor**, **Windsurf**, **Codex**, **Gemini**, **Antigravity**, and universal/custom-instruction agents the ability to:
-- 🧠 **Think like a designer:** Understand user flows and journey maps before coding.
-- ♿ **Audit for accessibility:** Automatically check for WCAG 2.2 AA compliance and ARIA patterns.
-- 🧩 **Enforce design systems:** Keep your brand colors, typography, and spacing consistent.
+```bash
+# Recommended — project install
+npm install --save-dev ui-ux-master
+npx ui-ux-master install --project
 
-## What Makes It Different
+# No install needed (one-time)
+npx ui-ux-master install --project
+```
 
-| Common open-source prompt/skill | UI/UX Master |
-|---|---|
-| Focuses on visual polish only | Covers research, UX strategy, IA, flows, UI, accessibility, content, metrics, and handoff |
-| Always-on rules that interfere with normal coding | Opt-in `/ui-ux-master` trigger only |
-| One agent or editor only | Cross-agent templates for Claude, Codex, Windsurf, Antigravity, Gemini, Cursor, and universal agents |
-| Generic design advice | Concrete templates, checklists, quality gates, and implementation rules |
-| No persistent design memory | Project `.ui-ux-memory.md` workflow keeps brand/design decisions consistent |
-| Weak accessibility coverage | WCAG 2.2 AA plus advanced ARIA/widget patterns and test matrix |
-| No deployment validation | Release validator, npm package metadata, tests, and deployment zip builder |
-| No product-risk coverage | Ethics, privacy, dark-pattern, high-risk domain, AI-interface, and inclusive-design checks |
-| Hidden from AI tooling | Ships `llms.txt`, machine-readable manifest, system prompt add-ons, and a local MCP server for automatic discovery |
-
-## AI Discoverability
-
-UI/UX Master is now designed for both humans and AI systems to discover:
-
-- `llms.txt` gives agents a concise map of the package.
-- `ai-discovery/ui-ux-master.manifest.json` provides a machine-readable manifest.
-- `system-prompts/` contains full, compact, and MCP-focused system prompt add-ons.
-- `ui-ux-master-mcp` exposes the package through a local MCP server with tools, resources, and prompts.
-- Project installs copy these discovery assets into `.ui-ux-master/` so no-save `npx` installs remain usable after the npm cache disappears.
-
-## Capabilities
-
-UI/UX Master can help agents produce:
-
-- Product UX strategy and user goals
-- UX research plans, evidence confidence, and research synthesis
-- Information architecture, navigation, taxonomy, and search/filter models
-- User flows, task flows, journey maps, and service blueprints
-- Wireframes, layout specs, visual direction, and interaction design
-- Accessibility audits and WCAG 2.2 AA remediation guidance
-- Advanced component accessibility patterns for dialogs, tabs, comboboxes, menus, grids, live regions, and drag/drop alternatives
-- Design systems, tokens, component specs, governance, and usage rules
-- Content design, UX writing, error copy, empty states, localization, RTL, and i18n checks
-- Platform-specific guidance for web, iOS, Android/Material, Windows/desktop, kiosk, email, TV, and universal agents
-- SaaS dashboards, data visualization, tables, alerts, ecommerce, checkout, onboarding, settings, auth, forms, and landing pages
-- Ethical UX, privacy, consent, dark-pattern detection, AI transparency, and high-risk domain safeguards
-- Developer handoff with states, tokens, responsive behavior, analytics events, QA, and acceptance criteria
+Works with **Claude**, **Windsurf**, **Cursor**, **Codex**, **Gemini**, and any agent that supports instruction files.
 
-## Install with npm
+---
 
-Global install:
+## Quick Start — Try These
 
-```bash
-npm install -g ui-ux-master
-ui-ux-master install --global
+```text
+/ui-ux-master audit this dashboard for accessibility and give me fixes
 ```
 
-Project-local install, recommended:
-
-```bash
-npm install --save-dev ui-ux-master
-npx ui-ux-master install --project
+```text
+/ui-ux-master design a checkout flow for my e-commerce app
 ```
 
-No-save project install (copies reusable skill files into `.ui-ux-master/` so agents can still read the source after npx exits):
+```text
+/ui-ux-master build a landing page for a healthcare startup
+```
 
-```bash
-npx ui-ux-master install --project
+```text
+/ui-ux-master create a full design system for this SaaS product
 ```
 
-Install only selected agents:
+> The skill only activates when you type `/ui-ux-master` — your normal coding workflow is untouched.
 
-```bash
-npx ui-ux-master install --project --agents claude,codex,windsurf,gemini,cursor
-```
+---
 
-Dry run:
+## What It Does
 
-```bash
-npx ui-ux-master install --project --dry-run
-```
+| Without UI/UX Master | With UI/UX Master |
+|---|---|
+| Jumps straight to code | Discovery form first — brief, audience, and brand locked before design |
+| Generic colors and layout | Industry reasoning engine → instant Design System Block per product type |
+| No design system | Portable 9-section schema saved to `.ui-ux-memory.md` per project |
+| Ignores accessibility | WCAG 2.2 AA + ARIA patterns audited on every output |
+| AI slop output | Anti-slop blacklist + 5-dimensional quality gate before every emit |
+| One-size-fits-all style | 20+ named UI styles with complete token overrides |
+| Forgets your brand | Design memory persists across all sessions |
 
-## Package
+---
 
-| Channel | Package | Purpose |
-|---|---|---|
-| npmjs | [`ui-ux-master`](https://www.npmjs.com/package/ui-ux-master) | Primary public package for normal installs and `npx` usage |
-| GitHub | [`Seance1723/UI-UX-Skills`](https://github.com/Seance1723/UI-UX-Skills) | Source, issues, releases, workflows, and open-source collaboration |
-| GitHub Packages | Optional scoped mirror | Use only if you want the repository Packages section to show a package |
+## What's New
 
-The canonical npm package is intentionally unscoped as `ui-ux-master`. GitHub Packages requires npm packages to be scoped, so a GitHub Packages mirror should use `@seance1723/ui-ux-master` while the public npmjs package remains `ui-ux-master`.
+### v1.5.0 — Industry Intelligence Update *(May 2026)*
 
-Package entrypoints:
+- **Industry Reasoning Engine** — describe your product, get a complete Design System Block instantly (pattern + style + palette + typography + effects + anti-patterns) for 15+ industries
+- **UI Styles Catalog** — 20+ named styles: Glassmorphism, Liquid Glass, Data Brutalism, Aurora Borealis, Cyberpunk, AI-Native, Bento Grid, Soft UI Evolution, Claymorphism, and more — each with full CSS token overrides
+- **Architectural Color Scales** — 11-step (50–950) OKLch ramps for every hue family, semantic states, and dark mode mappings
+- **16-Framework Tech Stack Guidelines** — React, Next.js, Vue, Nuxt, Angular, Svelte, Astro, Remix, SolidJS, React Native, Flutter, SwiftUI, shadcn/ui, Jetpack Compose, Laravel, HTML+Tailwind
+- **Landing Page Patterns** — 12 named conversion patterns (Hero-Centric, Problem-Solution, Social Proof First, Comparison, Product Demo First, and more) with section-by-section structure
+- **Chart Type Guide** — 25-type decision tree + dashboard layout rules and anti-patterns
+- **Code-Level AI Audit** — 30 error codes (AI001–AI030): Tailwind interpolation bugs, hallucinated utilities, missing a11y, React anti-patterns, invented metrics — each with severity level and line reference
+- **MASTER + Page Overrides** — `design-system/MASTER.md` + `pages/[page].md` hierarchy for multi-page consistency
 
-- `ui-ux-master` - CLI installer and project integration tool.
-- `ui-ux-master-mcp` - local MCP server for tools, resources, and prompts.
-- `import { assets, bins, trigger } from "ui-ux-master"` - lightweight ESM metadata API.
-- `require("ui-ux-master")` - CommonJS metadata API.
+### v1.4.0 — Quality Gates Update
 
-Package metadata is connected to GitHub through `repository`, `homepage`, `bugs`, license, funding, exports, engines, and npm provenance-ready publish settings in `package.json`.
+- 6-question discovery form runs before any visual output
+- Brand extraction protocol — never guesses colors from a company name
+- 5 OKLch visual directions for brandless projects
+- 5-dimensional self-critique + P0/P1/P2 quality gates before every emit
+- Anti-AI-slop blacklist — purple gradients, generic emojis, invented metrics all forbidden
+- Portable 9-section design system schema (DESIGN.md-compatible)
 
-## Supported Agents
+### v1.3.0 — Brand Methods Update
 
-| Agent | Install target | Trigger |
-|---|---|---|
-| Claude Code | `.claude/commands/ui-ux-master.md` | native `/ui-ux-master` command |
-| Codex | `AGENTS.md` marked section | type `/ui-ux-master` |
-| Windsurf/Cascade | `.windsurf/rules/ui-ux-master.md` and `.windsurfrules` fallback | type `/ui-ux-master` |
-| Antigravity | `AGENTS.md` plus `.antigravity/rules/ui-ux-master.md` fallback | type `/ui-ux-master` |
-| Gemini CLI | `GEMINI.md` marked section | type `/ui-ux-master` |
-| Cursor | `.cursor/rules/ui-ux-master.mdc` | type `/ui-ux-master` |
-| Other agents | `agent-templates/universal/ui-ux-master-trigger.md` | copy trigger into instruction file |
-| MCP clients | `ui-ux-master-mcp` | discover tools/resources/prompts automatically |
+- 10 top-brand design method skill files (Product Cinema, Enterprise Trust Hub, Conversion Simplicity, and more)
+- Color Psychology and Branding skill with industry-specific palette prescriptions
 
-See `docs/slash-command-compatibility.md` for details.
+---
 
-## System Prompt Add-ons
+## Supported Agents
 
-Copy one of these into any AI custom-instructions field when the agent does not support project rules:
+| Agent | Trigger |
+|---|---|
+| Claude Code | `/ui-ux-master` (native slash command) |
+| Windsurf / Cascade | `/ui-ux-master` |
+| Cursor | `/ui-ux-master` |
+| Codex | `/ui-ux-master` |
+| Gemini CLI | `/ui-ux-master` |
+| Antigravity | `/ui-ux-master` |
+| Any other agent | Copy `agent-templates/universal/` into your instruction file |
+| MCP clients | Auto-discovered via `ui-ux-master-mcp` |
 
-- `system-prompts/ui-ux-master-system-add-on.md` — full add-on.
-- `system-prompts/ui-ux-master-compact.md` — compact add-on.
-- `system-prompts/ui-ux-master-mcp-add-on.md` — MCP-focused add-on.
+---
 
 ## MCP Server
 
-Run the local MCP server:
-
 ```bash
-ui-ux-master-mcp
-# or without global install
 npx -y --package ui-ux-master ui-ux-master-mcp
 ```
 
-MCP client config:
-
 ```json
 {
   "mcpServers": {
@@ -175,130 +127,129 @@ MCP client config:
 }
 ```
 
-See `docs/mcp-server.md` for tools, resources, prompts, and Hermes config.
+---
 
-## Usage Examples
+## CLI Reference
 
-```text
-/ui-ux-master redesign this SaaS onboarding flow for faster activation and create dev handoff specs
+```bash
+ui-ux-master install --project                             # install for current project
+ui-ux-master install --project --agents claude,windsurf   # specific agents only
+ui-ux-master install --project --dry-run                  # preview without writing
+ui-ux-master install --global                             # global install
+ui-ux-master doctor                                       # check install health
+ui-ux-master uninstall --project                          # remove
 ```
 
-```text
-/ui-ux-master audit the checkout flow for accessibility, trust, conversion, and mobile UX
-```
+---
 
-```text
-/ui-ux-master create a design system starter for this app using the existing components and tokens
-```
+## Full Capabilities
 
-```text
-/ui-ux-master inspect this dashboard and improve hierarchy, data visualization, empty states, and responsive behavior
-```
+<details>
+<summary>Expand to see everything</summary>
 
-```text
-/ui-ux-master turn this rough product idea into IA, user flows, wireframes, content, metrics, and implementation tasks
-```
+**Design & Research**
+- UX strategy, user goals, jobs-to-be-done
+- UX research plans and evidence-confidence scoring
+- Information architecture, navigation, taxonomy, search/filter models
+- User flows, task flows, journey maps, service blueprints
+- Wireframes, layout specs, visual direction, interaction design
 
-## CLI Commands
+**Accessibility**
+- WCAG 2.2 AA audits and remediation guidance
+- Advanced ARIA patterns: dialogs, tabs, comboboxes, menus, grids, live regions, drag/drop
 
-```bash
-ui-ux-master install --project
-ui-ux-master install --global
-ui-ux-master install --project --agents claude,codex,windsurf,antigravity,gemini,cursor
-ui-ux-master install --project --dry-run
-ui-ux-master doctor
-ui-ux-master where
-ui-ux-master mcp
-ui-ux-master-mcp
-ui-ux-master uninstall --project
-```
+**Design Systems**
+- Token architecture, component specs, governance, usage rules
+- Portable 9-section schema saved per project (`.ui-ux-memory.md`)
+- MASTER.md + page-level override hierarchy
 
-## Package Structure
+**Content & Platform**
+- UX writing, error copy, empty states, i18n, RTL
+- Web, iOS, Android/Material, Windows, kiosk, email, TV
 
-- `SKILL.md` — main orchestration skill.
-- `index.mjs`, `index.cjs`, `index.d.ts` — ESM, CommonJS, and TypeScript metadata entrypoints.
-- `references/` — advanced playbooks and standards-aligned checklists.
-- `templates/` — briefs, audits, component specs, design-system specs, and project UI/UX memory template.
-- `agent-templates/` — Claude, Codex, Windsurf, Antigravity, Gemini, Cursor, and universal `/ui-ux-master` activation rules.
-- `docs/` — cross-agent slash-command compatibility docs and MCP server docs.
-- `system-prompts/` — full, compact, and MCP-focused system prompt add-ons.
-- `ai-discovery/` — machine-readable discovery manifest.
-- `llms.txt` — AI-readable package map.
-- `bin/ui-ux-master.mjs` — npm CLI installer.
-- `bin/ui-ux-master-mcp.mjs` — local MCP server.
-- `scripts/validate_skill.py` — dependency-free release validator.
-- `scripts/build_deployment_zip.py` — clean deployment zip builder.
-- `tests/` — npm installer and package smoke tests.
+**Specialized Screens**
+- SaaS dashboards, data visualization, ecommerce, checkout, onboarding, auth, forms, landing pages
 
-## GitHub Repository Setup
+**Ethics & Handoff**
+- Dark-pattern detection, privacy, consent, AI transparency, high-risk domain safeguards
+- Developer handoff: states, tokens, responsive behavior, analytics events, QA, acceptance criteria
 
-Recommended About section:
+</details>
 
-- Description: `Opt-in UI/UX master skill, CLI, and MCP server for AI coding agents. Accessibility, design systems, UX research, and frontend handoff in one workflow.`
-- Website: `https://www.npmjs.com/package/ui-ux-master`
-- Enable releases and issues. Enable discussions when you are ready to support community questions.
+---
 
-Recommended GitHub topics:
+## Package Layout
 
-`ai-agent`, `ai-coding`, `ui-ux`, `ux-research`, `product-design`, `design-system`, `accessibility`, `wcag`, `mcp`, `model-context-protocol`, `claude-code`, `codex`, `windsurf`, `cursor`, `gemini-cli`, `npm-package`, `cli`, `prompt-engineering`, `frontend`, `llms-txt`
+```
+ui-ux-master/
+├── SKILL.md                         main orchestration (steps 1–12)
+├── references/
+│   ├── industry-reasoning-rules.md  15+ industry → instant design system
+│   ├── ui-styles-catalog.md         20+ named styles with full token specs
+│   ├── color-scale-system.md        11-step OKLch architectural scales
+│   ├── tech-stack-guidelines.md     16 frameworks with component patterns
+│   ├── landing-page-patterns.md     12 patterns + 25-type chart guide
+│   ├── output-quality-gates.md      AI audit codes + 5-dim self-critique
+│   ├── design-system-schema.md      9-section schema + MASTER/overrides
+│   ├── visual-directions.md         5 OKLch directions for brandless projects
+│   ├── design-discovery-protocol.md 6-question intake + brand extraction
+│   └── brand-method-*.md            10 top-brand design methods
+├── templates/                       briefs, specs, memory template
+├── agent-templates/                 Claude, Windsurf, Cursor, Codex, Gemini
+├── system-prompts/                  copy into any AI custom-instructions
+└── bin/                             CLI + MCP server
+```
 
-For publishing and registry details, see `docs/package-publishing.md`.
+---
 
 ## Validation and Testing
 
-Run from this folder:
-
 ```bash
 python scripts/validate_skill.py --release
 npm test
 npm pack --dry-run
 ```
 
-Build a clean deployment zip:
+Expected output: `PASS: UI/UX skill package is valid`
 
-```bash
-python scripts/build_deployment_zip.py
-```
+---
 
-Expected validation result:
+## Limitations
 
-```text
-PASS: UI/UX skill package is valid
-Release mode: PASS
-```
+- Guides research — does not replace real user testing
+- Assists accessibility review — does not replace AT expert testing for high-risk products
+- Flags legal/privacy risks — does not replace legal review
+- No live preview or media generation
+
+---
 
 ## Competitive Positioning
 
-UI/UX Master is designed to outperform narrow UI prompt packs and simple design rules by combining:
+UI/UX Master combines what every competitor does best into one opt-in, daemon-free, cross-agent skill:
 
-1. Opt-in activation: no pollution of normal coding prompts.
-2. Cross-agent portability: one package for Claude, Codex, Windsurf, Antigravity, Gemini, Cursor, and generic agents.
-3. Full lifecycle coverage: discovery to deployment handoff.
-4. Standards alignment: WCAG, WAI-ARIA patterns, GOV.UK, NN/g, Material, Apple HIG, Microsoft, Baymard-style ecommerce practice, ISO human-centered design concepts.
-5. Project memory: durable brand/design consistency via `.ui-ux-memory.md`.
-6. Release engineering: npm packaging, CLI installer, validation, tests, and deployment zip.
-7. Advanced risk coverage: ethics, privacy, dark patterns, localization, platform conventions, high-risk domains, and AI UX transparency.
-8. AI discoverability: `llms.txt`, manifest, system prompt add-ons, and local MCP server.
+- **Discovery-first** — no visuals until brief is locked (beats generic prompt packs)
+- **Industry reasoning engine** — instant Design System Block per product type (matches `ui-ux-pro-max-skill`)
+- **11-step OKLch color scales** — architectural palette system (matches `saifyxpro`)
+- **Code-level audit AI001–AI030** — catches Tailwind bugs, missing a11y, React anti-patterns (matches `saifyxpro`)
+- **16-framework tech stack rules** — component patterns per framework (matches `saifyxpro`)
+- **Quality gates** — 5-dimensional self-critique + anti-slop blacklist (inspired by `open-design`)
+- **Full lifecycle** — research → IA → UI → accessibility → dev handoff (beats all narrow skills)
+- **Project memory** — `.ui-ux-memory.md` persists brand/design across sessions
 
-## Deployment Readiness Checklist
+See `references/competitive-landscape.md` for the full analysis.
+
+---
 
-- [ ] `python scripts/validate_skill.py --release` passes.
-- [ ] `npm test` passes.
-- [ ] `npm pack --dry-run` contains only intended files.
-- [ ] `ui-ux-master install --project --dry-run` works.
-- [ ] Agent templates contain `/ui-ux-master` and do not include local absolute paths.
-- [ ] System prompt add-ons and MCP docs are included and mention `/ui-ux-master`.
-- [ ] MCP smoke test returns `tools/list` and `resources/list` successfully.
-- [ ] No `node_modules`, `__pycache__`, `.pyc`, graphify cache, coverage, logs, secrets, or local credentials are included.
+## Deployment Readiness Checklist
 
-## Known Limitations
+- [ ] `python scripts/validate_skill.py --release` passes
+- [ ] `npm test` passes
+- [ ] `npm pack --dry-run` contains only intended files
+- [ ] `ui-ux-master install --project --dry-run` works
+- [ ] No `node_modules`, `.pyc`, secrets, or local paths in package
 
-- It guides research planning but does not replace real users.
-- It helps accessibility review but does not replace expert assistive-technology testing for high-risk products.
-- It flags legal/privacy/health/finance risks but does not replace legal or domain-expert review.
-- Brand and competitor sites change; verify live claims before citing them as facts.
-- Agents without native slash commands use `/ui-ux-master` as a text trigger through installed instruction files.
+---
 
 ## License
 
-MIT.
+MIT — by Rupak Biswas. Contributions welcome.