Linear vs GitHub Issues for Design-System Exceptions

A design-system exception should not disappear into a product issue or become a permanent request for the shared system by default. The useful tracking location is the one that preserves why the deviation exists, what it affects, who owns the decision, how implementation is verified, and whether the exception should remain local, be fixed, or be promoted into the system.

The choice between Linear and GitHub Issues therefore depends less on a generic feature comparison than on the exception’s center of gravity. GitHub Issues is usually the stronger default when the authoritative evidence lives in a repository and pull requests. Linear is a better candidate when the work begins as cross-team design or product triage, before a code change exists. Using both can work, but only when the team defines which record owns each decision.

Define the exception before choosing the tool

A design-system exception is a deliberate departure from a shared token, component, pattern, or guideline. It might be temporary, product-specific, technically necessary, or evidence that the shared system needs to change. A local spacing value used because a legacy integration cannot yet consume the shared token is one hypothetical example. It is not automatically a defect or a contribution request.

The record should make the next decision possible. Capture the affected component, token, or surface; the reason for the deviation; supporting evidence; the owner; the reviewer; the current scope; and the intended disposition. Add an implementation link when code changes exist, plus an expiry date or review trigger when the exception is temporary.

That last field matters because an exception without a review condition can become invisible infrastructure. The team may later remember that the deviation exists but not whether it remains necessary. A review trigger could be a migration release, removal of a legacy dependency, adoption by a second product, or a scheduled design-system review.

The record does not need to preserve every discussion. It needs to preserve the facts and decisions that affect routing, implementation, review, or retirement. This is consistent with the narrower purpose of a lightweight design-system decision record: preserve rationale and scope when they will matter later, without turning every conversation into permanent documentation.

When GitHub Issues should be the center of gravity

GitHub Issues fits an exception whose main work is changing, testing, or documenting repository content. The issue can sit near the code, implementation discussion, commits, pull requests, tests, and release history that establish what actually changed.

This continuity is valuable when the design rationale is relatively compact and the implementation evidence is decisive. A maintainer investigating a token override may need to answer questions such as:

• Which component or package contains the exception?
• Which pull request introduced or removed it?
• What test or rendered review checked the affected state?
• Which dependency or compatibility constraint justified the deviation?
• What condition permits the team to delete it?

A GitHub-centered workflow keeps those answers close to the repository’s change history. A supplied comparison describes GitHub’s native references as more seamless within GitHub, while positioning Linear as a dedicated issue-tracking layer with a GitHub integration (the comparison of Linear and GitHub Issues). That is a workflow observation, not proof of better outcomes, but it identifies the relevant tradeoff: repository continuity versus a separate coordination layer.

GitHub Issues is less suitable when the exception requires substantial prioritization among product teams before anyone knows which repository will change. It can still hold the record, but the team may need to create its own fields, labels, templates, and cross-repository conventions to preserve design rationale and ownership consistently.

When Linear should be the center of gravity

Linear is a stronger candidate when an exception begins as a cross-functional decision rather than an implementation task. The initiating questions may involve product scope, design rationale, affected teams, prioritization, or whether the shared system should respond at all.

That early stage benefits from a workflow that can keep an exception visible while its disposition is still undecided. The record might move through intake, clarification, design-system review, implementation planning, verification, and closure. Not every item needs to become a code change. Some should be documented and kept local; others should be declined, deferred, or converted into a broader system proposal.

Linear’s official GitHub integration documentation says that Linear issues can be linked to pull requests and commits, that pull-request activity can automate issue status, and that pull-request diffs can be exposed in Linear (Linear’s GitHub integration documentation). Those are documented integration capabilities, not evidence that the resulting workflow improves speed, quality, or adoption. They do, however, make Linear a plausible coordination layer for teams that need cross-functional intake before implementation and repository links after implementation begins.

The cost is another workflow beside the repository. If a designer updates the rationale in Linear, an engineer updates status in GitHub, and neither record clearly owns closure, the team has created two partially authoritative histories. Linear is most useful when its additional workflow context changes a decision or routes work that GitHub alone would not represent well.

The connected workflow needs ownership rules

A connected Linear-and-GitHub workflow should not begin with synchronization. It should begin with a source-of-truth decision.

Linear can own: the exception’s cross-team rationale, priority, affected products, design-system disposition, and review owner.

GitHub can own: implementation details, commits, pull requests, tests, package changes, and repository-level verification.

One record must own closure: the final decision should state whether the exception was removed, retained locally, documented, promoted into the system, or retired for another reason.

This division avoids copying every field into both tools. The implementation record can link back to the decision record, while the decision record links forward to the pull request or commit. Status synchronization may be useful, but it does not resolve conflicting ownership. A status such as “done” in one tool cannot by itself establish that the design rationale was accepted or that a temporary exception is safe to retire.

A practitioner-maintained project describes automating transfers from GitHub Issues to Linear to reduce manual copying and missed updates (the GitHub Issues-to-Linear synchronization project). That illustrates an available implementation pattern and its intended purpose. It does not establish synchronization completeness, reliable failure handling, or production performance. Teams adopting a connected workflow still need to decide what happens when a transfer fails, a field changes in both places, or an issue is closed before the other system receives the update.

Keep the exception local when the system does not need to change

The most important routing decision may be to create no shared design-system issue. A deviation can remain within the product team’s implementation when it is narrow, understood, and unlikely to become a reusable rule. Recording it in a local code comment, product decision record, or linked pull request may be enough if future maintainers can still understand the reason and removal condition.

Promote the exception into design-system tracking when it affects multiple consumers, exposes an unclear token or component contract, requires system-team ownership, creates migration work, or may become a reusable pattern. The design-system contribution intake guidance is relevant here: intake should route a request toward clarification, collaboration, contribution, or a local solution rather than promise delivery for every deviation.

A hypothetical legacy-integration exception shows the distinction. If one product cannot yet consume the shared spacing token, the product repository may own the implementation workaround. A Linear record becomes useful if several teams need to coordinate the migration or decide whether the token contract is inadequate. A GitHub Issue becomes the natural center if the work is already a specific package change with a clear pull request. If neither condition applies, a durable local record may be the least misleading choice.

A conditional recommendation

Choose GitHub Issues when the exception is primarily a repository change and pull requests provide the strongest evidence of implementation. Choose Linear when the exception needs cross-team intake, prioritization, design rationale, or a disposition decision before code work exists. Connect the tools only when both contexts are genuinely necessary, and assign ownership for rationale, implementation status, and closure before enabling synchronization.

The tool should follow the exception lifecycle, not define it. A useful workflow lets the team make one explicit disposition decision: keep local, document, fix, promote, or retire, while preserving enough context to explain that decision later. That is what keeps an exception from becoming either an undocumented workaround or a permanent design-system request.