Internal Documentation AI & Technology

Restructuring MSPbot's Design System

Contract Period

Q1 - Q4 2025

A year-long background project with my colleague, Nora Li, where I’ve documented and aligned all basic components, plus authored an Accessibility Doc and Writing Guidelines doc independently.

Deliverables

Figma Design System File

Accessibility Documentation

Writing Guidelines

Table of Contents

Context Impact Features Research & Discovery Key Insights Design Iteration

Context

MSPbots’ design system at the time was originally rough and had a lot of missing components. Due to this, the library didn’t reflect the existing Legacy Product, forcing designers to spend extra time reconciling mockups against the real interface.

The restructuring project was initiated to fix the following:

Have a design system that new designers could open and understand independently
The components matching the actual product; and
The availability to replace the team's reliance on Element Plus' external documentation site.

The project was also formally scoped into three phases: documentation, enhancement, then UI application, but was consistently treated as a low-priority background task, worked on between higher-priority assignments throughout the year.

Team

Nora Li

Duration

1 Year

Role

UX/UI Designer

UX Writer

AI Agent Developer

Skills

UI Auditing

Writing

Designing and Project Management

Researching

Impact

Phase 1 delivered a complete documentation foundation, however the conditions for adoption was shifted faster than the project could land.

The Design System's Outcome

Result 1: Complete Basic and Custom Component Library

All components were documented by end of year, with variant properties defined and design tokens attached. The Figma file became an internally sourced reference independent of Element Plus' external documentation.

Result 2: Accessibility and Writing Standards Established

Two additional documentation layers were completed beyond the initial brief. The Accessibility & Writing Guidelines doc were self-initiated based on observed gaps, and they represent the only written standards of their kind for the Legacy Product design system.

Result 3: Adoption Did Not Occur as Intended

By the time the system was complete, the PM and Dev Teams had shifted to using ChatGPT to generate mockups directly. The design system was never fully adopted as the team's primary source of truth. The organizational conditions that would have driven adoption(designer-led mockup workflows and a stable Legacy Product roadmap) had already changed.

Result 4: Phase 2(Enhancement) and Phase 3(UI Application) Were Cancelled

The company's strategic pivot towards AI app development made the Legacy Product’s UI enhancement a lower priority. Combined with a mass layoff across multiple departments, Phases 2 and 3 were never initiated. The design system remains a complete Phase 1 artifact with no current continuation plan.

Result 5: GPT Contribution Interrupted

A self-initiated GPT agent that was designed to help team members query the design system and assess mockup feasibility was in progress as part of the company's AI contribution initiative. It was not completed before the layoff. A parallel initiative by Nora was a vibe-coded website version of the design system was finished but got paused due to dev unavailability.

Features

FEATURE 1

All Component Documentation

Each basic component was documented with its variant properties, design tokens, and applicable states, building a foundation that matched the actual Legacy Product rather than a theoretical or aspirational component set. Discrepancies between the design system and the real product were identified through page-by-page audit of the Legacy App.

Basic Components

image caption 1

image caption 2

image caption 3

image caption 4

FEATURE 2

Admin View vs. Client View Differentiation

A late-stage discovery revealed that the table component rendered completely differently depending on whether the user was in admin view or client view. These were not minor style differences, they were substantively different UI states of the same component. The inconsistencies were surfaced, documented, and resolved as a feature enhancement rather than being left as silent gaps in the system.

image caption 5

image caption 6

Table Subcomponents

image caption 7

image caption 8

image caption 9

FEATURE 3

Accessibility Documentation

Written standards covering accessibility considerations for the Legacy Product design system. Informed by external design system references and authored independently. Intended as a baseline reference for designers and eventually, developers.

image caption 10

FEATURE 4

Writing Guidelines

Internal documentation establishing writing standards and tone for the product. Adapted from external references to fit MSPbots.ai's context. Authored independently due to English fluency advantage within the team.

image caption 11

FEATURE 5

Design Tokens and Element Plus Figma Library Integration

Upon discovering that Element Plus maintained an official Figma library, the workflow shifted: rather than building components from scratch, components were copy-pasted from the library, and variant properties were adjusted to match the Legacy Product. 80% of the remaining Primitive and Token Variants were still fleshed out manually, but time saved was still significant nonetheless.

Though observed efficiency was gained, no formal time measurement was tracked*

Table Subcomponents

image caption 10

image caption 11

image caption 12

image caption 13

Research & Discovery

Discovery happened through these three primary inputs.

Legacy App Audit

I reviewed the legacy app page by page to identify how components actually appeared in the product(not how they were theoretically defined). This audit surfaced UI inconsistencies, undocumented component states, and the admin vs. client view discrepancies that later required dedicated documentation. The table component was the most complex example: its header varied based on grid style selection and changed entirely between admin and client views.

Element Plus Documentation and Figma Library Element Plus

Material Design 3

Used for the Accessibility Doc and Writing Guidelines, this was reviewed to benchmark language, structure, and coverage. Content was then adapted to MSPbot’s design system rather than reproduced directly.

Key Insights

Because the existing design system was built for one person... it led to the file needing to be rebuilt so it could scale for a team.

My Insight

Always going back to Nora for questions, clarifications, and history-related context on pages and specific components as her foundation work was extremely valuable to the project.

Because the target audience shifted mid-way... it led to the documentation portions had to rewritten, not just extended.

My Insight

Since PM-facing and Dev-facing instructions are fundamentally different, I changed my original approach(Do’s and Don’ts) to something like how Element Plus does it(attributes). The only components that still had the original format were the Foundational ones(i.e. Logo & Favicon, Typography, Colors, et)

Because the Legacy App was never fully audited before the project started... it led to the real scope actually being larger than anticipated.

My Insight

The page-by-page audit revealed that components had more states, more variations, and more view-dependent differences than expected. A pre-project audit would have produced a more accurate timeline estimate and potentially changed the three-phase plan.

Because the project was always low-priority... it led to the medium was never seriously questioned.

My Insight

A Figma file is the right home for design assets, but it’s not the right home for PM instructions, developer HTML attributes, accessibility standards, and writing guidelines. Personally, an internal documentation website would have served all three audiences more effectively and been significantly easier to maintain and update as the product evolved.

Design Iterations

Iteration 1

Atomic Design Proposal (Scrapped)

Early in the project, an Atomic Design structure was proposed: organizing the system into Sub-atoms, Atoms, Molecules, Organisms, and so on. The proposal was reviewed and was actually approved, however over time, the feedbacks afterwards shifted to following Element Plus' existing documentation structure.

The Rationale
Consistency with the external reference the team already used.

The Tradeoff
A structure optimized for Element Plus rather than one that reflected the product's actual component hierarchy.

Iteration 2

Documentation Method Evolved Over the Year

Early component documentation was more manual and text-heavy. The discovery of the Element Plus official Figma library changed the production workflow mid-project with components being copy-pasted directly rather than building from scratch. Additionally, a cleaner method for displaying components alongside their states was developed later in the year. Earlier documented components predate this improvement and reflect a less refined presentation approach.

Iteration 3

Scope Shifted from PM-facing to Dev-Facing

From Q2 onward, the writing audience shifted from PMs needing instructional guidance to developers needing HTML attributes and technical documentation. This wasn't a minor tone adjustment, as it was a fundamental change in content type, requiring a different understanding of the reader's context and what counts as useful information for each audience.

Iteration 4

Self-Initiated Addition: Design System GPT Agent (currently incomplete)

As MSPbots moved toward an AI-first culture and required all employees to submit AI contributions, a GPT agent was initiated to serve as an interactive layer on top of the design system. The intent: allow any team member to query the system conversationally, receive component guidance, and assess mockup feasibility without needing to navigate the Figma file directly.

The agent was not completed before the layoff. A parallel initiative by teammate Nora, which was a vibe-coded website version of the design system was also left unfinished due to tooling friction with Cursor and a developer collaborator who was pulled to higher-priority tasks.

In hindsight, the more effective split would have been to swap contributions as the front-end development background required to vibe-code the website was already present on the team.

Reflection

What Worked

The collaboration structure with Nora was effective throughout as we had weekly catch-up meetings. We’d shared the work that was normally prioritized more, as well as informal knowledge-sharing that prevented us from hitting any walls while working on the design system. Discovering the Element Plus Figma library was a genuine process improvement that made an under-resourced project more sustainable. The Accessibility Doc and Writing Guidelines were completed without being formally requested, and represent the only written standards of their kind for the Legacy Product.

What Remained Unsolved

Phase 1 was completed, but the system was never adopted. The audience for the documentation changed twice during the project. Plus the Figma file format served neither audience, as a purpose-built internal website would have. The GPT agent might have driven adoption by lowering the barrier to accessing the system, but was never finished.

Components documented in the early part of the year reflect an older, less refined display approach that wasn't updated retroactively.

What I’d Do Differently

I’d push for a vibe-coded internal website from the start, and given what I know now, I would have taken on the front-end build myself. A website would have served the PM audience, the developer audience, and the copy-paste use case in ways a Figma file structurally cannot.

I'd also follow the Atomic Design structure over Element Plus' documentation hierarchy. The project was building an internal system for a specific product, and organizing it around that product's actual component relationships would have produced something more useful long-term than mirroring an external library's structure.

The broader lesson is about medium and audience alignment. The same mistake made in the MSPbot Welcome Screen Guidelines project, on choosing a static document over a living accessible website, showed up here again on a larger scale. Some differences were that the audiences varied, and the cost of the wrong medium compounded across a full year of work.

Other

Case Studies

Internal Documentation AI & Technology

Crafting Guidelines for MSPbots’ Asset Team

Shopify Development E-commerce

CRO Strategy and Shopify Development for Veii Apparel

Internal Documentation AI & Technology

Case Study Title

Related Service

Context

Impact

The Design System's Outcome

Features

All Component Documentation

Admin View vs. Client View Differentiation

Accessibility Documentation

Writing Guidelines

Design Tokens and Element Plus Figma Library Integration

Research & Discovery

Legacy App Audit

Element Plus Documentation and Figma Library Element Plus

Material Design 3

Key Insights

Design Iterations

Reflection

What Worked

What Remained Unsolved

What I’d Do Differently

Other

Case Studies

Crafting Guidelines for MSPbots’ Asset Team

CRO Strategy and Shopify Development for Veii Apparel

Case Study Title

Join My Newsletter