Fanoos Design System

From a minimum style guide to a design system

I joined when Rahkaran was Gen 2. Since then it has been through Gen 3 and Gen 4.

1. 2021-2023

   Gen 2 to Gen 3

   • I started on the infrastructure team, shipping v1 of the design system with the developers, in design and in code. I closed the communication gap between design and dev.
   • We started with a minimum style guide and grew it as new requirements came in.
   • I owned responsive behavior across the system, and designed the whole mobile version of Gen 3.
   • I used Tokens Studio to define primitive, semantic and component-level tokens, with token sets and themes so one system could serve multiple brands, in light and dark themes.

2. 2023-2024

   Abramad

   Abramad ran on a fork of Gen 3. The token setup I'd built in Tokens Studio is what made that possible: we customized colors, spacing and other tokens for a new brand, then defined new patterns on top.

3. 2024-2025

   CRM, Gen 4

   Designing CRM on Gen 4, I added patterns the system didn't have: an inline-editable record view instead of a form full of inputs, a kanban view and a status progress bar. Other teams picked them up across the system.

4. 2026-now

   Infrastructure and design system

   • I develop and maintain Gen 4 alongside the infrastructure team, driven by new business needs and UX improvements from audits.
   • I develop new components, and review designs and implementations for consistency with the system.

Making the design system ✦ AI-native

In 2025, I demoed a prototype to the CRM team. Mid-meeting, my team lead asked: "Did our action colors change? Why did they move?"

Nothing had changed. It was a throwaway prototype, built with AI to explore a problem. But it looked real enough that someone who knows the product couldn't tell it apart from the real thing.

People know Fanoos by how it looks. If every prototype comes out in a different style, it stops feeling like our product. Stakeholders start asking whether the design changed, and stop talking about the idea. And getting a prototype on-system took round after round of prompts and fixes. There was never time for that.

Better prompts weren't the answer

Without the design system, the AI's output was generic. My first instinct was to write better prompts. Then I tried feeding it Figma screenshots. Both helped a little. But the agent still didn't know what each component is for, how our patterns fit together, or how we write UX copy.

After a few rounds I saw that the prompt wasn't the problem. My intent was: stakeholders should trust what they see. A prompt can't carry a whole design system. Context can. So I stopped engineering prompts and started engineering context, and the context is the design system itself.

Context in four layers

I started this on my own initiative. Each layer fixes a failure I saw in the AI's output.

1. Design tokens. I pulled colors, theming, type, spacing and radius from our Figma library with the Figma MCP, into one tokens file for light and dark. It fixed the made-up colors.
2. Components and behavior. A script reads the real production runtime and writes a map of every component, 123 tags, with the attributes they actually accept. The Storybook MCP adds the behavior layer: what each component is for and how it acts.
3. Patterns. The guidelines were already in Figma, documented by the team over years. I turned them, plus page templates for master, detail and detail of detail, into a reusable agent skill. It fixed page structures that didn't feel like Fanoos.
4. A check the agent can't skip. Rules alone didn't stop drift, so I wrote check.mjs, covered below.

A check the agent can't skip

Agents still invented CSS variables, or reached for core tokens that don't exist. check.mjs runs on every output and checks that:

• every tag and attribute exists in the runtime
• every icon name is real
• every CSS variable resolves to a real token
• no color or pixel value is hardcoded
• the page stays RTL, in Persian

The agent runs it itself and fixes what it finds before it says done.

$ node scripts/check.mjs supplier-list.html

ERRORS supplier-list.html
     3: <html> must have dir="rtl"
     3: <html> must have lang="fa"
     8: var(--spacing-md) is not defined in tokens.css or vendor theme — the reference resolves to nothing
     9: raw color "#7c3aed" — use a var(--*) token
    10: var(--color-surface-glow) is not defined in tokens.css or vendor theme — the reference resolves to nothing
    10: border-radius: hardcoded "14px" — use a var(--space-*) token
    15: <f-button icon="add-supplier"> is not an icon ligature — see docs/ICONS.md
    16: unknown component <f-data-grid> — not registered by the runtime
    17: <f-badge> has no attribute "variant" (valid: label, icon, size, color-scheme, unwrapped, ellipsis)

9 problem(s) in 1 file(s).

Prompts are suggestions. Checks are guarantees.

Plain HTML, not the production codebase

The prototypes come close to production, in visuals and behavior, because they run on the real components. They're throwaway on purpose: built to answer questions fast, not to ship.

Early signs

This is a beta. I haven't run a rigorous test yet, but the early signs are good.

• Nothing off-system ships. check.mjs blocks any color, tag or icon outside the system, so a prototype can't drift the way that CRM demo did.
• It passes for production. Recently the front-end lead showed the Embedded BI prototype to PMs of several teams that build on our infrastructure. He told me they all thought it was already live.
• It's faster. Two days of Figma down to an afternoon, by my estimate over three tasks.
• Fewer handoff questions. Clicking through a prototype answers most behavior questions: from about 4 developer questions per task to 1 or 2 est..

From me to the team

I run knowledge-sharing sessions for 8 designers every two weeks.

In one session, a designer built a working prototype on the spot.

I'm still checking in with each designer to find where they get stuck, and fixing it in the kit.

Two other things it does:

• Onboarding. Fanoos docs are scattered across Figma, and new designers struggle. The skill doubles as a knowledge base. A new designer can ask the agent about the guidelines and components.
• Portability. Nothing here is tied to one company. The same steps can make any design system AI-native.

Better prompts make one good prototype. Context makes every prototype trustworthy.

The skill in use: Embedded BI

Embedded BI is an AI analysis panel inside the ERP. I built its prototype with the skill, and it passed check.mjs. After I fixed two small notes, the PM wrote:

Try the demo and read the full story.

What's next

A feature takes 11 steps today. The design engineer loop takes 5.

The goal is fewer bugs and less lost intent.

I've validated the HTML handoff with the head of the front-end core team. The next phase is making it usable for developers: prototype code landing as pull requests, reviewed by the front-end core team.