UI Design

UI Design — The Holy Qur'an

Everything goes through the configs layer (lib/configs/). Never hardcode colors, font sizes or pixel values. Full API reference: docs/architecture/configs.md.

Brand at a glance

Calm, reading-first. Soft coral accent on white (light) or near-black (dark). Arabic Qur'an text in the Noor font, UI text in Poppins. Light and dark themes are both first-class (toggle in the drawer, persisted by AppProvider).

Every widget

class _Header extends StatelessWidget {          // class, never a function
  const _Header();
  @override
  Widget build(BuildContext context) {
    App.init(context);                            // always first
    final appProvider = Provider.of<AppProvider>(context);   // if you need isDark
    return …;
  }
}

Screens wrap their body in Screen(...) (lib/ui/widgets/core/screen/screen.dart): it sets status-bar brightness, optional keyboardHandler, PopScope, drawers and FABs. Screen-private widgets are part files under widgets/.

Color tokens — AppTheme.c!.<token>

Rules: no Color(0xff…) inline (the coral #ee8f8b still appears in legacy dividers — use AppTheme.c!.accent instead); no Colors.white/Colors.black for surfaces/text — use background/text; .withValues(alpha:) not .withOpacity.

Typography — AppText.<style> (sizes scale with AppDimensions.font)

b = weight 600. Extensions: AppText.b1!.cl(AppTheme.c!.textSub!), .s(18), .tsc(1.2), .w(5). Qur'an text: TextStyle(fontFamily: 'Noor', fontSize: AppDimensions.normalize(…)), textAlign: TextAlign.right.

Spacing & sizing — Space / AppDimensions

• Gaps: Space.y! (½ unit), Space.y1! (1), Space.y2! (2), Space.x… for rows, Space.xm!/Space.ym! expanding spacers, Space.yf(1.5) custom, Space.top!/Space.bottom! safe-area.
• Padding: Space.z! zero, Space.h!/Space.v! (½), Space.h1!/Space.v1!, Space.h2!/Space.v2!, Space.all(1), Space.hf(0.5); extensions .st()/.sb()/.sv() add safe-area, .t(n)/.b(n)/.l(n)/.r(n) set a side.
• Sizes: AppDimensions.normalize(n) for icons/images/heights, AppDimensions.font(n) for text. Never raw SizedBox(height: 16).
• Radii/shadows/decorations: UIProps.radius, buttonRadius, cardRadius, cardShadow, boxCard, borderButton, durations UIProps.duration/duration2.

Reuse before building

AppButton (primary CTA), AppBackButton, CustomTitle, AppName/DrawerAppName, AppVersion, CustomImage (faded header image), LoadingShimmer, WidgetAnimator (list entrance), EntranceFader, Flare (dark-mode particles), QuranRail, Calligraphy, FocusHandler, ScrollColumnExpandable. Icons: iconsax.

Patterns to copy

• Index screens: Stack inside SafeArea → CustomImage header + AppBackButton + CustomTitle + search field + list/grid (see surah_index_screen.dart, juz_index_screen.dart).
• Reading screen: CustomScrollView with pinned SliverAppBar + SliverList of ListTiles (see page_screen.dart).
• States: BlocBuilder branches on XFetchLoading → LoadingShimmer, XFetchFailed → message + retry, XFetchSuccess → content.

Output

Write the widget as a class in the right place (lib/ui/widgets/… if shared, lib/ui/screens/<screen>/widgets/ if private), wire routes via AppRoutes if it's a screen, add/extend the widget test, run fvm flutter analyze.