DESIGN.md Has No Sense of Direction: Making AI-Readable Design Systems Work for Arabic

In one week this October, design systems got a new audience. Google published DESIGN.md, a spec for handing design tokens and intent to coding agents. Figma's agent went generally available. Anthropic launched Claude Design, which stores a design system as a design.md file. Designers are now writing documentation that machines will read before people do.

I read through the spec with one question in mind: what happens when the product is in Arabic? The answer is that it doesn't say. Colors, type, layout and components are all covered, but text direction, mixed Arabic/English content and script-specific typography are not. For anyone building bilingual products in MENA, that gap is where agents will get things wrong.

Key takeaways

Agent-facing specs like DESIGN.md describe one script and one direction by default. RTL rules have to be written down, or the agent will guess.
The decisions that matter most (what mirrors, what doesn't, numerals, Arabic line height) usually live in designers' heads, not token files.
A short "Direction & Script" section with tokens plus plain-language rules covers most of the gap.
Give each script its own typography tokens instead of one scale with an Arabic fallback.

What DESIGN.md is, and why it matters this month

DESIGN.md is a Markdown file that sits in a repository and tells an AI coding agent how the product should look and behave: color tokens, type scale, spacing, layout rules, component guidance. Think of it as the design system's README, written for an agent instead of a new hire.

The idea isn't new, but the timing is. When the spec, a GA design agent and a new AI design tool all arrive in the same week, teams start writing these files now. Whatever ends up in the first version tends to stay. If direction and script aren't in it from day one, they'll be patched in later, one bug report at a time.

What breaks when an agent builds Arabic from an English-only spec

Hand an agent an English-only design file and ask for the Arabic version of a screen. It will usually do the obvious part: set dir="rtl" and swap the copy. The problems are in everything it can't infer:

Everything mirrors, or nothing does. Back arrows stay pointing left, or the media player's play button flips too.
Physical spacing. margin-left and padding-right stay where they were, so icons end up on the wrong side of their labels.
Latin type settings applied to Arabic. Letter-spacing on headings, 1.4 line height on body text, and diacritics clipped at the top of buttons.
Numerals and mixed text. Order numbers, prices and English product names inside Arabic sentences render in the wrong order.

[Waleed: add a before/after screenshot here from a quick test: one English-only spec, one prompt asking for the Arabic screen.]

The RTL decisions that never make it into token files

Token files are good at values: colors, sizes, radii. RTL is mostly about rules. On every bilingual system I've worked on, these were the decisions that existed only in conversations and design reviews:

Mirroring rules

Navigation, lists, progress steps, sliders and directional icons mirror. Media controls, clocks, time-based charts, phone numbers and logos don't. A human designer knows this. An agent needs a list.

Icons that must not flip

Search, checkmarks, a camera, a heart: no direction, so no flip. Chevrons, "send", "reply" and "undo" point in the reading direction, so they do. Tag icons in your library as directional or neutral and the agent has something to follow.

Logical properties

If the spec says "16px left padding", you've already lost. Write spacing as start and end, and tell the agent to use padding-inline-start, margin-inline-end and inset-inline-start instead of left and right.

Numerals and formats

Western (123) or Eastern Arabic (١٢٣) numerals, per market. Currency position, date format, and whether the Hijri calendar appears. These are product decisions, and they belong in the spec.

A drop-in "Direction & Script" section

Here's the section I'd add to any DESIGN.md for a bilingual product. Adapt the values; keep the structure.

## Direction & Script

Supported directions: ltr (en), rtl (ar). Default: rtl.

Rules:
- Use logical CSS properties only (inline-start/end, block-start/end).
  Never use left/right for spacing, alignment or positioning.
- Mirror: navigation, back/forward, chevrons, lists, steppers,
  sliders, carousels, progress bars, swipe direction.
- Do not mirror: media controls, clocks, time-axis charts,
  phone numbers, code, logos, checkmarks, search icon.
- Icons are tagged directional or neutral. Only directional icons flip.
- Numerals: Western digits (0-9) in all markets. [adjust per market]
- Mixed text: wrap LTR runs (emails, URLs, order IDs, English
  product names) in <bdi> or use unicode-bidi: isolate.
- Never apply letter-spacing or italic to Arabic text.

Plain sentences work well here. Agents follow explicit rules better than they infer intent from tokens alone.

Typography tokens for two scripts

The most common mistake I see is one type scale with Arabic bolted on as a fallback font. Arabic and Latin don't share metrics, so the same 16px size and 1.5 line height look different in each script. Give each script its own tokens:

Font family per script: font.family.latin and font.family.arabic, chosen as a pair that matches in weight and color on the page.
Size adjustment: Arabic often needs to be one step larger to read at the same visual size as the Latin text next to it.
Line height per script: around 1.4–1.5 for Latin body text, 1.6–1.8 for Arabic, so dots and diacritics don't clip.
A switching rule: set the font from the lang attribute, not from the page direction, so an English name inside an Arabic paragraph still uses the Latin face.

Checklist for handing a bilingual system to an AI-assisted team

The spec states supported directions and the default.
Spacing and alignment rules are written with start/end, never left/right.
There's an explicit mirror / don't-mirror list.
Every icon is tagged directional or neutral.
Numeral, date and currency rules are set per market.
Typography has separate tokens per script, including line height.
Mixed-direction text has a rule and a real example.
Someone reviews the first agent-built Arabic screens against the spec before the team scales up.

DESIGN.md is a good idea. It just assumes one direction. If your product speaks Arabic, write the second half yourself.

See it in real projects

You can see these rules applied in Arabic-first products I designed, like Qarib food delivery, Waddini ride hailing and the Almenasa Arabic analytics dashboard. For the full RTL design checklist, read my Arabic RTL app design checklist.

Sources: Why DESIGN.md broke the internet in under 24 hours (DEV), Design News Digest, week of October 8 (Design Agent), Design Tokens in 2026: The W3C Format, Explained (CODERCOPS).

FAQs

Does DESIGN.md support right-to-left languages?

The spec doesn't include a section for text direction or script-specific typography. You can add one yourself: a "Direction & Script" section with mirroring rules, logical-property rules and per-script type tokens.

Should Arabic and English share one type scale?

No. Arabic usually needs a slightly larger size and more line height to read at the same visual weight as Latin text. Give each script its own size and line-height tokens.

Can you help set up a bilingual design system for AI-assisted development?

Yes. I design Arabic/English design systems for teams across MENA, including the documentation agents and developers need to build the RTL version correctly.