Skip to main content

DO1 — Figma Library Structure

Scope: How the Melmastoon design library is organised in Figma — pages, naming conventions, component binding to code, branch flow, and the design QA handoff workflow.

1. Library files overview​

The design library lives as a set of Figma files in the Melmastoon / Design System project:

FilePurposePublished as library
🎨 FoundationsTokens (color, typography, spacing, radius, shadow, motion)✅
🧩 ComponentsAtomic + composite components bound to Storybook✅
🏨 PatternsPage-level layouts, flows, screen templates✅
📐 IconsPhosphor icon subset + hospitality glyph set✅
🖼️ IllustrationsSpot illustrations + empty state art✅
🔬 PlaygroundScratch space; never published; no naming conventions required❌

2. Page structure — Foundations file​

Foundations
├── 🌑 Color / Primitives        ← raw palette (OKLCH swatches, all steps)
├── 🎨 Color / Semantic          ← semantic role tokens (surface, primary, error…)
├── 🌓 Color / Dark              ← dark-mode overrides
├── 🏨 Color / Tenant Themes     ← sample tenant overrides (Hotel A, Hotel B)
├── Aa Typography                ← type scale (Size / Weight / Leading / Tracking)
├── ⬡ Spacing                   ← 4-pt grid swatches
├── ◻ Radius                    ← none / sm / md / lg / full
├── 🌫️ Shadow                   ← xs / sm / md / lg / xl + colored variants
├── ⏱️ Motion                   ← easing curves + duration scale
└── 📖 Usage Notes               ← text frames explaining token intent

Naming convention (tokens):
{Category}/{Role}/{State} — e.g., Color/Surface/Default, Color/Primary/Hover, Spacing/4.

3. Page structure — Components file​

Components
├── _Cover                      ← file cover frame
├── _Changelog                  ← dated entries; links to ADRs
├── 🔴 Atoms
│   ├── Button
│   ├── Input / Textarea / Select
│   ├── Checkbox / Radio / Toggle
│   ├── Badge / Tag / Chip
│   ├── Avatar
│   ├── Icon (passthrough)
│   └── Skeleton
├── 🟡 Molecules
│   ├── Form Field (label + input + helper/error)
│   ├── Search Bar
│   ├── Date Picker
│   ├── Phone Input
│   ├── Price Display (amount + currency + strike-through)
│   ├── Rating Stars
│   ├── Room Card
│   ├── Booking Summary Strip
│   └── Notification Toast / Banner
├── 🟢 Organisms
│   ├── Global Header (Booking shell)
│   ├── Global Footer
│   ├── Operator Sidebar
│   ├── Room Grid
│   ├── Booking Funnel Step Nav
│   ├── Folio Table
│   ├── Housekeeping Board
│   └── Data Table (generic)
├── 🔵 Overlays
│   ├── Modal (sm / md / lg / full)
│   ├── Drawer (right / bottom)
│   ├── Command Palette
│   └── Context Menu
└── 🟣 Native / Platform
    ├── iOS — Tab Bar
    ├── iOS — Navigation Bar
    ├── Android — Bottom Nav
    └── Kiosk — Touch Button (60×60 minimum)

3.1 Component frame naming​

[ComponentName] / [Variant] / [State] — e.g., Button / Primary / Hover, Room Card / Compact / Loading.

3.2 Component properties​

Every component uses Figma Component Properties (not Variants only):

  • Size: sm / md / lg
  • State: default / hover / focus / disabled / loading / error
  • RTL: false / true (toggle to preview RTL layout)
  • ColorScheme: light / dark

3.3 Component → Code binding​

Each component frame has a Link in the Description field pointing to its Storybook story URL. Format:

Code: packages/ui/src/components/Button
Storybook: https://storybook.melmastoon.app/story/atoms-button--primary

The @ghasi/design-sync tool (runs in CI) validates that:

  1. Every published Figma component has a matching Storybook story
  2. Token usage in the Figma component matches the CSS custom property used in code

4. Page structure — Patterns file​

Patterns
├── _Cover
├── _Changelog
├── 🌐 Web — Meta (melmastoon.com)
│   ├── Home
│   ├── Search Results — List
│   ├── Search Results — Map
│   ├── Property Detail
│   └── Shortlist
├── 🏨 Web — Tenant Booking (tenant.melmastoon.app)
│   ├── Booking Home (Block Builder output — sample)
│   ├── Room Selection
│   ├── Guest Details
│   ├── Payment
│   └── Confirmation
├── 🖥️ Desktop — Operator
│   ├── Dashboard
│   ├── Arrivals List
│   ├── Reservation Detail
│   ├── Folio
│   ├── Housekeeping Board
│   └── Reports
├── 📱 Mobile — Consumer
│   ├── Home / Search
│   ├── Search Results
│   ├── Property Detail
│   └── Booking Funnel
├── 🏟️ Kiosk — Self Check-in
│   ├── Welcome / Attract Loop
│   ├── Language Picker
│   ├── Booking Lookup
│   ├── Room Assignment
│   ├── Payment
│   └── Key Issuance
└── 🌐 Guest Portal
    ├── Home (booking summary)
    ├── Folio
    └── Service Requests

5. Icons file structure​

Icons
├── _Cover
├── Phosphor — UI (subset of ~300 icons used in product)
├── Phosphor — RTL Mirrored (directional icons with RTL counterpart)
└── Hospitality Glyphs (30 custom: bed, breakfast, pool, wifi-full, wifi-weak, key, housekeeping, spa, luggage, shuttle, passport, etc.)

Glyph naming: icon/hospitality/{name} — e.g., icon/hospitality/key, icon/hospitality/bed.
RTL mirror flag: Each directional icon has a rtlMirror: true annotation in the Description. The @ghasi/icon-export script reads this flag to set aria-hidden and CSS transform: scaleX(-1) in the code package.

6. Illustrations file structure​

Illustrations
├── _Cover
├── Empty States (spot, 200×200 target)
│   ├── no-results-search
│   ├── no-reservations
│   ├── no-messages
│   ├── no-housekeeping-tasks
│   ├── offline
│   └── error-generic
├── Onboarding
│   ├── welcome-consumer
│   ├── welcome-operator
│   └── welcome-kiosk
└── Marketing
    ├── hero-illustration (used in meta-web default hero)
    └── partner-illustration

Style: Flat vector; 2-color (primary + neutral); no gradient fills (accessibility + token-binding). All illustrations SVG-exportable with semantic color fills mapped to design tokens.

7. Branching and contribution flow​

main (published library)
  └── feature/[ticket-id]-[description]   ← designer's branch
        ↓ PR in Figma (Branch Merge)
        ↓ Design review (guild lead sign-off)
        ↓ Dev review (token check, Storybook parity)
      main (published)

7.1 Rules​

  • Never edit main directly
  • Branch name format: feature/MEL-123-update-room-card
  • One Jira ticket per branch (max)
  • Design review gate: guild lead ✅ in Figma comment before merge
  • Dev review gate: FE platform engineer confirms code parity in PR comment

7.2 Changelog​

Every merge to main requires an entry in _Changelog frame:

2026-04-25 | MEL-123 | Updated Room Card: added "Instant confirm" badge variant | @designer

8. Design QA handoff workflow​

  1. Design complete: Designer creates a handoff frame in the relevant Patterns page
  2. Handoff frame contents:
    • Annotated screen with token refs (spacing/4, color/primary/default)
    • Interaction notes (hover states, transitions, error states)
    • Accessibility annotations (focus order numbers, aria-label values, contrast ratios)
    • Link to JIRA ticket
  3. Design review: Guild lead or peer reviews against DESIGN_REVIEW_CHECKLIST.md
  4. Dev pick-up: Engineer reads handoff frame and inspects component in Inspect panel for exact token/spacing values
  5. Dev complete: Engineer posts Storybook story link + Chromatic snapshot link in JIRA ticket
  6. Design sign-off: Designer compares implementation to Figma; posts ✅ Design approved in JIRA

References​