DEV Community

Cover image for An Icon API Should Be Able to Say “RTL Behavior Unknown
Svg/icons
Svg/icons

Posted on

An Icon API Should Be Able to Say “RTL Behavior Unknown

#webdev #svg #internationalization #api

Right-to-left support creates an interesting problem for icon libraries.

Some icons clearly depend on reading direction. Others clearly do not. Some need a dedicated RTL drawing rather than a simple horizontal flip.

But there is another case that matters when you work with icons from many different sources:

What if nobody has documented the intended RTL behavior at all?

For an icon aggregator, that should be a valid state.

Not an invitation to guess.

RTL support is not just a rendering problem

It is tempting to treat right-to-left support as something that happens at the CSS layer.

For example:

[dir="rtl"] .icon {
  transform: scaleX(-1);
}
Enter fullscreen mode Exit fullscreen mode

Technically, this flips the icon.

Semantically, however, it may be wrong.

An icon representing navigation may need to change direction.

A clock normally should not.

A list icon may need a different composition.

An icon containing letters or numbers may require a completely separate asset, because mirroring the SVG would also mirror its content.

So the real question is not:

Can this SVG be flipped?

It is:

Was this icon intended to change in an RTL interface?

Those are very different questions.

Some icon systems already encode this knowledge

This is not purely theoretical.

Microsoft's Fluent UI System Icons includes direction information in icon metadata. An icon can be marked as one that can be mirrored or one that has distinct RTL and LTR versions.

Source:

https://github.com/microsoft/fluentui-system-icons/blob/main/README.md

Wikimedia's Codex design system also documents that some icons should be mirrored, some should remain unchanged, and some require dedicated RTL assets.

For example, Codex treats icons representing horizontal direction or text differently from icons representing concepts such as time.

Source:

https://doc.wikimedia.org/codex/latest/style-guide/icons.html

The important lesson is not that every icon library must use the same rules.

It is almost the opposite.

Different icon systems may make different decisions.

The aggregator problem

Things become more complicated when an icon service contains assets from many independent icon sets.

Imagine four source libraries:

Set A → explicitly documents RTL behavior
Set B → provides separate LTR and RTL assets
Set C → contains directional icons but no metadata
Set D → says nothing about RTL
Enter fullscreen mode Exit fullscreen mode

An aggregator cannot safely treat all four sources the same way.

It may know that an icon from Set A can be mirrored.

It may know that an icon from Set B has a dedicated RTL equivalent.

But with Set C or Set D, the correct behavior may simply be unknown.

That distinction should survive the import process.

Unknown is useful metadata

A directionality model for a multi-source icon library could expose states such as:

neutral
mirror
variant
unknown
Enter fullscreen mode Exit fullscreen mode

Where:

neutral
Enter fullscreen mode Exit fullscreen mode

means the same icon should normally be used in both directions.

mirror
Enter fullscreen mode Exit fullscreen mode

means horizontal mirroring is explicitly supported.

variant
Enter fullscreen mode Exit fullscreen mode

means a separate RTL asset exists.

And:

unknown
Enter fullscreen mode Exit fullscreen mode

means the source does not provide enough information to make that decision safely.

unknown may look like incomplete data.

In reality, it is valuable data.

It tells developers:

We do not have an authoritative directionality decision for this icon.

That is much better than silently inventing one.

Absence of metadata is not permission

Consider an icon named:

arrow-turn-right
Enter fullscreen mode Exit fullscreen mode

An automated importer could decide:

It contains "right", therefore it must be mirrored in RTL.

That sounds reasonable until naming describes geometry rather than semantic direction.

Or consider:

reply
Enter fullscreen mode Exit fullscreen mode

Should it mirror?

Possibly.

But that decision may depend on how the source design system defines the metaphor.

The same problem appears with:

enter
exit
login
logout
forward
undo
redo
send
Enter fullscreen mode Exit fullscreen mode

Names provide hints.

They do not provide authority.

A large icon platform should therefore distinguish between:

inferred behavior
Enter fullscreen mode Exit fullscreen mode

and:

source-defined behavior
Enter fullscreen mode Exit fullscreen mode

Ideally, automatic inference should never silently replace the latter.

Preserve provenance

Directionality becomes much more useful when combined with provenance.

Instead of returning only:

{
  "directionality": "mirror"
}
Enter fullscreen mode Exit fullscreen mode

an API could eventually expose something closer to:

{
  "directionality": {
    "mode": "mirror",
    "source": "upstream"
  }
}
Enter fullscreen mode Exit fullscreen mode

Or:

{
  "directionality": {
    "mode": "unknown",
    "source": null
  }
}
Enter fullscreen mode Exit fullscreen mode

This makes an important distinction visible.

Did the original icon project specify this behavior?

Was it added by the aggregation platform?

Was it inferred?

Was it manually reviewed?

Once icon metadata is consumed automatically, provenance matters almost as much as the metadata itself.

Why this matters for APIs

Suppose an application requests:

GET /icons/back
Enter fullscreen mode Exit fullscreen mode

Today, an icon API might simply return an SVG.

A direction-aware API could return:

{
  "name": "back",
  "svg": "...",
  "directionality": "mirror"
}
Enter fullscreen mode Exit fullscreen mode

A different icon could return:

{
  "name": "document-numbered-list",
  "directionality": "variant",
  "variants": {
    "ltr": "...",
    "rtl": "..."
  }
}
Enter fullscreen mode Exit fullscreen mode

And another:

{
  "name": "custom-arrow",
  "directionality": "unknown"
}
Enter fullscreen mode Exit fullscreen mode

Now the consumer has enough information to make a deliberate decision.

Why this matters even more for coding agents

This becomes especially important when an AI agent is choosing assets.

Imagine asking:

Add a back action suitable for an Arabic interface.
Enter fullscreen mode Exit fullscreen mode

Without metadata, the agent may:

  1. search for a back icon,
  2. retrieve an SVG,
  3. notice that the interface is RTL,
  4. decide by itself whether to mirror it.

That last step is where uncertainty is being hidden.

A better workflow would be:

search icon
→ retrieve directionality metadata
→ choose RTL behavior
→ generate implementation
Enter fullscreen mode Exit fullscreen mode

And when the metadata says:

unknown
Enter fullscreen mode Exit fullscreen mode

the agent should not silently pretend otherwise.

It could instead choose an icon with known RTL support or flag the decision for review.

For automated UI generation, this distinction matters.

CLI tools need the same information

The same idea applies outside an HTTP API.

A CLI could expose directionality during search:

svgicons search "back"
Enter fullscreen mode Exit fullscreen mode

with results such as:

Back Arrow        mirror
Chevron Left      mirror
History Back      unknown
Navigation Back   variant
Enter fullscreen mode Exit fullscreen mode

Or allow filtering:

svgicons search "back" --rtl-safe
Enter fullscreen mode Exit fullscreen mode

An MCP tool could expose the same property to IDE agents.

Once this information exists as structured metadata, every interface can use it:

  • web search
  • API
  • CLI
  • React components
  • Vue components
  • MCP tools
  • coding agents
  • design system pipelines

Do not flatten upstream knowledge

An aggregator creates value by making many icon sets searchable through one interface.

But aggregation should not erase useful differences between those sets.

If a source library provides:

icon-x-ltr.svg
icon-x-rtl.svg
Enter fullscreen mode Exit fullscreen mode

that relationship should ideally be preserved.

If another source explicitly says an icon can be mirrored, that should also be preserved.

And if a third source provides no information, that absence should remain visible.

Otherwise, aggregation can accidentally turn carefully designed behavior into guesswork.

A possible metadata model

A simple model might look like this:

{
  "directionality": {
    "status": "known",
    "behavior": "mirror",
    "provenance": "upstream"
  }
}
Enter fullscreen mode Exit fullscreen mode

For a dedicated pair:

{
  "directionality": {
    "status": "known",
    "behavior": "variant",
    "provenance": "upstream",
    "ltr": "icon-id-ltr",
    "rtl": "icon-id-rtl"
  }
}
Enter fullscreen mode Exit fullscreen mode

And when nothing reliable is known:

{
  "directionality": {
    "status": "unknown"
  }
}
Enter fullscreen mode Exit fullscreen mode

The exact schema is less important than the principle:

uncertainty should be represented instead of hidden.

This is bigger than RTL

There is a broader lesson here for icon infrastructure.

Modern icon libraries increasingly feed automated systems.

SVG files are consumed by:

  • build tools,
  • component generators,
  • APIs,
  • IDE extensions,
  • design systems,
  • AI agents.

As this happens, an icon is no longer just vector geometry.

It increasingly needs machine-readable context.

Directionality is one example.

Others might include:

theme compatibility
semantic role
filled/outline relationship
deprecated aliases
accessibility guidance
brand restrictions
source provenance
Enter fullscreen mode Exit fullscreen mode

Better metadata reduces the number of assumptions downstream tools need to make.

The safest default is sometimes “we don't know”

Developers usually prefer APIs that return precise answers.

But precision should not be manufactured.

For an icon platform aggregating many independent sources, there will always be metadata that exists for some sets and not for others.

RTL behavior is a good example.

When the upstream project provides the answer, preserve it.

When an explicit RTL variant exists, expose it.

When mirroring is documented, expose that too.

And when the information does not exist:

unknown
Enter fullscreen mode Exit fullscreen mode

is a perfectly useful answer.

Because when a tool does not know whether an icon should change direction, the safest behavior is not to guess more confidently.

It is to preserve the uncertainty.

At SVGicons.com, we are interested in how icon metadata can make large multi-set libraries more useful to developers, APIs and automated workflows.

RTL directionality is a small detail visually.

But for machines choosing and transforming icons automatically, it is exactly the kind of detail that should not be left implicit.

Top comments (0)