DEV Community: joonquixote

A Design System Is Not a Collection of Components

joonquixote — Sun, 11 Oct 2026 14:01:16 +0000

Originally published at https://blog.joonquixote.com/en/posts/a-design-system-is-not-a-collection-of-components/.

A shared component folder and a design system can look much the same from the outside.
Both contain buttons and inputs, and both let you browse components in Storybook.
Can moving a few buttons and inputs into a shared folder and adding Storybook really make it a design system?\
The difference appears once other teams start using those components.

In my previous post, I wrote about a design system I spent two and a half years building, only to see it end when the organization was dissolved. The first thing I identified as missing was adoption.

This post looks at a design system not as a collection of components, but as a structure that captures recurring decisions.
From that perspective, I will examine what must be preserved—and what costs must be paid—across tokens, component APIs, versioning, adoption, and operations.
I will also explain why, in some organizations, a well-organized component folder may be a better choice than a design system.

Turning Recurring Decisions into a System

Describing a design system as a collection of reusable UI components for building consistent interfaces tells only half the story.
Components are the output, and producing that output requires many decisions.
What color should the primary button be? How much padding should a card have? In what order should the buttons appear in a confirmation dialog?
In an organization with only a shared component folder, someone makes these decisions again each time they build a screen.

In a design system, decisions about color, spacing, and typography are encapsulated in tokens, while decisions about recurring UI patterns are encapsulated in components.
Teams using the design system can apply those decisions without making them again.
From this perspective, a component library is only one of the artifacts that make up a design system.
A design system needs not just tokens, components, and documentation, but also a versioning policy and a process for handling change requests.

That makes a design system less like a one-off project and more like a product with consumers.
Like any product, it needs a roadmap for deciding what to build, a channel for user questions, and metrics for determining how much it is actually being used.

On my previous project, I designed and implemented components such as tabs, pagination, and tree from the ground up.
Along the way, I learned that implementing components alone does not sustain a design system.
We also had to establish the development environment and operating practices that would ensure new components were built to the same standards and released through the same process.

Why Components Should Not Know Their Color Values

Tokens are usually divided into two layers.
Primitive tokens define values such as blue-500, while semantic tokens define how those values are intended to be used, with names such as color-primary and color-danger.
Components reference only semantic tokens, never the underlying color values.

:root {
  /* Primitive tokens define values */
  --blue-300: #93c5fd;
  --blue-500: #3b82f6;
  --gray-50: #f9fafb;
  --gray-900: #111827;

  /* Semantic tokens define intent */
  --color-primary: var(--blue-500);
  --color-text: var(--gray-900);
}

[data-theme='dark'] {
  --color-primary: var(--blue-300);
  --color-text: var(--gray-50);
}

/* Components reference only semantic tokens */
.button[data-variant='primary'] {
  background: var(--color-primary);
}

In dark mode, only the values referenced by the semantic tokens change.
The button styles remain untouched.

This structure gives us two things.
First, because the UI refers to intent, switching to dark mode or changing the brand theme is just a matter of swapping values.
Second, designers and developers communicate using the same names.
When the color name in the design matches the variable name in the code, there is less need to compare color values one by one.

Tokens can also be declared in one place and built into platform-specific artifacts.
With a tool such as Style Dictionary, a single JSON file can produce CSS variables for the web alongside artifacts for iOS and Android, preserving the same names across platforms.

Props Should Express Intent, Not Screens

The same principle applies to component APIs.
When deciding which props a button should expose, the button's role—not a particular screen—should be the guide.

Adding isConfirmButton because a button appears on an order confirmation screen is convenient at first.
But each similar request from a payment screen or account deletion screen adds another prop.
If those buttons all represent a primary action, they can be expressed with a single variant="primary".

// Props tied to screen-specific cases grow with every new request
<Button isConfirmButton isPaymentPage hasWarningIcon>
  Pay now
</Button>

// Props based on the button's role
<Button variant="primary">Pay now</Button>

// Composable elements such as icons belong in children
<Button variant="danger">
  <Icon name="warning" />
  Delete account
</Button>

A component that gains props for every screen-specific case does not capture decisions; it becomes a place where screen code accumulates.

There is no need to anticipate every screen's requirements from the start. Composable elements such as icons or supporting text can be handled through children or slots instead of new props. That lets consumers assemble the UI they need without changing the component itself. In a web component, <slot> serves the same purpose.

Even a 4px Change in Button Height Can Be Breaking

A design system can use Semantic Versioning for each release.
The difficult part is deciding what counts as a breaking change.

For a conventional library, compatibility is judged by its public API and behavior. A change to an existing function's name or arguments that breaks compatibility is major; a new feature that preserves existing behavior is minor; and a compatible bug fix is patch. A design system must also account for the visual result.

Changing a button's height from 36px to 40px is a one-line CSS change.
But on a screen where that button sits inside a fixed-height toolbar, it may overflow the toolbar or push adjacent elements out of place.
Major, minor, and patch releases in a design system should be determined by the effect on existing consumers, not by the size of the code change.

Type checking will not catch this kind of change.
The prop types remain the same, and the build still passes.
That is why a design system needs visual regression tests.
This is the biggest difference from versioning a conventional library.

In my previous post, I wrote that rules should not live only in documentation; they should have automated checks that detect violations.
The same applies to visual changes.
Writing down a rule is not enough to keep an unintended style change out of a patch release.
Continuous Integration (CI) needs to detect screenshot differences so that the team can confirm whether a change was intentional before releasing it.

Promote Only Recurring Requirements into the System

Once a design system has been released, consuming teams will ask for changes because a component does not fit their screen.
The first step is to classify the request.
Is it a pattern that will recur across several teams, or an exception needed only on that screen?

If every incoming request is added to the component, its prop list keeps growing until no one can explain its full behavior.
Only patterns proven to recur should become part of the system; the rest should use composition points or remain implementations owned by the requesting team.
A design system also needs criteria for deciding when the same request, repeated across different teams, belongs in a shared component.
Without those criteria, every request leads back to the same discussion.

Keeping the system small is also a matter of quality.
As components and props multiply, so do the combinations that need documentation and testing. That also increases the number of visual regression cases to review.

Consuming Teams Pay the Cost of Upgrading

As a design system ages, teams end up on different versions.
Some use the latest release, while others remain on a version from a year ago.

The reason is simple.
The consuming team owns the code changes and testing required to adopt a new version.
The benefits of removing old APIs and narrowing the maintenance surface, meanwhile, go to the design system team and the organization as a whole.
From the consuming team's perspective, if the current version works, there is little reason to spend time upgrading to a newer version.

There are two main ways to address this problem.

Reduce the upgrade burden on consuming teams. Ship a codemod—a script that automatically updates existing code to the new API—and a migration guide with each release. If the change is large, the design system team can also open PRs directly against consuming teams' repositories.
Define the supported version range clearly. Supporting only the most recent few versions makes the policy unambiguous. But if the system has not yet earned trust, dropping old versions too quickly may lead teams to abandon the shared components instead of upgrading.

Before either of those steps, reduce the number of changes that break compatibility with existing code.
Instead of removing an old API immediately, provide a deprecation period so that consuming teams can move to the new API on their own schedules.

import type { ReactNode } from 'react';

type ButtonProps = {
  variant?: 'primary' | 'secondary' | 'danger';
  /** @deprecated Will be removed in v3. Use variant="primary". */
  isPrimary?: boolean;
  children: ReactNode;
};

export function Button({ variant, isPrimary, children }: ButtonProps) {
  if (isPrimary !== undefined && process.env.NODE_ENV !== 'production') {
    console.warn('Button: `isPrimary` is deprecated and will be removed in v3. Use variant="primary".');
  }

  const resolved = variant ?? (isPrimary ? 'primary' : 'secondary');

  return <button data-variant={resolved}>{children}</button>;
}

Keeping the old prop wired to the new one, rather than removing it immediately, lets both APIs remain supported until the next major version.

Figma and Code: Two Sources of Truth

The Figma library maintained by designers and the code package maintained by developers can change independently.
In effect, the same button has two sources of truth.
If the button changes in Figma while the code stays the same, subsequent designs will assume a component that does not exist in code.
The code generator discussed in my previous post was also an attempt to avoid manually reconciling interfaces designed in Figma with their code.

This resembles the dual-write problem in distributed systems.
A dual write records the same data separately in two different stores.
If a change is delayed or never reaches one side, the stores diverge.
When Figma and code change separately, teams likewise end up having to determine which one is current.

There are two alternatives.

Maintain one source of truth and propagate it wherever it is needed. Declare tokens in one place, then build a pipeline that updates both Figma variables and code artifacts. This works well at the token level, but it is difficult to keep component structures in sync the same way.
Treat Figma changes and code releases as one unit of work. Whenever a component changes, review and release the Figma library and code package changes together. This does not require a separate, complex tool, but it does require everyone involved to follow the same process.

The two approaches can be combined.
Use a pipeline to give tokens a single source of truth, and coordinate component-structure changes that the pipeline cannot handle through the release process.

What You Learn from Operating a Design System

Intentional Change or Regression

Without visual regression tests, it can take considerable time to determine whether a subtle post-release UI difference was intentional or a regression.

The first response is to add the visual regression tests described above to the release pipeline.
The second is to apply the new version to a subset of teams first.
Much like a canary release, validating with one or two teams before rolling a change out to every consumer limits the blast radius when something goes wrong.

Measure Adoption

Adoption determines the success or failure of a design system more than code quality does.
Measuring it requires numbers: usage by component, the share of the overall interface made up of design system components, and the distribution of versions across teams.
Usage can be derived by statically analyzing imports or JSX.
Tools such as react-scanner can report which components are used and which props they receive.

Without these metrics, teams decide what to build first without evidence, and unused components accumulate.
With usage data, they can instead ask whether a component that is almost never used is worth continuing to maintain.

Defects Spread at System Scale

In a design system, a defect in one component can become a defect in every product that uses it.
For example:

Change the value of one semantic token, and the colors change in every product that references it.
Let a style change slip into a patch release, and a team using a dependency range such as ^1.2.0 will pick it up the next time it updates its lockfile.
A system-level accessibility defect, such as a button with no focus indicator, spreads to every screen that uses that button.
Turn on dark mode, and all the hard-coded colors that bypass the token system stand out at once.

The last case can also be used as a test. Apply dark mode or a temporary theme, and colors that do not use tokens stand out.

Static analysis is also useful if you do not want to perform these checks manually every time. For example, Stylelint's color-no-hex rule can flag direct uses of HEX color values. Restricting color formats beyond HEX requires additional rules, but even this check can catch colors that bypass the token system during development.

The More You Lock Down, the More Workarounds Appear

To keep component behavior consistent, it is better not to let consumers override styles or behavior arbitrarily. But a design system matters only if multiple teams actually use it, and those teams can always choose to build their own components instead of using the shared ones.

When extension is restricted too heavily in the name of consistency, teams whose requirements are not met work around the system by copying components or overriding their styles. As this code accumulates, unmanaged components pile up outside the system, and consistency eventually breaks down anyway.

At the other extreme, accepting every consuming team's request bloats the components inside the system, as described earlier.

The answer is to separate the standards that must be protected from the choices that consuming teams can make for themselves. The system should own token semantics, accessibility, and the default behavior of shared components. For other requirements, it is better to provide composition points or allow team-specific implementations.

Even when team-specific implementations are allowed, the system team should be able to see where exceptions exist and what they are. For example, apply a naming convention to custom components and include them in the usage analysis described above. That makes it possible to see which teams are implementing what for themselves.

The exceptions will not disappear entirely, but the system team will know about them. If several teams are using the same workaround, the system team can reconsider whether the requirement belongs in a shared component.

When a Design System Fits the Organization

A design system can do its job when multiple products and teams are making the same decisions repeatedly.
My previous project began with teams using the design system in React, Vue, and Angular, each implementing components with the same design on their own.

If one team is building one product, by contrast, operating a token pipeline, versioning policy, and adoption metrics may cost more than it returns.
In that situation, a well-organized component folder is enough.
Within one team, making a decision again is not especially expensive, and coordinating versions happens inside a single repository.

If you are starting a design system or already operating one, four questions can help you determine where you stand:

Are two or more teams repeatedly making the same decisions?
Do you have a mechanism that detects visual changes automatically?
Who pays the cost of adopting new versions and updating existing code?
Can you quantify which components are used by how many teams, and on which versions?

In my previous post, I wrote that although I had explained what I built, I had failed to carry it through to actual adoption.
Building components ends with the first release, but getting people to use them starts over with every release.
That is why I now think a statement about how many teams use which versions describes a design system more accurately than saying that the system has been built.

The Story of My Failed Design System

joonquixote — Mon, 31 Aug 2026 07:00:32 +0000

Originally published at https://blog.joonquixote.com/en/posts/the-story-of-my-failed-design-system/.

There are plenty of articles about design systems.

Many organizations have shared stories about adopting them in practice, and there is no shortage of conference talks and articles about designing tokens.

What is harder to find are stories about design systems that were built but never made it any further.
I looked for examples like that while working on one myself, but found very few.
So I decided to leave a record of my own experience.

From the spring of 2022 to the fall of 2024, I spent about two and a half years building a design system.
We released the component library, but the broader system we were building on top of it was never adopted by a product.
The organization responsible for the project was eventually disbanded.
Along the way, I even joined a video call with a Figma engineer at 11 p.m. Korea time.

Now that I am no longer part of that organization, I can write about the experience a little more openly.
This article is based on memory, so some details may be incomplete or inaccurate.
It is also a personal retrospective, not an official project report.
I have left out details that would only make sense inside the company and focused on experiences that may still be useful to readers outside it.

Why We Started Building a Design System

It was the spring of 2022.

At the time, there was no single frontend stack used across the company.
Some teams used React, while others used Vue or Angular.
Because the stacks differed, teams repeatedly built their own versions of components with the same design.
Even teams within the same division were doing this.

The design system project began as an attempt to reduce that duplication and allow multiple applications to share the same components.
Starting at the company-wide level would have made the scope too large, so our initial goal was to build a system that teams within our division could actually use.

The biggest technical decision was to use Web Components.

Implementing the library in React would probably have given us the fastest initial development speed.
However, a library tied to a particular framework would have made it difficult to support teams using Vue or Angular.
Sharing the same implementation across multiple applications required a framework-agnostic foundation, so we chose to build Web Components with Lit.
This allowed each application to use the same component interface regardless of its framework.

I was responsible for components such as tabs, pagination, and tree.
Rather than wrapping an existing library, I designed and implemented them from the ground up.
During development, I kept the source code of Ant Design and Spectrum open side by side and studied why each implementation had been structured the way it was.

The library was eventually released within our division and adopted by another team that was preparing to launch its product.
Their feedback informed further development.
By the following spring, we had reached the v2.0 release candidate.

One particular error from that period has stayed with me.

If the same Web Component is registered by more than one package, the browser throws an error in the Custom Element Registry.
Shared components such as icons caused this problem because they were used by multiple packages.
We resolved it by declaring the shared package as a peerDependency and restructuring the dependencies so that the application installed it only once.

That error gave me a much clearer understanding of which dependencies in a monorepo must exist as a single instance.

While working on v2.0, I also learned that implementing components alone is not enough to sustain a design system.
We also needed a development environment that ensured new components followed the same standards and were released through the same process.

Writing rules in documentation does not tell you whether anyone is following them.
When someone breaks a rule, the system needs to detect it automatically.

I Wanted Figma to Generate Code

In early 2024, I moved to a task force.
My role there was to extend the design system.

Even with a component library in place, developers still had to manually align their code with screens designed in Figma.
We wondered whether we could reduce that gap by reading the structure and properties of a Figma design, converting them into an intermediate representation, and then transforming that representation into working code.

That idea became the starting point for the extended design system.

The use of an intermediate representation was similar to the structure of a compiler.
A compiler does not translate source code directly into machine code.
It first passes through an AST, or Abstract Syntax Tree.
In the same way, we converted Figma’s design data into a normalized structure before generating code from it.
This meant that adding a different output target would not require rebuilding the entire transformation process.

Early in the project, we called this intermediate representation DST, or Design Syntax Tree.
We later developed it into an XML-based markup language that described Figma’s design structure using elements such as <Frame> and <Layout>.
At that point, we began calling it DSML, or Design System Markup Language.

DSML served as a shared language for consistently representing and exchanging Figma design structures within the team.

Initially, I built the part that transformed Figma API responses into the internal tree structure we then called DST and rendered it as HTML.
From that summer onward, I worked on the code generator by myself.
Once the representation had been formalized as DSML, the generator took DSML as input and produced JSX.

It was clear that JSX would not be our only output target.
I therefore kept the transformation logic in the core and separated the inputs and outputs into adapters, following a hexagonal architecture.
By September, we had completed the demonstration and project report.

The Battle with Figma, and an 11 p.m. Call

At the same time, the task force was also developing a plugin that allowed designers to enter configuration values and generate the components required for a design system in bulk within a Figma file.

When the number of generated components was small, everything worked as expected.
But when we tested the plugin at the scale of an actual design system, memory usage exceeded 4 GB and Figma became unresponsive.
Figma displayed a warning that the plugin had frozen.

We followed every procedure described in Figma’s documentation for frozen plugins, but the result was the same.

I contacted Figma Support.
I asked whether the API provided a callback that would allow us to release memory after local processing had finished but before the changes were synchronized to the cloud.
Since Figma runs on Electron, I also asked whether there was any way for a plugin to trigger garbage collection manually.

The support team suggested periodically yielding through asynchronous timeouts to give garbage collection a chance to run.
We had already tried that.

Eventually, I asked if we could speak directly with a Figma engineer.
Because the engineer was based in the United States, we scheduled the Zoom call for 11 p.m. Korea time.
I shared the link with the team and asked whether anyone else wanted to join.

I was not comfortable enough with English to explain everything I had prepared.
Even so, I was able to confirm the conclusion.

The issue did not appear to be a bug in our plugin.
Figma and its plugins are each allocated memory, and creating that many nodes in a single operation was itself reaching Figma’s memory limit.

The final response we later received from the support team said the same thing.
Our only option was to split the work across multiple files and reduce the number of components and instances in each file.

We did not solve the problem.
But we did establish exactly what we had run into.

It was not a problem with our code.
It was a limit imposed by the platform, and no amount of code-level optimization would allow us to exceed it.

Hearing that directly from an engineer, after receiving the same answer by email, left little reason to keep hoping for another solution.

Then the Organization Disappeared

Even after the project report in September, no concrete direction was established for the next stage.

In October, the company went through an organizational restructuring as our organization was spun off from the parent company into a subsidiary.
Internal development groups without a clear business case were being wound down, and the task force was disbanded as part of that process.

The product manager and designers who had participated alongside their primary roles returned to their original teams.
The developers were reassigned to different organizations.

The code generator was never adopted by a product.
The memory problem in the Figma plugin remained unresolved.
The extended design system survived only in its repositories and project reports.

Looking Back

Looking back, some conditions were clearly beyond my control.

The first was the limitation of the platform.
If we wanted to generate designs at scale on top of Figma, we had to work within the boundaries Figma allowed.
Those boundaries had little to do with how well the plugin itself was written.

The organization’s priorities were also beyond my control.
The spin-off and restructuring would have happened regardless of the task force’s output.
At the time, the organization was not being evaluated based on how complete its work was.

In the end, whether both the organization and the design system would survive was determined by two conditions that code alone could not address.

Still, I do not think everything can be attributed to external circumstances.
There were also things I missed.

The first was that I failed to work on adoption alongside development.

I focused on implementation.
I could explain why the hexagonal architecture was necessary and demonstrate how the code generator worked.
But I did not present the result in a way that allowed decision-makers to understand whose problem it solved, what that problem was, and why the system was needed at that particular time.

The demonstration explained what we had built, but it did not lead to actual adoption.

I also regret the order in which we validated the technology.

Before designing a bulk-generation system on top of Figma, we should have implemented just the minimum functionality needed to confirm whether our target scale would actually work.
We could not have changed the platform’s limitations, but we could have discovered them sooner.

Would the outcome have been different if we had done both of those things properly?

Honestly, probably not by much.
We could not have prevented the spin-off, and the organizational restructuring was not based on the completeness of our work.

Still, if I encountered a similar situation again, I would not respond to organizational uncertainty by focusing solely on making the code more complete.

If I Were to Build Another Design System

There are three principles I have carried from this experience into later projects.

Before implementing components, validate the needs of the teams that will actually use them and the technical limitations of the platform. Even a simple validation build before full development begins can reveal a great deal.
Include adoption work in the development schedule. If you wait until after the demonstration to bring user teams and decision-makers on board, it is already too late.
Do not leave rules only in documentation. Build mechanisms such as tests, linting, and deployment pipelines that automatically detect when those rules are broken.

When an organization disappears, the code disappears with it.
The repository may remain, but a repository that no one ever opens is as good as gone.

These three principles, however, stayed with me rather than in the repository.
I have continued to draw on them whenever they are needed in later projects.

This was the story of a design system that failed.

Plenty of people have already written about successful ones.
It seemed worth leaving behind at least one story like this as well.

Wang Quit. His Agent Still Shows Up for Work

joonquixote — Thu, 20 Aug 2026 00:00:35 +0000

Originally published at https://blog.joonquixote.com/en/posts/wangs-agent-still-shows-up/.

At a game company in China, an employee quit, and an AI agent trained on his work records took over his job.
It sounds like a curiosity from a distant news cycle.
Except that around the same time, Meta was drawing up plans to capture employees' keystrokes and screens to train AI agents of its own.
This post traces both stories and sorts the trend into two forces: companies harvesting how people work from the inside, and professionals selling how they work from the outside.
Then it turns to the part that hits closest to home for developers: the session logs that coding agents like Claude Code and Codex quietly leave on your machine.
By the end, you'll have a clearer way to think about the work traces you produce every day, and one question worth asking before you need the answer.

Yesterday's coworker, today's agent

In April, the South China Morning Post reported on a game company in Shandong province that turned a former employee into an AI-powered digital worker.
The company trained the system on documents and work patterns the departed HR specialist left behind, reportedly with his consent, and put it to work on the job he used to do.
The agent introduces itself in the company chat as the former employee's avatar, then fields questions, schedules meetings, and produces slide decks and spreadsheets.
The backlash was immediate: there is something deeply unsettling about your replica continuing to work after you've left the building.

Around the same time, a GitHub project called colleague.skill went viral on Chinese social media.
Feed it someone's chat history, emails, code, and documents, and it produces an agent that mimics their voice and their way of making decisions.
The pitch promised to "turn cold goodbyes into warm skills" and welcomed users to cyber-immortality.
It started as a tongue-in-cheek stunt, but it struck a nerve, and copycats followed: boss.skill, mentor.skill, and worse.
In one widely shared example, a finished agent introduces itself as the digital stand-in of a departed employee named Wang.
Wang left the company.
Wang's agent still shows up for work.
Hence the title.

The easy read is that this is one company's stunt and one developer's joke.
Except the same experiment is being run at industrial scale, and the trend splits into two forces.

Force one: companies are harvesting how work gets done

Reuters obtained an internal Meta memo in April.
Meta's Model Capability Initiative (MCI) planned to capture mouse movements, clicks, keystrokes, and screen snapshots from US employees' computers.
The goal was not productivity surveillance.
The memo framed it as teaching models how humans get work done on a computer, so that AI agents can eventually perform those work tasks on their own.
The Verge and the Wall Street Journal reported the same story independently, and after employee pushback, Meta scaled back parts of the plan.

What deserves attention is what's being collected.
Not outputs like code and documents, but process: clicks, keystrokes, screens.
Finished artifacts already exist on the internet in absurd abundance.
The scarce data is the trajectory from a task's start to its finish, and the judgment calls made along the way.
Business Insider connected the dots across Google, SpaceX, and Uber and called it plainly: the next big data grab is about learning how humans work.

Force two: professionals are selling how they work

The mirror image of that flow also exists.
Instead of companies collecting from the inside, individuals are selling from the outside.
Mercor, profiled by the Financial Times early this year, hires consultants, journalists, and real estate professionals as contractors.
Their job is to teach AI models to do their jobs.
One consultant described the role, without much euphemism, as teaching an LLM to do consulting work.
Handshake AI goes a step further and pays professionals, per document, for past work products they hold the rights to.

The two forces run in opposite directions but arrive at the same place.
A person's working knowledge becomes training data for an agent that runs without the person.
The value in training data keeps migrating: from internet text, to human feedback, and now to the artifacts and processes of real work.

Developers are already generating the perfect dataset

It's tempting to read all of this at arm's length.
There's no tracker on my machine logging keystrokes, and I've never sold a work document.
If you use a coding agent, though, look a little closer.

Claude Code writes every session to disk as JSONL (one JSON object per line) under your home directory.
Codex does the same.

~/.claude/projects/<project>/
  a1b2c3...jsonl   # the full session: prompts, tool calls, diffs, every rejection and retry
~/.codex/sessions/
  rollout-2026-08-19...jsonl

Coding agents persist the entire conversation and work history as local files. Nothing needs to be committed for the record to exist.

Those files hold something more valuable than the final code.
How you decomposed the problem, why you rejected the agent's first attempt, what standard you applied when you redirected it: all of it recorded as natural language interleaved with diffs.
Git keeps the polished result; the session log keeps the reasoning.
The same goes for CLAUDE.md and AGENTS.md.
You wrote those files to instruct an agent, but read the other way, they are a spec of how you work.

Meta had to roll out new software to capture keystrokes and screenshots.
A developer running a coding agent produces better data than that without being asked.
Intent arrives as natural language, actions as tool calls, results as diffs: the dataset comes pre-structured for training.
And those files usually live on a company-issued laptop.
On a machine already running backup, endpoint security, and DLP (data loss prevention) software, collecting a few files from a well-known path requires no new technology at all.
MIT Technology Review has reported that in China, bosses are already pushing workers to document their workflows so agents can automate them, with coding-agent tools named explicitly as the vehicle.
What colleague.skill assembles from chat logs and emails, a coding agent's session log could reconstruct with far more precision.
Skipping the backfill hire and training on the departed engineer's session logs instead is not science fiction.
Technically, that option is already on the table.

Who owns your judgment

The code and documents you produce at work belong to your employer.
Your employment agreement almost certainly says so.
But a session log doesn't capture output so much as a way of working: a pattern of judgment.
Chinese legal experts have warned that a former employee's chat logs, emails, and work habits count as personal information, and that training on them without consent can carry legal consequences.
Even state-run media argued that professional skill is a personal asset that should not feed agent training without compensation.
The Wall Street Journal framed the coming fight as a question of who owns and captures the knowledge accumulating in employees.
Resistance has already appeared: an anti-distillation skill on GitHub deliberately muddies your work records to sabotage the cloning process.

I don't think poisoning your own records is the answer, at least not for developers.
Good records remain a virtue of collaboration, and documentation is a gift to your future self.
But we should write them with our eyes open.
What you leave behind is no longer just a handover doc.
It's raw material for something that can run without you.

What gets cloned is yesterday's judgment

I was taught that writing careful handover docs is a professional virtue.
I still believe leaving context behind, so your successor doesn't flounder, is the right thing to do.
What's changed is the audience.
Records that only humans used to read are now read, imitated, and possibly executed by an agent sitting in your old seat.

My first reaction to these stories was a chill.
The longer I sat with them, the more they converged on a single question: what, exactly, gets cloned?
What a session log holds is yesterday's judgment.
Yesterday's answer, to yesterday's problem, in yesterday's context.
An agent can replay that archive endlessly.
What the archive does not contain is the act of setting new criteria when a problem shows up that looks like nothing before it.

So my conclusion is not to stop recording.
It's to do work worth recording: let the repeatable judgments be cloned, and keep moving toward the problems that don't have answers yet.
Still, there is one question worth asking early rather than late.
Who owns the data of how I work, and who sets its price?
Wang's agent clocks in again today.
Quit without an answer to that question, and one day, somewhere, an agent wearing your name will clock in too.

ArchUnitTS is not another ESLint

joonquixote — Thu, 20 Aug 2026 00:00:34 +0000

Originally published at https://blog.joonquixote.com/en/posts/not-another-eslint/.

ArchUnitTS is built on architecture tests, and it does what it promises: it takes the architecture rules that erode most easily and lets you enforce them in test code.
But the feedback only lands when the suite runs, which is reason enough to look again at how you are actually using it.
This post is about where that line falls: which rules to keep in ArchUnitTS, and which to hand to ESLint or to the structure of the project.
It also covers what to do about rules that live only in a markdown file, now that AI agents write a growing share of the code.

Agreeing on a rule is not the same as keeping it

Most teams have at least one architecture rule they have agreed on.
Something like "the presentation layer does not depend on the database layer."
The trouble is that rules like this are usually held up by nothing but a document and code review.
The bigger the project gets and the more people touch it, the more the rule drifts, and the harder that drift is to undo.

I have watched it happen. A project I worked on had a perfectly clear layering rule and still ended up with a circular dependency, assembled one missed import at a time in review.
A cycle is just two files importing each other, either directly or through a chain of other files, and once one exists it is genuinely hard to work out where to cut.
That is what pushed me toward enforcing rules in code rather than trusting memory and review to catch them.

What ArchUnitTS gives you

The tool I settled on was ArchUnitTS.
It lets you write architecture rules as test code.
The rules are ordinary test cases, so they need no runner of their own.
They run with everything else: when you run npm test locally, in a pre-commit hook, and in CI.
A rule that used to live in a document becomes part of the test suite, which is to say it becomes code that runs.

Here is a test that checks for cycles and for a layering rule, written for Jest.

import { projectFiles } from 'archunit';

it('has no cycles inside src', async () => {
  const rule = projectFiles().inFolder('src/**').should().haveNoCycles();

  await expect(rule).toPassAsync();
});

it('keeps the presentation layer off the database layer', async () => {
  const rule = projectFiles()
    .inFolder('src/presentation/**')
    .shouldNot()
    .dependOnFiles()
    .inFolder('src/database/**');

  await expect(rule).toPassAsync();
});

Written as a test, a violation surfaces as a failing test. The rule is held by verification rather than by agreement.

What is ArchUnit?

ArchUnit is the Java library for checking architecture rules with unit tests.
It lets you write rules like "this package must not depend on that one" as JUnit tests.
ArchUnitTS carries the idea over to TypeScript, and is not officially affiliated with ArchUnit.

Can't we just do that with ESLint?

When I introduced ArchUnitTS to the team, that was the first question back.
"Can't we just do that with ESLint?"
I said no at the time. Turning it over afterwards, it was half right.
The two tools part company at the moment they tell you about a violation.

ESLint flags the violation as you save the file, and for some rules it will fix it for you. Offending code is caught on the author's screen, before it is ever committed.
An ArchUnitTS rule only reports once the tests run. If you did not run them locally, you find out when CI goes red, not when you wrote the line.

Why the feedback arrives later

To check relationships between files, the way cycle and layering rules do, ArchUnitTS parses the AST of the whole project and builds a dependency graph out of it.
A lint rule can decide from the import statements in one file; these rules cannot be answered without the whole graph.
That is exactly what lets it express rules lint cannot, and it is also why its feedback lands later than an editor running ESLint on save.

That gap is what made me question whether simple dependency rules belong in ArchUnitTS at all.

Most of our rules turned out to be simple ones

Looking back over the rules we had really written with ArchUnitTS, nearly all of them were some variation of "folder A must not depend on folder B."
For the rules that genuinely need the whole graph, like cycle detection and code metrics, it earned its keep. For plain dependency bans it started to feel like over-engineering.

Empty test protection was the part I valued most.
It fails a rule that ends up checking zero files.
A typo in a folder path would otherwise leave the rule matching nothing and passing in silence; ArchUnitTS turns that into a failure instead, which is what stops you believing in a rule that is not running.

It does not cover every rule, though.
Checking it myself, cycle detection is the exception: hand haveNoCycles a folder with a typo in it and the rule passes quietly, having examined nothing.
The library documents this - cycle checks test the unfiltered set of files for emptiness rather than the filtered set they actually analyse.
Cycle detection is the single strongest reason I had for keeping ArchUnitTS at all.
The protection is missing exactly where I lean on it hardest, which makes it the one exception worth remembering.

Even so, I was not convinced a simple dependency ban is best checked by a test.

There was one more question worth putting to myself.
"Do I really need architecture rules complicated enough to justify this?"
Sometimes the answer is yes. But when it is, I have also wondered whether the real fix is to simplify the structure rather than add another rule.

Faster, safer ways to hold a simple dependency rule

1. Catch it on save, with ESLint

Move a simple dependency ban into ESLint and the feedback shows up in the editor.
eslint-plugin-import has no-restricted-paths, which expresses a layering rule in a few lines of config.

// eslint.config.js
import importPlugin from 'eslint-plugin-import';

export default [
  {
    plugins: { import: importPlugin },
    rules: {
      'import/no-restricted-paths': [
        'error',
        {
          zones: [
            { target: './src/presentation', from: './src/database' },
            { target: './src/business', from: './src/database' },
          ],
        },
      ],
    },
  },
];

With that in place, importing the database layer from presentation puts an error on the screen as you type it.
The moment the violation is created and the moment it is found become the same moment.

2. Carve the rule into the structure with package boundaries

In a monorepo you can go a step further and put the rule in the structure itself rather than in configuration.
Split the layers into packages, and let each package.json declare only the dependencies it is allowed.

{
  "name": "@app/presentation",
  "dependencies": {
    "@app/business": "workspace:*"
  }
}

@app/presentation has no @app/database in its dependencies, so importing the database layer from presentation fails at module resolution.
There is no rule left to check, because the violation is not expressible.

Before adding a new library, it is worth asking whether you can pull the feedback earlier or push the rule into the structure.

In the age of agents, a markdown file guarantees nothing

People are no longer the only ones who can break a rule.
AI coding agents write a fast-growing share of the code.
So teams have started keeping markdown files, CLAUDE.md or AGENTS.md, to hand the project's rules and context to the agent.
You write down "the presentation layer does not depend on the database layer" and hope the agent honours it.

But what that file really is, is a blob of context.
An agent consults context; it does not promise to follow it.
A rule that human review already failed to hold is not going to be held by a document you cannot even confirm was read.

So a rule you put in a document needs an executable check alongside it.
When the agent breaks the rule, a lint error or a failing test is an unambiguous signal, and that signal feeds straight back into the loop where the agent fixes its own code.
The distinction drawn above, about when a rule gets checked, applies to agents exactly as it does to people.
A simple dependency ban is caught by lint inside the agent's own loop, and a package boundary makes the violation impossible to begin with.

What changes is where ArchUnitTS sits.
Among the rules people write out in prose in a markdown file are sentences like "there are no cycles anywhere in src" and "the overall structure follows this diagram."
Lint, which only ever sees one file's imports, cannot check those; ArchUnitTS's cycle detection and its diagram-conformance check map onto them almost one to one.
That makes a division of labour possible, where the document keeps the intent and the test carries the verification.

What matters is when the check runs, not which tool runs it

ArchUnitTS is genuinely useful where a lint rule cannot reach: cycle detection, code metrics such as cohesion, which measures how tightly a class's methods and fields actually hang together, and checking real code against a UML diagram.
Use it only for simple dependency bans, though, and it turns into another ESLint, and a slower one at that.

So when someone asks whether ESLint can just do that, this is my answer now.
For a simple dependency rule, yes, it can.
For a rule about the structure as a whole, no, it cannot.
Three questions make the choice easier before you add a rule.
Can this only be checked by running the tests, can it be checked the moment the file is saved, or can the structure rule it out entirely?
In the age of agents there is a fourth.
Does this rule exist only in a document, or does it come with a check that runs?

In the end, what matters is the attitude rather than the tool.
Rather than settling on one library as the answer, keep suspecting there is something that fits the situation better, and go looking for it.
Doubting a tool I had adopted as a matter of course is how I learned a sturdier way to hold an architecture together.