ui-ux-master 1.1.0

package/scripts/validate_skill.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+"""Validate the UI/UX skill package.
+
+Dependency-free by design so the package can be checked on a fresh machine.
+Use --release for stricter deployment packaging checks.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SKILL = ROOT / "SKILL.md"
+PACKAGE = ROOT / "package.json"
+
+REQUIRED = [
+    "README.md",
+    "LICENSE",
+    "package.json",
+    "bin/ui-ux-master.mjs",
+    "docs/slash-command-compatibility.md",
+    "agent-templates/claude/commands/ui-ux-master.md",
+    "agent-templates/universal/ui-ux-master-trigger.md",
+    "agent-templates/codex/AGENTS.append.md",
+    "agent-templates/windsurf/rules/ui-ux-master.md",
+    "agent-templates/antigravity/AGENTS.append.md",
+    "agent-templates/gemini/GEMINI.append.md",
+    "agent-templates/cursor/rules/ui-ux-master.mdc",
+    "references/ui-ux-complete-checklist.md",
+    "references/ui-ux-frontend-implementation-rules.md",
+    "references/ui-ux-memory-workflow.md",
+    "references/wcag-aa-quick-reference.md",
+    "references/design-system-playbook.md",
+    "references/top-100-brand-website-analysis.md",
+    "references/ux-research-methods.md",
+    "references/usability-heuristics.md",
+    "references/platform-guidelines.md",
+    "references/content-design-and-i18n.md",
+    "references/ux-measurement-quality-gates.md",
+    "references/ethical-inclusive-design.md",
+    "references/service-design-journey-mapping.md",
+    "references/data-visualization-dashboard-ux.md",
+    "references/accessibility-advanced-patterns.md",
+    "references/ui-ux-curriculum-and-standards.md",
+    "references/competitive-landscape.md",
+    "templates/ui-ux-brief.md",
+    "templates/ui-ux-memory.md",
+    "templates/ui-ux-audit-report.md",
+    "templates/component-spec.md",
+    "templates/design-system-spec.md",
+    "templates/top-brand-frontend-spec.md",
+    "scripts/build_deployment_zip.py",
+    "tests/install-smoke.test.mjs",
+]
+
+REQUIRED_PHRASES = [
+    "Information Architecture",
+    "User Flows",
+    "Accessibility",
+    "Design Systems",
+    "Responsive",
+    "Handoff",
+    "WCAG",
+    "Screen State Checklist",
+    "Top-Brand Frontend Method",
+    "UI/UX memory",
+    "research",
+    "heuristic",
+    "platform",
+    "content design",
+    "Internationalization",
+    "Measurement and Quality Gates",
+    "Ethics",
+    "privacy",
+    "/ui-ux-master",
+    "Cross-Agent Activation",
+]
+
+REQUIRED_HEADINGS = {
+    "README.md": ["## Install with npm", "## Supported Agents", "## Competitive Positioning", "## Validation and Testing", "## Deployment Readiness Checklist"],
+    "docs/slash-command-compatibility.md": ["## What `/ui-ux-master` Does", "## Native Slash Commands vs Text Triggers", "## Supported Agents"],
+    "references/ux-research-methods.md": ["## Research Decision Tree", "## Research Plan Template", "## Evidence Confidence Levels"],
+    "references/usability-heuristics.md": ["## Nielsen's 10 Usability Heuristics", "## Severity Rating"],
+    "references/platform-guidelines.md": ["## Web App", "## iOS / Apple Platforms", "## Android / Material", "## Cross-Platform Rule"],
+    "references/content-design-and-i18n.md": ["## Content Design Principles", "## Internationalization Checklist"],
+    "references/ux-measurement-quality-gates.md": ["## Metric Selection", "## Quality Gate Template"],
+    "references/ethical-inclusive-design.md": ["## Dark Pattern Checks", "## Privacy UX", "## Inclusive Design"],
+    "references/service-design-journey-mapping.md": ["## Journey Map Elements", "## Service Blueprint Elements"],
+    "references/data-visualization-dashboard-ux.md": ["## Dashboard Principles", "## Chart Selection", "## Tables and Data Grids"],
+    "references/accessibility-advanced-patterns.md": ["## Complex Widget Checklist", "## Testing Matrix"],
+    "references/ui-ux-curriculum-and-standards.md": ["## Beginner Foundations", "## Intermediate Practice", "## Advanced Practice"],
+    "references/competitive-landscape.md": ["## What Existing Tools Do Well", "## Gaps UI/UX Master Must Beat", "## Strategy to Stay Ahead"],
+    "templates/ui-ux-brief.md": ["## Research and Evidence Plan", "## Constraints", "## Deliverables Needed"],
+    "templates/ui-ux-audit-report.md": ["## Heuristic Findings", "## Measured Evidence and Quality Gates"],
+    "templates/component-spec.md": ["## Acceptance Criteria and Test Matrix"],
+    "templates/design-system-spec.md": ["## Governance"],
+    "templates/top-brand-frontend-spec.md": ["## 11. Quality Gates", "## 12. Do Not Copy"],
+}
+
+
+def fail(message: str) -> None:
+    print(f"FAIL: {message}")
+    sys.exit(1)
+
+
+def warn(message: str) -> None:
+    print(f"WARN: {message}")
+
+
+def parse_frontmatter(content: str) -> tuple[dict[str, str], str]:
+    if not content.startswith("---\n"):
+        fail("SKILL.md must start with YAML frontmatter at byte 0")
+    end_marker = content.find("\n---\n", 4)
+    if end_marker == -1:
+        fail("SKILL.md frontmatter is not closed")
+    frontmatter_text = content[4:end_marker]
+    body = content[end_marker + 5 :]
+    if not body.strip():
+        fail("SKILL.md body is empty")
+    frontmatter: dict[str, str] = {}
+    for raw_line in frontmatter_text.splitlines():
+        if not raw_line or raw_line.startswith(" ") or raw_line.lstrip().startswith("#"):
+            continue
+        if ":" in raw_line:
+            key, value = raw_line.split(":", 1)
+            frontmatter[key.strip()] = value.strip().strip('"').strip("'")
+    return frontmatter, body
+
+
+def skill_version() -> str:
+    fm, _ = parse_frontmatter(SKILL.read_text(encoding="utf-8"))
+    return fm.get("version", "")
+
+
+def check_required_files() -> None:
+    for rel in REQUIRED:
+        path = ROOT / rel
+        if not path.exists():
+            fail(f"missing supporting file: {rel}")
+        text = path.read_text(encoding="utf-8")
+        min_len = 150 if rel.endswith((".json", ".mjs")) else 200
+        if len(text.strip()) < min_len:
+            fail(f"supporting file too small or empty: {rel}")
+
+
+def check_required_headings() -> None:
+    for rel, headings in REQUIRED_HEADINGS.items():
+        text = (ROOT / rel).read_text(encoding="utf-8")
+        for heading in headings:
+            if heading not in text:
+                fail(f"{rel} missing heading: {heading}")
+
+
+def check_skill_frontmatter_and_body() -> None:
+    if not SKILL.exists():
+        fail("SKILL.md is missing")
+    content = SKILL.read_text(encoding="utf-8")
+    fm, body = parse_frontmatter(content)
+    for key in ["name", "description", "version", "author", "license", "metadata"]:
+        if key not in content.split("---", 2)[1]:
+            fail(f"frontmatter missing {key}")
+    name = fm.get("name", "")
+    if not re.fullmatch(r"[a-z0-9][a-z0-9-]{0,63}", name):
+        fail("name must be lowercase hyphenated and <=64 chars")
+    description = fm.get("description", "")
+    if len(description) > 1024:
+        fail("description must be <=1024 chars")
+    if not description.startswith("Use when"):
+        fail('description should start with "Use when"')
+    if len(content) > 100_000:
+        fail("SKILL.md exceeds 100,000 characters")
+    if len(content) > 45_000:
+        warn("SKILL.md is getting large; keep detailed material in references/")
+    lower_body = body.lower()
+    for phrase in REQUIRED_PHRASES:
+        if phrase.lower() not in lower_body:
+            fail(f"SKILL.md missing required phrase: {phrase}")
+
+
+def check_package_json() -> None:
+    try:
+        data = json.loads(PACKAGE.read_text(encoding="utf-8"))
+    except Exception as exc:
+        fail(f"package.json is invalid JSON: {exc}")
+    for key in ["name", "version", "description", "type", "bin", "files", "scripts", "license", "engines"]:
+        if key not in data:
+            fail(f"package.json missing {key}")
+    if data["name"] != "ui-ux-master":
+        fail("package.json name must be ui-ux-master")
+    if data["version"] != skill_version():
+        fail("package.json version must match SKILL.md version")
+    if data.get("license") != "MIT":
+        fail("package.json license must be MIT")
+    if data.get("bin", {}).get("ui-ux-master") != "./bin/ui-ux-master.mjs":
+        fail("package.json bin.ui-ux-master must point to ./bin/ui-ux-master.mjs")
+    for script in ["validate", "test", "prepack"]:
+        if script not in data.get("scripts", {}):
+            fail(f"package.json scripts missing {script}")
+    required_files = ["SKILL.md", "references/", "templates/", "agent-templates/", "docs/", "bin/", "scripts/", "tests/"]
+    for item in required_files:
+        if item not in data.get("files", []):
+            fail(f"package.json files missing {item}")
+
+
+def check_bin_installer() -> None:
+    text = (ROOT / "bin/ui-ux-master.mjs").read_text(encoding="utf-8")
+    if not text.startswith("#!/usr/bin/env node"):
+        fail("bin/ui-ux-master.mjs must have node shebang")
+    for phrase in ["install", "doctor", "uninstall", "--dry-run", "fileURLToPath", "/ui-ux-master", "copyProjectSkillAssets", ".ui-ux-master"]:
+        if phrase not in text:
+            fail(f"bin installer missing {phrase}")
+    forbidden = ["C:\\", "C:/xampp", "C:/Users", "/home/"]
+    for bad in forbidden:
+        if bad in text:
+            fail(f"bin installer contains local absolute path: {bad}")
+
+
+def check_agent_templates() -> None:
+    template_files = [rel for rel in REQUIRED if rel.startswith("agent-templates/") or rel.startswith("docs/")]
+    for rel in template_files:
+        text = (ROOT / rel).read_text(encoding="utf-8")
+        for phrase in ["/ui-ux-master", "UI/UX", "memory", ".ui-ux-master"]:
+            if phrase not in text:
+                fail(f"{rel} missing required trigger phrase: {phrase}")
+        for bad in ["C:\\", "C:/xampp", "C:/Users", "/workspace"]:
+            if bad in text:
+                fail(f"{rel} contains local absolute path: {bad}")
+    docs = (ROOT / "docs/slash-command-compatibility.md").read_text(encoding="utf-8")
+    for agent in ["Claude", "Codex", "Windsurf", "Antigravity", "Gemini", "Cursor", "native slash"]:
+        if agent not in docs:
+            fail(f"slash compatibility docs missing {agent}")
+
+
+def check_referenced_files_exist() -> None:
+    content = SKILL.read_text(encoding="utf-8")
+    refs = sorted(set(re.findall(r"`((?:references|templates|agent-templates|docs|bin|scripts)/[^`]+?\.(?:md|mjs|py)|README\.md)`", content)))
+    for rel in refs:
+        if rel in {"docs/ui-ux-memory.md", "docs/design/ui-ux-memory.md", "design/ui-ux-memory.md"}:
+            continue
+        if not (ROOT / rel).exists():
+            fail(f"SKILL.md references missing file: {rel}")
+
+
+def check_markdown_links() -> None:
+    for path in [ROOT / rel for rel in REQUIRED if rel.endswith(".md")]:
+        text = path.read_text(encoding="utf-8")
+        for match in re.findall(r"\[[^\]]+\]\(([^)]+)\)", text):
+            if match.startswith(("http://", "https://", "mailto:", "#")):
+                continue
+            target = (path.parent / match.split("#", 1)[0]).resolve()
+            if not target.exists():
+                fail(f"broken local markdown link in {path.relative_to(ROOT)}: {match}")
+
+
+def check_release_artifacts(strict: bool) -> None:
+    bad_patterns = [
+        "**/__pycache__",
+        "**/*.pyc",
+        "**/.DS_Store",
+        "**/Thumbs.db",
+        "graphify-out/cache",
+        "node_modules",
+        "coverage",
+        ".nyc_output",
+        "*.tgz",
+        "npm-debug.log*",
+    ]
+    found: list[str] = []
+    for pattern in bad_patterns:
+        for path in ROOT.glob(pattern):
+            found.append(str(path.relative_to(ROOT)))
+    if found:
+        message = "release artifacts found: " + ", ".join(sorted(found)[:20])
+        if strict:
+            fail(message)
+        warn(message)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--release", action="store_true", help="run stricter deployment packaging checks")
+    args = parser.parse_args()
+    check_skill_frontmatter_and_body()
+    check_required_files()
+    check_required_headings()
+    check_package_json()
+    check_bin_installer()
+    check_agent_templates()
+    check_referenced_files_exist()
+    check_markdown_links()
+    check_release_artifacts(strict=args.release)
+    print("PASS: UI/UX skill package is valid")
+    print(f"Root: {ROOT}")
+    print(f"Files checked: {1 + len(REQUIRED)}")
+    if args.release:
+        print("Release mode: PASS")
+
+
+if __name__ == "__main__":
+    main()

package/templates/component-spec.md

@@ -0,0 +1,127 @@
+# Component Spec
+
+## Component Name
+
+## Purpose
+
+What user problem does this component solve?
+
+## Platform and Context
+
+- Platform(s): web / iOS / Android / desktop / email / kiosk / other:
+- Existing component to reuse:
+- User task:
+- Accessibility risk level:
+
+## Anatomy
+
+- Container:
+- Header/title:
+- Body/content:
+- Leading icon/media:
+- Trailing action:
+- Supporting text:
+- Error/help text:
+
+## Variants
+
+- Default:
+- Primary:
+- Secondary:
+- Destructive:
+- Ghost/tertiary:
+- Custom variants:
+
+## Sizes
+
+- Small:
+- Medium:
+- Large:
+- Touch target minimum:
+
+## States
+
+- Default:
+- Hover:
+- Focus-visible:
+- Active/pressed:
+- Disabled:
+- Loading:
+- Selected/current:
+- Error:
+- Success:
+- Empty/no data:
+- Permission/offline if applicable:
+
+## Behavior
+
+- Click/tap:
+- Keyboard:
+- Focus management:
+- Open/close if applicable:
+- Validation if applicable:
+- Async behavior:
+- Escape/back behavior:
+
+## Accessibility
+
+- Semantic element/role:
+- Accessible name:
+- ARIA attributes if needed:
+- Keyboard support:
+- Focus indicator:
+- Contrast requirements:
+- Screen reader notes:
+- Reduced motion behavior:
+- Complex-widget pattern reference:
+
+## Content Guidelines
+
+- Label style:
+- Length limits:
+- Tone:
+- Examples:
+- Avoid:
+- Localization/text expansion notes:
+
+## Responsive Behavior
+
+- Mobile:
+- Tablet:
+- Desktop:
+- Wide:
+
+## Tokens Used
+
+- Color:
+- Typography:
+- Spacing:
+- Radius:
+- Elevation:
+- Motion:
+
+## Implementation Notes
+
+- Props/API:
+- Data requirements:
+- Events/analytics:
+- Error handling:
+- Tests:
+
+## Acceptance Criteria and Test Matrix
+
+| Requirement | Test | Pass Criteria |
+|---|---|---|
+| Default behavior |  |  |
+| Keyboard behavior |  |  |
+| Screen-reader behavior |  |  |
+| Responsive behavior |  |  |
+| Error/loading/empty states |  |  |
+| Localization/text expansion |  |  |
+| Visual regression |  |  |
+
+## Usage Examples
+
+### Good
+
+### Bad

package/templates/design-system-spec.md

@@ -0,0 +1,121 @@
+# Design System Spec
+
+## System Overview
+
+- Product:
+- Brand personality:
+- Platforms:
+- Accessibility target:
+- Tech stack:
+- Version:
+- Owners:
+
+## Foundations
+
+### Color Tokens
+
+| Token | Value | Usage |
+|---|---|---|
+| color.background |  | Page background |
+| color.surface |  | Cards/panels |
+| color.text.primary |  | Main text |
+| color.text.secondary |  | Secondary text |
+| color.border |  | Default borders |
+| color.primary |  | Primary actions |
+| color.danger |  | Destructive/status |
+| color.focus |  | Focus indicator |
+
+### Typography Tokens
+
+| Token | Size | Line height | Weight | Usage |
+|---|---:|---:|---:|---|
+| text.h1 |  |  |  |  |
+| text.h2 |  |  |  |  |
+| text.body |  |  |  |  |
+| text.label |  |  |  |  |
+| text.caption |  |  |  |  |
+
+### Spacing Tokens
+
+| Token | Value | Usage |
+|---|---:|---|
+| space.1 | 4px | Tight gaps |
+| space.2 | 8px | Small gaps |
+| space.3 | 12px | Component internals |
+| space.4 | 16px | Default gaps |
+| space.6 | 24px | Section gaps |
+| space.8 | 32px | Page/module gaps |
+
+### Radius, Elevation, Motion
+
+| Token | Value | Usage |
+|---|---|---|
+| radius.sm |  |  |
+| radius.md |  |  |
+| radius.lg |  |  |
+| shadow.sm |  |  |
+| shadow.md |  |  |
+| motion.fast | 120ms | Simple feedback |
+| motion.base | 180ms | Default transition |
+
+### Content, Localization, and Data Visualization Tokens
+
+- Voice/tone rules:
+- Error/empty/success copy patterns:
+- Locale and RTL rules:
+- Number/date/currency formats:
+- Chart color semantics:
+- Data density options:
+
+## Components
+
+For each component, include purpose, anatomy, variants, sizes, states, accessibility, content rules, responsive behavior, platform variants, acceptance criteria, and examples.
+
+### Button
+
+### Input
+
+### Select/Combobox
+
+### Checkbox/Radio/Switch
+
+### Modal/Dialog
+
+### Toast/Alert
+
+### Card
+
+### Table/Data Grid
+
+### Navigation
+
+### Empty State
+
+### Chart/Data Visualization
+
+## Patterns
+
+- Onboarding:
+- Search/filter:
+- Create/edit forms:
+- Destructive actions:
+- Permissions:
+- Loading and error recovery:
+- Notifications:
+- Checkout/payment if relevant:
+- Dashboard drill-down if relevant:
+- AI disclosure if relevant:
+
+## Governance
+
+- Contribution process:
+- Naming conventions:
+- Versioning:
+- Changelog:
+- Deprecation process:
+- Accessibility review process:
+- Content/i18n review process:
+- Platform variant review process:
+- Token release process:
+- Visual regression process:
+- Owner/approver:

package/templates/top-brand-frontend-spec.md

@@ -0,0 +1,133 @@
+# Top-Brand Frontend Spec Template
+
+Use this when the user wants a frontend that feels as polished as leading global brands without copying any single brand exactly.
+
+## 1. Product Context
+
+- Product name:
+- Category:
+- Primary user:
+- Primary task:
+- Business goal:
+- Platform:
+- Evidence confidence:
+
+## 2. Brand-Inspiration Blend
+
+Choose 2-3 compatible methods from `references/top-100-brand-website-analysis.md`.
+
+- Primary method:
+- Secondary method:
+- Optional accent method:
+
+Example blends:
+
+- Premium SaaS: Apple Product Cinema + Stripe/Adobe ecosystem clarity + IBM technical authority.
+- Ecommerce marketplace: Amazon utility + Airbnb card discovery + Target friendly retail.
+- Luxury product: Chanel restraint + Cartier detail + Apple product cinema.
+- Developer tool: IBM/NVIDIA technical authority + Vercel minimal precision + Linear dashboard discipline.
+- Food ordering: McDonald's/KFC direct ordering + Domino's tracking utility + Burger King playful brand.
+
+## 3. UX Structure
+
+- Primary entry point:
+- Main CTA:
+- Secondary CTA:
+- Navigation model:
+- Key sections:
+  1.
+  2.
+  3.
+  4.
+  5.
+
+## 4. Layout Rules
+
+- Hero layout:
+- Grid system:
+- Card style:
+- Section rhythm:
+- Sticky/persistent elements:
+- Mobile behavior:
+- Platform-specific behavior:
+
+## 5. Visual Language
+
+- Brand personality:
+- Color strategy:
+- Typography strategy:
+- Spacing density:
+- Radius/elevation:
+- Icon/imagery style:
+- Motion style:
+
+## 6. Components
+
+- Header/nav:
+- Hero:
+- CTA buttons:
+- Cards:
+- Forms/search:
+- Tables/lists if needed:
+- Testimonials/proof:
+- Pricing/comparison if needed:
+- Footer:
+
+## 7. States
+
+- Loading:
+- Empty:
+- Error:
+- Success:
+- Disabled:
+- Hover/focus/active:
+- Mobile menu:
+- Offline/permission/partial data if relevant:
+
+## 8. Accessibility
+
+- Semantic structure:
+- Keyboard behavior:
+- Focus states:
+- Contrast:
+- Reduced motion:
+- Labels and error messages:
+- Complex widget behavior:
+
+## 9. Copy System
+
+- H1:
+- Value proposition:
+- Primary CTA label:
+- Secondary CTA label:
+- Proof line:
+- Empty-state copy:
+- Error copy:
+- Localization/text expansion notes:
+
+## 10. Implementation Notes
+
+- Existing framework/components:
+- CSS approach:
+- Token names:
+- Data requirements:
+- Analytics events:
+- QA checks:
+
+## 11. Quality Gates
+
+- Primary task success criteria:
+- Accessibility gate:
+- Responsive/platform gate:
+- Performance perception gate:
+- Content/i18n gate:
+- Ethics/privacy gate:
+
+## 12. Do Not Copy
+
+- Do not copy brand logos.
+- Do not copy exact trademarked color combinations unless the user owns the brand.
+- Do not copy proprietary images or illustrations.
+- Do not copy exact page layouts pixel-for-pixel.
+- Extract reusable principles instead: hierarchy, spacing, structure, behavior, tone.
+- Verify current brand/site claims before citing them as facts.