Pinned items

Problem Context

• The product has many revisitable objects such as files, folders, repositories, gists, records, reports, channels, dashboards, or project links.
• Users or owners need a small set to remain visible even as recents, search results, or activity order changes.
• Pinned state may be personal, team-owned, public-profile, admin-managed, or policy-locked.
• A pin may control placement in a list, a top section, a profile showcase, a sidebar, a workspace home, or a document library.
• Pinned items can become deleted, moved, inaccessible, stale, over limit, duplicated, or controlled by someone else.

Selection Rules

• Choose pinned items when the user intentionally keeps a small set of known objects in a stable prominent position.
• Use recently viewed when the list should be automatic personal history ordered by what the user opened most recently.
• Use favorites when the user marks affinity or saved preference without necessarily changing item placement or order.
• Use saved view when the saved object is a reusable presentation or criteria state for one data surface.
• Use follow / subscribe when the user's intent is future update delivery rather than quick return access.
• Use custom dashboard when users arrange multiple widgets on a canvas rather than pinning individual objects or shortcuts.
• Expose whether a pin is personal, shared, public, admin-managed, or inherited before users add, remove, or reorder it.
• Cap pinned items to preserve scan speed and provide replace or reorder choices when the cap is reached.
• Keep unpin distinct from delete, archive, hide, unfavorite, unsubscribe, and remove-from-recent-history actions.
• Avoid pinned items when the item set is dynamic, unknown, recommended by an algorithm, or too large to remain meaningfully prominent.

Required States

• No pinned items state with a path to pin an eligible item.
• Pinned section with item identity, type, scope, position, and unpin controls.
• Pin available, pinned, unpin pending, unpinned, reorder, and replace-at-limit states.
• Personal pin, shared pin, public profile pin, inherited pin, and policy-locked pin states.
• Pinned item deleted, moved, permission-lost, stale, duplicate, and inaccessible states.
• Mobile or narrow-screen state where pinned identity, order, and unpin actions remain reachable.

Interaction Contract

• Pinning creates a durable placement or prominence record for the selected item without duplicating or changing the underlying item.
• Unpinning removes only the pin relationship and leaves the underlying item, favorite state, recent history, and subscriptions intact.
• Pinned items stay in the declared section or order until the user, owner, or policy changes them.
• Reordering pinned items updates visible order, keyboard order, and mobile order together.
• When the pin limit is reached, the UI asks users to unpin, replace, or reorder instead of silently dropping an existing pin.
• Shared or public pins require ownership, permission, and audience cues before the pin is changed.
• Deleted, moved, or permission-lost pinned items remain explainable with remove, replace, or request-access paths.
• Pin state is announced and reversible from the item context and from the pinned list.

Implementation Checklist

• Define the pin model with item ID, item type, owner, scope, position, pinned by, pinned time, policy lock, and visibility audience.
• Separate pin state from favorite state, recent history, saved view criteria, subscription state, and item deletion.
• Show pin and unpin controls with accessible pressed state or status text wherever pinning is available.
• Provide move earlier, move later, replace, unpin, restore, and limit-reached handling for pinned sections.
• Validate permissions and visibility before exposing shared, team, public profile, or admin-managed pins.
• Refresh pinned item metadata and mark deleted, moved, permission-lost, stale, or unavailable items before navigation.
• Test keyboard reordering, mobile stacking, long names, duplicate item names, pin limit, failed pin saves, and shared-scope conflicts.

Common Generated-UI Mistakes

• Using a pin icon as a favorite without changing placement or explaining selected state.
• Mixing pinned items with automatic recents, favorites, saved searches, subscriptions, and recommendations in one ambiguous list.
• Letting unpin delete or hide the underlying item.
• Allowing unlimited pins until the pinned section becomes another noisy list.
• Changing shared or public pins without owner, audience, permission, or rollback cues.
• Providing drag-only reorder with no keyboard move controls.
• Letting stale or inaccessible pinned items become dead links.

Critique Questions

• What placement, order, or audience changes when this item is pinned?
• Is the pin personal, shared, public, inherited, admin-managed, or policy locked?
• Can users unpin without deleting, unfavoriting, unsubscribing, or removing recent history?
• What is the maximum useful number of pinned items for this surface?
• How can users reorder pins by keyboard and understand mobile order?
• What happens when a pinned item is deleted, moved, renamed, archived, or no longer accessible?