Marcelo Paiva

A woman in a headscarf and overalls stands in profile beside a paned window with swirling patterns. Generated by a visitor on September 24, 2026.

ClearCo: rebuilding a research and design team for agents

Agents write a serious share of our code, which only works because the material they draw from is readable, testable and checkable. I built that first, and I am still rebuilding a traditional research and design team into one that ships production code through the same gate as the engineers.

Role
Head of UX and accessibility — product, design and engineering; one of the leads of the AI transformation
Year
2024–present
Built with
TypeScript and React, Design systems, WCAG 2.2 AA, TDD, AI agents

When I joined ClearCo, design ended with a file handed to engineering. Research happened when somebody had time, with no protocols and no agreed way to write down what we heard. Accessibility problems surfaced months after the decisions that caused them.

A year later, designers and product managers ship features in the production monorepo every day, through the same review gate as the engineers. Something a customer says on a Tuesday call can be in front of them the week after.

Design, research and accessibility are mine. Most of what follows is not about models. It is about what a team has to become before a model is any use to it.

Underneath it sit fourteen applications in human capital management, four industry-specific tenants and nine personas, running and under test at the same time. I drove it from a blank repository. The personas run from recruiters who live in the product eight hours a day to frontline employees who open it four times a year on a phone. A team handing over drawings has no way to check even one of them.

The talent profile running inside the prototype harness. A review bar across the top carries the screen name, a Handed off badge at version 1.0, and two dropdowns that change the whole application underneath it: persona, set to Rec Practitioner with four apps, and tenant, set to OmniFlow Logistics. Beside them sit buttons for comments and UX notes. Below that is the product itself — a left rail of Workspace, People, Hire and Settings with Design System at the foot, an Ask me anything search field, and the profile of Priya Sharma, Senior Manager of Transportation Operations, reporting to a VP of Operations marked Vacant. Seven tabs run from Overview to Events. An AI insights card reduces seven point four years in role and an Outstanding review to three chips, then offers two questions to put to the assistant. A CoWorker panel on the right opens with What's up next, Jane? over four suggested actions and an Ask anything field.
Persona and tenant are dropdowns, not builds. The same code serves a recruiting practitioner on one tenant and every other combination behind it.

Persona and tenant are things you change, not things you rebuild for, so any combination is one dropdown away from being looked at — including by the person whose job it describes.

Everyone is an engineer who designs and makes quantifiable decisions

Not a change of tools. A change of standing.

The goal was never to turn designers into engineers. It was to take out the handoffs that stopped anyone owning the outcome. Telling a traditional UX team to design in code would have failed on its own. So it started in a sandbox: the real design system on fake data, where nothing could reach a customer. Three months later everybody had moved into the monorepo.

A company store where employees spend recognition points. A balance card reads 3,450 points, with 250 added this week from a colleague for covering a double shift. Filters below it cover category, size, and a ticked option to show only what the balance can buy. Six product cards fill the grid, each with an outline illustration, a name, one line of description, a points price and a stock badge: a hi-vis vest (600, Popular), insulated gloves (450), steel-toe boots (2,400, Low stock), a crew hoodie (1,500, New), an insulated tumbler (700) and a low-profile cap (500), each with Add to cart.
The real system on fake data, which is still how an idea starts: a points store for frontline staff, put together from the library's components and tokens. Built to show the material, not shipped.

I underestimated that part for longer than I should have, because from where I stood the change was obviously good. Asking people who are expert at their work to be beginners in public, in a system where being wrong leaves a permanent record with their name on it, is not a tooling problem. Six things made it work.

The designer who picks a gray that fails contrast finds out from the build, in the minute they picked it. It used to surface eleven months later, in an audit note to a team that had not chosen it.

The theme showcase with a teal accent picked from a row of seven swatches, its custom value reading #0D9488. From that one color the page has generated a ten-step scale, numbered 0 to 9 and grouped as backgrounds, subtle fills, solid fills, borders and accessible text, each step with its hex value. A green notice under the scale reads: black text on this accent is 4.83:1, passing WCAG AA for all text sizes. Below it, form controls, tabs, an active nav item and a progress bar have already taken the new color.
The same rule at the moment of choosing: one accent color in, a full scale out, and the contrast of the text it will carry checked on the spot.
How the work moved, before and after

Two sequences. Before: drawing, build, ship, then a review pass, then a ticket in another backlog — what the designer found landed weeks after release, queued behind work that had already shipped. After: runnable material, the behavior written as tests, design in it, a pull request, then gates that fail the build — the same findings arrive in minutes, before anything merges.

BEFORE — DESIGN HANDS OVER A DRAWINGDrawingBuildShipReviewpassTicket inanother backlogWeeks later, queued behind work that already shipped.AFTER — DESIGN HANDS OVER A PULL REQUESTRunnablematerialBehaviorin testsDesign in itPull requestGates failthe buildMinutes, before it merges.

Shipping the foundations

We started from no shared specifications at all. Fourteen products, and no agreed answer to what a button was.

A design system program is usually a two-year argument with nothing delivered in month two. I ran it as four deliveries instead, each useful before the next one started: a tokens repository, the legacy product restyled in those tokens, the component library as versioned packages, and the boilerplate.

The first landed in thirty days. The restyle reached customers within weeks.

The typography page of the design system, describing the 3.0 type system as Atkinson Hyperlegible for headings and Public Sans for body. A type scale tagged In library shows each level at true size with its role, size, weight and line height: Candidate Pipeline Review as H1 at 2.125rem, Open Positions as H2, Engineering Team as H3, Senior Frontend Engineer as H4, Interview Scorecard as H5, then a line of body text from an interview note.
Tokens as people read them: the 3.0 type scale, set in the product's own words rather than lorem ipsum.

The material is dull on purpose: Style Dictionary for the tokens, Mantine under the components, Storybook where people read them, axe in the pipeline. What we argue about is what the system should refuse to do.

A data table dimmed behind a filter drawer that has slid in from the right. The drawer's title carries a badge reading 4 Active. Under Status, Active and Pending are ticked and Closed and Archived are not, with a count of 2 beside the heading. Stage is collapsed. Creation date, counted 1, is set to Custom range, from Mar 1, 2026 to Mar 31, 2026, below the presets Today, This week, This month and Last 3 months. Ownership opens on a field for finding an owner by name. Apply filters and Clear all sit at the foot.
A pattern a team takes rather than draws: the library's filter drawer, ready to use.

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

Figma went from the center of the work to almost unused. We cut that bill by 60% and moved the difference into AI tokens.

Behavior written down before it is built

Testing is part of designing here, not a pass afterward. For the interactions that matter, the expected behavior gets written down before the feature counts as finished. That means keyboard paths, where focus lands next, the accessibility requirements for the pattern, each component state, and the workflows that keep regressing.

If an interaction matters, a person should not be the only thing that can check it.

What did research look like before?

Informal. Whoever had time, however they felt like doing it, with nothing written down afterwards that anybody else could use.

Working product now goes in front of customers every week, usually well before it is polished.

Build, use, observe, learn, improve.

Sessions run on the product itself, with persona and tenant set to the person in the room, so nobody is asked to imagine the rest of their own job.

Research sits with me now, and it is getting protocols for the first time. There is one route for whatever customers tell us, whether that turns up in a session, a support ticket, a call with customer success, or a question put to product education.

I cannot separate what those sessions changed from what we would have found later on our own. What I can point at is the cadence, and the decisions that moved in the room.

What AI actually exposed

AI did not replace any of this. It exposed every part of the design process that had never been made explicit.

Every process has parts nobody wrote down. They stay invisible until something that cannot ask you a question tries to follow them.

An agent that needs a fact it does not have will not ask for it. It invents a token, a spacing scale, a component that looks right and shares nothing with ours — confidently, across every file it touches.

So I made three things true before an agent was allowed near the design system. Readable: a specification, not a reference. Testable: a test is something to satisfy, not to interpret. Checkable: drift guards fail the build instead of filing a ticket.

A page titled Agent discovery surface: the reference files a coding agent reads to build on-brand, accessible, on-token UI without guessing. A first panel explains that a small set of files hands the agent exact token names, values and rules instead of letting it invent hex values, with the repository's CLAUDE.md as the entry point. A second lists why to ship it: on-brand output, accessible by default, on-voice copy, less review churn and portability. The first file card, DESIGN.md, is marked as mirrored from clearco-ui.
Readable, in practice: the files an agent reads before it touches the system, so it uses our tokens instead of inventing its own.

With those in place it runs end to end: research, specification, tests, design, implementation, review, help, release. Product help comes out of the same scenarios the feature was designed against. An agent writes the article and drives a browser for the screenshots. Product education edits that draft instead of writing a manual against a launch date.

Where this goes is not my invention. Josh Bersin's HR 2030 (opens in a new tab) blueprint argues agentic HR is a new business system rather than HR with AI added on top, and forecasts HR headcount falling 30 to 50 percent this decade. I do not have to believe the forecast to take the design problem seriously. If what is left of a recruiter's day is mostly judgment, the product cannot stay a dense surface they filter by hand first.

A hiring pipeline for a Warehouse Associate, 2nd shift requisition at the Dallas distribution center: 14 openings, 38 candidates in play. Under Pipeline, Candidates and Job details tabs, five columns run from Applied (12) through Phone screen (8), Interview (6) and Offer (3) to Hired (9). Each card carries a candidate's initials, name and source (Indeed, a referral, the career site, a job fair), one line on where they stand, a status badge and days in the stage. Aisha Bello's screen is booked for Thursday at 2:30 PM, Sam Okafor's offer has gone out at $19.50 an hour and is awaiting a reply, and two hires start Oct 27.
Built with the system, not shipped: a hiring pipeline as cards that each say what happens next, rather than rows to filter.

What stays a person's call

The harder half of this is deciding where it stops, and we are still deciding.

Some of this work is a judgment with somebody's name on it: what a rejection says to a candidate, whether a recommendation belongs on the screen at all. The complexity you cannot remove is usually somebody's payroll regulation, union agreement or accommodation.

Accessibility is the clearest case, and what makes me careful about it is that it looks automatable. In the pipeline, axe catches the contrast failure, the missing label and the control with no name. It will also pass a screen that is entirely compliant and unusable with a screen reader. Somebody has to sit down with the assistive technology and say whether the thing actually works. The more of a screen a model draws, the more I want a person in that chair.

I cannot tell you we have drawn every one of those lines in the right place. We have moved several of them more than once, and we are not finished moving them.

None of it was in reach a year ago

2025 was rough. What fixed it was not a better model. It was a team that kept learning and stayed narrow while it did.

Thirty days, two weeks, three months to the monorepo: none of it was in reach a year ago. All of it is ordinary now.

We stopped sending each other pictures of our software. We started sending each other the software.

GitHub's merge box on a pull request, every row of it green. A tick beside All checks have passed, with one successful check counted underneath. A second tick beside No conflicts with base branch, and under that the line saying merging can be performed automatically. A green Merge pull request button waits at the bottom, next to an offer to do the same thing from the command line.
The satisfying part. Every gate green, and a merge nobody has to think twice about.

You do not transform a design team by asking it to move faster. You change what it is able to own. Everything here came from one move: shortening the distance between deciding something and finding out whether it was right.

About the drawing

The drawing for this piece was generated, not chosen. Hashing the piece’s name fixes one point on the color wheel; the other two follow from it. The same name always gives the same three colors.

#5f5fd4#783da1#8ea13a

How this drawing was made

The line under the drawing marked “Meant to show” is written by a person, not the model. A generated drawing keeps what is large and loses what is small, so the detail that decides who someone is can go missing, and a picture only reaches people who can see it. Where the drawing and that line disagree, the line is the intent.

Or press the right arrow.

A case study

This is a report on one project, read straight down in one column: a drawing, what the problem was, and what I did about it.

From top to bottom

  1. At the top, the site header: my name, which goes home, then links to Writing, Work, Signal, Tools and Resume, then Settings, where you choose the drawings, light or dark, and movement.
  2. The case study’s drawing, its title and a one-paragraph summary. Some have a link to the project itself.
  3. The case study, in sections with their own headings, with screenshots along the way.
  4. Some have a gallery of screenshots at the end. Each opens larger, in a viewer you can step through.
  5. About the drawing: how the drawing was made, and the colors it was drawn with.
  6. Links to the newer and older case study. The left and right arrow keys go there too.
  7. At the bottom, the footer: a note on how this site is built, links to Illustrations, Pens, Concepts and Accessibility, this Describe this page button, then GitHub, LinkedIn and email.

What you can do here

Read how the project went.