VMSpark
Client project · Healthcare staffing operationsA new interface for a reliable data pipeline
VMSpark moves hospital job feeds into staffing agencies’ applicant tracking systems. The pipeline was reliable, but the admin app looked unfinished just as the company began showing it to investors. I audited it, then rebuilt its interface on a design system made for the people who use it all day.
- 3.5 → 7.5
- heuristic score, before and after
- 178
- color pairings passing WCAG AA, light and dark
- My role
- Product design and front-end engineering
- Owned
- Usability audit, navigation, design system, style guide, every view
- Built with
- Rails 7, Stimulus, HTMX, plain CSS on three-tier tokens, PostgreSQL
Project summary
Staffing operators spend their day in VMSpark fixing feeds that won't map. A heuristic audit scored the app 3.5 out of 10: failure reasons hid in hover popovers, 33 of 43 delete buttons ran without a confirmation, and nothing told an operator what to do next.
- The decision
- I chose a design system built from scratch over theming Bootstrap again, so every page could say its one job, show its state in words, and work the same in light, dark, and on a phone.
- The result
- A re-score with the same rubric went from 3.5 to 7.5. Every delete now confirms, operators get one inbox for unmapped values, and lint and contrast checks keep all 318 views and 178 color pairings on the system.
Audience
VMSpark takes job feeds from the vendor management systems hospitals use, maps each listing to a staffing agency’s own vocabulary, runs the agency’s rules, and sends it to their applicant tracking system. When a value doesn’t map, the job stops before it reaches the agency, and nurses don’t see the shift.
Operators fix those values, and VMSpark sells the pipeline. I checked each decision against the needs of both groups below. A change that helped one group at the other’s expense wasn’t finished.
The main audience for this work was venture capitalists and angel investors like Graham. The goal was to make the case for the business.
-
Operators at staffing agencies
They use the app all day. Their job is to make sure every hospital job from every feed maps correctly and reaches their applicant tracking system, so recruiters can fill it.
- Know what needs fixing without hunting
- See why a job failed, in words
- Safeguards on actions that touch thousands of jobs
- A screen they can read for eight hours
-
VMSpark, the business
VMSpark sells the pipeline, and the admin app is where people judge it. Customers decide whether to trust it there. Their questions go to support from there. Investors see it in demos.
- Fewer “why didn’t this job sync?” tickets
- No accidental reprocessing across a whole account
- A demo that matches the marketing site
- An interface the team can change without breaking
Operators use this screen most. The header states its purpose and the last import time above the table operators already knew.
Research
Requirements gathering
The admin app looked unfinished just as VMSpark began showing it to investors. It had started as a Bootstrap project and collected mixed styles over time. The team knew it. They paid for a design and usability audit first, agreed with its findings, and hired me to do the work. At their request, we managed the project in Monday.com.
We had no opportunity to research VMSpark’s customers, so the evidence had to come from the app and from established best practices. I audited about 350 templates, then scored the whole app against Nielsen’s ten heuristics, with a file and line for every finding.
After the redesign, an AI agent that hadn’t seen my notes re-scored the app from the code with the same rubric. It had only the original audit and the repo, and it had to verify each fix in the code.
average score out of 10
before and after, same rubric, scored from the code
error prevention
the lowest score before the redesign
Score by heuristic
Before → after, the change that moved it, and what still keeps it from a 10. The design decisions below explain the changes.
-
Visibility of system status
4 8 /10
Every page gets its own title and a next-step line where there is work. “Sync with ATS” became “Import from Bullhorn”, disables while it runs, and confirms with a message.
Still open: Most HTMX failures still fail silently.
-
Match with the real world
3 8 /10
Titles like “AtsPayloads#show” and values like not_nil became plain words. Conditions read as sentences.
Still open: VMS and ATS are never spelled out.
-
User control and freedom
3 7 /10
Every confirm works, Esc and a click outside close every dialog, and a failed reorder rolls back with a message.
Still open: There is still no undo, only confirmation.
-
Consistency and standards
3 8 /10
Two sidebars, four variants, and three icon sets became one labeled sidebar, one icon family, and one table component.
Still open: A few “Sync” labels and scaffold flash messages remain.
-
Error prevention
2 8 /10
Deletes with a working confirmation went from 10 of 43 to all 28. Reprocess and feed rebuilds confirm too.
Still open: Reprocess all doesn’t state how many listings it touches.
-
Recognition over recall
4 8 /10
About 33 popovers and 65 hover titles went to zero. Failure reasons sit on the row.
Still open: Icon-only row buttons have no visible label.
-
Flexibility and efficiency
7 7 /10
Kept the command palette, shortcuts, saved views, and resizable columns, and added a keyboard step for resizing.
Still open: The density setting dropped out of the new menus. No bulk mapping yet.
-
Aesthetic and minimalist
4 7 /10
Tables holding two-row lists became simple lists. Popovers that repeated the cell were deleted.
Still open: Some dead scaffold views are still routed.
-
Recovering from errors
3 7 /10
“Prohibited this record from being saved” went from 11 forms to none. Errors sit under their field and are linked to it.
Still open: Adding manual jobs can lose typed rows on failure.
-
Help and documentation
2 7 /10
Index pages without an empty state went from 35 to 2. Page subtitles went from 1 to 102.
Still open: No glossary or in-app docs.
The audit also turned up a SQL injection in a search allowlist and feed text rendered unescaped in popovers and emails. Both were fixed before any styling work.
Most of the low scores had one cause. The information an operator needed was available only on hover. The app’s old style guide said not to hide required information behind a tooltip. The app did so about a hundred times.
Personas
-
Graham Whitlock
The investor
“If I have to be told to ignore part of the demo, I start wondering what else is unfinished.”
A venture capitalist or angel investor deciding whether VMSpark is a finished business worth backing. Investors were the main audience for this work.
Needs
- A product that looks as reliable as the pipeline is
- An app and marketing site that feel like one company
- Evidence that problems are visible and under control
Frustrations
- A dashboard copied from an example page, with a chart that never loaded
- Mixed styles and five icon sets
- Unfinished screens that need explaining during a demo
A working persona based on the client’s goal. No investors were interviewed.
-
Nadia Hassan
The operator
“Don’t make me hover to find out what broke. Tell me what failed and what to do next.”
Works at a staffing agency and spends the day making sure every hospital job maps correctly and reaches the applicant tracking system.
Needs
- Know what needs fixing without hunting
- See why a job failed, in words
- A screen that’s comfortable to read all day
Frustrations
- Failure reasons hidden in hover popovers
- Delete buttons that ran without a confirmation
- Nothing saying what to do next
A working persona based on the heuristic audit and stakeholder reviews. No operators were interviewed.
Persona names and photos are illustrative, as are quotes without a named source.
Investor demo journey map
-
Reads the marketing site
Activity
The investor forms a first impression of the company.
Problem
The app and the marketing site had drifted apart.
Design response
The app borrows the site’s navy, blue, Spark bolt, and line drawings. -
Signs in to the demo
Activity
The investor moves from the pitch to the product.
Problem
The app mixed Bootstrap 4 and 5 and used five icon sets.
Design response
One design system behind sign-in and every screen, in light and dark. -
Looks around the app
Activity
The investor checks whether this looks like a finished product.
Problem
The dashboard came from a Bootstrap example, and its chart never loaded.
Design response
Every page says its one job and shows its state in words. -
Asks what happens when a job fails
Activity
The investor wants to know the pipeline’s problems are visible.
Problem
Failure reasons were hidden on hover, and nothing said what to do next.
Design response
One inbox for unmapped values, which block jobs from reaching a customer’s ATS. -
Weighs the risk
Activity
The investor considers what could go wrong in daily use.
Problem
33 of 43 delete buttons ran without a confirmation.
Design response
Confirmations say what will happen before it happens.
A design system built from scratch
Re-theming Bootstrap would have kept five ways to render a form. I replaced it with a small library in plain CSS. Each component has one partial or helper, one CSS block, and one live entry in the style guide. Pages can use only what the library contains.
Foundations
-
Legible type
The body face is Atkinson Hyperlegible, designed with the Braille Institute, at a 16px base. A matching mono face sets IDs, dates, and rates so they line up.
-
Color by role
Navy marks structure. Brand blue marks anything you can click. Spark orange appears only in the brand. Red, amber, and green appear only for state.
-
Status labels with icons
Every status, such as Processed, Failed, or Skipped, pairs an icon with a word. Color is never the only signal.
-
No information in tooltips
Anything an operator needs is on the page, in a note, or in the details drawer.
-
Light and dark from one set of tokens
The theme follows the system setting and can be changed per person. Both themes pass the same contrast checks.
-
Page headers
Every page header has a title, one sentence of purpose, and at most one primary action. When there is work, a next-step line says what to do.
Token tiers
-
Primitive
Raw values with no meaning, such as
--blue-510. Read only by the semantic tier. -
Semantic
What a value is for, such as
--color-accent. Light, dark, and the navy chrome map it differently. -
Component
One component’s palette, such as
--button-bg. A variant only reassigns these tokens.
Dark mode is a second mapping of the semantic tier. Matching the marketing site took changes to a few semantic tokens, which updated every screen.
I didn’t design or work on the marketing site. It already existed, and I borrowed its style. Investors like Graham see the marketing site first and the app second, so they should feel like one company. The app borrows the site’s navy, its blue, the Spark bolt, and its two-tone line drawings.
Each primitive is named by lightness. A darker step always has a higher number.
The first screen borrows the marketing site’s navy and its feeds-to-ATS drawing.
One inbox for work that needs mapping
The old navigation listed 14 mapping pages with a count on each, and operators opened them one by one to find work. I added Needs mapping, one inbox sorted by how much is waiting, with a next step at the top.
Each unmapped value blocks jobs from reaching a customer’s ATS. Clearing this list is the most valuable work an operator does for the business.
The header states the page’s purpose, the total, and where to start. Lists with nothing to map stay visible and dimmed.
Each mapping page uses the same mapping ledger. The value from the feed sits on the left, the ATS value on the right, and every row has its own Save button. An Ignore switch sits beside it, and a hint says what ignoring does.
Each row pairs a feed value with its ATS value. A hint above the rows explains Ignore.
A failed job used to show its reason as a raw Ruby hash in a hover title. Now the reason is a sentence on the row.
The details drawer opens over the filtered list, so an operator doesn’t lose their place. Fields are grouped by where they came from, ending with the raw feed, which is where a bad value is usually traced.
The drawer opens over the filtered list. It shows the key facts, then every field, then the raw feed.
Confirmations that say what will happen
Deleting a mapping can unmap thousands of listings. Reprocessing an account queues work for every open job in it. A misclick costs the operator time to repair and costs the business compute and support time.
-
Confirmations that say what happens
Turbo and rails-ujs were off, so every confirm in the codebase silently did nothing. One shared dialog now handles them. Each message asks a specific question, which becomes the dialog’s title. The body says what happens next. The written rules ban “Are you sure?”
-
Reprocess all states its reach
One click re-runs mapping, rules, and the ATS sync for every open job in the account. The confirm now says so and says that it runs in the background and takes minutes. The button disables while the request posts.
-
Buttons say which way data moves
“Sync with ATS” actually imported values from the ATS. Renaming it “Import from Bullhorn” removed a question operators had been sending to support.
Forms follow the same idea: label above, hint under the label, and the error under the field it belongs to, linked for screen readers. The heading over a failed form says how many fields to fix, in plain words.
The title asks the question. The body states the consequence, and the button repeats the verb.
Every confirmation in the app uses this dialog.
Light, dark, and phone layouts
Operators keep this app open through a full shift, often beside other dark tools. The theme follows their system setting, and each person can override it from the account menu. A small script applies the choice before first paint, so pages never flash.
Each semantic token has its own dark value. Brand blue is lighter in dark mode so links and buttons stay readable on navy. A script checks all 178 text and control pairings in both themes against WCAG AA.
The same page as above, with each token mapped for dark.
Most mapping happens at a desk, but failed-listing alerts arrive by email, and an operator should be able to check one from a phone. The main screens were checked at 390 pixels wide with no sideways page scroll. Layouts collapse to one column below 640 pixels. Every target is at least 24 pixels, and primary actions are at least 40.
Drag-to-reorder doesn’t work well with a thumb or a keyboard, so rules and rate plans also have up and down buttons.
-
NavigationThe same labeled sidebar, as a drawer.
-
Needs mappingCounts stay on the same line as each list.
-
Job listingsOnly the table scrolls sideways.
-
Custom rulesUp and down buttons reorder rules without dragging.
Results
heuristic average after
up from 3.5 across ten heuristics
deletes confirm first
up from 10 of 43
For operators like Nadia
- One inbox for everything that needs mapping
- Failure reasons in words, on the row
- Every destructive action confirms first
- Light, dark, and phone layouts
For the team
- One component library and one style guide
- Checks that fail the build on drift
- Bootstrap, jQuery, and page-level scripts removed
- About 13,000 fewer lines of view code
For investors like Graham and the business
- A demo that matches vmspark.com
- Fewer ways to reprocess an account by accident
- Routes, params, and integrations unchanged
- Two security holes closed
Testimonial
Jon Sturm
Director of Product & Customer Success · VMSpark
Josh inventoried 350 ERB templates before writing a line of new CSS, then turned that audit into a phased rollout we could ship behind no flags. The shell finally reads like the enterprise product the pipeline always was, and operators didn't lose a single piece of muscle memory in the move.
Build process
Routes, params, form field names, and HTMX targets stayed the same, so the pipeline and every integration were untouched.
The style guide lives in the app. It renders every component live with the code to copy. It also states the system’s rules, including where the system lives, how it changes, and which checks it has to pass.
It also has a section for AI coding agents. The team builds with them, so the same rules sit in the repo’s agent instructions too. An agent asked to build a page reads the system before it writes a class.
Drift checks
-
bin/ui_lint
Fails on unknown classes, inline styles and scripts, tooltips, Bootstrap leftovers, dashes in copy, and primitives read outside tier 2.
-
bin/color_audit
Fails on any hex, RGB, or HSL value outside the token file.
-
bin/contrast_check
Checks every text and control pairing against WCAG AA, in both themes.
-
Style guide spec
Fails if a listed token, icon, or illustration stops rendering.
Plate 01
The About section covers purpose, principles, governance, and instructions for AI agents ahead of the components.
Plate 02
The style guide follows the app’s theme setting. This capture is in dark mode.
Plate 03
Full-page patterns that use real copy from the app.
Limitations
-
Not yet watched in real use
Both scores come from the code and the reviews came from stakeholders. I haven’t watched operators like Nadia work in the new interface, so I can’t claim it’s faster.
-
Silent save failures
When a save fails on the server, most inline actions show nothing. One shared listener that says “Couldn’t save. Try again.” would raise the scores for visibility and error recovery.
-
Confirmation instead of undo
Every delete asks first, but none can be undone. For mappings, where one change touches thousands of listings, undo is the next step.
-
Wide tables on phones
Job listings keeps its full table on small screens and scrolls it sideways. A card view for phones needs a decision on which columns matter most.
More screens
The wireframes and flow diagrams I drew to document the system for the team, plus more screens from the shipped app.
See all 23 in the gallery