Design
The component was renamed and the documentation was not
A weekly drift report between the component library and the documentation that describes it.
What the worker does
Design system maintenance with an AI worker is a weekly drift report. The worker compares the component library against its documentation through the Figma, Notion and GitHub connections, then lists components with no documentation page, documentation describing components that were renamed or removed, and design tokens referenced in docs that no longer exist in the library. Deprecation decisions stay with the design system owner.
- Runs
- Weekly
- Connections
- Figma, Notion, GitHub
- Output
- Three drift lists
Design systems fail at the documentation, not the components
The components are fine. Somebody renamed a variant, somebody else added a spacing token, a third person deprecated a card and left it in the library so nothing would break. Each move was reasonable. Together they mean the documentation now describes a system that partially exists, and engineers have started guessing.
The moment a designer cannot trust the docs, they open an old file and copy from it, and the system starts forking in a way that takes a quarter to notice.
The three lists
| List | What it means | Usual cause |
|---|---|---|
| Undocumented components | In the library, described nowhere | Added in a hurry during a project |
| Stale documentation | Describes something renamed or removed | A rename that touched the library and not the docs |
| Dangling references | Docs cite tokens or variants that do not exist | Token cleanup done without a documentation pass |
Two things worth adding to the brief
Check the code side too
If the implemented components live in a repository, the GitHub connection lets the worker report components that exist in Figma and not in code, or the reverse. That gap is usually where engineers start improvising.
Report the delta, not the inventory
A weekly report that lists every component is a report nobody reads. Brief the worker to report what changed since last week, with a full inventory only when you ask for one.
Who does what
The worker
- Reads the library and the docs weekly
- Names every mismatch with a link to both sides
- Reports the change since last week
- Drafts the missing documentation page when asked
The system owner
- Decides what gets deprecated
- Sets the naming convention the audit checks against
- Approves and publishes the drafted pages
- Decides when drift is worth a migration
Questions people ask
+Does the worker edit our Figma library?
No. It reads the library through the Figma connection and delivers findings as a comment on a Polaris task. Files stay authored by designers, which is also why the report links to each component rather than proposing an edit.
+Can it write the missing documentation pages?
It can draft them from the component structure and any existing usage, delivered as a file on the task. Publishing is yours, and pages published into Polaris Docs are versioned with review comments so the draft can be argued with in place.
+How does it know what our naming convention is?
From the worker's SKILL.md file, which you write and can edit at any time. A convention stated there, such as every component page carries a Usage and a Do not use section, turns a vague audit into a checkable one.
+Is weekly too often?
For a stable system, monthly is enough and the report is shorter. During a migration, weekly catches divergence while it is still one component rather than a pattern. Billing follows delivered work, so a quiet week is a cheap week.
Related
Design work an AI teammate can take, and the part it cannot
Five jobs around the work, none of them the work itself. Taste stays where it belongs.
Four versions of the logo are live and nobody signed off on three
A quarterly pass over your public surfaces, checked against the rules your brand doc states.
The README describes a version of the code that no longer exists
A monthly list of statements in your docs that the code no longer supports.
Connect Figma to Polaris
A Figma token belongs to a person, and Polaris shows you which person it verified, which is the detail worth checking before you store it.
Connect GitHub to Polaris
Fine-grained tokens let you hand over three repositories instead of an account, which is the whole reason to use them here.
Hire an AI technical writer
The documentation debt on your team is not a writing problem, it is a nobody-has-two-free-hours problem, and this is the worker for those two hours.
Skill file
The capability an agent has, written down where a person can read and edit it.