Principles
The Cadrage is the strategic backbone of the brozz design system. It defines why this system exists, what problems it solves, and what principles guide every design and development decision. Without a clear cadrage, a design system becomes a disconnected collection of components. With one, it becomes a coherent product language.
Main objective
The muba design system exists to give Muba a consistent, accessible, and performant interface language that works in the unique conditions of a gym environment, so that users can track workouts, log sets, and monitor progress with zero friction, even with sweaty hands, between sets, under harsh lighting, and at a glance.
The design system is the contract between design and development. It ensures that every screen, every component, and every interaction follows the same rules, uses the same tokens, and meets the same accessibility standards, regardless of who builds it or when.
Secondary objectives
UX objectives
Reduce cognitive load during workouts by providing a predictable, learnable interface. Users should never need to think about how the app works while they are focused on their training. Every interaction pattern (tapping a set, logging a weight, navigating between exercises) should feel automatic after the first use.
Link to the design system: Standardized component behavior (the same toggle works the same way everywhere), consistent state conventions (8 mandatory states per interactive element), and a strict hierarchy model (one primary action per screen) reduce decision fatigue and make the app feel intuitive.
UI objectives
Create a visually distinctive, warm, and energetic identity that stands out from the cold, clinical aesthetic of most fitness apps. The interface should feel like a knowledgeable gym buddy, not a medical dashboard.
Link to the design system: The Bloody Orange brand palette, the Hakgyoansim display font, the Bro mascot with 6 expressions, the glossy progress bar effects, and the warm Dune neutral tones all contribute to a recognizable visual identity that is encoded in tokens and enforced by the component library.
Product and business objectives
Build trust through consistency. Users who see a polished, reliable interface are more likely to subscribe to premium features, recommend the app, and maintain long term engagement. The upgrade button hierarchy (golden/amber with crown icon) creates a clear, non intrusive path to monetization.
Link to the design system: The upgrade button is a dedicated hierarchy level in the button component, not an ad hoc design. The empty state pattern always includes a CTA. The streak component drives daily engagement through visual consistency psychology. Every motivational touchpoint is systematized, not improvised.
Technical objectives
Enable developers to build new screens and features using pre built, documented components with predictable APIs. Reduce the time from design to implementation by providing exact token references, named effect styles, and comprehensive interaction state documentation.
Link to the design system: The three layer token architecture (primitives, semantics, component tokens) means developers never hardcode values. Every color, spacing value, border radius, and shadow is a named variable.
Design principles
Principle 1: Gym first, everything else second
Why: Muba is used in degraded conditions that most apps never consider. Users have sweaty hands, limited attention (90 second rest windows), impaired motor precision from physical fatigue, and are reading screens under bright overhead lighting. Every design decision must be validated against this context first.
Observable UI consequences:
Touch targets are 48px or larger in workout flows, exceeding the 44px platform minimum. The help button uses invisible padding to expand a 26px visual icon to a 44px+ tappable area. Button sizes start at 36px (small) and go up to 58px (large) for primary actions. The Dune neutral palette uses warm browns instead of cool grays, which are easier to read under warm gym lighting. All state changes use multiple signals (color + icon + position/weight) so no information depends on color perception alone.
Principle 2: One primary action per screen
Why: Between sets, users make split second decisions. If a screen presents competing actions at the same visual weight, the user hesitates. Hesitation costs time, and time is the most valuable resource in a gym.
Observable UI consequences:
The button hierarchy enforces one primary (filled, dark) button per screen, supported by secondary (outlined), tertiary (ghost), and destructive variants. The footer actions component always places the primary action on the right. The action button (FAB) popover anchors the primary action at the bottom, closest to the thumb. Empty states always lead with a single primary CTA, with the secondary option below it.
Principle 3: Tokens are the API
Why: A design system that relies on screenshots and redline specs falls apart the moment a value changes. By encoding every visual decision as a named token, the system becomes a living codebase, not a static document. Changes propagate automatically, and dark mode or theming becomes a configuration change, not a redesign.
Observable UI consequences:
No component uses hardcoded color values. Every color references a broz-bg/, broz-borders/, broz-content/, or broz-icons/ token. Every spacing value references a responsive/layout/padding/ or responsive/layout/gap/ token. Every border radius, border width, and shadow references a named token. The three layer architecture (primitive to semantic to component) means a brand color update requires changing one primitive value, and every button, input, badge, and banner downstream updates automatically.
Principle 4: Accessible by default, not by checklist
Why: Accessibility in Muba is not about compliance. It is about serving the actual conditions users face: fatigue, sweat, glare, distraction. If the app is accessible to someone using a screen reader, it is also accessible to someone squinting at their phone between heavy deadlifts. Accessibility and usability are the same goal.
Observable UI consequences:
Every interactive component documents its ARIA role, keyboard interaction, focus indicator, and screen reader announcement. The toggle uses three simultaneous signals for the on state (color change, thumb position, checkmark icon). Feedback icons use unique shapes per variant (checkmark, triangle, cross, sparkle), never relying on color alone. The checkbox and radio button use invisible padding to expand tappable areas beyond their visual size. Focus rings are semantic (brand/success/danger/upgrade) so the ring color matches the element's context.
Principle 5: Show the system, not the component
Why: A component in isolation is just a rectangle. A component in context tells a story. The design system documents not just what a component looks like, but when to use it, when not to use it, how it pairs with other components, and how it behaves in the specific flows of Muba.
Observable UI consequences:
Every component page leads with "When to use / Don't use" before showing any visuals. The action button page documents the popover as a nested component, not a separate page, because they always work together. The input page documents the full hierarchy (parent input wrapping master input, master dropdown, menu, and menu list item) as one cohesive system. The streak page explains not just the visual states but the psychology of why showing a full week (including upcoming days) matters for motivation.
Transversal rules
Tone and UX writing (microcopy)
Language style: Direct, encouraging, knowledgeable. Like a gym buddy who knows what they are talking about but never talks down to you. Avoid corporate formality and clinical jargon.
Label rules: Use action verbs, 1 to 3 words maximum. "Start workout", "Save changes", "Add exercise", "Go Premium". Never "Submit", "OK", "Done" without context. Sentence case, no full stop. No first person pronouns ("me", "my", "I").
Error conventions: Structure every error as problem, then solution. "Sync failed. Please try again." is good. "Error" is bad. "An error has occurred. Please contact support if the issue persists." is bad. Be specific about what went wrong and what the user can do.
Empty state conventions: State what is missing in a friendly tone ("Nothing to see here for the moment!"), tell the user what to do next ("Tap the button to start building a workout template."), and always provide at least one CTA. The dashed border on the empty state container signals "this area is waiting to be filled."
Validation conventions: Validate on blur, not on keystroke. Success shows a green border + green feedback message with check icon. Error shows a red border + pink background tint + red feedback message with error icon. Feedback messages appear below the field and push content down; they never overlay.
State conventions (mandatory checklist)
Every interactive component must define all of these states:
Default
Hover
Focus
Active
Pressed
Disabled
Loading
Error
Empty
Not every component needs all 8 states (e.g., a skeleton has none, a badge only has default). But the system requires that each state is explicitly considered and documented as either "supported" or "not applicable" on every component page.