Project Brief
Designing a scalable tagging and filtering system for technical documentation.
I designed a multi-phase tagging and filter bar experience that helped Swimm users organize, discover, and manage documentation across workspaces.
Product Design
Developer Tools
SaaS
Design Systems
Feature Release
Role
UX/UI Design, Design Systems Designer, UXQA
Team
Product Manager, Engineering Manager, 3 Developers
Company
Swimm, a developer documentation platform for engineering teams.
Problem Space
Users need a more flexible way to organize and find documentation beyond playlists.
The only way to arrange documents in a workspace is through playlists: ordered lists of docs with a built-in progression model. That works well for onboarding, but not effective when teams want to group documentation by topic, feature area, workflow, or team ownership.
Project Goals
Create a flexible tagging system for organizing and finding documentation.
01 Organization
Give users a flexible way to group docs outside of linear playlists.
02 Discovery
Help teams browse, filter, and find documentation by shared metadata.
03 Scalability
Build a pattern that could expand from the editor into filters and tables.
Solution & Release Strategy
Tags - the solution that met both user needs and developer resources.
The phased approach let us validate the tagging model in a focused area first, then reuse the same pattern across higher-volume workflows.
01
Tagging inside the editor
Introduce tag creation, search, editing, and reuse within the existing right-side panel.
02
Filtering documents by tag
Add a visible filter pattern so users could narrow documentation tables by tag and metadata.
03
Tag management in tables
Bring tag creation and editing into table rows for faster workflows at scale.
Phase 1
Designing tag creation inside the editor.
The first phase needed to fit within Swimm’s existing right-side panel architecture while creating a pattern that could scale into future table workflows.
I designed a reusable tagging experience that supported creating, searching, editing, removing, and reusing tags without adding unnecessary complexity to the editor.
Phase 2
Extending tags into a filter bar.
Once tagging existed, users needed a way to actively filter the main documentation tables by tag.
We compared a collapsed right-side filter panel with sticky top bar chips, then chose the chip pattern because it had stronger visibility and reused an existing component.
Phase 3
Bringing tag management into tables.
The final phase made the feature faster to use at scale by allowing users to create and manage tags directly from documentation tables.
To account for long document titles and dense table data, we introduced a single visible tag limit and moved additional tags into the dropdown input.
Design Spec
Translating a new component into production-ready detail.
Because this was a new component, I also included detailed specs specifying existing typography, states, and color tokens when relevant.
Reflection
One interaction I would revisit.
Looking back, I would iterate further on the tag removal mechanism. The released implementation did not support single-click tag removal, even though analytics showed removal was one of the primary tag actions users took, especially in tables.
