Estimated 8 pts at Editing standup using following rubric (Peter may decide to adjust scope based on this estimate):

• 1 point = Small, ½ day. We feel we understand most requirements and consider it relatively easy.
• 2 points = Small-ish, roughly a day. Straightforward but may have known potential gotchas.
• 3 points = Medium, 1-2 days. We know what needs to be done, but there may be a few extra steps. Probably won’t need to research anything.
• 5 points = Medium-large, 2-3 days. This is complex work, or work we don’t do very often. Will likely involve research or consultation.
• 8 points = Large, ~1 week. Ideally completed in conjunction with another engineer to spread context and lift. May be a sign that a given task is too large and needs to be broken down further.
• 13 points and up = Extra large, > 1 week. We need to break this down further before it can be brought onto the sprint board.

Scope change

In T414518#11693753, @ldelench_wmf wrote:

Estimated 8 pts at Editing standup using following rubric (Peter may decide to adjust scope based on this estimate)...

In light of the complexity/size of this feature, as currently scoped, and in service of the Editing Team being aligned in wanting to ship more iteratively, I've cut scope that depends on us "storing" information about how/if someone is likely to have seen the single-use button in a previous edit session.

The task description should be updated to reflect the above. Of course, if there are pieces I've missed, please let me know.

Meta
Concretely, the above will amount to us removing the following bits of functionality from the initial implementation:

• ❌ The first time the “View suggestions” button is shown, it should subtly bounce to draw the user's attention.
• ❌ The first time: It will include just the arrow + "View suggestions" text.

As a result, the View suggestions button will never bounce and always include the ability for people to dismiss it by way of the X being present within it.

In doing so, I think we increase the likelihood of the following happening:

1. Removing the bounce could lower the likelihood that people notice the View suggestions button
2. Including the X the first time the View suggestions button is shown could reduce the likelihood that people will see a suggestion.

We will monitor the extent to which the above are happening in T419066 and from there, decide whether it's worth prioritizing to work to add in the functionality we are deciding to descope here. See T419066#11695346.

I've updated the prototype to include the decided solution for the "View suggestions" button in this implementation version:

• Removed the bouncing animation from the button for now
• The "View suggestions" button will appear, along with the ability to close the button, when entering edit mode on each edit session
• The “View suggestions” button disappears once clicked on it or once found and expanded the 1st suggestion while scrolling

https://bmartinezcalvo.github.io/suggestion-mode/preview/

Regarding founding the 1st suggestion while scrolling, what about automatically expanding the 1st suggestion once reached? This way, we will ensure the user finds at least the first suggestion, especially on mobile.

In implementing I'm comparing this to the "Reply to reply" feature in DiscussionTools and there are some technical reasons for the implementation details used there:

1. In DT the "up" variant appears at the top of the page. This places it close to where there hidden component is, and also avoids the technical issue of what to do when the floating widget intersects with the footer at the bottom of the page.

2. DT uses a standard button widget. The designed component differs from a normal button in padding, border radius, background colour (and presumably hover, active, focus states). This is a lot to re-implement when we already have button components, and would add a lot of technical and maintenance debt.

3. The DT version uses stem-less arrows (^/v) which appear to be more commonly used in MW, even though the arrows are available in the libraries. (cf pagination tools), and personally I think stemless looks better. We should be consistent either way:

Stemmed	Stemlesss

4. The nested close button: Having click areas within click areas creates a fiddly and confusing interaction component (missing the 'x' target slightly would trigger an unexpected action). It also seems unnecessary, if the user has no interest in suggestions they can close the whole sidebar, otherwise the button can just be ignored as it takes up no additional space.

Change #1259970 had a related patch set uploaded (by Esanders; author: Esanders):

[mediawiki/extensions/VisualEditor@master] Implement a scroll-into-view button for checks/suggestions

https://gerrit.wikimedia.org/r/1259970

It also seems unnecessary, if the user has no interest in suggestions they can close the whole sidebar, otherwise the button can just be ignored as it takes up no additional space.

Agreed about desktop, but it does take up non-sidebar space on mobile. There it'll be hovering over content. And we're currently not giving a toggle for suggestions on mobile because of how otherwise unobtrusive the gutter is...

Regarding founding the 1st suggestion while scrolling, what about automatically expanding the 1st suggestion once reached? This way, we will ensure the user finds at least the first suggestion, especially on mobile.

I don't like that as an experience on mobile -- expanding the suggestion suddenly takes up half the user's screen and maybe dismisses their keyboard, all for a reason that might not make sense to them if they don't care about suggestions.

In T414518#11745634, @DLynch wrote:

It also seems unnecessary, if the user has no interest in suggestions they can close the whole sidebar, otherwise the button can just be ignored as it takes up no additional space.

Agreed about desktop, but it does take up non-sidebar space on mobile. There it'll be hovering over content. And we're currently not giving a toggle for suggestions on mobile because of how otherwise unobtrusive the gutter is...

Yeah, I realised this when I implemented mobile. I still think the nested click target is not great, especially on mobile. I think we have a different design for new messages on DT that we can look at...

This is the DT component, which is a slightly modified ButtonGroupWidget (just increased border radius):

El T414518#11743210, @Esanders escribió:

In implementing I'm comparing this to the "Reply to reply" feature in DiscussionTools and there are some technical reasons for the implementation details used there:

1. In DT the "up" variant appears at the top of the page. This places it close to where there hidden component is, and also avoids the technical issue of what to do when the floating widget intersects with the footer at the bottom of the page.

I intentionally designed the button to remain in a fixed position, only changing the arrow direction, to avoid spatial jumps. If the button moves from bottom to top it could feel disorienting on mobile when switching from section edit to full-page edit, where the position of suggestions changes. Keeping the button in the same position keeps it consistent and reduces cognitive load, while the arrow direction already communicates where the next suggestion is located.

Widget in footer issue (not trivial to fix with CSS):

The button should always appear within the container where suggestions appear, I mean within the height of the article. I assume this is an issue also happening when the suggestions are below (when the button includes the arrow pointing down). So I think this is a specific issue with the footer to solve.

2. DT uses a standard button widget. The designed component differs from a normal button in padding, border radius, background colour (and presumably hover, active, focus states). This is a lot to re-implement when we already have button components, and would add a lot of technical and maintenance debt.

This is not a fully custom button. It’s based on the existing Primary Progressive Button, only adjusting to border-radius-pill which is one of our decision tokens so I guess is relatively low-cost to implement and maintain. I also used the large size already included in Codex Button. This highlights a gap between OOUI and the direction we’re moving towards with Codex. In some cases, we may need to evolve some OOUI components to better align with current design system standards, rather than limiting design decisions to legacy constraints.

4. The nested close button: Having click areas within click areas creates a fiddly and confusing interaction component (missing the 'x' target slightly would trigger an unexpected action). It also seems unnecessary, if the user has no interest in suggestions they can close the whole sidebar, otherwise the button can just be ignored as it takes up no additional space.

Regarding the close (X) action: this would indeed require an extension of the current button capabilities, since neither OOUI nor Codex supports this pattern today. If this adds significant complexity, we could evaluate whether this action should instead be handled as a separate adjacent control rather than part of the button itself.

3. The DT version uses stem-less arrows (^/v) which appear to be more commonly used in MW, even though the arrows are available in the libraries. (cf pagination tools), and personally I think stemless looks better. We should be consistent either way:

Stemmed	Stemlesss

From a UX perspective, and based on widely established interaction patterns:

⌄ (stemless) = standard pattern for expand/collapse (and also used for previous/next navigation)
↓ (stemmed) = more associated with scrolling

Since this button is to scroll to see a suggestion that was not visible in the viewport position, I think the ↓ arrow is more accurate.

Test wiki created on Patch demo by ESanders (WMF) using patch(es) linked to this task:
https://1459009920.catalyst.wmcloud.org/wiki/Regent's Park?veaction=edit&ecenable=experimental,suggestions

I intentionally designed the button to remain in a fixed position,
...
The button should always appear within the container where suggestions appear,

These two things are in conflict. This is quite difficult to achieve using CSS due to the footer issue highlighted (on desktop)

If the button moves from bottom to top it could feel disorienting when switching from section edit to full-page edit, where the position of suggestions changes.

I can see this would be an issue on mobile in section editing. Fortunately on mobile we don't have the footer issue we have on desktop.

It’s based on the existing Primary Progressive Button, only adjusting to border-radius-pill which is one of our decision tokens so I guess is relatively low-cost to implement and maintain. I also used the large size already included in Codex Button. This highlights a gap between OOUI and the direction we’re moving towards with Codex.

Agreed - although I think implementing OOUI large buttons is out of scope for this task. Note also the design is a "normal progressive button" (blue text on light blue background), which is still implemented as blue text on a grey background in OOUI (again, I think out of scope of this task to fix). "primary progressive" would be white text on a blue background (in both codex and OOUI).

I agree that just modifying the border-radius will result in minimal technical/maintenance burden.

Regarding the close (X) action: this would indeed require an extension of the current button capabilities, since neither OOUI nor Codex supports this pattern today.

As implemented above and in DiscussionTools - the button group allows us to do this quite neatly I think, avoiding the issue of nested click areas and giving clear interaction feedback (hover/focus states).

From a UX perspective, and based on widely established interaction patterns:

From a quick image search of "scroll to top", both appear to be widely used. We should update DiscussionTools if we go with arrows though.

El T414518#11753200, @Esanders escribió:

I can see this would be an issue on mobile in section editing. Fortunately on mobile we don't have the footer issue we have on desktop.

@Esanders is the footer issue affecting both button position when it appears on top and at the bottom on desktop? If yes, we will need to solve this issue anyway for when the button would appear at the bottom (suggestions below)

Agreed - although I think implementing OOUI large buttons is out of scope for this task. Note also the design is a "normal progressive button" (blue text on light blue background), which is still implemented as blue text on a grey background in OOUI (again, I think out of scope of this task to fix). "primary progressive" would be white text on a blue background (in both codex and OOUI).

I think aligning OOUI with Codex is important, especially for buttons since they communicate action hierarchy so inconsistent styles across pages could confuse users. While it may be out of scope for this task, we should create a task to align this. It would be great if we can move to Codex as well to avoid these inconsistencies in the future (or at least, align OOUI to Codex as much as possible).

As implemented above and in DiscussionTools - the button group allows us to do this quite neatly I think, avoiding the issue of nested click areas and giving clear interaction feedback (hover/focus states).

I agree on using a button group for this. Good solution.

From a quick image search of "scroll to top", both appear to be widely used. We should update DiscussionTools if we go with arrows though.

If this is possible, it would be great.

@Esanders is the footer issue affecting both button position when it appears on top and at the bottom on desktop? If yes, we will need to solve this issue anyway for when the button would appear at the bottom (suggestions below)

It only appears at the bottom when there are suggestions below, which means there is more of the edit surface below the bottom of the viewport, which means the footer can't be visible. As such showing the button at the top side-steps this issue (as you can see in the patch demo).

El T414518#11754652, @Esanders escribió:

@Esanders is the footer issue affecting both button position when it appears on top and at the bottom on desktop? If yes, we will need to solve this issue anyway for when the button would appear at the bottom (suggestions below)

It only appears at the bottom when there are suggestions below, which means there is more of the edit surface below the bottom of the viewport, which means the footer can't be visible. As such showing the button at the top side-steps this issue (as you can see in the patch demo).

ah ok, got it. In that case it makes more sense to move the button on top at least on desktop to avoid the issue.

Could you please add 32px spacing from the screen edges for both bottom and top buttons?

I've added the remaining issues (button colour, button size) to T386388, and updated the demo.

El T414518#11763144, @Esanders escribió:

I've added the remaining issues (button colour, button size) to T386388, and updated the demo.

@Esanders thank you. I've reviewed the patch updates and there are still the following things to fix:

1. The arrow is still using the cdxIconCollapse. It should use the cdxIconArrowDown instead (↑, ↓) as commented above. I assume we should do this change in both here and DiscussionTool.
2. The close button (X) should be the same style as the "View suggestions", using the Normal Progressive Button.
3. When using the “View suggestions” button on desktop, the auto-expanded card is not centered in the viewport, so part of it is cut off you need to manually scroll to see it fully.
4. When using the “View suggestions” button on mobile, the bottom sheet auto-expands before making the scroll to that suggestion, which is confusing. The scroll should occur first, before auto-expanding the card.

Apart from that, we will need to work in T386388 as soon as possible to style this "View suggestions" button as in Codex since, especially on mobile, the button is not visible enough in this size and style.

1. Fixed
2. Surely close is not a progressive action? (Everywhere else we have a close button it is unflagged). I see it is next another button which is progressive but it would still feel odd to have it be progressive?
3. This looks like an issue with the "duplicate link" check and our scroll-into-view functionality (it is scrolling the actionable link which is the second link, but the card aligns with the first link) - we should fix this separately.
4. Due to the way things are currently wired up, it's quite difficult to re-order the scroll and reveal. We should file a follow-up task to cleanup the animation order.

2. Surely close is not a progressive action? (Everywhere else we have a close button it is unflagged). I see it is next another button which is progressive but it would still feel odd to have it be progressive?

We should use the same flavour in both buttons so users feel it's part of the same button, even if in code they are 2 different buttons. This is how it was originally designed for this reason.

3. This looks like an issue with the "duplicate link" check and our scroll-into-view functionality (it is scrolling the actionable link which is the second link, but the card aligns with the first link) - we should fix this separately.

Created T421765 to fix this.

4. Due to the way things are currently wired up, it's quite difficult to re-order the scroll and reveal. We should file a follow-up task to cleanup the animation order.

Created T421764 to fix this.

Change #1259970 merged by jenkins-bot:

[mediawiki/extensions/VisualEditor@master] Implement a scroll-into-view button for checks/suggestions

https://gerrit.wikimedia.org/r/1259970

Moving to current sprint for me to review and close-out.

In T414518#11767112, @bmartinezcalvo wrote:

2. Surely close is not a progressive action? (Everywhere else we have a close button it is unflagged). I see it is next another button which is progressive but it would still feel odd to have it be progressive?

We should use the same flavour in both buttons so users feel it's part of the same button, even if in code they are 2 different buttons. This is how it was originally designed for this reason.

@Esanders: what is the status of the requirement you and Bárbara were discussing here?

@bmartinezcalvo: more broadly, what (if any) facets of the UX that is in scope for this task NOT yet implemented? I want to be sure everything is accounted before venturing to review and resolve this task.

El T414518#11832031, @ppelberg escribió:

@bmartinezcalvo: more broadly, what (if any) facets of the UX that is in scope for this task NOT yet implemented? I want to be sure everything is accounted before venturing to review and resolve this task.

1. View suggestions button needs to be updated to the large size T422031 and the updated version of the Progressive Neutral button T422032 (both tasks are now in Code Review).
2. “Edit full-page” button indicator on mobile: I guess this will be implemented instead in T422979. So removing from this task.

Priority
This task is a blocker for the start of the Suggestion Mode controlled experiment (T404600)

Observations:

1. Tapping the entry point scrolls to the 1st suggestion available, and this suggestion card expands when scrolling to it - ✅
2. The “View suggestions” button disappears once clicked on it or once found the 1st suggestion while scrolling, where the definition of found has been changed here in this comment but was not updated in the task description.

In T414518#11689547, @ppelberg wrote:

Per what @bmartinezcalvo and I discussed offline just now, we're going to move forward with the meaning of "found" described in T414518#11683955 and now reflected in the task description.

---

For the future: Bárbara also entered the possibility of implementing something like what she helpfully showed in T414518#11687599 with the addition of some visual cue that would, ideally, encourage people to tap the 💡.

3. The side rail seems to be overlapping with the appearance menu/tools menu, after resizing it down and up. Probably not relevant, but mentioning everything that's being observed.

4. The arrow icon indicates where the 1st suggestion is:

If the 1st suggestion is below the viewport position, it uses the cdxIconArrowDown
If the 1st suggestion is above the viewport position, it uses the cdxIconArrowUp
✅

5. On mobile, after tapping X on a suggestion card, it seems sometimes the keyboard is appearing and upon closing it, an empty suggestion card appears. {F77558604}
6. I am not seeing any suggestions ToggleButton on mobile: {F77580372}

In T414518#11527675, @ppelberg wrote:

@bmartinezcalvo: below are the refinements to the mobile prototype I think would be useful for us to explore...

Mobile UX (newcomer)

• Once people tap the "suggestions available" banner, have it disappear.

This happens for both Mobile UX (newcomer) and Mobile UX (experienced editor)

Mobile UX (experienced editor)

• Show the suggestion rail by default with any and all suggestions that have been activated in a collapsed state

happens for both Mobile UX (newcomer) and Mobile UX (experienced editor)

Mobile UX (newcomer and experienced)

• If >1 suggestion is available within the article you are editing, when you tap the "suggestions available" banner add the ability to navigate between said suggestions from within the suggestion card directly (rather than having to manually scroll the page to find it, as the prototype currently requires)
• Remove the floating 💡 button
• When people cause the suggestion card to appear (by way of tapping the "suggestions available" banner), add the ability for them to dismiss the suggestion mode card and content highlight by tapping either a) somewhere outside of the highlighted content span or b) the suggestion "rail"

Note: we'll revisit the desktop experience once we get mobile to a solid spot.

Not seeing any of these being implemented.

Test wiki on Patch demo by ESanders (WMF) using patch(es) linked to this task was deleted:

https://1459009920.catalyst.wmcloud.org/wiki/Regent's Park?veaction=edit&ecenable=experimental,suggestions

@ppelberg to decide on next steps based on QA outcomes