Marcelo Paiva
Theme

ClearCompany: an HCM platform, designed in code

Two years leading UX and accessibility at ClearCompany — fourteen applications, rebuilt so designers could work in running software instead of drawings of it.

Role
UX and accessibility lead — platform design, design system architecture, and the tooling between them
Year
2024–2026
Built with
TypeScript, React, Design tokens, WCAG 2.2 AA, AI agents

What this was

Two years leading user experience and accessibility at ClearCompany. Fourteen applications — recruiting, onboarding, performance, payroll and more — across nine personas, from recruiters and hiring managers to frontline employees who open the product four times a year on a phone.

What this software decides is who gets hired, onboarded and promoted. A hiring form that fails on a phone shuts out people without a laptop. An onboarding form that fails with a screen reader shuts people out of work itself.

The problem

The product runs on IIS, a Microsoft web server. It does not run on a Mac. Designers worked in Figma, and when they needed to see something real, they asked an engineer to screen-share.

Nobody was doing anything wrong. But it made a whole class of things impossible to check: keyboard order, screen reader output, what a page does at 375 pixels wide. Those only exist once something runs, so they were found after release and became tickets queued behind work that had already shipped.

One example. A designer ran a keyboard pass over a page that was already live. Getting from the account picture to the first menu link took eight presses of the Tab key, with no skip link and no accessible name on the navigation. Every person involved had made the right call, and the result was still a keyboard trap.

What I built

Four environments, ordered so each one paid for itself before the next began:

  1. A design tokens repository.
  2. The legacy product restyled with those tokens — a visible change for customers, fast.
  3. A component library, versioned and published as packages, so other teams stopped waiting on mine.
  4. A boilerplate: no backend, mock data, runs on anyone's laptop.

Design system programmes rarely fail on craft. They fail because they are a two-year argument with no deliverable in month two. An architecture argument on its own moves nobody; an architecture argument with a delivery in thirty days moves everybody.

I built the boilerplate in two weeks, mostly with an AI agent. Two days after I showed it, someone forked it into their own repository without being asked. That is the only adoption signal I have ever trusted.

Making the system readable by machines

By 2026, agents were writing a serious share of our code. Our design system lived in Figma files, a spreadsheet of approved wording, documentation behind the VPN, and the heads of about five people. Normal for 2024, and unreadable to an agent.

An agent will not ask. It fills the gap with a plausible token name, an invented spacing scale, a component that looks about right and shares nothing with ours — confidently, across every file it touches.

So the design system became a specification rather than a reference: a two-tier token architecture in W3C DTCG format with one documented override point for white-labelling, component specs an agent reads before it generates, a written accessibility standard with writing rules beside it, and drift guards that fail a build instead of filing a ticket.

What changed

  • Decisions got faster. Mobile-first signing, base font size and the navigation model were each settled in a single session, because everyone in the room could pick the thing up and try it.
  • The navigation shipped out of the boilerplate and into the product — as a pull request, not a programme.
  • Accessibility moved before the merge. Gates fail a build in minutes instead of producing findings weeks later.
  • The standard outlived me. It is a markdown file in the repository. When someone asked last month what conformance level the new platform targets, the answer came out of that file rather than out of me.
  • Mobile stopped being a second drawing. Same code at a smaller width, openable on a real phone the same day.
Where the accessibility question gets asked, before and after

Two sequences. Before: drawing, build, ship, keyboard pass, then a ticket in another backlog — the check lands after release, weeks later, queued behind work that already shipped. After: runnable material, design in it, pull request, gates that fail the build, merge — the check runs before the merge, in minutes.

BEFORE — THE QUESTION ARRIVES AS A FINDINGDrawingBuildShipKeyboardpassTicket inanother backlogWeeks later, queued behind work that already shipped.AFTER — THE QUESTION IS A PROPERTY OF THE MATERIALRunnablematerialDesign in itPull requestGates failthe buildMergeMinutes, before it merges.

What I got wrong

I pushed to put our component documentation on the open web, because you cannot test components with assistive technology from behind a corporate VPN. It went up with internal engineering documentation attached that was never meant to leave the building. Colleagues spotted it, said so, and we pulled public access inside a day.

The error was mine and it was specific: our documentation contained material that could not be public, and both facts were available to me beforehand. The whole episode took a day, because we had put something real out and let people look at it. I will take a corrected mistake over an uncorrected opinion.

Where it stands

I am careful about what I claim. The platform is not fully accessible — there is older software and there are known gaps, and we publish conformance reports rather than adjectives. What changed is where the work happens.

We stopped passing around pictures of our software. We started passing around the software.