ui-ux-master 1.1.0

package/agent-templates/antigravity/AGENTS.append.md

@@ -0,0 +1,15 @@
+<!-- ui-ux-master:start -->
+## UI/UX Master opt-in trigger
+
+When the user writes `/ui-ux-master`, activate the UI/UX Master workflow from the installed `ui-ux-master` package. If the prompt does not include `/ui-ux-master`, do not use this workflow automatically.
+
+Use it for UI/UX design, audits, redesigns, frontend polish, accessibility, responsive behavior, design systems, product flows, and implementation handoff.
+
+Activation requirements:
+- Read `.ui-ux-master/SKILL.md` from this project first. If `.ui-ux-master/` is missing, fall back to the installed package.
+- Follow `references/ui-ux-memory-workflow.md`.
+- Follow `references/ui-ux-frontend-implementation-rules.md` for frontend implementation.
+- Check for `.ui-ux-memory.md` or equivalent before making UI decisions.
+- Preserve existing design tokens, components, and brand style unless the user asks for redesign.
+- End with a note saying whether UI/UX memory was read, created, updated, or unavailable.
+<!-- ui-ux-master:end -->

package/agent-templates/claude/commands/ui-ux-master.md

@@ -0,0 +1,25 @@
+---
+description: Activate UI/UX Master for design, audit, accessibility, frontend polish, and implementation-ready handoff.
+argument-hint: [task, screen, URL, repository area, product, or design goal]
+---
+
+Activate the `ui-ux-master` skill only for this `/ui-ux-master` request.
+
+Read and follow `.ui-ux-master/SKILL.md` in the target project first. If `.ui-ux-master/` is missing, fall back to the installed package:
+- `SKILL.md`
+- `references/ui-ux-memory-workflow.md`
+- `references/ui-ux-frontend-implementation-rules.md`
+- `references/ui-ux-complete-checklist.md`
+- `references/wcag-aa-quick-reference.md`
+- `templates/ui-ux-memory.md`
+
+User request:
+$ARGUMENTS
+
+Required behavior:
+1. Check for existing UI/UX memory and branding first.
+2. If memory exists, follow it.
+3. If no memory exists, inspect tokens, CSS, components, routes, screenshots, dependencies, and brand clues.
+4. Create `.ui-ux-memory.md` in the target project when useful; do not put project memory inside the skill package.
+5. Produce concrete UI/UX artifacts: flow, IA, layout, states, accessibility, responsive behavior, copy, QA, and implementation handoff.
+6. Mention whether UI/UX memory was read, created, updated, or unavailable.

package/agent-templates/codex/AGENTS.append.md

@@ -0,0 +1,15 @@
+<!-- ui-ux-master:start -->
+## UI/UX Master opt-in trigger
+
+When the user writes `/ui-ux-master`, activate the UI/UX Master workflow from the installed `ui-ux-master` package. If the prompt does not include `/ui-ux-master`, do not use this workflow automatically.
+
+Use it for UI/UX design, audits, redesigns, frontend polish, accessibility, responsive behavior, design systems, product flows, and implementation handoff.
+
+Activation requirements:
+- Read `.ui-ux-master/SKILL.md` from this project first. If `.ui-ux-master/` is missing, fall back to the installed package.
+- Follow `references/ui-ux-memory-workflow.md`.
+- Follow `references/ui-ux-frontend-implementation-rules.md` for frontend implementation.
+- Check for `.ui-ux-memory.md` or equivalent before making UI decisions.
+- Preserve existing design tokens, components, and brand style unless the user asks for redesign.
+- End with a note saying whether UI/UX memory was read, created, updated, or unavailable.
+<!-- ui-ux-master:end -->

package/agent-templates/cursor/rules/ui-ux-master.mdc

@@ -0,0 +1,10 @@
+---
+description: Activate UI/UX Master only when the user writes /ui-ux-master.
+alwaysApply: false
+---
+
+# UI/UX Master opt-in trigger
+
+When the user writes `/ui-ux-master`, activate the installed UI/UX Master workflow. Do not use it automatically without the trigger.
+
+Follow `.ui-ux-master/SKILL.md` first, with installed-package fallback. Check UI/UX memory first, preserve existing brand/tokens/components, and include accessibility, responsive behavior, states, content, quality gates, and implementation handoff.

package/agent-templates/gemini/GEMINI.append.md

@@ -0,0 +1,9 @@
+<!-- ui-ux-master:start -->
+## UI/UX Master opt-in trigger
+
+When the user writes `/ui-ux-master`, activate the UI/UX Master workflow. Read `.ui-ux-master/SKILL.md` first; if `.ui-ux-master/` is missing, fall back to the installed `ui-ux-master` package. If the prompt does not include `/ui-ux-master`, do not use this workflow automatically.
+
+Required references from `.ui-ux-master/` first, with installed package fallback: `SKILL.md`, `references/ui-ux-memory-workflow.md`, `references/ui-ux-frontend-implementation-rules.md`, and `references/ui-ux-complete-checklist.md`.
+
+Always check UI/UX memory and existing brand/tokens/components before designing. Preserve the baseline unless the user asks for redesign. Include accessibility, responsive behavior, states, content, platform conventions, quality gates, and handoff. State whether UI/UX memory was read, created, updated, or unavailable.
+<!-- ui-ux-master:end -->

package/agent-templates/universal/ui-ux-master-trigger.md

@@ -0,0 +1,18 @@
+# /ui-ux-master Trigger
+
+When the user writes `/ui-ux-master`, activate the UI/UX Master skill. If the user does not include `/ui-ux-master`, do not apply this skill automatically.
+
+Use UI/UX Master for UI design, UX strategy, audits, redesigns, frontend polish, accessibility, responsive behavior, design systems, content design, user flows, wireframes, prototypes, and engineering handoff.
+
+Activation behavior:
+
+1. Treat the rest of the user prompt as the task.
+2. Read `.ui-ux-master/SKILL.md` from the target project. If `.ui-ux-master/` is missing, fall back to the installed `ui-ux-master` package.
+3. Check for existing UI/UX memory first: `.ui-ux-memory.md`, `docs/ui-ux-memory.md`, `docs/design/ui-ux-memory.md`, or `design/ui-ux-memory.md`.
+4. If memory exists, follow it as the source of truth.
+5. If memory does not exist, inspect branding, tokens, CSS variables, components, fonts, layouts, screenshots, and dependencies before designing.
+6. Preserve existing brand and component conventions unless the user asks for redesign/rebrand.
+7. Always include accessibility, responsive behavior, loading/empty/error/success states, copy, platform conventions, and implementation handoff.
+8. State whether UI/UX memory was read, created, updated, or unavailable.
+
+Default output should be concrete and useful: design direction, IA/flow, layout, component states, accessibility, responsive behavior, copy, quality gates, and developer handoff.

package/agent-templates/windsurf/rules/ui-ux-master.md

@@ -0,0 +1,17 @@
+# UI/UX Master Rule
+
+Trigger: activate only when the user writes `/ui-ux-master`.
+
+Do not apply this rule automatically to normal prompts without `/ui-ux-master`.
+
+When active, use `.ui-ux-master/SKILL.md` in this project as the source of truth. If `.ui-ux-master/` is missing, fall back to the installed `ui-ux-master` package:
+- `SKILL.md`
+- `references/ui-ux-memory-workflow.md`
+- `references/ui-ux-frontend-implementation-rules.md`
+- `references/ui-ux-complete-checklist.md`
+
+Required workflow:
+1. Inspect existing UI/UX memory, brand, tokens, components, CSS, dependencies, and similar screens.
+2. Preserve existing brand and components unless the user asks for redesign.
+3. Produce practical UI/UX output: IA/flow, layout, states, accessibility, responsive rules, copy, and developer handoff.
+4. Mention whether UI/UX memory was read, created, updated, or unavailable.

package/bin/ui-ux-master.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const packageRoot = path.resolve(path.dirname(__filename), '..');
+const markerStart = '<!-- ui-ux-master:start -->';
+const markerEnd = '<!-- ui-ux-master:end -->';
+
+function read(rel) {
+  return fs.readFileSync(path.join(packageRoot, rel), 'utf8');
+}
+
+function mkdirp(dir, dryRun) {
+  if (dryRun) return;
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeFile(target, content, dryRun) {
+  if (dryRun) {
+    console.log(`[dry-run] write ${target}`);
+    return;
+  }
+  mkdirp(path.dirname(target), false);
+  fs.writeFileSync(target, content, 'utf8');
+  console.log(`wrote ${target}`);
+}
+
+function appendMarked(target, block, dryRun) {
+  const content = block.includes(markerStart) ? block.trim() + '\n' : `${markerStart}\n${block.trim()}\n${markerEnd}\n`;
+  const old = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
+  const re = new RegExp(`${escapeRegExp(markerStart)}[\\s\\S]*?${escapeRegExp(markerEnd)}\\n?`, 'm');
+  const next = re.test(old) ? old.replace(re, content) : `${old.replace(/\s*$/, '')}${old.trim() ? '\n\n' : ''}${content}`;
+  if (dryRun) {
+    console.log(`[dry-run] append/update marked section ${target}`);
+    return;
+  }
+  mkdirp(path.dirname(target), false);
+  fs.writeFileSync(target, next, 'utf8');
+  console.log(`updated ${target}`);
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function parseArgs(argv) {
+  const opts = { command: 'help', scope: 'project', agents: null, dryRun: false, dir: null, postinstall: false };
+  const args = [...argv];
+  if (args.includes('--postinstall')) opts.postinstall = true;
+  const first = args.find(a => !a.startsWith('--'));
+  if (first) opts.command = first;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--project') opts.scope = 'project';
+    else if (a === '--global') opts.scope = 'global';
+    else if (a === '--dry-run') opts.dryRun = true;
+    else if (a === '--dir') opts.dir = path.resolve(args[++i]);
+    else if (a === '--agents') opts.agents = args[++i].split(',').map(x => x.trim().toLowerCase()).filter(Boolean);
+  }
+  return opts;
+}
+
+function findProjectRoot(start) {
+  let cur = path.resolve(start || process.cwd());
+  while (true) {
+    for (const name of ['package.json', '.git', 'pyproject.toml', 'Cargo.toml', 'go.mod']) {
+      if (fs.existsSync(path.join(cur, name))) return cur;
+    }
+    const parent = path.dirname(cur);
+    if (parent === cur) return path.resolve(start || process.cwd());
+    cur = parent;
+  }
+}
+
+function wanted(opts, name) {
+  return !opts.agents || opts.agents.includes(name) || opts.agents.includes('all');
+}
+
+function copyProjectSkillAssets(root, dryRun) {
+  const dest = path.join(root, '.ui-ux-master');
+  const files = ['SKILL.md', 'README.md', 'LICENSE', 'package.json'];
+  const dirs = ['references', 'templates', 'docs'];
+  for (const file of files) {
+    writeFile(path.join(dest, file), read(file), dryRun);
+  }
+  for (const dir of dirs) {
+    copyDir(path.join(packageRoot, dir), path.join(dest, dir), dryRun);
+  }
+  console.log(`${dryRun ? '[dry-run] ' : ''}project skill assets available at ${dest}`);
+}
+
+function installProject(root, opts) {
+  const dry = opts.dryRun;
+  const installedPath = packageRoot;
+  console.log(`Installing /ui-ux-master project trigger into ${root}`);
+  console.log(`Package root: ${installedPath}`);
+
+  copyProjectSkillAssets(root, dry);
+
+  if (wanted(opts, 'claude')) writeFile(path.join(root, '.claude', 'commands', 'ui-ux-master.md'), read('agent-templates/claude/commands/ui-ux-master.md'), dry);
+  if (wanted(opts, 'codex') || wanted(opts, 'antigravity') || wanted(opts, 'universal')) appendMarked(path.join(root, 'AGENTS.md'), read('agent-templates/codex/AGENTS.append.md'), dry);
+  if (wanted(opts, 'windsurf')) {
+    writeFile(path.join(root, '.windsurf', 'rules', 'ui-ux-master.md'), read('agent-templates/windsurf/rules/ui-ux-master.md'), dry);
+    appendMarked(path.join(root, '.windsurfrules'), read('agent-templates/universal/ui-ux-master-trigger.md'), dry);
+  }
+  if (wanted(opts, 'antigravity')) writeFile(path.join(root, '.antigravity', 'rules', 'ui-ux-master.md'), read('agent-templates/universal/ui-ux-master-trigger.md'), dry);
+  if (wanted(opts, 'gemini')) appendMarked(path.join(root, 'GEMINI.md'), read('agent-templates/gemini/GEMINI.append.md'), dry);
+  if (wanted(opts, 'cursor')) writeFile(path.join(root, '.cursor', 'rules', 'ui-ux-master.mdc'), read('agent-templates/cursor/rules/ui-ux-master.mdc'), dry);
+
+  console.log('Done. Use: /ui-ux-master <your normal UI/UX request>');
+}
+
+function copyDir(src, dest, dryRun) {
+  if (dryRun) {
+    console.log(`[dry-run] copy ${src} -> ${dest}`);
+    return;
+  }
+  fs.cpSync(src, dest, { recursive: true, force: true, filter: (p) => !p.includes(`${path.sep}.git${path.sep}`) && !p.includes(`${path.sep}graphify-out${path.sep}`) && !p.includes(`${path.sep}__pycache__${path.sep}`) && !p.endsWith('.pyc') });
+}
+
+function installGlobal(opts) {
+  const root = path.join(os.homedir(), '.ui-ux-master');
+  console.log(`Installing global UI/UX Master files into ${root}`);
+  copyDir(packageRoot, root, opts.dryRun);
+  const claudeTarget = path.join(os.homedir(), '.claude', 'commands', 'ui-ux-master.md');
+  writeFile(claudeTarget, read('agent-templates/claude/commands/ui-ux-master.md'), opts.dryRun);
+  console.log('Global install complete. Project-local install is still recommended for Codex/Windsurf/Gemini rules.');
+}
+
+function uninstallProject(root, opts) {
+  const dry = opts.dryRun;
+  const files = [
+    path.join(root, '.ui-ux-master'),
+    path.join(root, '.claude', 'commands', 'ui-ux-master.md'),
+    path.join(root, '.windsurf', 'rules', 'ui-ux-master.md'),
+    path.join(root, '.antigravity', 'rules', 'ui-ux-master.md'),
+    path.join(root, '.cursor', 'rules', 'ui-ux-master.mdc'),
+  ];
+  for (const file of files) {
+    if (fs.existsSync(file)) {
+      if (dry) console.log(`[dry-run] remove ${file}`);
+      else { fs.rmSync(file, { force: true, recursive: true }); console.log(`removed ${file}`); }
+    }
+  }
+  for (const file of [path.join(root, 'AGENTS.md'), path.join(root, 'GEMINI.md'), path.join(root, '.windsurfrules')]) {
+    if (!fs.existsSync(file)) continue;
+    const old = fs.readFileSync(file, 'utf8');
+    const re = new RegExp(`${escapeRegExp(markerStart)}[\\s\\S]*?${escapeRegExp(markerEnd)}\\n?`, 'm');
+    const next = old.replace(re, '').trimEnd() + '\n';
+    if (dry) console.log(`[dry-run] remove marker block from ${file}`);
+    else { fs.writeFileSync(file, next, 'utf8'); console.log(`updated ${file}`); }
+  }
+}
+
+function doctor(opts) {
+  const root = opts.scope === 'global' ? os.homedir() : findProjectRoot(opts.dir || process.cwd());
+  console.log(`ui-ux-master package root: ${packageRoot}`);
+  console.log(`target root: ${root}`);
+  console.log(`node: ${process.version}`);
+  console.log(`trigger: /ui-ux-master`);
+  const required = ['SKILL.md', 'README.md', 'references/ui-ux-complete-checklist.md', 'agent-templates/universal/ui-ux-master-trigger.md'];
+  let ok = true;
+  for (const rel of required) {
+    const exists = fs.existsSync(path.join(packageRoot, rel));
+    console.log(`${exists ? 'ok' : 'missing'} ${rel}`);
+    ok = ok && exists;
+  }
+  if (!ok) process.exitCode = 1;
+}
+
+function help() {
+  console.log(`UI/UX Master\n\nUsage:\n  ui-ux-master install [--project|--global] [--agents claude,codex,windsurf,antigravity,gemini,cursor,universal] [--dir path] [--dry-run]\n  ui-ux-master uninstall [--project] [--dir path] [--dry-run]\n  ui-ux-master doctor [--dir path]\n  ui-ux-master where\n\nAfter install, use: /ui-ux-master <your normal UI/UX prompt>`);
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.postinstall) {
+  console.log('ui-ux-master installed. Run `npx ui-ux-master install --project` inside a repo, then use `/ui-ux-master ...`.');
+} else if (opts.command === 'install') {
+  if (opts.scope === 'global') installGlobal(opts);
+  else installProject(findProjectRoot(opts.dir || process.cwd()), opts);
+} else if (opts.command === 'uninstall') {
+  uninstallProject(findProjectRoot(opts.dir || process.cwd()), opts);
+} else if (opts.command === 'doctor') {
+  doctor(opts);
+} else if (opts.command === 'where') {
+  console.log(packageRoot);
+} else {
+  help();
+}

package/docs/slash-command-compatibility.md

@@ -0,0 +1,58 @@
+# Slash Command Compatibility
+
+`/ui-ux-master` is the opt-in activation phrase for this package.
+
+## What `/ui-ux-master` Does
+
+When a user writes `/ui-ux-master`, the agent switches into the UI/UX Master workflow for that request: research-aware UX, IA, flows, design systems, accessibility, responsive states, content design, platform conventions, UI/UX memory, quality gates, and engineering handoff.
+
+If the user does not include `/ui-ux-master`, the skill should not be applied automatically.
+
+## Native Slash Commands vs Text Triggers
+
+Agent ecosystems are not consistent:
+
+- Some agents support native custom slash commands.
+- Some agents support project instruction files such as `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.windsurfrules`, or `.cursor/rules`.
+- Some agents only see normal prompt text.
+
+This package handles both models. Native slash commands are installed where available. Everywhere else, project instructions define `/ui-ux-master` as a plain-text opt-in trigger.
+
+## Supported Agents
+
+| Agent | Install target | Trigger behavior |
+|---|---|---|
+| Claude Code | `.claude/commands/ui-ux-master.md` | Native `/ui-ux-master` command |
+| Codex | `AGENTS.md` marked section | Type `/ui-ux-master` in the prompt |
+| Windsurf/Cascade | `.windsurf/rules/ui-ux-master.md` and optional `.windsurfrules` | Type `/ui-ux-master` in the prompt |
+| Antigravity | `AGENTS.md` / universal fallback | Type `/ui-ux-master` in the prompt |
+| Gemini CLI | `GEMINI.md` marked section | Type `/ui-ux-master` in the prompt |
+| Cursor | `.cursor/rules/ui-ux-master.mdc` | Type `/ui-ux-master` in the prompt |
+| Other agents | `agent-templates/universal/ui-ux-master-trigger.md` | Copy the trigger into the agent's instruction file |
+
+## Project-local Install
+
+Project-local install is recommended because it keeps activation scoped to a repository and copies the skill source into `.ui-ux-master/` so all agents can find it, including no-save `npx` installs.
+
+```bash
+npx ui-ux-master install --project
+```
+
+## Global Install
+
+Global install creates reusable templates under your home directory and, where supported, user-level slash commands.
+
+```bash
+npm install -g ui-ux-master
+ui-ux-master install --global
+```
+
+## Troubleshooting
+
+- If `/ui-ux-master` does nothing, your agent may not support native slash commands. Add the universal trigger text to the agent's project instructions.
+- If the agent applies the skill too often, ensure the installed rule says "activate only when the user writes `/ui-ux-master`."
+- If project instructions already have a UI/UX rule, merge carefully and preserve the `/ui-ux-master:start` and `/ui-ux-master:end` markers.
+
+## Security and Consent
+
+The installer should not overwrite existing agent instruction files without marker-based replacement. Review generated instruction files before committing them to a shared repository.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "ui-ux-master",
+  "version": "1.1.0",
+  "description": "One-stop UI/UX master skill for AI agents with opt-in /ui-ux-master activation across Claude, Codex, Windsurf, Antigravity, Gemini, Cursor, and universal agents.",
+  "type": "module",
+  "bin": {
+    "ui-ux-master": "./bin/ui-ux-master.mjs"
+  },
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "LICENSE",
+    "package.json",
+    "references/",
+    "templates/",
+    "agent-templates/",
+    "docs/",
+    "bin/",
+    "scripts/",
+    "tests/"
+  ],
+  "scripts": {
+    "validate": "python scripts/validate_skill.py --release",
+    "test": "node --test tests/*.test.mjs",
+    "prepack": "npm run validate && npm test",
+    "build:zip": "python scripts/build_deployment_zip.py"
+  },
+  "keywords": [
+    "ai-agent",
+    "ui",
+    "ux",
+    "ui-ux",
+    "design-system",
+    "accessibility",
+    "wcag",
+    "claude-code",
+    "codex",
+    "windsurf",
+    "antigravity",
+    "gemini-cli",
+    "cursor",
+    "slash-command",
+    "agent-skill",
+    "frontend"
+  ],
+  "license": "MIT",
+  "author": "UI/UX Master contributors",
+  "engines": {
+    "node": ">=18"
+  },
+  "preferGlobal": true,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/accessibility-advanced-patterns.md

@@ -0,0 +1,43 @@
+# Advanced Accessibility Patterns
+
+Use this reference when designing or implementing complex interactive components beyond simple links, buttons, and forms.
+
+## Core Rule
+
+Use native HTML first. Add ARIA only when native semantics cannot express the pattern. Bad ARIA is worse than no ARIA.
+
+## Complex Widget Checklist
+
+- Dialog/modal: focus moves in, is trapped, Escape closes if safe, focus returns to opener.
+- Tabs: arrow-key navigation, selected state, panel association.
+- Accordion: button semantics, expanded state, heading structure.
+- Menu: correct role only for application menus, keyboard support, Escape, typeahead if useful.
+- Combobox/autocomplete: label, active descendant or focus strategy, listbox relationship, keyboard behavior.
+- Tooltip: not required to complete task, available on focus and hover.
+- Toast/live region: polite/assertive only as appropriate, not focus stealing.
+- Data grid: row/column headers, keyboard model, sort state, accessible names.
+- Drag and drop: provide keyboard and non-drag alternative.
+
+## WCAG 2.2 Criteria to Remember
+
+- Focus Appearance.
+- Dragging Movements.
+- Target Size.
+- Consistent Help.
+- Accessible Authentication.
+- Redundant Entry.
+
+## Testing Matrix
+
+At minimum test:
+
+- Keyboard only.
+- Browser zoom 200%.
+- Reduced motion.
+- High contrast/forced colors where relevant.
+- Screen reader smoke test: NVDA/JAWS on Windows, VoiceOver on Apple, TalkBack on Android as applicable.
+- Touch target size and orientation changes on mobile.
+
+## Accessible Handoff
+
+For each complex component specify role/semantic element, name, state, keyboard interaction, focus behavior, announcements, and fallback behavior.

package/references/competitive-landscape.md

@@ -0,0 +1,47 @@
+# Competitive Landscape and Differentiation
+
+This reference summarizes the open-source/UI-agent landscape checked while improving UI/UX Master.
+
+## What Existing Tools Do Well
+
+- `skills` / open agent skills ecosystem: broad multi-agent distribution and many supported agent names.
+- `bentoskills`: simple npm-based installation for Claude-oriented UI/UX skills.
+- `extract-design-system`: strong focused capability for extracting design tokens from public websites and packaging it as a CLI/agent skill.
+- `@assistant-ui/react`: production-grade React components for AI chat interfaces.
+- `@figma/code-connect`: strong design-to-code component mapping for Figma and codebases.
+- Mature design systems such as GOV.UK Frontend, Salesforce Lightning, Material, Carbon, Atlassian, and Fluent: strong component guidance and production CSS/component foundations.
+
+## Where Narrow Skills Often Outperform Generic UI Prompts
+
+- They are easier to install.
+- They have a simple trigger or CLI.
+- They focus on one concrete task, such as token extraction or component mapping.
+- Some have npm packaging and tests.
+- Some integrate with a specific agent's native command system.
+
+## Gaps UI/UX Master Must Beat
+
+UI/UX Master is designed to lead by combining the best parts:
+
+1. One simple opt-in trigger: `/ui-ux-master`.
+2. Cross-agent installation instead of one-agent lock-in.
+3. Full lifecycle coverage from research to handoff, not only visual polish.
+4. Project UI/UX memory for consistent branding across repeated work.
+5. Standards alignment across WCAG, WAI-ARIA, NN/g-style heuristics, GOV.UK service patterns, Material, Apple HIG, Microsoft, ISO HCD concepts, and Baymard-style ecommerce practice.
+6. Advanced risk coverage: privacy, ethics, dark patterns, high-risk domains, AI transparency, localization, and platform conventions.
+7. Release engineering: npm package, CLI installer, tests, validator, and deployment zip.
+
+## Remaining Honest Limitations
+
+- It does not replace specialized code libraries such as assistant-ui React components or GOV.UK Frontend CSS.
+- It does not extract live design tokens from websites by itself; pair it with token-extraction tools if needed.
+- It does not integrate directly with Figma APIs; pair it with Figma Code Connect or MCP/Figma tooling if needed.
+- It cannot replace real user research, accessibility expert review, or legal/domain review in high-risk contexts.
+
+## Strategy to Stay Ahead
+
+- Keep `/ui-ux-master` simple and opt-in.
+- Keep references standards-aligned and updated.
+- Add focused subcommands only when they preserve simplicity.
+- Validate every release with Python, Node tests, npm pack dry-run, zip extraction validation, and independent review.
+- Prefer concrete outputs: memory, specs, states, QA, acceptance criteria, and handoff.

package/references/content-design-and-i18n.md

@@ -0,0 +1,53 @@
+# Content Design and Internationalization
+
+Content is part of the interface. Agents must design words, labels, errors, empty states, and localization behavior deliberately.
+
+## Content Design Principles
+
+- Start with user task and context.
+- Use plain language and familiar vocabulary.
+- Put the most important information first.
+- Prefer specific verbs for actions.
+- Avoid jargon unless the target user uses it.
+- Write labels that predict the result of the action.
+- Use consistent terminology across screens.
+- Make errors explain what happened, why if useful, and how to recover.
+
+## Voice and Tone
+
+Define:
+
+- Voice: stable brand personality.
+- Tone: adapts to user emotion and risk.
+- Vocabulary: preferred terms, banned terms, product naming.
+- Reading level: simpler for broad audiences, precise for expert tools.
+
+## Microcopy Patterns
+
+- Button: verb + object when ambiguity exists, e.g. "Invite teammate".
+- Empty state: what is missing, why it matters, first action.
+- Error: problem + recovery + support if needed.
+- Success: confirm outcome and next step.
+- Loading: set expectation if longer than a moment.
+- Permission: explain access requirement and request path.
+
+## Inclusive Language
+
+Avoid stereotypes, unnecessary gendering, ableist wording, and culturally narrow examples. Do not imply blame when users make mistakes.
+
+## Internationalization Checklist
+
+- Text expansion: allow 30-50% longer strings where possible.
+- RTL/bidirectional layout: mirror layout where appropriate; do not mirror icons with fixed meaning.
+- Dates/times: use locale-aware formatting and time zones.
+- Numbers/currency: use locale-aware separators, symbols, precision.
+- Names: do not require Western first/last assumptions unless legally required.
+- Addresses/phones: support regional formats.
+- Plurals/gender: avoid concatenated strings that cannot translate correctly.
+- Sorting/search: consider accents, scripts, and transliteration.
+- Images/icons: avoid culture-specific metaphors unless validated.
+- Legal/regulatory copy: localize with qualified review.
+
+## Content Handoff
+
+Include final copy, alternatives, character limits, translation keys, dynamic variables, fallback text, and error states.

package/references/data-visualization-dashboard-ux.md

@@ -0,0 +1,46 @@
+# Data Visualization and Dashboard UX
+
+Use this reference for dashboards, reports, analytics, monitoring, admin panels, tables, and decision-support interfaces.
+
+## Dashboard Principles
+
+- Start with the decision the user must make.
+- Prioritize signal over decoration.
+- Show timeframe, unit, owner, freshness, and definitions.
+- Separate overview, diagnosis, and action.
+- Make drill-down paths clear.
+- Handle missing, stale, partial, loading, and error states.
+
+## Chart Selection
+
+- Line: trend over time.
+- Bar: compare categories.
+- Stacked bar: composition with caution.
+- Scatter: relationship or distribution.
+- Histogram: distribution.
+- Table: exact values, scanning, operational work.
+- KPI card: single important measure with context.
+- Avoid pie/donut charts for precise comparison.
+
+## Chart Quality Checklist
+
+- Title states insight or metric.
+- Axes are labeled and not misleading.
+- Units and timeframe are visible.
+- Baseline and scale are appropriate.
+- Colors are semantic and colorblind-safe.
+- Legends are close to data or labels are direct.
+- Annotations explain anomalies.
+- Uncertainty and estimates are labeled.
+- Screen-reader alternative or data table exists.
+
+## Tables and Data Grids
+
+- Support sorting, filtering, search, pagination/virtualization, column visibility, density controls, bulk actions, export, and row-level actions where relevant.
+- Keep keyboard navigation and focus visible.
+- Preserve user filters and table state when returning.
+- Provide empty, no-results, loading, stale, and permission states.
+
+## Alerting
+
+Avoid alert fatigue. Severity, owner, cause, time, impact, and next action must be clear.