UX Design Hub

Routes to specialist sub-skills or runs the built-in 7-step UX pipeline.

Hub Decision Tree

Request arrives
|
+-- Product planning (vision, roadmap, data model, export)?
|   -> Load: skillsdb://design-ux/design-os
|      (~/.agents/skills-db/design-ux/design-os/SKILL.md + references/)
|
+-- Visual design / .pen file / design sweep?
|   -> Use Pencil MCP tools (batch_design, get_screenshot, style guides)
|      Ref: skillsdb://design-ux/pencil for character/illustration work
|
+-- CLI / agentic UX patterns?
|   -> Load Phase 0.5 lev-ref patterns (below)
|
+-- UX pipeline (wireframes, flows, IA, JTBD)?
|   -> Run 7-step pipeline (this skill body)
|
+-- "What design skills exist?" / browse?
|   -> Query: ls ~/.agents/skills-db/design-ux/
|      Deep:  lev-skill resolve "{query}" --json
|
+-- Ambiguous?
    -> Ask one clarifying question, then route

Skills-DB Design Catalog (skillsdb://design-ux/*)

UX Thinking Patterns (scored, from skills-db)

Load from ~/.agents/skills-db/thinking/patterns/{name}/SKILL.md when reasoning depth needed:

Hub Shortcuts

UX Pipeline

Mode Parsing

Treat the user's message (including any /ux ... text) as the input.

• •

  If it contains full or interactive: ask a small set of clarifying questions first, then run step-by-step.

• •

  If it contains step N (N=1..7): run only that step and update artifacts.

• •

  If it contains continue: resume the most recent run folder under .lev/ux/.

• •

  Otherwise: AUTO mode. Run all 7 steps end-to-end and produce wireframes.

Output Location

Create a run folder:

• •RUN_DIR=.lev/ux/{YYYYMMDD-HHMMSS}-{slug}/

Write artifacts below. If resuming, reuse the existing RUN_DIR.

Artifacts (expected):

• •

  problem_spec.yaml

• •

  routed_skills.json

• •

  jobs.graph.json

• •

  task_graph.json

• •

  ia_schema.json

• •

  interaction_fsm.json

• •

  components.md

• •

  wireframes.md

• •

  summary.md

Phase -1: Setup (Deterministic)

1. •Create run dir and establish shell vars:

TS="$(date +%Y%m%d-%H%M%S)"
SLUG="$(printf '%s' "$USER_MSG" | tr '[:upper:]' '[:lower:]' | rg -o "[a-z0-9]+" | head -n 6 | paste -sd- -)"
RUN_DIR=".lev/ux/${TS}-${SLUG}"
mkdir -p "$RUN_DIR"

1. •Persist the raw request for traceability:

printf '%s\n' "$USER_MSG" > "$RUN_DIR/request.txt"

Phase 0: Prior Art (Fast)

1. •If bd exists and .beads/ exists:

• •bd list --status=open | rg -n "ux|design|wireframe|ia|flow" -i || true

1. •Scan local UX artifacts:

• •ls -t .lev/ux 2>/dev/null | head -n 10 || true

1. •Scan UI code quickly (keep it cheap):

• •rg -n "struct\\s+.*View\\b|SwiftUI|Navigation(Stack|SplitView)|TabView" apps packages extensions 2>/dev/null | head -n 50 || true

If you find relevant prior art, cite paths in summary.md and either extend it or explicitly supersede it.

Phase 0.5: Agentic UX Patterns (lev-ref)

Apply lev-ref patterns to all UX outputs (especially summary.md and any routed-skill handoff).

This phase doubles as the agentic-ux hub route. Load directly when asked about CLI design, progressive disclosure, or prompt steering — no need to run the full 7-step pipeline.

Key patterns:

• •CLI-as-Prompt: Every CLI surface is a prompt-steering opportunity
• •Progressive Disclosure: Metadata first, body on trigger, references on demand
• •Every Surface a Steering Attempt: Follow-ups, related skills, confidence inline
• •Audio Design: Consider sonic feedback for agent interactions

1. •Load lev-ref patterns:

sed -n '1,220p' docs/_inbox/lev-ref/SKILL.md

1. •Apply inline conventions (CLI-as-Prompt):

• •

  Add confidence lines like [85% confident] for key recommendations.

• •

  Add → Next: and → Related: follow-ups.

• •

  Add a short 💡 Tip: in summary.md if there's a non-obvious UX lesson.

Phase 0.6: Skills-DB Enrichment

Route to specialized skills using the Hub Decision Tree above.

1. •

   Check hub_routes (frontmatter) for trigger match against request keywords.

   • •If match -> load that skill, optionally resume pipeline at Step 3+.
2. •

   If no hub_route match, query skills-db dynamically:

# Design-ux category first (high-signal, 12 skills)
rg -l -i "{keywords}" ~/.agents/skills-db/design-ux/*/SKILL.md

# Broader search only if design-ux returns empty
lev-skill resolve "{keywords}" --json 2>/dev/null | jq '.results[:5]'

1. •If curated scores available, prefer higher-scored patterns:

grep -i "{keyword}" ~/.agents/skills-db/thinking/11-ui-ux/task.csv \
  | sort -t, -k8 -rn | head -3

1. •Emit routed_skills.json (keep existing schema for compatibility):

{ "request_terms": [...], "candidates": [...], "selected": [...] }

1. •

   Present discovered skills:

   • •1 clear match -> propose loading it
   • •2-3 matches -> ranked list, let user choose
   • •0 matches -> continue with built-in UX pipeline
2. •

   Continue pipeline regardless — routing enriches, never blocks.

Step 1: Problem Framing

Write problem_spec.yaml:

problem:
  statement: "{1-2 sentences}"
  for_whom: "{primary user segment}"
  constraints:
    - "{constraint}"
  success_criteria:
    - "{measurable outcome}"
  scope:
    in: ["{in}"]
    out: ["{out}"]

Rules:

• •

  Make success criteria measurable.

• •

  Keep scope boundaries crisp.

Step 2: Jobs To Be Done (JTBD)

Write jobs.graph.json:

{
  "jobs": [
    {
      "id": "job-1",
      "statement": "When I {situation}, I want to {motivation}, so I can {outcome}",
      "type": "functional",
      "triggers": ["{trigger}"],
      "user_types": ["{archetype}"]
    }
  ]
}

Rules:

• •

  Prefer progress language over feature language.

• •

  Include at least one emotional or social job if relevant.

Step 3: Task Decomposition

Write task_graph.json:

{
  "tasks": [
    {
      "id": "task-1",
      "name": "{verb} {object}",
      "entry_state": "{precondition}",
      "exit_state": "{postcondition}",
      "happy_path": ["{step}"],
      "failure_modes": ["{failure}"],
      "depends_on": []
    }
  ]
}

Rules:

• •

  Include failure modes and recovery paths.

• •

  Keep tasks at a UI-actionable granularity.

Step 4: Information Architecture (IA)

Write ia_schema.json:

{
  "entities": [
    {"name": "{Entity}", "attributes": ["{attr}"], "actions": ["{verb}"]}
  ],
  "relationships": [
    {"from": "{Entity}", "to": "{Entity}", "type": "has_many"}
  ],
  "navigation": {
    "primary": ["{screen}"],
    "secondary": ["{screen}"]
  }
}

Rules:

• •Avoid navigation that doesn't map to an entity or job.

Step 5: Interaction Models

Write interaction_fsm.json:

{
  "screens": [
    {
      "id": "screen-1",
      "name": "{Screen Name}",
      "states": ["idle", "loading", "empty", "error", "success"],
      "transitions": [
        {"from": "idle", "event": "tap_primary", "to": "loading"}
      ],
      "feedback": ["spinner", "toast"]
    }
  ]
}

Rules:

• •

  Explicitly model loading, empty, and error states.

• •

  Call out accessibility considerations if there's complex interaction.

Step 6: Components

Write components.md:

• •

  Reusable components list (name, purpose, props/data).

• •

  Screens-to-components mapping.

Rules:

• •

  Prefer composable components over mega-views.

• •

  Name components after user intent (not implementation).

Step 7: Wireframes

Write wireframes.md:

• •

  A short global nav map.

• •

  For each screen:

• •

  Purpose (one line).

• •

  Primary actions (1-3).

• •

  Layout: header/body/footer sections.

• •

  State variants: idle/loading/empty/error/success.

If the user asks for a design-file deliverable, propose using the pencil tool to generate a .pen wireframe and confirm the target path under .lev/ux/.

Final Summary

Write summary.md:

• •

  Problem + success criteria.

• •

  Key tradeoffs and open questions.

• •

  The wireframe screen list (ordered).

• •

  What to implement first (smallest shippable slice).

• •

  Include lev-ref inline conventions: [N% confident], → Next:, and 💡 Tip:.

Technique Map

• •Identify scope — Determine what the skill applies to before executing.
• •Follow workflow — Use documented steps; avoid ad-hoc shortcuts.
• •Verify outputs — Check results match expected contract.
• •Handle errors — Graceful degradation when dependencies missing.
• •Reference docs — Load references/ when detail needed.
• •Preserve state — Don't overwrite user config or artifacts.

Technique Notes

Skill-specific technique rationale. Apply patterns from the skill body. Progressive disclosure: metadata first, body on trigger, references on demand.

Prompt Architect Overlay

Role Definition: Specialist for ux domain. Executes workflows, produces artifacts, routes to related skills when needed.

Input Contract: Context, optional config, artifacts from prior steps. Depends on skill.

Output Contract: Artifacts, status, next-step recommendations. Format per skill.

Edge Cases & Fallbacks: Missing context—ask or infer from workspace. Dependency missing—degrade gracefully; note in output. Ambiguous request—clarify before proceeding.