iom-frontend-design-system

name	iom-frontend-design-system
description	Align frontend design and implementation with the IOM ITB design system used in this repository. Use when creating or updating Vue and Tailwind pages, layouts, navigation, forms, tables, cards, CTAs, responsive states, or visual polish that should match the IOM public site or admin dashboard instead of introducing a new visual language.

IOM Frontend Design System

Overview

Use this skill to keep UI work consistent with the existing IOM visual system. Decide first whether the target surface is the public site or the admin dashboard, then follow the matching guidance and references before making design changes.

Workflow

1. Classify the target surface. Public marketing, donation, activity, merchandise, and informational pages use the public-site system. Authenticated dashboard CRUD screens, tables, filters, modals, and analytics use the admin-dashboard system.

2. Load only the relevant reference file. Read references/public-site.md for the public website. Read references/admin-dashboard.md for the dashboard.

3. Preserve the existing interaction model before styling details. Keep route structure, component composition, form behavior, and data flows aligned with nearby files. Do not redesign the information architecture unless the user asked for it.

4. Reuse existing tokens and primitives. Prefer existing colors, radii, shadows, spacing rhythms, and component patterns over inventing new ones. If a new token is unavoidable, make it a near-neighbor of the current system rather than a new theme.

5. Match the repo's restraint level. The public site is brand-forward, friendly, rounded, and centered around IOM blue. The admin dashboard is template-like, neutral, and productivity-first with gray surfaces plus indigo accents. For the admin dashboard, use Manrope for body text and Google Sans Flex for headings/display unless the local file already establishes a different choice. For custom admin dropdowns, avoid native browser select UI when the visual design calls for a custom control. Do not cross those aesthetics accidentally.

6. Validate the result visually in code. Check headings, CTA weight, border radius, spacing density, and mobile behavior against nearby pages. If the new UI would look out of place next to existing screens, revise it.

7. Prefer the user's established admin preferences when local patterns are ambiguous. The current dashboard direction is compact, list-based, professional, and AWS-console-adjacent without copying AWS branding. Favor clear hierarchy, consistent form controls, useful operational information, and restrained surfaces over decorative layout.

Design Rules

Public site

• Prefer text-main and white as the core palette, with soft light sections and occasional supporting grays.
• Prefer large centered headings, heavy font weights, rounded pills, and generous vertical spacing.
• Prefer friendly, content-led sections over dense app-shell layouts.
• Use imagery, banners, cards, and clear CTA buttons freely when they fit the existing page patterns.
• Keep forms approachable: white cards, medium shadows, rounded corners, gray inputs, clear labels.
• Default to mobile-first layouts that stack cleanly and widen progressively.

Admin dashboard

• Prefer neutral gray surfaces, white cards, dark sidebar navigation, and indigo or blue accents.
• Keep layouts utilitarian: app shell, header, sidebar, content container, then data widgets.
• Prefer compact headings, tables, filters, pagers, and action buttons over marketing-style sections.
• Reuse standard form controls and CRUD-table patterns instead of creating bespoke components.
• Keep motion minimal and functional.
• Prefer list-based layouts for admin CRUD pages and forms when card-heavy pages feel bulky.
• Do not overuse cards. Avoid cards inside cards, filter cards inside table cards, and repeated decorative panels when a list, table, or simple section divider is clearer.
• Remove redundant page headings and labels when the route, sidebar, or page context already makes the screen obvious.
• Replace generic counters like "x data tampil" or "filter aktif" with information that helps the admin act, or omit them.
• Display database values in user-facing Indonesian labels, not raw enum/status strings from the DB.
• Keep internal-only information, such as PIC names and phone numbers, out of public pages.

Admin typography

• Use Manrope for body text.
• Use Google Sans Flex for admin headings/display when available.
• Avoid overusing uppercase. Prefer Pascal Case or sentence-style labels, then use size and weight for hierarchy.
• Section labels in sidebars can be slightly larger and semibold, but should not feel forced or overly bright.
• Sidebar item labels should be readable at a glance; use moderate size, normal-to-medium weight for inactive items, and semibold only for active/important states.

Admin controls

• Text fields, date inputs, dropdown triggers, and search inputs should share the same border styling unless there is a strong local reason.
• Preferred control border: border border-[#8c8c94] or the closest existing neutral token, radius around 8px, white background, no heavy shadow.
• Field labels should be dark and slightly bold; helper text should be muted and clearly secondary.
• Keep placeholder text visibly lighter than entered text.
• For custom dropdown triggers, balance left and right padding. The chevron side should not feel cramped.
• Use a real custom dropdown component when styling is important; avoid falling back to the native macOS select popup.
• Dropdown menu containers should not add extra top/bottom padding around the option list unless needed for grouping.
• Dropdown chevrons/icons should be visually sturdy enough to match the text weight.

Admin sidebar

• Use the IOM logo in the sidebar header without a white background card unless the surrounding implementation already requires it.
• Avoid duplicating the same brand/logo/title in both sidebar and page header.
• Sidebar contrast matters: dark blue backgrounds need light text, muted blue-white secondary labels, and clear active states.
• Group related routes in the sidebar with useful category labels.
• Use distinct, feature-specific line icons instead of repeating generic icons across unrelated menu items.
• Active sidebar items should fill the row width cleanly and include a clear left active marker.

Admin forms

• Prefer list-based or sectioned form layouts: label/help on the left and control on the right for wider screens, stacked on mobile.
• Align input columns consistently so text fields do not appear staggered.
• Keep related fields grouped, but use spacing, dividers, and headings before adding another card.
• Do not add unnecessary "pill" metadata in forms.
• File inputs and image upload controls should communicate empty/current state clearly without making the row feel bulky.

Admin tables

• Tables should be readable and compact, with clear borders and row separation.
• Use sortable table headers when sorting exists. Support multi-key sorting when the data model benefits from it.
• Sort affordances should look like dropdown/chevron controls and should not show intrusive focus borders after click.
• Table-related documentation or key/value lists need borders strong enough to scan, but still consistent with the rest of the admin UI.

Admin icons

• Prefer simple line icons from a consistent visual family such as Lucide-style icons.
• Choose semantic icons per feature: donation/payment, school/faculty, merchandise, receipts/transactions, partnerships, calendar activities, guide/docs, and user/member flows should not all reuse one generic calendar/chart icon.
• Keep icon stroke width consistent with sidebar text weight and active/inactive contrast.

Shared constraints

• Use Tailwind utility composition in the same style as surrounding files.
• Preserve the repo's current rounded-corner bias instead of switching to sharp enterprise styling.
• Prefer editing existing components over creating parallel variants with overlapping purpose.
• Keep color changes conservative. If the surrounding code uses bg-main, text-main, bg-white, bg-gray-200, or indigo accents, stay in that neighborhood.
• Keep typography weight-driven. This codebase relies more on weight and size than on sophisticated type systems.
• Keep DTOs, type hints, and separation of concern clean when UI work touches data shaping. Avoid scattered sanitization or many local if branches when a typed DTO, mapper, or computed normalization layer is more appropriate.

Reference Files

• references/public-site.md Read when working on the marketing site, donation flows, informational pages, public forms, or public navigation.

• references/admin-dashboard.md Read when working on dashboard pages, tables, analytics widgets, CRUD forms, sidebar/header layout, or admin modals.

If Unsure

Inspect the nearest existing page or component in the same app and imitate its structure first. When the public site and admin dashboard patterns conflict, prioritize local consistency with the target app over abstract design cleanliness. If the user asks for a more ambitious redesign, keep the same brand DNA and interaction patterns unless they explicitly want a broader visual departure.