Naming Components for a Bilingual Team and an AI Agent

Component names used to be read by designers and developers. Now they're also read by AI agents. With Code Connect and MCP, an agent looks up Button/Primary/Large in Figma and decides which component to use in code. If the name is vague, the agent guesses. If the name says "left", the Arabic version breaks.

Smashing Magazine published a practical guide to naming things this month, and it's worth reading. But teams working in Arabic and English have problems most naming guides never mention. Here are the conventions I use on bilingual design systems, and why.

Key takeaways

Component names are now an API, read by designers, developers and AI agents.
Use direction-neutral names: start/end and leading/trailing, never left/right.
Keep one glossary that links what the client says, what designers call it and what's in code.
Name variants and properties by role, not by position or appearance.

Names are now an API

When an agent builds a screen from a Figma file, the layer and component names are part of its instructions. A component called Card 2 copy tells it nothing. A component called ProductCard with a media slot and a price property tells it what the thing is and how to use it.

The same names show up in code, in tickets and in client calls. If they're consistent everywhere, humans and agents work from the same map.

Direction-neutral naming

This is the rule that matters most for RTL. Any name with "left" or "right" in it is wrong in one of your two languages.

icon-left becomes icon-start or leadingIcon
icon-right becomes icon-end or trailingIcon
align-left becomes align-start
drawer-right becomes drawer-end
padding-left-16 becomes padding-inline-start-16

Pick either start/end or leading/trailing and use it everywhere. Mixing both is almost as confusing as left/right. I use start/end because it matches CSS logical properties (margin-inline-start), so design and code use the same words.

Two exceptions: things that genuinely don't mirror, like a media player's rewind control, and icons. For icons, name what the icon means (icon-back, icon-next) rather than what it looks like (arrow-left). Then the RTL version can show a different arrow without a misleading name.

One glossary, two languages

On bilingual teams there are often three names for one thing: the Arabic word the client uses, the English word the designer uses, and the name in code. When those drift apart, meetings get confusing and agents get the wrong component.

Keep one glossary table with four columns:

Code / Figma name: OrderSummary
English label: Order summary
Arabic label: ملخص الطلب
Notes: Not the same as the invoice. Shown before payment.

Put the glossary in the design system docs, link it from the Figma file, and include it in the agent's context. It removes a surprising number of misunderstandings.

Should Figma layers have Arabic names?

Keep component and layer names in English, since they map to code. Put Arabic in the content, not the structure. Arabic layer names mixed with English ones make files harder to search and confuse agents that expect code-like names.

Variants and properties that hold up in RTL

Name by role, not appearance: variant=primary | secondary | danger, not variant=blue | grey | red.
Use boolean properties for optional parts: hasLeadingIcon, hasBadge.
Don't make direction a variant. A direction=rtl variant doubles the component set and goes out of sync. Build components with auto layout and logical spacing so the same component works both ways.
Name slots by content: media, title, meta, actions.

Before and after

A typical example from a system that grew without naming rules:

Before                       After
Card 2 copy                  ProductCard
  img left                     media
  Title txt                    title
  btn-right                    actions
Button / Blue / Icon Left    Button / Primary / hasLeadingIcon=true
arrow-left                   icon-back

[Waleed: replace with a real before/after from one of your systems, anonymized if needed.]

See it in real projects

These conventions come from bilingual products like Qarib food delivery and the Almenasa Arabic analytics dashboard. For the layout and typography side of RTL, read my Arabic RTL app design checklist.

Sources: A Practical Guide To Naming Things (Smashing Magazine), The benefits of Code Connect in MCP (Figma).

FAQs

Should I use start/end or leading/trailing in component names?

Either works, as long as you use one consistently. Start/end matches CSS logical properties, which keeps design and code vocabulary the same.

Should a design system have separate RTL components?

No. Build components with auto layout and logical spacing so one component works in both directions. Separate RTL variants double the work and drift out of sync.

Should Figma layer names be in Arabic?

Keep component and layer names in English so they match code and stay searchable. Put Arabic in the content and in a shared glossary.