ui-design

name	ui-design
description	Design Flutter UI screens and widgets for The Holy Qur'an app. Use when asked to build, design, create, or prototype a screen, widget, tile, dialog, or UI component. Enforces this app's configs layer (AppTheme, AppText, Space, AppDimensions, UIProps), fonts (Poppins / Noor), Screen wrapper, and class-widget rules.
argument-hint	<what to 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>

Token	Light	Dark	Use
accent	#EE8F8B coral	same	CTAs, FAB, dividers, highlights
primary	#5BA897 teal	same	borders (UIProps.borderButton), secondary accents
primaryDark	#896277	same	rare, deep accent
background	white	#212121	cards, surfaces
backgroundSub	#F0F0F0	#1C1C1E	secondary surfaces
scaffold / scaffoldDark	#FEFEFE / #FCFCFC	#0E0E0E	page backgrounds
text / textSub / textSub2	black87 / greys	white70	body, secondary, hints
shadow / shadowSub	black 20% / 12%	same	UIProps.cardShadow

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)

Style	Base	Use
h1 / h1b	20	screen titles (CustomTitle)
h2 / h2b	14	section headers, juz names
h3 / h3b	8	sub-headers, error titles
b1 / b1b	8	body, surah Arabic name in tiles
b2 / b2b	6.25	secondary labels, hints
l1 / l1b, l2 / l2b	5 / 4	captions, ayah numbers

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.