Design System Contribution Intake

Every healthy design system gets more requests than it can build. A product team needs a card with a chart in it, another needs a date-range picker, a third wants a variant of something that already exists but does not know it exists. Without a pipeline, these arrive as Slack messages and Figma comments, get answered inconsistently, and the system either grows by accretion or earns a reputation for saying no.

The expensive part of a good answer is not the decision; it is the research behind it. Someone has to check whether the need is already covered by existing components or a documented composition, estimate how many surfaces would actually adopt the new thing, and draft what its API would look like if it were built. That research is hours of careful reading per proposal — exactly the work that does not happen when proposals arrive faster than the team can investigate them.

This workflow makes that research repeatable. Agents do the reading: the overlap analysis against the existing system, the adoption estimate against the product codebase, and a first-draft spec. The design system council still makes the call, but it makes it from a packet of evidence instead of from instinct under time pressure.

Reach for it when proposals are arriving faster than the team can investigate them, when contribution decisions are being questioned because the reasoning is invisible, or when a backlog of requests has built up and needs consistent triage.

It is an Advanced workflow because the value depends on judgment at both ends: a well-formed proposal going in, and a council willing to own the decision coming out. The agents make the middle cheap; they do not replace either end.

• A contribution backlog the team is embarrassed about.
• Repeated near-duplicate components appearing in product code because requests went unanswered.
• A federated contribution model where product teams propose and a central team decides.
• An org-wide design system push that just generated a wave of requests.

Strip away the politics and every contribution decision rests on three questions. Is the need already covered — by an existing component, a documented composition, or a small extension to something that exists? If not, how many product surfaces would genuinely adopt the new thing, as opposed to the one team that asked? And if it were built, what would it actually be — its API, tokens, states, and accessibility requirements?

Each question maps to one stage of the pipeline and one kind of agent. They run in order because each stage can end the process early: a proposal fully covered by composition does not need an adoption estimate, and a proposal with two potential adopters rarely needs a full spec.

The intake runs as a Claude Code dynamic workflow. Including the word workflow in the prompt, or running with /effort ultracode, makes Claude write a JavaScript orchestration script that runs in the background. The script holds the proposal, each stage's report, and the early-exit logic in its own variables; intermediate results stay in the script rather than in Claude's context, so a proposal can be investigated against a large codebase without flooding the conversation.

Unlike a fan-out workflow, the stages here run mostly in sequence because later stages depend on earlier answers — the spec agent should know what the overlap agent found so it does not re-invent an existing pattern. Within a stage, the impact agent can still fan out across product areas, up to sixteen concurrent subagents and a thousand per run if the codebase is large. The run is resumable, and the working orchestration is saved to .claude/workflows/ in the project (or ~/.claude/workflows/ for a personal copy) so each new proposal runs through the identical pipeline as a /command.

Subagent definitions for the overlap, impact, and spec roles live in .claude/agents/ as markdown files. Keeping them versioned in the repo is what makes intake decisions comparable over time: the council can trust that proposal twelve was investigated by the same standard as proposal three.

Intake quality starts with the proposal. The template asks for the underlying need, the surfaces where it appears, and what the team is doing today, before it asks what they want built. Proposals written as solutions tend to smuggle in an API; proposals written as needs give the overlap agent something honest to check.

# Contribution proposal: {short name}

## The need
What the user or team is trying to do, in one or two sentences. No component names yet.

## Where it appears
Product surfaces, routes, or flows where this need shows up today. Links or paths if possible.

## What we do today
The current workaround: existing components composed, custom code, or nothing.

## Proposed solution (optional)
If you have a shape in mind, sketch it — but the intake checks the need, not the sketch.

## Evidence
Usage counts, screenshots, research findings, or support tickets that show this is real.

## Constraints
Deadlines, accessibility requirements, platform constraints, or brand requirements that bound the answer.

## Proposer
Team, contact, and how urgently a decision is needed.

The prompt names the proposal file, the system source, the product directories the impact agent may search, and the packet output. It also encodes the early exits, so the pipeline does not produce a full spec for a proposal the overlap stage already answered.

Run this as a workflow.

Process the contribution proposal at intake/proposals/2026-06-data-card.md through the intake pipeline.

Stage 1 — overlap: dispatch the overlap agent against packages/ui/src and the pattern docs in docs/patterns/. Report whether the need is fully covered, partially covered, or not covered, with the components or compositions that cover it and a worked example if composition is the answer. If fully covered, skip stages 2 and 3 and assemble the packet with a 'redirect to composition' recommendation.

Stage 2 — impact: dispatch the impact agent across apps/ to find surfaces showing this need today (custom implementations, repeated compositions, or workarounds). Report counts per product area and a conservative adoption estimate.

Stage 3 — spec: dispatch the spec agent to draft the component API (props, slots, variants), the semantic tokens it would consume, the interaction states, and the accessibility requirements, informed by stages 1 and 2.

Assemble intake/packets/2026-06-data-card.md: proposal summary, overlap report, impact report, draft spec, a recommendation (accept, accept narrowed, redirect to composition, decline) with confidence and the evidence behind it.

Do not modify any source code. The design system council makes the decision, not this workflow.

Overlap is the stage most often skipped under time pressure and the one with the highest payoff, because the cheapest component is the one you do not build. The agent's job is concrete: read the proposal's need, search the system and pattern docs, and either show the composition that covers it or state precisely what is missing.

---
name: overlap-analyst
description: Checks whether a proposed component or pattern is already covered by the existing design system, a documented composition, or a small extension to an existing component. Read-only.
tools: Read, Grep, Glob
---

You receive one contribution proposal. Answer one question: is this need already covered?

Method:
- Search the system source and pattern documentation for components whose purpose overlaps the stated need.
- If a composition of existing components covers it, write the composition as a short worked example with real component names and props.
- If a small extension would cover it (a new variant, prop, or slot on an existing component), name the component and the extension.
- If nothing covers it, say so and list the nearest neighbors and why they fall short.

Verdicts: fully covered, covered by composition, covered by small extension, partially covered, not covered.
Cite every component and doc you relied on. Do not evaluate whether the proposal is worth building; that is the impact stage's job.

Adoption estimates from proposers are optimistic by nature; estimates from the codebase are not. The impact agent searches the product code for the places the need already shows up — repeated compositions, one-off implementations, or copy-pasted workarounds — and counts them per product area. A need that appears in eleven surfaces across four teams is a different decision than one that appears in the proposer's feature and nowhere else.

The agent reports a conservative adoption estimate and labels it as an estimate. It also reports the cost of not building: how much duplicated or drifting code exists today because the system has no answer.

• Count current occurrences of the need: custom implementations, repeated compositions, workarounds.
• Group counts by product area and team so the council can see who benefits.
• Estimate realistic adoption — surfaces that would actually migrate, not surfaces that theoretically could.
• Report the duplication cost of doing nothing, with file paths as evidence.

The spec agent drafts what the component would be if built: its props and slots, the variants the impact evidence justifies, the semantic tokens it consumes, the interaction and loading states, and the accessibility requirements stated as requirements rather than aspirations. It is a draft for the council and the eventual builders to argue with, not a finished design.

The packet that goes to the council is one document: the proposal summary, the three stage reports, and a recommendation with an explicit confidence level. The recommendation is the workflow's opinion, clearly labeled as such — councils that rubber-stamp the recommendation have outsourced governance to a script, and councils that ignore the evidence have wasted the pipeline. The decision and its reasoning are recorded in the packet, which becomes the system's institutional memory.

# Intake packet: {proposal name}
Date, proposer, decision needed by.

## Need (from the proposal)
## Overlap report — verdict and worked composition if any
## Impact report — current occurrences, adoption estimate, cost of doing nothing
## Draft spec — API, tokens, states, accessibility requirements
## Recommendation
Accept / accept narrowed / redirect to composition / decline, with confidence and the evidence each part rests on.

## Council decision (filled in by humans)
Decision, reasoning, conditions, owner, and date. This section is the record of why.

A growth team proposed a DataCard component: a card with a metric, a sparkline, and a call to action, needed for a new dashboard. The proposal arrived as a finished Figma component and a request to add it to the system.

The overlap agent's verdict was covered by composition: Card, Stat, and Sparkline already existed, and the pattern docs included a metrics-card composition that covered two of the three layouts in the Figma file. The worked example in the report was eleven lines of JSX. The impact stage still ran and found four other places in the product where teams had hand-rolled similar cards — useful, but not a reason to add a fourth way of doing it.

The council redirected the proposal to composition in a fifteen-minute review, and the worked example went into the pattern docs the same week. The proposer's feedback was telling: the answer was a no, but it arrived in two days with the alternative attached, which is what made it land as help rather than gatekeeping.

A proposal for a date-range picker arrived with an expansive API: presets, comparison ranges, fiscal calendars, and timezone switching. The overlap agent found nothing covering it — the system had a single-date picker only — and the impact agent found nine surfaces across analytics, billing, and reporting that currently used three different third-party pickers.

The spec agent's draft kept the core: range selection, keyboard and screen reader interaction modeled on the existing single-date picker, min/max constraints, and preset ranges as a slot rather than a built-in list. It explicitly deferred comparison ranges and fiscal calendars, because the impact evidence showed only one of the nine surfaces needed them.

The council accepted the narrowed spec, recorded the deferred features and the reason in the packet, and the component shipped a release later. Two of the three third-party pickers were removed within the quarter, which the team counted as the real return on the intake hour.

After an org-wide design system push, a central team inherited 24 open contribution requests, some over a year old. Investigating each one by hand was estimated at two to three days per proposal — a quarter of work the team did not have.

They ran the intake pipeline across the backlog over two weeks, roughly ninety minutes of agent time per proposal plus council review in two batched sessions. The results: nine proposals redirected to existing components or compositions, six accepted (four with narrowed scope), five declined with reasoning recorded, and four sent back to proposers because the need was too vague for the overlap stage to check — a useful failure that improved the proposal template.

The number the team quotes is the nine redirects: nine components not built, documented as compositions instead, and nine product teams unblocked without adding surface area to the system.

The pipeline fails quietly when its reports become generic. An overlap report that says 'partially covered, consider composition' without a worked example, or an impact estimate with no file paths behind it, gives the council nothing to push against. Spot-check packets for evidence density before they reach the council.

The pipeline produces evidence and a recommendation; it does not own the system. Strategic questions — whether the system should expand into data visualization at all, whether to absorb a pattern one team loves but the brand team distrusts, how much surface area the maintainers can support — belong to the council and the people accountable for the system's long-term shape.

The evidence also has limits. Codebase counts measure what teams built, not what users need; a need can be real and urgent while appearing nowhere in the code yet. Research, roadmap context, and platform strategy enter at the council table, not in the script.

• It cannot decide the system's strategic scope or appetite for new surface area.
• It cannot weigh roadmap and research context the codebase does not contain.
• It cannot resolve naming, brand, or taste disputes; it can only document them for the council.
• It cannot make a declined proposal feel fair — the recorded reasoning and the offered alternative do that.

Save the orchestration to .claude/workflows/ and run every proposal through it, including the ones that look obvious. Consistency is the point: the council's credibility rests on proposal twelve being investigated exactly like proposal three, and the packets become a searchable record of why the system is shaped the way it is.

1. Receive the proposal on the template: the need, where it appears, what the team does today.
2. Run the overlap agent against the system source and pattern docs; exit early if fully covered.
3. Run the impact agent across the product code: current occurrences, adoption estimate, cost of doing nothing.
4. Run the spec agent: draft API, tokens, states, and accessibility requirements, informed by stages 1–2.
5. Assemble the council packet with a labeled recommendation and its confidence.
6. Council reviews, decides (accept, narrow, redirect, decline), and records the reasoning in the packet.
7. Publish the outcome to the proposer with the alternative attached when the answer is no.
8. Save the workflow and the packets; rerun the same pipeline for every future proposal.