first commit

文档润色流和知识库构建流/claude-scholar/skills/ui-ux-pro-max/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: ui-ux-pro-max
+description: This skill should be used when the user asks to design or review a UI, create a landing page or dashboard, choose colors or typography, improve accessibility, or implement polished frontend interfaces with a clear design system.
+version: 0.2.0
+---
+
+# UI/UX Pro Max
+
+Use this skill to turn a vague UI request into a **concrete design system plus implementation guidance**.
+
+## Role
+
+This skill is for:
+- design-system selection,
+- palette and typography choices,
+- UX review and remediation,
+- stack-aware frontend implementation guidance,
+- lightweight design-system persistence for multi-page work.
+
+It is **not** a replacement for product strategy or user research. Use it to make execution sharper after the product direction is already roughly known.
+
+## Core workflow
+
+### 1. Infer the request shape
+
+Extract the minimum design signals first:
+- product type,
+- industry,
+- style keywords,
+- target platform,
+- implementation stack.
+
+If the user does not specify a stack, default to `html-tailwind`.
+
+### 2. Generate the design system first
+
+Use the helper script to produce a compact design recommendation:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/ui-ux-pro-max/scripts/search.py" "<product_type> <industry> <keywords>" --design-system -p "Project Name"
+```
+
+This produces:
+- recommended style direction,
+- palette family,
+- typography direction,
+- interaction / visual effects,
+- landing or layout bias,
+- anti-patterns to avoid.
+
+If the work spans multiple turns or pages, persist the design system:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/ui-ux-pro-max/scripts/search.py" "<query>" --design-system --persist -p "Project Name"
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/ui-ux-pro-max/scripts/search.py" "<query>" --design-system --persist -p "Project Name" --page "dashboard"
+```
+
+This creates:
+- `design-system/MASTER.md`
+- optional page-level override notes under `design-system/pages/`
+
+### 3. Pull targeted guidance only when needed
+
+Use a focused search instead of loading everything at once:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/ui-ux-pro-max/scripts/search.py" "glassmorphism dark" --domain style
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/ui-ux-pro-max/scripts/search.py" "animation accessibility" --domain ux
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/ui-ux-pro-max/scripts/search.py" "real-time dashboard" --domain chart
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/ui-ux-pro-max/scripts/search.py" "elegant luxury serif" --domain typography
+```
+
+Supported domains:
+- `product`
+- `style`
+- `color`
+- `typography`
+- `landing`
+- `chart`
+- `ux`
+
+### 4. Add stack-specific guidance before coding
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/ui-ux-pro-max/scripts/search.py" "forms table responsive" --stack html-tailwind
+```
+
+Supported stacks:
+- `html-tailwind`
+- `react`
+- `nextjs`
+- `vue`
+- `svelte`
+- `swiftui`
+- `react-native`
+- `flutter`
+- `shadcn`
+- `jetpack-compose`
+
+### 5. Synthesize before implementation
+
+After gathering the design system, convert it into:
+- layout structure,
+- component rules,
+- visual tokens,
+- interaction rules,
+- accessibility constraints,
+- implementation notes for the chosen stack.
+
+Do not dump raw search output into the final answer. Use it to justify a coherent design direction.
+
+## Default output shape
+
+A good response should usually include:
+1. product and UI framing,
+2. recommended style system,
+3. palette and typography,
+4. component and layout rules,
+5. accessibility and interaction checks,
+6. stack-aware implementation notes.
+
+## Safety rules
+
+- Do not hardcode a design language without connecting it to the product type.
+- Do not use emoji as primary UI iconography.
+- Do not weaken text contrast for visual flair.
+- Do not scale interactive cards on hover if it destabilizes layout.
+- Do not use animation that violates `prefers-reduced-motion`.
+- Do not invent unsupported helper scripts or datasets; use the bundled `search.py` and `data/ui-reasoning.csv` only.
+
+## References
+
+Load only what is needed:
+- `references/USAGE.md` - recommended command patterns and retrieval flow
+- `data/ui-reasoning.csv` - compact product-to-design heuristics used by the helper script
+- `scripts/search.py` - deterministic helper for design-system, domain, and stack lookup

文档润色流和知识库构建流/claude-scholar/skills/ui-ux-pro-max/data/ui-reasoning.csv

@@ -0,0 +1,9 @@
+slug,keywords,style,palette,typography,effects,landing_pattern,anti_patterns,notes
+saas,"saas,software,productivity,b2b,platform",minimal-modern,slate-indigo,Inter + Space Grotesk,subtle shadows and crisp borders,hero + product proof,"low-contrast cards; decorative gradients that hide hierarchy",Optimize for clarity and scanability.
+fintech,"fintech,finance,banking,crypto,trading",trust-dark,navy-cyan,Inter + IBM Plex Sans,controlled glow with high contrast,hero + trust signals + metrics,"playful colors; weak contrast; noisy motion",Signal rigor and reliability.
+healthcare,"healthcare,medical,clinic,patient,biotech",clean-reassuring,teal-blue,Inter + Source Serif 4,soft surfaces and calm whitespace,problem -> trust -> workflow,"alarm-red emphasis everywhere; crowded dashboards",Reduce anxiety and keep forms obvious.
+beauty,"beauty,spa,wellness,skincare,salon",elegant-soft,rose-stone,DM Sans + Cormorant Garamond,soft blur and restrained glass,hero + treatments + testimonials,"harsh black blocks; neon accents; cluttered cards",Favor softness and premium restraint.
+ecommerce,"ecommerce,shop,store,retail,marketplace",conversion-clean,neutral-emerald,Inter + Manrope,clear elevation and strong CTA contrast,hero + product grid + reviews,"weak CTA hierarchy; oversized paragraphs",Prioritize trust and frictionless checkout.
+education,"education,learning,course,student,training",friendly-structured,blue-amber,Inter + Nunito,bright accents with clear cards,hero + curriculum + outcomes,"too much gamification; low information density",Balance warmth with instructional structure.
+portfolio,"portfolio,agency,studio,creator,personal",editorial-bold,charcoal-lime,Space Grotesk + Inter,bold type with restrained motion,hero + selected work + proof,"generic SaaS blocks; too many accent colors",Let typography carry distinction.
+dashboard,"dashboard,analytics,monitoring,admin,ops",data-dense,slate-cobalt,Inter + JetBrains Mono,compact panels and precise separators,summary row + filters + charts,"3D charts; crowded legends; uneven spacing",Optimize for comparison and rapid scanning.

文档润色流和知识库构建流/claude-scholar/skills/ui-ux-pro-max/references/USAGE.md

@@ -0,0 +1,21 @@
+# UI/UX Pro Max Usage
+
+## Recommended sequence
+
+1. Run `--design-system` first.
+2. Run one or two focused `--domain` queries only if the first pass leaves gaps.
+3. Run `--stack` before writing code.
+4. Persist the design system only if the project will span multiple pages or multiple turns.
+
+## Good queries
+
+- `fintech analytics dashboard trust serious`
+- `beauty spa wellness service elegant`
+- `developer tool docs clean minimal dark`
+- `education mobile app playful structured`
+
+## Persisted design system rule
+
+- `design-system/MASTER.md` is the default authority.
+- `design-system/pages/<page>.md` overrides the master only for that page.
+- Page files should record only deviations, not duplicate the whole master note.

文档润色流和知识库构建流/claude-scholar/skills/ui-ux-pro-max/scripts/search.py

@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import csv
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class DesignRule:
+    slug: str
+    keywords: tuple[str, ...]
+    style: str
+    palette: str
+    typography: str
+    effects: str
+    landing_pattern: str
+    anti_patterns: str
+    notes: str
+
+
+DOMAIN_LIBRARY = {
+    "style": [
+        {"name": "minimal-modern", "tags": {"saas", "productivity", "software"}, "summary": "Clean grids, restrained color, strong spacing rhythm."},
+        {"name": "trust-dark", "tags": {"fintech", "security", "analytics"}, "summary": "Dark surfaces with high-contrast metrics and controlled glow."},
+        {"name": "elegant-soft", "tags": {"beauty", "wellness", "premium"}, "summary": "Soft neutrals, editorial typography, gentle depth."},
+        {"name": "editorial-bold", "tags": {"portfolio", "studio", "creator"}, "summary": "Typography-led layouts with fewer but stronger components."},
+    ],
+    "color": [
+        {"name": "slate-indigo", "tags": {"saas", "b2b", "dashboard"}, "summary": "Reliable product palette with strong focus color."},
+        {"name": "navy-cyan", "tags": {"fintech", "security", "crypto"}, "summary": "Trust-heavy dark palette with crisp accent highlights."},
+        {"name": "teal-blue", "tags": {"healthcare", "medical", "education"}, "summary": "Calm, legible palette for guidance-heavy flows."},
+        {"name": "rose-stone", "tags": {"beauty", "wellness", "service"}, "summary": "Soft premium palette without losing contrast."},
+    ],
+    "typography": [
+        {"name": "Inter + Space Grotesk", "tags": {"saas", "dashboard", "tech"}, "summary": "Functional UI body with sharper display headlines."},
+        {"name": "Inter + IBM Plex Sans", "tags": {"fintech", "data", "ops"}, "summary": "Trustworthy and technical without feeling cold."},
+        {"name": "DM Sans + Cormorant Garamond", "tags": {"beauty", "luxury", "editorial"}, "summary": "Soft body copy plus premium display contrast."},
+        {"name": "Inter + Nunito", "tags": {"education", "learning", "friendly"}, "summary": "Warm, approachable pair for guided workflows."},
+    ],
+    "landing": [
+        {"name": "hero + product proof", "tags": {"saas", "b2b", "product"}, "summary": "Lead with problem, product UI, and trust proof."},
+        {"name": "hero + trust signals + metrics", "tags": {"fintech", "security"}, "summary": "Move quickly from promise to credibility to evidence."},
+        {"name": "hero + treatments + testimonials", "tags": {"beauty", "service"}, "summary": "Show the offering, then emotion, then social proof."},
+        {"name": "summary row + filters + charts", "tags": {"dashboard", "analytics", "ops"}, "summary": "Start with key numbers, then enable fast drill-down."},
+    ],
+    "chart": [
+        {"name": "line chart", "tags": {"trend", "time-series", "monitoring"}, "summary": "Use for change over time and directional narratives."},
+        {"name": "bar chart", "tags": {"comparison", "ranking", "category"}, "summary": "Use for category comparison with clear labels."},
+        {"name": "funnel chart", "tags": {"conversion", "checkout", "pipeline"}, "summary": "Use only when the user cares about progressive drop-off."},
+        {"name": "table + sparkline", "tags": {"dashboard", "ops", "dense"}, "summary": "Best when users must compare many rows quickly."},
+    ],
+    "ux": [
+        {"name": "contrast-first", "tags": {"accessibility", "contrast", "readability"}, "summary": "Keep body text at 4.5:1 or better and check muted states."},
+        {"name": "touch targets", "tags": {"mobile", "touch", "interaction"}, "summary": "Keep tap targets at 44x44px or larger."},
+        {"name": "motion restraint", "tags": {"animation", "performance", "a11y"}, "summary": "Prefer opacity/transform and honor reduced motion."},
+        {"name": "feedback locality", "tags": {"forms", "validation", "errors"}, "summary": "Place errors next to the field or action that caused them."},
+    ],
+    "product": [
+        {"name": "B2B SaaS", "tags": {"saas", "b2b", "workflow"}, "summary": "Prioritize clarity, trust, and information hierarchy."},
+        {"name": "consumer marketplace", "tags": {"ecommerce", "retail", "marketplace"}, "summary": "Prioritize CTA hierarchy and decision speed."},
+        {"name": "editorial portfolio", "tags": {"portfolio", "agency", "studio"}, "summary": "Let type and spacing carry most of the brand signal."},
+    ],
+}
+
+STACK_LIBRARY = {
+    "html-tailwind": [
+        "Use spacing and typography scales consistently; avoid arbitrary values unless they encode a real token.",
+        "Prefer semantic HTML first, then layer Tailwind utilities for layout and state.",
+        "Use visible focus rings, not shadow-only focus states.",
+    ],
+    "react": [
+        "Separate presentational components from stateful orchestration when the screen gets dense.",
+        "Memoize only after identifying re-render pressure; do not cargo-cult memo everywhere.",
+        "Keep loading, error, and empty states explicit in component contracts.",
+    ],
+    "nextjs": [
+        "Use server components for data-heavy static surfaces and client components only for interaction islands.",
+        "Optimize images and fonts early; layout shift hurts perceived polish.",
+        "Keep route segments and layout nesting readable; complexity leaks into UX fast.",
+    ],
+    "vue": [
+        "Keep composables focused and avoid mixing data fetching, presentation logic, and event plumbing in one file.",
+        "Use Pinia only when state truly spans multiple views.",
+        "Prefer explicit prop contracts over implicit slot conventions for complex widgets.",
+    ],
+    "svelte": [
+        "Use stores sparingly; local state is usually enough for page-scoped interaction.",
+        "Keep transitions subtle and intentional.",
+        "Use semantic markup because Svelte speed does not compensate for weak accessibility.",
+    ],
+    "swiftui": [
+        "Prefer a small number of reusable view modifiers instead of repeated inline styling.",
+        "Use state hoisting for reusable components.",
+        "Make navigation state obvious; hidden transitions confuse users quickly.",
+    ],
+    "react-native": [
+        "Design for touch targets and text scaling first.",
+        "Avoid over-nesting views; spacing bugs compound quickly on mobile.",
+        "Budget for offline and loading states in every primary screen.",
+    ],
+    "flutter": [
+        "Use a small, explicit theme surface; avoid per-widget color drift.",
+        "Keep widget trees readable by extracting repeated sections early.",
+        "Use platform-appropriate motion and haptics sparingly.",
+    ],
+    "shadcn": [
+        "Treat shadcn/ui as a starting system, not the finished product identity.",
+        "Normalize spacing and type across imported primitives before scaling the page.",
+        "Audit keyboard and dialog behavior after customization.",
+    ],
+    "jetpack-compose": [
+        "Keep state hoisting explicit and avoid business logic inside composables.",
+        "Use Material theming consistently before introducing custom tokens.",
+        "Measure recomposition hotspots before optimizing prematurely.",
+    ],
+}
+
+
+def load_rules(csv_path: Path) -> list[DesignRule]:
+    rows: list[DesignRule] = []
+    with csv_path.open(newline="", encoding="utf-8") as handle:
+        reader = csv.DictReader(handle)
+        for row in reader:
+            rows.append(
+                DesignRule(
+                    slug=row["slug"],
+                    keywords=tuple(token.strip() for token in row["keywords"].split(",") if token.strip()),
+                    style=row["style"],
+                    palette=row["palette"],
+                    typography=row["typography"],
+                    effects=row["effects"],
+                    landing_pattern=row["landing_pattern"],
+                    anti_patterns=row["anti_patterns"],
+                    notes=row["notes"],
+                )
+            )
+    return rows
+
+
+def score_rule(query_tokens: set[str], rule: DesignRule) -> int:
+    overlap = len(query_tokens & set(rule.keywords))
+    return overlap * 10 + (1 if rule.slug in query_tokens else 0)
+
+
+def pick_rule(query: str, rules: list[DesignRule]) -> DesignRule:
+    query_tokens = set(token.lower() for token in query.replace("-", " ").split())
+    return max(rules, key=lambda rule: (score_rule(query_tokens, rule), -len(rule.keywords)))
+
+
+def score_entry(query_tokens: set[str], entry: dict[str, object]) -> tuple[int, str]:
+    tags = set(entry.get("tags", set()))
+    score = len(query_tokens & tags)
+    return score, str(entry["name"])
+
+
+def top_domain_entries(domain: str, query: str, limit: int) -> list[dict[str, object]]:
+    query_tokens = set(token.lower() for token in query.replace("-", " ").split())
+    entries = DOMAIN_LIBRARY[domain]
+    ranked = sorted(entries, key=lambda entry: score_entry(query_tokens, entry), reverse=True)
+    return ranked[:limit]
+
+
+def render_design_system(rule: DesignRule, query: str, project: str | None, markdown: bool) -> str:
+    title = project or query.strip() or rule.slug
+    lines = [
+        f"# Design system: {title}" if markdown else f"Design system: {title}",
+        "",
+        f"- Query: {query}",
+        f"- Matched profile: {rule.slug}",
+        f"- Style direction: {rule.style}",
+        f"- Palette: {rule.palette}",
+        f"- Typography: {rule.typography}",
+        f"- Effects: {rule.effects}",
+        f"- Landing/layout bias: {rule.landing_pattern}",
+        f"- Avoid: {rule.anti_patterns}",
+        f"- Notes: {rule.notes}",
+    ]
+    return "\n".join(lines)
+
+
+def render_domain(domain: str, query: str, limit: int, markdown: bool) -> str:
+    entries = top_domain_entries(domain, query, limit)
+    header = f"# Domain lookup: {domain}" if markdown else f"Domain lookup: {domain}"
+    lines = [header, "", f"Query: {query}", ""]
+    for entry in entries:
+        lines.append(f"- {entry['name']}: {entry['summary']}")
+    return "\n".join(lines)
+
+
+def render_stack(stack: str, markdown: bool) -> str:
+    header = f"# Stack guidance: {stack}" if markdown else f"Stack guidance: {stack}"
+    lines = [header, ""]
+    for item in STACK_LIBRARY[stack]:
+        lines.append(f"- {item}")
+    return "\n".join(lines)
+
+
+def persist_design_system(text: str, page: str | None) -> list[Path]:
+    base = Path.cwd() / "design-system"
+    base.mkdir(exist_ok=True)
+    pages = base / "pages"
+    pages.mkdir(exist_ok=True)
+    created: list[Path] = []
+    master = base / "MASTER.md"
+    master.write_text(text + "\n", encoding="utf-8")
+    created.append(master)
+    if page:
+        page_path = pages / f"{page}.md"
+        page_path.write_text(
+            f"# Page override: {page}\n\n- Base authority: ../MASTER.md\n- Record only page-specific deviations here.\n",
+            encoding="utf-8",
+        )
+        created.append(page_path)
+    return created
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Search the bundled UI/UX guidance library.")
+    parser.add_argument("query", nargs="?", default="")
+    parser.add_argument("--design-system", action="store_true")
+    parser.add_argument("--domain", choices=sorted(DOMAIN_LIBRARY))
+    parser.add_argument("--stack", choices=sorted(STACK_LIBRARY))
+    parser.add_argument("--persist", action="store_true")
+    parser.add_argument("-p", "--project")
+    parser.add_argument("--page")
+    parser.add_argument("-n", type=int, default=5)
+    parser.add_argument("-f", "--format", choices=("ascii", "markdown"), default="ascii")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    markdown = args.format == "markdown"
+    script_dir = Path(__file__).resolve().parent
+    rules = load_rules(script_dir.parent / "data" / "ui-reasoning.csv")
+
+    if args.design_system:
+        rule = pick_rule(args.query, rules)
+        output = render_design_system(rule, args.query, args.project, markdown)
+        print(output)
+        if args.persist:
+            created = persist_design_system(output, args.page)
+            print("\nPersisted:")
+            for path in created:
+                print(f"- {path}")
+        return 0
+
+    if args.domain:
+        print(render_domain(args.domain, args.query, args.n, markdown))
+        return 0
+
+    if args.stack:
+        print(render_stack(args.stack, markdown))
+        return 0
+
+    print("No mode selected. Use --design-system, --domain, or --stack.")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())