Bayut Token System
Scaling the Bayut app design system with semantic tokens and improved system maintenance.
RoleLeading the Design System
TeamTech — 12 Mobile App Engineers, Product — 2
Timeline1 month
Overview
As the Bayut app scaled across mobile and web, design debt increased due to inconsistent patterns and absence of any documentation. Feature speed often outpaced system maintenance, making it quite difficult to maintain and work efficiently.
Working across both mobile and front-end web surfaces exposed the need for a more resilient design foundation. This case study outlines how semantic design tokens and improved system maintenance helped reduce inconsistencies and support scalable product development.
As the primary designer on the Bayut app, I needed a system that could scale beyond a single contributor. This work ensures that any designer collaborating on the app can move faster, stay consistent, and build with confidence.
Product & Engineering — Clear tokens and documented system rules reduce doubt, making design decisions easier to implement and maintain over time.
Audit for Token Taxonomy
Before defining a new token structure, I audited existing design systems and industry-leading approaches to understand how teams draft semantic token naming at scale. This helped identify existing patterns and common problems before introducing changes internally.
Atlassian's design system helped as a primary reference due to its extensive use of semantic color tokens across backgrounds, content, and accents. Also, teams like Uber to understand how token layers map from theme to component-level usage.
Industry design system references for semantic token taxonomy
Process for Bayut Tokens
To define semantic tokens, I used a single detail view screen which consists of a high number of reusable components and could be a source of truth. This helped me add realistic tokens with the help of knowing the intent, component and the usage.
By mapping every UI element on the screens with backgrounds, text, icons, borders and actions to semantic tokens, I validated how the new taxonomy would scale across themes and additional screens. This process helped identify gaps early and ensured the tokens were flexible enough to support future use cases without redesigning the system.
Process for Bayut tokens — detail view mapping
Based on the audit across key areas of the app, I identified a core set of semantic naming patterns that could scale reliably across the system. Rather than tying tokens to specific colors or components, the taxonomy was structured around usage, purpose, and state.
Tokens were defined across three primary dimensions: Attribute (Text, Background, Icon, Border), Purpose (Error, Info, Positive, Neutral), and State (Default, Action).
Token writing — semantic dimensions
These tokens were then implemented as variables in Figma and mapped directly to component usage. This ensured the system was flexible to use for future theming as well.
Figma variables and component usage
What We Chose Not to Tokenise
There were some decisions on what to tokenize and it was mainly on reusable component level and basic elements to reduce any complexity in maintenance.
Highly illustrative elements were refrained from using variables or semantic tokens to increase flexibility and not make the design tokens fragile for every use case. Experimental components and areas with no clear semantic meaning didn't require tokens. These decisions led to a level head in component documentation for adding variables and using them with intention.
Illustrative elements
Experimental components
Decisions on what not to tokenise
Component Documentation
As component tokens were introduced, we began to see repeated breakages—often caused by components being detached or modified incorrectly during rapid design work. This made it clear that tokens alone were not enough without clear guidance on how components should be used and extended.
I started by documenting the most complex UI components—such as bottom sheets with multiple states and configurations—where the risk of misuse was highest. From there, the same documentation patterns were applied to simpler components across the system.
The documentation focused on: preserving component structure while enabling fast iteration; clearly defining configurable states and variants; helping designers work efficiently without breaking underlying logic. By pairing component documentation with token usage, the system became easier to scale, safer to modify, and more resilient as the app continued to evolve.
I started by documenting the most complex UI components—such as bottom sheets with multiple states and configurations—where the risk of misuse was highest.
Component documentation examples
Outcomes
This initiative laid the foundation for a more scalable and maintainable design system at Bayut. While full engineering adoption is still in progress, the token framework has already enabled faster exploration, reduced design inconsistency, and clarified how themes could be supported in the future.
By defining semantic tokens upfront, the system is now structurally ready for features such as dark mode and theme-level experimentation for future theme designs.
This work was initiated as a solo effort and designed to be extensible, ensuring it could scale as more stakeholders and engineers are brought into the process.
Outcomes — design system in practice
Key Learnings
Design debt
Design debt harms the design team and the lack of early system documentation led to inconsistencies and rework.
Component consistency
Manually breaking and reassembling components to handle small variations introduced inconsistencies that were often missed during handoff, increasing design QA and implementation risk.
Slots and variables
Using slots for a bigger component and using variables smartly does the job for multiple use cases which keeps the component future proof.