Welcome to the
stc pay UI Kit

If you just tried to sync the main app and it failed — or you can’t find StcPayTheme anywhere in the codebase — you’re in the right place.

The stc pay app is built on a shared UI Kit: the theme, the brand colours, the language engine and a library of Compose components all live in a separate repo (stcpay-bh-android-ui-kit). The main app pulls it in as a composite build — and until you set that up, the app won’t even sync. This short guide gets you past that and explains what the kit gives you.

This guide pairs with the main Developer Knowledge Transfer; keep both open, and walk through the setup with your lead the first time.

• A · Start Here
• §01Welcome & Why This Guide Exists
• §03What the UI Kit Is & Why It’s Required
• B · Getting It Building
• §04Inside the Kit — Structure & Resources
• §05Link It — the Composite Build
• §06The Sync Gotcha — “Class Already Exists”
• C · What’s Inside
• §07Theme & Design Tokens
• §08The Component Library
• §09Language, Utilities & Security
• D · Reference
• §10How the App Uses It
• §11Quick Reference

The UI Kit is stc pay’s shared design system and component library, packaged as the Gradle module :stcpay-ui-kit (namespace com.stcpay.uikit). It’s bigger than it sounds — it holds almost everything the app is built from:

• The theme & design tokens — StcPayTheme, the colour palette, typography, dimensions (§07).
• The component library — buttons, text, text fields, checkboxes, switches, dropdowns, app bars, OTP, pickers, bottom sheets and more (§08).
• The language engine — LocaleManager / LocaleWrapper (English, Arabic + 5 more, RTL) (§09).
• The shared resources — the STC Forward fonts, the app’s strings in 7 languages, and the icon set.

Put simply: if you’ve tapped a button, typed in a field, or seen a bottom sheet in the app, it came from here.

The main app depends on it as the artifact com.stcpay:stcpay-ui-kit (declared once in the :util module). That artifact isn’t published to a repository you can reach, so you supply it from source via a composite build.

So the first job is simply to point the app at a local copy of this repo. Here’s the kit itself, then how to link it.

It’s a single Gradle module — a Compose Android library on JDK 17 (compileSdk 36, minSdk 23, Hilt) — but don’t mistake “one module” for “small”: it’s around 90 source files plus the fonts, strings and icons. The module is :stcpay-ui-kit under rootProject.name = "stcpay_ui_kit" (that name matters in §06).

Packages (under com.stcpay.uikit)

Coordinates

This is the step that makes the main app sync. You’re telling the app “use this local folder as the UI Kit”.

1. Clone stcpay-bh-android-ui-kit somewhere on your machine.
2. In the main app’s root local.properties, add the path to that clone:

stcPayUiKitProjectPath=/Users/you/claude/stcpay-bh-android-ui-kit

That’s it. The app’s settings.gradle.kts picks up the key and wires the kit in as a composite build — includeBuild pulls in your local source, and dependencySubstitution swaps the published artifact for it:

localProperties?.getProperty("stcPayUiKitProjectPath")?.let { path ->
    includeBuild(path) {
        name = "stcpay-uikit"
        dependencySubstitution {
            substitute(module("com.stcpay:stcpay-ui-kit")).using(project(":stcpay-ui-kit"))
        }
    }
}

Sync now. If it works — great. If you hit a duplicate-class error, that’s the next section (and it’s expected).

Almost everyone hits this on first sync after linking the kit: a duplicate-class / “class already exists” error. It happens because the composite build’s name and the kit’s own project name don’t line up. The fix is quick.

The fix: make the two names match, sync, then revert

By default the names differ — the kit calls itself stcpay_ui_kit, while the app includes it as stcpay-uikit:

1. Set both names to the same value (e.g. make both "stcpay-uikit").
2. Sync the project — it should now complete.
3. Once the sync succeeds, revert both names to their originals.

Once you’re synced, the rest is just knowing what the kit offers.

This is the app’s visual language in one place — and the reason StcPayTheme isn’t in the app repo.

This is the heart of the kit and what you’ll use every day. Nearly every shared UI building block in the app lives here — reach for these before writing your own.

Language & locale

The kit owns the whole localization engine: LocaleManager (init, setLocale, localizedString, getPersistedLanguage), the LocaleWrapper composable that provides language context, LanguageViewModel, and the Language enum (which carries each language’s LayoutDirection for RTL). It also ships the app’s strings in 7 languages and the STC Forward fonts.

Utilities

utils/ holds shared helpers you’ll reuse constantly: FormattingUtils (prices / currency), DateTimeUtils, Validations, QRCodeUtils, CopyUtils, SendMessageUtils, ContextUtil.

Security

KeyboardSecurityManager (a secure-keyboard guard) and ScreenCaptureUtils (screenshot control) — small but important for a banking app.

You almost never add the dependency yourself — it’s declared once and flows everywhere. The :util module pulls it in with api(...), and because :util sits low in the dependency chain, the whole app gets the kit transitively.

The main app wires the kit’s big pieces in at startup (see the main guide’s §12 and §16):

• StcPayTheme wraps the app’s content in MainActivity.
• LocaleManager.init(...) runs in StcApplication at startup.
• BottomSheetHost is mounted once; any screen raises a sheet through BottomSheetManager.

Everything on one card

Get it building, in three steps

1. Clone the kit; set stcPayUiKitProjectPath in the app’s local.properties (§05).
2. If sync errors with a duplicate class, match the two project names, sync, then revert (§06).
3. Done — the kit’s theme, components, language and resources are now available app-wide.