agentleFS
mastro993mastro993/fstack/skills/ux-brainstorm/SKILL.md

ux-brainstorm

Skill3 starsChanged 13 days agoMITView on GitHub

Use when the user wants to brainstorm, explore, mock up, or prototype a UI or UX before building it, such as a new screen, flow, or component, a redesign, or "what should this look like?".

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ask with the question tool when the harness has one.

    line 17
  2. Distinctive:

    Ask about behavior, rules, scope, and edge cases.

    line 33
  3. Distinctive:

    Search by pattern with the kind of app ("add members dialog with search and multi-select").

    line 53
  4. Very specific:

    When a result carries an ai_usage_notice, show its text to the user word for word.

    line 56
  5. Distinctive:

    Copy: every string, icon, tooltip, and aria-label.

    line 94

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

UX brainstorm

You are the product designer on this feature. The user decides UX and product behavior; you decide architecture. Agree on behavior first, let prototypes settle layout, and finish with a plan an engineer can build from without reopening the conversation.

  • Area: one screen, component, or flow under decision (a library list, an add-member picker, a progress dialog). Each area gets one prototype.
  • Decisions: the agreed behavior, rules, scope, and edge cases, kept as numbered rules in decisions.md. Every prototype obeys them; a variant that can't express one is reported under Things to weigh (step 6), never quietly bent.
  • Direction: a visual stance backed by references ("dense triage table", "calm one-task cards"). Chosen only when the look is open.
  • Variant: one structural answer for an area (popover, side panel, own page). Variants disagree on layout, hierarchy, or primary affordance; recolors of one layout are one variant.
  • Lean copy: the prototype's words, cut to what icons and layout can't carry. Rules in references/prototyping.md.

Ask with the question tool when the harness has one; otherwise ask in chat.

Files: OUT holds what lasts, in <project>/.ux-brainstorm/<YYYYMMDD>-<slug>/, with .ux-brainstorm/ added to the file git rev-parse --git-path info/exclude prints (this works in worktrees too); outside a git repo, ./.ux-brainstorm/<YYYYMMDD>-<slug>/. RUN holds working files: the harness's scratchpad when it has one, otherwise OUT.

Subagents don't load this skill. Brief each with this file's path and the part it runs (step 3 for research; references/prototyping.md for builders and reviewers), plus decisions.md, references.md, and the base.

1. Map what exists

Learn what the project already answers before asking anything: what each affected screen shows and does today, the rules and data behind it, the component library, theme tokens (light and dark), icon set, glossary or domain docs, and real data shapes. Screenshot the running app when you can start it. With subagents, map in parallel.

When the request names the screens or components and the Mobbin MCP is available, start inspiration now, alongside the mapping (in a subagent when available). Without Mobbin, put "Where should I look for inspiration?", with step 3's options, into the first interview round. When no screen is named, start inspiration once the decisions exist.

Done when every point where the request conflicts with current behavior or leaves a rule open is listed in RUN/decisions.md as an open item. Those are your questions.

2. Interview to decisions

Ask about behavior, rules, scope, and edge cases. Layout belongs to the prototypes, and architecture is yours, so ask about neither. Ask in rounds of up to four questions, grouped by theme. Each question:

  • names the consequence the user will feel, in their words, without internal terms ("your agents' skill folders", not "global skill directory");
  • says so when an option changes how the app behaves today ("Changes today: removing a skill also deletes your edits");
  • offers your recommended option first, labeled (Recommended);
  • describes each option by what the user will see or lose.

With nothing to map, or when the request doesn't say what problem it solves, also cover what the request and the mapping leave open: who uses it and when, the job and its one primary action, content with realistic volumes, constraints (platform, brand, accessibility), products they like or dislike for this, and what's out of scope.

Push vague answers until they name a behavior: "simple" → which step goes away; "smart" → what it does on its own, and when. Taste answers ("clean", "like Linear") go to inspiration as references, not into decisions.

Name things with the glossary's terms in questions, decisions, and copy. When a domain word comes up that the glossary lacks or that means two things, settle it per the domain-driven-design skill's language rules; its questions join the next round.

After each round, turn the answered items in decisions.md into numbered rules. After the last round, restate the decisions in one message; when any answer was free text, ask the user to confirm the restatement before going on. Done when every open item, and every fallback item the request left open, has a decision.

3. Gather inspiration

With the Mobbin MCP (when its tools aren't listed yet, look them up with ToolSearch before calling them missing):

  • search_screens per screen, search_flows for multi-step journeys, search_sections for marketing-site sections.
  • Search by pattern with the kind of app ("add members dialog with search and multi-select"); a search by app name often misses the screen you need.
  • Mobbin covers web and iOS only. For desktop or Android, use web or iOS patterns as stand-ins and say so.
  • Record each reference in RUN/references.md under its area: its mobbin_url (the lasting link), its image_url (thumbnails for this run; expires in about 30 days), and one line on what it lends.
  • When a result carries an ai_usage_notice, show its text to the user word for word; a research subagent returns it to you for that.

Without it (tools missing, unauthenticated, or erroring), ask the user where to look: links or screenshots they have, apps they admire (you find screenshots with web search), galleries such as Dribbble, Behance, Land-book, or Page Flows, or an open web search.

Done when every area has at least two references, each with its link and what it lends, or the user chose to skip them.

4. Pick a direction, when the look is open

Skip this step inside an existing app with a component library or theme, unless the user asks for a new visual style. Asking what a screen should look like is about structure, which the variants answer.

Otherwise group the references into two or three directions that disagree on a real axis: density, navigation model, primary affordance, or tone. Give each a two- or three-word name, a one-line thesis, its references as thumbnails linked to the source, and its trade-off. Save them as one board, RUN/directions.html, render it (see Rendering), and ask the user to pick one or say what to mix. Done when they chose; add the choice to decisions.md.

5. Build the prototypes

Build one prototype per area, saved as RUN/<area>.html, following references/prototyping.md: the template, what every prototype holds, 2–4 variants each drawn from the area's references, and lean copy. With more than one area, build the shared base first; with subagents, one agent builds it, then one builder per area runs in parallel, telling each which variants to build.

Review each prototype before showing it, per that file's Review checklist (with subagents, one reviewer per prototype). Done when every prototype passed its review, and every gap a reviewer couldn't fix is listed for Things to weigh.

6. Let the user pick

Render each prototype without describing it. Then reply with:

  • Things to weigh: what the prototypes can't show, such as a variant that can't express a decision, an Undo that loses edits, or a new icon a variant needs.
  • The file paths, for viewing full width.
  • One compact pick prompt the user can answer in a line: "1. Library: A popover · B side panel · C own page. 2. Picker: A … · B …".

When the user mixes variants or asks for changes, add the result as a new letter beside the originals, review it, render it, and ask again. Done when the user approved one variant per area (a plain pick counts). Add each approval to decisions.md and set its prototype's <body data-first-variant> to it, so the file opens on the pick.

7. Hand off

Write the handoff into the project, never RUN, which may end with the session. Copy the approved prototypes, decisions.md, and references.md to OUT. OUT is git-ignored and local to this machine, so every record and issue must stand without it: describe each approved variant in words, add a light-theme screenshot of it (from the preview tool or a headless browser), and mark any OUT path as local. Attach the screenshot to each issue that builds that area; to embed it in a decision record, save it beside the record.

Use the project's own format when it has one: decision records that keep the alternatives the user rejected, glossary updates, and issues or tickets as vertical slices with dependency order, file:line references, and acceptance checks. Show the issue list, and file it in the tracker only once the user approves. Otherwise write OUT/spec.md. Either way, cover:

  • Decisions and picks: the decisions and the approved variant per area, in words with its screenshot, plus reference links and the local prototype path.
  • States: each area's states, what triggers them, and what they show.
  • Component map: each element → the project component that renders it, or, when none fits, the closest existing pattern to build it from. With no codebase, the platform's standard components.
  • Tokens: each color, size, radius, and spacing → the project token, or new.
  • Copy: every string, icon, tooltip, and aria-label.
  • Interactions: what each control does, keyboard and focus order.
  • Open questions.

Done when an engineer could build from the handoff alone: each decision is implemented by exactly one issue or spec section (decision records and the glossary may cite it), and every element and string appears in the component map and copy. Reply with the paths or links and a three-line summary, then ask whether to implement it now. On yes, build from the component map. Ask first before creating any new component or icon, when a match is unclear, and, with no codebase, about the stack and where the project lives.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.