📝 Figma Naming Convention Guide

Purpose: Standardize naming untuk frame, page, component, variant, layer, style, dan variable.

Why it matters: Designer + Developer + PM perlu language shared. Consistent naming = faster find, faster review, fewer bugs.

---

🗂️ FILE & PAGE NAMING

Current File Structure (recommended)

Main file: Amal E-Santri Design System

Pages (top-level tabs):

0. 🏠 Cover
1. 📐 Style Guide
2. 🧩 Component Library
3. 🎨 Patterns
4. 1. Parent (Orang Tua)
5. 2. Guru
6. 3. Wali Kelas
7. 4. Bendahara
8. 5. Admin Lembaga
9. 6. Kepala Sekolah
10. 🗄️ Archive / Explorations
11. 📚 Documentation

Pattern:

• Pakai emoji untuk quick visual scan
• Nomor urut untuk hierarchy
• Uppercase leading words, sentence-style

---

📱 FRAME NAMING

Pattern

{Persona} / {Category} / {ScreenName} / {State?}

Examples:

✅ Good	❌ Bad
Parent / Dashboard / Home	Dashboard (no persona, ambiguous)
Parent / Billing / Invoice Detail	parent-billing-invoice (kebab-case inconsistent)
Parent / Billing / Invoice Detail / Loading	Parent Invoice Detail (Loading) (parens non-standard)
Parent / Payment / QRIS	parent_payment_QRIS (snake + uppercase mix)
Parent / State / Empty - Tagihan Kosong	Tagihan Kosong State (non-hierarchical)

Categories (konsisten per persona)

Untuk Parent:

• Dashboard — main entry screens
• Billing — tagihan-related
• Payment — payment methods & flows
• Academic — Nilai, Rapor, Jadwal, Subject
• Spiritual — Hafalan, Setoran, Ibadah
• Attendance — Absensi
• Communication — Chat, Notifikasi, Pengumuman
• Profile — user profile
• Settings — pengaturan
• Auth — login, forgot password, register
• Onboarding — splash, welcome, fitur
• Common — empty states, error states, generic

State Suffixes (kapan butuh)

Tambahkan state suffix kalau ada multiple variants dari screen sama:

Suffix	Arti	Example
Empty	No data yet	Parent / Billing / Invoice List / Empty
Loading	Data fetching	Parent / Billing / Invoice List / Loading
Error	Server error	Parent / Billing / Invoice List / Error
Success	Post-action	Parent / Payment / QRIS / Success
Failed	Action failed	Parent / Payment / QRIS / Failed
Offline	No connection	Parent / Dashboard / Home / Offline
Filtered	With filter active	Parent / Billing / Invoice List / Filtered
Expanded	Expanded state	Parent / Hafalan / Progress / Expanded
Hover	Hover state (rarely on mobile)	Parent / Billing / Invoice Card / Hover

Dark Mode Handling

Option A — In-file via Variables mode (PREFERRED): Single frame, switch mode di panel. No separate "Dark Mode" frame needed.

Option B — Separate frames (kalau perlu showcase side-by-side):

Parent / Dashboard / Home                   ← light
Parent / Dashboard / Home [Dark]            ← dark variant

Suffix [Dark] dalam bracket. Jangan pakai - Dark Mode (terlalu panjang).

---

🧩 COMPONENT NAMING

Pattern for master component

{Category} / {ComponentName}

Examples:

Atom / Button
Atom / Chip
Atom / Avatar
Atom / Icon

Molecule / Card
Molecule / TextField
Molecule / AppBar
Molecule / BottomNav

Organism / HeroCard
Organism / QuickActionCard
Organism / EmptyState
Organism / SkeletonLoader

Component hierarchy levels:

• Atom — indivisible (Button, Chip, Icon, Avatar)
• Molecule — composition of 2-3 atoms (Card, TextField, AppBar)
• Organism — complex, multiple molecules (HeroCard, EmptyState)
• Template — layout scaffold (Empty template, Form template)
• Page — complete screen (full Parent / Dashboard / Home frame)

---

🎛️ VARIANT PROPERTY NAMING

Property naming (camelCase)

✅ Good	❌ Bad
variant	Variant or VARIANT
size	Size
hasIcon	has_icon or HasIcon
iconPosition	icon-position
isActive	Active (not boolean-named)
count	Count
state	State

Property values

Variant (single-choice)

Use kebab-case atau camelCase (pilih satu dan konsisten):

variant:
  - primary
  - secondary
  - tertiary
  - danger
  - ghost

Atau:

iconPosition:
  - leading
  - trailing
  - iconOnly
  - none

Boolean

Use true / false literal. Property name harus natural-sounding with is/has/can prefix:

hasIcon: true / false
isDisabled: true / false
canDismiss: true / false

Text

Use generic placeholder in definition, actual value comes from instance:

label: "Button Label"
subtitle: "Subtitle text here"

Instance Swap

Named after role:

iconName: <Atom/Icon>
leadingIcon: <Atom/Icon>
trailingAction: <Atom/Button>

---

🎨 STYLE NAMING (Text, Color, Effect)

Pattern: Token-based (match semantic tokens)

{category}/{level}/{variant?}

Text Styles:

display
h1
h2
h3
h4
body-lg
body
body-sm
caption
micro-label

Color Styles (if not using Variables):

surface/background
surface/card
text/primary
text/secondary
brand/primary
brand/primary-hover
status/hadir
status/izin-bg
feedback/success
border/default

Effect Styles (shadows):

shadow/sm
shadow/md
shadow/lg
shadow/card
shadow/hero
shadow/fab
shadow/modal

Old pattern (if still in file) — to rename:

❌ Old	✅ New
Primary 500	brand/primary
Gray 900	text/primary
Green / 50	status/hadir-bg
Shadow Large	shadow/lg
Heading 1	h1

---

🏷️ VARIABLE NAMING

Collections

Color (Primitive + Semantic)
Typography
Spacing
Radius
Opacity

Primitive tokens (within Color collection)

Pakai Tailwind-style naming:

emerald-50, emerald-100, ..., emerald-950
zinc-50, zinc-100, ..., zinc-950
amber-50, ..., amber-950
red-50, ..., red-950
blue-50, ..., blue-950

Semantic tokens

Pattern: {category}/{role}/{modifier?}

brand/primary
brand/primary-hover
brand/primary-light

text/primary
text/secondary
text/tertiary
text/disabled

surface/background
surface/card
surface/variant

status/hadir
status/hadir-bg
status/lunas
...

Variable mode naming

Modes:
  - Light
  - Dark
  - (AMOLED future)

Jangan pakai:

• ❌ light mode, dark mode (redundant word)
• ❌ Day, Night (unclear)
• ❌ Default, Alt (too generic)

---

🏗️ LAYER NAMING (di dalam Frame)

Principles

1. Deskriptif, bukan visual — nama by purpose, not by appearance
2. Pascal-style atau kebab-case — pilih satu
3. Auto-label dari Auto Layout — kalau sudah Auto Layout, biarkan Figma generate names (Vertical, Horizontal) kecuali ada alasan rename
4. Rename yang matter — components, key sections, interactive elements

Examples:

HeroCard              ← good (PascalCase, semantic)
hero-card             ← good (kebab-case)
heroCard              ← good (camelCase)

Frame 123             ← bad (default Figma name)
Rectangle 5           ← bad (shape name)
green box             ← bad (visual only)
asdfasdf              ← bad (meaningless)

Named Sections di Screen Frame:

Screen Frame
├── AppBar
├── ScrollContent
│   ├── Section-Hero
│   ├── Section-AttendanceStrip
│   ├── Section-QuickActions
│   │   ├── Row-1
│   │   └── Row-2
│   ├── Section-HariIni
│   ├── Section-Hafalan
│   └── Section-Chat
├── BottomNav
└── FAB

Section prefix helps visual scan di Layers panel.

Icon-like layers:

Icon-Bell
Icon-ChevronRight
Icon-Check

Bukan:

• Vector (default)
• icon-bell.svg (file extension)
• bell icon (inconsistent casing)

---

🌐 LANGUAGE & TEXT CONVENTION

Bahasa default: Indonesian

Semua user-facing copy = Bahasa Indonesia.

Exception: Technical doc/internal bisa English (e.g. "Design tokens", "OAuth flow").

Capitalization:

Title Case untuk:

• Page names
• Major section headings
• Button labels
• CTA titles

Sentence case untuk:

• Body text
• Descriptions
• Placeholder
• Helper text

UPPERCASE untuk:

• Micro labels (ASSALAMU'ALAIKUM, SANTRI, HAFALAN)
• Badge status labels kalau designed uppercase (SEDANG BERLANGSUNG)

Abbreviations:

Preferred:

• SPP (standard — Sumbangan Pembinaan Pendidikan)
• NIS (Nomor Induk Siswa)
• NISN (Nomor Induk Siswa Nasional)
• H (Hijriah — "1447 H")

Avoid:

• & (ampersand) — gunakan "dan"
• # symbol kecuali dalam konteks teknis

Number format:

• 15 (not 15.)
• Rp 750.000 (titik untuk thousand separator)
• Rp 1.250.000,50 (koma untuk decimal kalau ada)
• 95% (tanpa spasi sebelum %)

Date format:

• 15 Apr 2026 (short)
• 15 April 2026 (long)
• Senin, 15 April 2026 (with day)
• 8 Syawal 1447 H (Hijri dengan "H" suffix)

Time format:

• 14:30 (24-hour Indonesia standard)
• 14:30 WIB (kalau timezone relevant)

---

🚦 STATUS INDICATORS

Frame status labels (emoji prefix):

Emoji	Meaning	Use case
🟢	Production ready	Stable, reviewed
🟡	In review	Designer menunggu approval
🔴	Broken / Outdated	Tidak dipakai, jangan di-reference
🔵	WIP — Work in progress	Masih di-design
⚫	Archived	Old version

Example: 🟢 Parent / Dashboard / Home = production ready

Gunakan sparingly, hanya untuk highlight status penting.

Component status (tanpa emoji, pakai description):

Di component description:

@status: production
@version: 1.2.0
@lastReviewed: 2026-04-16

---

📌 NAMING DO's AND DON'Ts

✅ DO

• ✅ Consistent casing dalam satu kategori
• ✅ Descriptive, semantic names
• ✅ Hierarchical dengan separator /
• ✅ Shorter when possible (balance with clarity)
• ✅ English untuk technical terms
• ✅ Indonesian untuk user-facing
• ✅ Rename auto-generated names kalau matter untuk review
• ✅ Update naming saat refactor

❌ DON'T

• ❌ Mix case styles dalam satu category (Button + card + BOTTOM_NAV)
• ❌ Emoji di dalam nama layer (hanya di page names)
• ❌ Leading/trailing whitespace
• ❌ Duplicate names dalam same scope
• ❌ "Copy of X" (rename setelah duplicate!)
• ❌ Version numbers di names (Button v2) — pakai changelog
• ❌ Designer initials (Hero-RF) — pakai git commit author

---

📊 EXAMPLE: RENAMING AUDIT UNTUK FILE CURRENT

Dari data yang saya lihat di 42 frame, berikut yang perlu di-rename:

Current → Recommended

Parent / 00 - Splash Screen
  → Parent / Onboarding / Splash

Parent / 00 - Splash Screen 2
  → Parent / Onboarding / Splash 2 (atau delete kalau duplicate)

Parent / 01 - Onboarding Welcome
  → Parent / Onboarding / Welcome

Parent / 02 - Onboarding Fitur
  → Parent / Onboarding / Features

Parent / 03 - Onboarding Mulai
  → Parent / Onboarding / Start

Parent / Absensi (Polished)
  → Parent / Attendance / Main

Parent / Chat Wali Kelas
  → Parent / Communication / Chat

Parent / Dashboard (Polished)
  → Parent / Dashboard / Home

Parent / Dashboard (Dark Mode)
  → 🗄️ Archive / Dashboard v1 Pre-Polish
  (atau delete)

Parent / Detail Invoice (Polished)
  → Parent / Billing / Invoice Detail

Parent / Edit Profil
  → Parent / Profile / Edit

Parent / Forgot Password
  → Parent / Auth / Forgot Password

Parent / Ganti Password
  → Parent / Profile / Change Password

Parent / Hafalan Progress
  → Parent / Spiritual / Hafalan Progress

Parent / Jadwal Pelajaran
  → Parent / Academic / Schedule

Parent / Multi-Child Switcher
  → Parent / Dashboard / Multi Child Switcher
  (ini actually bottom sheet, bukan full screen — consider move to Components)

Parent / Nilai (Polished)
  → Parent / Academic / Grades

Parent / Notifikasi Center
  → Parent / Communication / Notifications

Parent / Payment - QRIS
  → Parent / Payment / QRIS

Parent / Payment - Sukses
  → Parent / Payment / Success

Parent / Payment - Transfer Bank
  → Parent / Payment / Bank Transfer

Parent / Payment - Virtual Account
  → Parent / Payment / Virtual Account

Parent / Pengaturan Notifikasi
  → Parent / Settings / Notifications

Parent / Pengumuman
  → Parent / Communication / Announcements

Parent / Pengumuman Detail
  → Parent / Communication / Announcement Detail

Parent / Perizinan
  → Parent / Communication / Permissions

Parent / Perizinan Detail
  → Parent / Communication / Permission Detail

Parent / Profil (Polished)
  → Parent / Profile / Main

Parent / Rapor Digital
  → Parent / Academic / Report Card

Parent / Sesi Detail
  → Parent / Spiritual / Session Detail

Parent / Setoran Detail
  → Parent / Spiritual / Setoran Detail

Parent / State - Nilai Kosong
  → Parent / Academic / Grades / Empty

Parent / State - Offline
  → Common / State / Offline

Parent / State - Server Error
  → Common / State / Server Error

Parent / State - Tagihan Kosong
  → Parent / Billing / Invoice List / Empty

Parent / Subject Detail
  → Parent / Academic / Subject Detail

Parent / Tabungan (Polished)
  → Parent / Savings / Main

Parent / Tabungan - Atur Uang Saku
  → Parent / Savings / Configure Allowance

Parent / Tabungan - Setor
  → Parent / Savings / Deposit

Parent / Tagihan (Polished)
  → Parent / Billing / Invoice List

Parent / Tagihan (Dark Mode)
  → Parent / Billing / Invoice List [Dark]
  (atau handle via Variables mode)

Parent / Wali Kelas Profile
  → Parent / Communication / Teacher Profile

---

✅ NAMING VALIDATION CHECKLIST

Designer runs this check sebelum declare file "clean":

File level

• File title: Amal E-Santri Design System
• 11 pages present dengan emoji prefix

Page level

• Cover, Style Guide, Component Library, Patterns ada
• Persona pages numbered: 1. Parent, 2. Guru, dst
• Archive page exists

Frame level

• All frames follow {Persona} / {Category} / {ScreenName} pattern
• No "Copy of X" names
• No default names (Frame 123, Rectangle 5)
• State suffixes used correctly (Empty, Loading, Error, Success, Failed)

Component level

• All components under Atom/, Molecule/, Organism/ prefix
• Property names camelCase
• Variant values consistent casing

Variable level

• Primitive tokens Tailwind-style (emerald-600)
• Semantic tokens descriptive (brand/primary)
• Mode names: Light, Dark

Text Style

• Text styles follow token names (h1, body, caption)

Effect Style

• Shadow names follow shadow/{size} pattern

Language

• All user-facing text Bahasa Indonesia
• Technical terms English kalau standard

Emoji

• Emoji hanya di page names
• Tidak ada emoji di frame/component/layer names

---

Status: Convention complete, ready untuk designer implement Last updated: 2026-04-16 Version: 1.0