Working on a multi-module SaaS project — what belongs in the shared UI library vs staying local?
I'm a UI/UX designer working on a project basis (not in-house) on a health management SaaS platform with 8+ modules. Each module has its own primary color, unique workflows, and some module-specific components alongside shared ones. The dev team is 6+ full-time developers.
I used a design-first approach — designed screens iteratively and built the shared component library alongside as a reference and handoff tool, not as a prerequisite to design.
The shared library currently covers foundations (colors, typography, spacing, icons), core primitives (buttons, inputs, tables, modals, badges, progress bars), and patterns that recur across multiple modules.
The dev team is now pushing for every new component to go into the shared library — including cards and layout patterns that are unique to a single module. My position is that cross-module patterns belong in the shared library, and module-specific compositions stay local to that module's file. Adding everything bloats the library and defeats its purpose.
There's also friction around variant documentation — some components exist in the library but devs want every color/state variant explicitly listed rather than referencing the screen designs.
Questions:
- Is there a standard rule for what earns a place in a shared library vs staying local to a module? The "used in 2+ modules" rule — is that industry standard?
- On a project-based engagement with a large dev team, how explicit does variant documentation need to be in the library itself vs referencing Figma screens?
- Does the designer own variant documentation, or is cross-referencing screens during implementation considered normal dev work?
- Design-first vs library-first — does the methodology affect what the shared library is expected to contain?