GitHub’s Primer design system report
Primer is mature, but critical implementation rules can still get lost between documentation and working software.
How well does Primer stay aligned from design through production?
73.75/ 100
Primer’s building blocks are mature, but the safeguards around how they are combined are uneven. Critical behavior should be explicit in component guidance and verified in complete product flows before release.
Evidence boundary: This report distinguishes missing public evidence from a missing capability. When a current result was not found in public sources, GitHub may still have it internally and can share it for a re-run.
Foundations
75 / 100
Primer’s token foundations are well documented and covered by the sampled evidence.
Bindings
68.75 / 100
Primer has useful design-to-code mappings, but they are not explained consistently across every supported language and framework.
Components
75 / 100
Primer’s core components have strong usage guidance and accessibility foundations.
Structure
75 / 100
Primer provides clear layout and pattern guidance for product teams.
Governance
75 / 100
Primer has clear ownership and active stewardship. This study did not find public trend data showing how its operating practices perform over time.
FoundationsTokens are well structured and documented.Strong shared values help every product stay visually consistent.First confirm whether GitHub already checks that shared values work in every supported design tool and code library. If not, add compatibility checks that identify the affected output and block unexplained differences before release.BindingsFigma controls and code properties are not explained consistently across supported implementations.Fragmentation creates extra interpretation work and raises the risk of drift.Publish one versioned mapping from Figma controls to supported code properties, then fail a release when a name, property, shared value, mapping, or deprecation changes on only one side without an approved exception.ComponentsCore components are mature, documented, and accessible.Product teams depend on these components for everyday work.Define the states, screen sizes, keyboard paths, and assistive-technology checks required for each component. Publish current results and assign an owner and review date to every exception.StructureReusable layout guidance and product patterns exist.Shared structure lets teams build coherent product experiences instead of isolated screens.Choose the product flows Primer officially supports and test them end to end across validation, loading, recovery, focus, and responsive layouts.GovernanceOwnership, contributions, releases, and migrations have clear operating guidance.Good governance builds trust and helps teams adopt changes safely.Set targets for reviews, migrations, exceptions, adoption, and regressions. Publish trends and record what leadership changes when a target is missed.Can an AI agent use Primer successfully?
14 of 15 runs produced working software
Foundations✓✓✓100%Bindings✓✓✓100%Components✓✓×66.7%Structure✓✓✓100%Governance✓✓✓100%1 Components run failed. The generated save action did not submit the form. The implementation rendered Primer Button without type="submit". Primer Button defaults to non-submitting button behavior, so clicking Save repository never invoked the form submit handler.
The result supports agent-assisted work with automated tests and human validation. The failed run means it is not yet evidence for unattended use.
How Primer can get better
Fix the known submission failure and clarify agent-facing Button guidance.
- Problem
- Generated buttons sometimes omit type="submit", and the full Figma-to-code mapping is not easy to inspect.
- Action
- State in Button API documentation, Code Connect mappings, and agent-facing component data that a form button requires type="submit". Add one submitting and one non-submitting example, then publish the sampled Figma-control-to-React-prop mapping beside the component guidance.
- Owner
- Primer React, Primer design system, and developer experience
- Finish line
- New agent runs submit forms correctly and reviewers can explain every sampled Figma control and React prop.
- Save for the next evaluation
- Published guidance, mapping decisions, and three new agent test results
- Decision enabled
- Whether Primer Button guidance is reliable enough for agent-assisted form work without extra human correction.
Keep Figma and code aligned before changes ship.
- Problem
- Names, properties, tokens, mappings, and deprecations can change in one place without one system-wide check.
- Action
- Generate a versioned manifest of Figma properties, Code Connect mappings, React types, token outputs, and deprecations. Compare it in release CI and block any unexplained difference.
- Owner
- Primer React platform, Figma library, and build infrastructure
- Finish line
- A seeded mismatch fails the release check and identifies the exact difference.
- Save for the next evaluation
- CI results, coverage reports, drift trends, and approved exceptions
- Decision enabled
- Whether a Figma or code change is safe to release without creating an unexplained mismatch.
Test complete product experiences across the whole system.
- Problem
- This study did not find one published coverage view spanning shared values, component states, accessibility, product flows, and devices. GitHub may already run some or all of these checks internally.
- Action
- List the states, themes, screen sizes, keyboard paths, and assistive-technology checks required for each supported component and flow. Run that checklist in CI and publish the current pass, failure, and exception results.
- Owner
- Primer foundations, component, accessibility, and product pattern teams
- Finish line
- Required states and flows pass across supported components, themes, tools, and breakpoints.
- Save for the next evaluation
- Coverage reports with current state, device, accessibility, and flow results
- Decision enabled
- Whether a supported component or product flow is ready for use across the conditions Primer promises to support.
Use operating results to decide where Primer needs investment.
- Problem
- This study did not find public trend data for adoption, exceptions, migrations, review speed, or quality. GitHub may track these internally; sharing current results would allow them to be assessed in a re-run.
- Action
- For each quarterly review, publish the target, current result, trend, accountable owner, and next action for reviews, migrations, adoption, exceptions, and regressions. Record the staffing or process decision made when a target is missed.
- Owner
- Primer governance and design infrastructure leadership
- Finish line
- The team can show clear trends for adoption, exceptions, migrations, review speed, and quality.
- Save for the next evaluation
- A metrics pack with baselines, targets, trends, and decisions
- Decision enabled
- Where leadership should invest, delay a migration, or intervene in ownership and process.
The bottom line
Primer is a mature design system with clear product value. The highest-value next work is to turn critical component behavior into machine-readable guidance, block unexplained Figma-to-code differences before release, and test supported product flows end to end. That would reduce plausible implementation mistakes instead of asking teams to manually keep every surface in sync.
Access the evidence
Review the scoring method, criterion-level rationales, citations, and downloadable study files.