How Revilo works

Revilo answers one question: how closely does your design system in Figma match the components and tokens in your codebase?

It produces three scores — Alignment, Adoption, and Architecture — each measuring a different dimension of design system health. These scores are backed by specific findings (individual issues) and recommendations (suggested fixes with effort and impact estimates).

To get a real report you need two things connected:

• Figma — a published component library or any file with components and styles/variables
• GitHub — a React codebase with .tsx / .jsx component files and token files

If you haven't connected sources yet, the dashboard shows a sample report based on a built-in design system example so you can explore the interface first.

You authorize Revilo to read your Figma file and GitHub repository via OAuth. Revilo only requests read access — it never writes to either source.

When you click Run scan, Revilo fetches data from both sources in parallel:

• From Figma: all components and component sets (grouped by their variant dimensions), all tokens via the Variables API or Styles API fallback, and usage signals like detached instances and local styles applied directly in the file.
• From GitHub: PascalCase .tsx/.jsx files in src/components, components, or packages/*. Token files in paths containing token, theme, color, spacing, etc. Reads CSS variables, JS/TS nested objects, and JSON (including W3C Design Token format).

All component and token names are normalized (lowercase, punctuation removed) so Button/Primary in Figma matches Button.tsx in GitHub. Revilo then pairs every Figma component with its GitHub counterpart, and every Figma token with its GitHub equivalent.

Components are matched by exact normalized name. A small synonym table handles known renames (e.g. Notification → Alert). Tokens are matched by name first, then by value (same value but different name = naming mismatch).

Each match produces data that feeds into the three scores and a list of findings. The scan typically completes in 10–30 seconds depending on library size.

Alignment asks: are the same components and tokens defined in both Figma and your code, with the same shape?

A score of 100 means every Figma component has a matching component in code with identical variants, and every token has the same name and value on both sides. Lower scores mean things exist in one place but not the other, or their definitions have drifted apart.

Alignment is a weighted average of four sub-scores:

Adoption asks: is your team actually going through the design system — or working around it?

A high adoption score means designers are using shared library components (not detaching and restyling them) and engineers are using design tokens (not hardcoding colors and spacing directly in component files).

Adoption is split evenly between the design and engineering perspectives:

Architecture asks: is your design system built on a solid structural foundation?

This covers whether your token system follows the right hierarchy (base values → semantic purpose tokens), whether your component organization in Figma maps to your folder structure in code, and whether naming is clean and intentional.

Revilo classifies each token into one of three tiers:

• Primitive — raw values with no semantic meaning. Example: color.blue.500 = #3B82F6
• Semantic — purpose-driven tokens that reference primitives. Example: color.action.primary.background = color.blue.500
• Unknown — can't be classified, usually because of ad-hoc naming. Example: homepage-purple

The classification is based on the token's name structure, not its value. A semantic token should describe where and how it's used, not what the value is.

A finding is a specific, detected issue in your design system. Each finding belongs to one of the three score areas (Alignment, Adoption, Architecture) and has a severity level.

The most common finding types and what they mean:

/dashboard

Top-level snapshot. Shows all three scores, your biggest risks, team drift breakdown (are designers or engineers creating more drift?), and top recommendations. The trend chart shows how scores have moved across your last several scans.

/dashboard/alignment

Full list of alignment findings — components that exist only in Figma or only in code, variant mismatches, and token name/value discrepancies. Filterable by severity and finding type.

/dashboard/adoption

Engineering and design adoption breakdown. Shows hardcoded values in component files with file paths, detached Figma instances, and local styles. The most actionable page for reducing drift fast.

/dashboard/architecture

Token tier distribution (primitive vs. semantic vs. unknown), component hierarchy issues, and structure consistency findings. Useful for long-term system health.

/dashboard/team-insights

Splits findings by team — which issues are coming from the design side vs. the engineering side. Helps direct conversations and accountability.

/dashboard/recommendations

All recommendations ranked by impact and effort. Each recommendation is linked to the finding(s) it addresses and includes a suggested fix.

/dashboard/sources

Manage your connected Figma and GitHub sources. Reconnect, add Figma file keys, change the GitHub repo, or disconnect.

Revilo tries the Figma Variables API first. This is available on Figma Professional and above and gives full token names and values.

If the Variables API returns a 403 (plan restriction), Revilo falls back to the Styles API. It then fetches the actual style node from Figma to get the fill color, typography spec, or effect value. The yellow notice on your dashboard tells you which mode is active.

Revilo walks your repo's git tree and reads:

• PascalCase .tsx/.jsx files in component directories
• Files with token, theme, color, spacing, variables, foundation, primitive in their path
• CSS custom properties (--token-name), JS/TS exports, JSON (including W3C Design Token format)

It skips test files, story files, config files, and node_modules. For large repos, it uses the Contents API to discover files by directory rather than walking the full tree.

You'll see sample data until you connect both Figma and GitHub sources. Go to Sources in the sidebar to connect them, then run a scan.

Check that the file is PascalCase (e.g. Button.tsx, not button.tsx), not in a test or story file, and lives under a recognized component directory (src/components, components, packages/*/src). The component must also export the name from the file.

If the Figma Variables API returns a 403, Revilo automatically falls back to your Styles. You'll see a yellow notice on the dashboard. Token name analysis still works; value comparisons use the style node values fetched via the Figma REST API.

The most common cause is hardcoded values — hex colors or pixel sizes written directly in component files instead of referencing tokens. Check the Adoption page for the specific files and values.

It walks the Figma file at depth 2 looking for FRAME or GROUP nodes whose name matches a known library component. These are likely instances that were detached and converted to regular frames.

Yes. On the Sources page you can add multiple Figma files and assign each a role (seed variables, primitive tokens, semantic tokens, component library, or project file). Revilo fetches all of them and merges the data.

After any significant design or code change. The Monitoring plan runs automatic scans and sends an email if scores drop significantly.