Design system health: score, grade and metrics

Design system health is one score from 0 to 100 that says how closely your code follows the design and the tokens. Next to the score you always see what it's made of, so you can check the number and see what to fix first. This page explains the score and the grade, each part with its weight, the trend, and the health of a single component.

Before you start

The design system in code is connected for the project and has been indexed at least once. See Connect the design system.
At least one components library is attached as the design side. Without a design to compare with, there is no score.

Where to find it

Open the project. Under From code, the Design system in code card already shows the score, the grade and the change since the last index run.
Click Open. The Overview tab starts with the Design system health card.

The card names the commit the score is counted from. The two parts that depend on the design are recounted every time you open it, so a components library sync shows up without a new index run. The other parts come from the latest index run.

The score and the grade

The big number is the score out of 100. The badge next to it is the grade, and the grade scale under the number shows where the score sits.

Grade	Score	Label
A	85–100	Healthy
B	70–84	Good
C	50–69	Needs attention
D	0–49	At risk

Under the grade, the card shows how the score moved since the last index run and what it was at that commit. On the very first run it says there is nothing to compare with yet.

What the score is made of

What the score is made of lists six parts. Each shows its weight, its value as a percentage and the numbers behind it.

Part	Weight	What it counts
Design matched to code	25%	Code components that have a pair in the design, out of all components in code
Matched and in sync	25%	Matched components whose variants and properties don't differ from the design
Usage through the design system	25%	Component usages in the code that resolve to a design system component, out of all component usages found
Free of bypasses	15%	Bypasses per usage: colours and spacing written past the tokens, raw scale tokens, inlined icons, assets loaded from outside, UI built outside the design system
Free of duplicates	5%	Components declared more than once
Variants actually used	5%	Variant values declared in code that at least one usage picks

The score is the weighted average of these parts. Bypasses are counted against the number of usages, so ten bypasses in a large codebase weigh less than ten in a small one.

Not measured is not zero

A part FISYCO has no data for shows Not measured. It drops out of the score together with its weight, and the remaining parts share the whole. Counting it as zero would punish your team for something FISYCO simply didn't see.

When there is no score

The score is about the design system, so it needs both sides. If no design file is attached, or there is no repository, the card says Nothing to score yet. It offers Attach a design file or Connect a repository, whichever side is missing. Code hygiene alone is not the health of a design system.

What would raise the score

What would raise the score most lists up to three actions, the biggest gain first. Each one names the work in numbers, such as "Map 16 components to the design", and shows "up to +N". That's how many points the score gains if the part reaches 100%, estimated from the weights.

Some actions open the place to do the work. Mapping, duplicates and unused variant values open Components. Structural differences open Differences, where each one shows what FISYCO does about it. See Differences.

When every measured part is at 100%, the card says there is nothing left to raise.

Score by index run

Score by index run draws the score of each recent index run, up to twelve, oldest on the left. The last point is hollow and marked now: it's the same number as at the top of the card. Dates run under the line, and two runs on the same day are labelled with the time.

The axis doesn't start at zero, so a move from 58 to 63 is visible. Before the first run, the chart says the trend appears after it.

FISYCO indexes the repository after a push to the tracked branch, and checks the branch every 30 minutes in case a webhook is missed.

Health of a single component

Every component gets its own score, built the same way and graded on the same scale.

In the Components tab

The Health column shows each component's score with a bar in the grade colour. Sort by it to see the weakest components first; components without a score always go last. A component scored without a design pair is marked without the design comparison.

Click a row to open the component. The chip in its header shows the score, the grade and the weakest measured part. Click it to open the Health tab.

The Health tab

Part	Weight	What it counts
Match with the design	25%	Design properties that match in code across the compared variants; a design layer missing in code counts as a mismatch
Accessibility	25%	Static accessibility checks that pass; unknown results count neither way
Tokens	15%	Properties the design binds to a token that match in code through that token, not a written number or another token
Variant axes	15%	Values of matched design variant axes that exist in code
API	10%	Exported, described, props documented, and a replacement named for a deprecated component
Adoption	10%	Whether the component is called, and how many of its variant values are in use

Each row shows a bar and a percentage. The three parts that would raise the score most also show "+N", the points they would add at 100%. The info icon opens the numbers behind the part, its weight and, where it helps, what would raise it. A part without data shows a dash, not zero.

Two badges explain an incomplete score. no design comparison means the component has no design pair, so the score comes from the other parts. partial comparison means some design variants have no known counterpart in code, and they stay out of the score. If neither Match with the design nor Accessibility is measured, the tab says there is nothing to assess yet.

Accessibility runs seven static checks without running the code: text contrast, accessible name, click on a non-interactive element, field label, image alternative text, visible focus and target size. It also says what static checks can't see, such as keyboard behaviour.

How is this counted? explains the score and shows stability: the number of breaking changes in the kept history. Stability is shown but not scored, because a component that evolves isn't unhealthy.

AI analysis on the same tab explains the computed facts and suggests what to fix first. It never sets or changes the score: the same facts always give the same number.

To see how a component differs from the design part by part, open the Compare tab. See Compare components. AI agents read the same component score through the FISYCO MCP server: see MCP for AI agents.