agentleFS
sametcelikbicaksametcelikbicak/opencode-team/skills/team-ux/SKILL.md

team-ux

Skill69 starsChanged 19 days agoMITView on GitHub

UX design specification writing. Screen flows, state inventory, component list, accessibility and mobile behavior. The playbook of the ux role.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If the same button style was copied in three places, it should be a single component.

    line 45
  2. Distinctive:

    Check for each screen:

    line 49
  3. Distinctive:

    Keyboard: all interactive elements are keyboard reachable, the tab order is logical, when a modal opens the focus stays inside and Esc …

    line 51

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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 Design Specification

You are writing a specification, not pixels. Implementation details are the developer's job.

1. Main flow

For each flow:

Flow: <what they want to do>
1. <screen> — what the user sees, what they can do, what decision they make
2. <screen> — ...
3. <result screen>

Each step must answer "what can the user do here?". If there is no answer, the step is unnecessary.

2. Screen inventory

ScreenPurposeEntryExitStates

The states column is mandatory for every screen:

StateWhat is shownWhat can be done
Loadingskeleton loadercancel
Emptytext explaining what to do + a primary actiontrigger the action
Errorwhat happened + what will happentry again / support
Populatedthe contentinteract with the content
Unauthorizedaccess denied + whygo back / support

The empty state is the most frequently forgotten one and the most expensive one: the user meeting an empty screen on first open kills the product.

3. Component inventory

ComponentWhere it is usedStatesNote

If the same button style was copied in three places, it should be a single component. Every repeated interface piece goes in here.

4. Accessibility (WCAG 2.1 AA)

Check for each screen:

  • Keyboard: all interactive elements are keyboard reachable, the tab order is logical, when a modal opens the focus stays inside and Esc closes it.
  • Focus: a visible focus ring (do not remove it). When the page changes, focus moves to the top.
  • Contrast: text 4.5:1, large text and icons 3:1.
  • Screen reader: meaningful aria-label, role, aria-live (for state changes), form errors linked with aria-describedby.
  • Color does not carry meaning alone: an error is not only red, it also has an icon + text.
  • Motion: prefers-reduced-motion is supported.
  • Touch target: at least 44x44 px.

5. Mobile behavior

  • Screen < 768px: which components are hidden, which are rearranged?
  • Table: horizontal scroll or cards?
  • Modal: full screen?
  • Form: single column or grouped?
  • Is there a bottom navigation, and how many items?

6. Tone and microcopy

  • Button text: names the action ("Save Invoice", "Send", not "OK").
  • Error message: what happened + what to do ("The invoice could not be uploaded. The file must be smaller than 10 MB.")
  • Empty state text: what will happen ("You have no invoices yet. Upload your first invoice" + button).
  • Confirmation: is it reversible, or not?

Common mistakes

MistakeThe right way
Giving color codesDefine hierarchy and behavior
Only the "happy path"Empty/error/loading/unauthorized are mandatory
Skipping the error stateShow errors on every form field
Thinking about accessibility laterAn AA check for every screen
"John Doe" sample dataRealistic, localized sample data

Output format

Markdown. Sections: Main flow / Screen inventory / Component inventory / Accessibility notes / Mobile behavior / Microcopy.

In the user's language (Turkish or English).

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.