A design system is only as useful as its documentation. If a developer cannot find the spec, or a designer does not know how to add a new component, the system breaks down. This page defines how the muba design system documentation is structured, how contributions work, and what a proper handoff looks like.
The goal is that anyone navigating this documentation, whether designer, developer, or stakeholder, can find what they need without asking questions. Every component, every token, every rule has a home.
Documentation structure
Source of truth hierarchy
Figma is the visual source of truth. The component file at muba design system contains the canonical version of every component, variant, and state.
Design system is the behavioral source of truth. This documentation defines when to use a component, when not to, interaction rules, accessibility requirements, content/microcopy guidelines, and best practices. These rules are not in Figma.
JSON token files are the technical source of truth. The four token files (broz-primitives.json, broz-semantic.json, broz-global-token.json, broz-color-token.json) are the values developers import into code.
Component documentation standard
Every component page in the muba design system follows a consistent structure. The sections appear in this order:
Intro paragraph. 2 to 3 sentences explaining what the component is and why it matters in Muba. Key terms highlighted in orange.
When to use / Don't use. The single most important section. Lists specific scenarios where the component is appropriate and specific scenarios where a different component should be used instead, with the alternative named explicitly.
Types, variants, or modes. The semantic categories of the component (e.g., primary/secondary/tertiary for buttons, inactive/active for toggles, underline/pill for tabs).
Sizes (if applicable). The available size options with their pixel dimensions and contexts.
Structure (if the component has nested parts). Breaks down the internal anatomy with token references.
Interaction. All supported states (default, hovered, pressed, focused, disabled, loading, error) with behavioral descriptions. Toggle/selection behavior. Animation expectations.
Placement. Where the component lives in the UI, positioning rules, and do/don't guidance.
Accessibility. Touch target compliance, keyboard pattern, screen reader announcements, focus indicator, color independence.
Content. Microcopy rules specific to this component with concrete good/bad examples.
Best practices. Design wisdom and edge cases that do not fit neatly into other sections.
Contribution rules
Adding a new component
Duplicate the Component Template page inside the Components section.
Fill in all sections following the documentation standard above. Every section is mandatory unless explicitly marked as "if applicable."
Design the component in Figma first, including all variants and states.
Document the component's Figma node ID so the page can reference the correct frame.
Write the "When to use / Don't use" section before any other section. If you cannot clearly articulate when to use the component, the component may not be necessary.
Add the component to the Components index page under the correct category.
Add an entry to the Changelog.
Modifying an existing component
Document the change rationale (why is this modification needed?).
Update the Figma component first, including all affected variants and states.
Update the DS documentation to match. Specifically check: interaction states, accessibility section, content rules, and best practices.
If the modification changes the component's API (new props, removed variants, changed behavior), add a breaking change entry to the Changelog.
Handoff specifications
What every component page must include for developers
Token references, not pixel values. Every color, spacing, radius, border, shadow, and typography value must reference a named token. Developers should never need to type a hex code or pixel value manually.
All interaction states visualized. The Figma component must show every supported state. The DS must describe the behavioral change for each state.
Accessibility specifications. ARIA role, keyboard interaction pattern, screen reader announcement text, and focus management rules. These are not optional.
Content constraints. Maximum character count, allowed content types, and microcopy rules that affect the component's behavior (e.g., "button labels must be 1 to 3 words").
What developers should expect from the system
All measurements reference tokens from the JSON files, importable directly into code. All colors reference component color tokens (broz-bg/, broz-borders/, broz-content/, broz-icons/). All interactive elements have defined states with both visual and behavioral descriptions. All accessibility requirements are explicitly stated, not implied. The 4 JSON token files serve as the bridge between Figma and code.
Quality checklist
Before a component page is considered complete, verify:
"When to use / Don't use" section is filled with specific, actionable scenarios
All variants and modes from Figma are documented
All interaction states are described with behavioral detail
Structure section includes token references (not hardcoded values)
Accessibility section covers touch target, keyboard, screen reader, focus, and color independence
Content section has at least 2 good examples and 1 bad example
Best practices section exists with at least 3 actionable points
Figma embed placeholders are present for visual reference
No dashes used as punctuation
No placeholder text remains ([define], [describe], etc.)