Shared Android building blocks for Fjord apps: design system, observability, icons
  • Kotlin 58.3%
  • Python 22.1%
  • Java 17.7%
  • Shell 1.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Stephen Way 4d29eb07bb
All checks were successful
CI / icons (push) Successful in 8s
CI / build (push) Successful in 7m22s
Import the design system, observability and icon modules from fjord-android (GRD-498) (#1)
2026-11-19 20:22:08 +00:00
.forgejo Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
.source-size Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
Config Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
config/detekt Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
designsystem Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
gradle Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
icons Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
observability Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
Scripts Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
.editorconfig Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
.gitignore Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
AGENTS.md Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
build.gradle.kts Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
gradle.properties Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
gradlew Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
gradlew.bat Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
README.md Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00
settings.gradle.kts Import the design system, observability and icon modules from fjord-android (GRD-498) (#1) 2026-11-19 20:22:08 +00:00

fjord-android-kit

Shared Android libraries for Fjord apps: the Fjord Android app and Fjord Grid. One repository, one version tag, three library modules. The Apple counterpart is fjord-apple-kit; the version numbers are independent.

Module Namespace What it is
:designsystem sh.fjord.kit.designsystem Theme (colors, typography with its three fonts, contrast and status bar handling), layout policy, large-text and reduce-motion helpers, FjordIcon, the dropdown menu, pull to refresh and the preview surface.
:observability sh.fjord.kit.observability Crash reporting that names nothing from an app: the consent-gated CrashReporter, the Sentry sink, the scrubbers, the install id, the build channel, launch tracing and the analytics policy and region helpers.
:icons sh.fjord.icons The icon set (drawables, FjordIcons, FjordSymbol), generated from fjord-icons for the union of the apps' usage lists.

None of them depends on a Forgejo client, a Fjord Account client or Push, so an app that is not a Forgejo client can use them.

Packages still read com.rasterstate.fjord.ui.* and com.rasterstate.fjord.observability: the code moved here unchanged from fjord-android so no import in the app had to move. A later release renames them; the version notes will say so.

Use

Composite build first. Add this repository as a checkout pinned to a tag, then in the app's settings.gradle.kts:

includeBuild("fjord-android-kit")

and depend on the modules by group and name:

implementation("sh.fjord.kit:designsystem")
implementation("sh.fjord.kit:observability")

minSdk 26, Kotlin 2.4, Compose BOM as in gradle/libs.versions.toml. Keep the host's Android Gradle Plugin, Kotlin and Compose BOM in step with it.

Things a host app provides

  • Observability configuration. Install an ObservabilityConfiguration first thing at launch (Application.attachBaseContext), before anything reads the engine: application id, version name and code, whether the build is debuggable, the Sentry DSN, the operated URLs and the rest. Until then the engine sees ObservabilityConfiguration.Unconfigured, which fails closed: no DSN, no key, every host redacted.
  • Consent storage and failure facts. The host implements AnalyticsSettings (where the crash reporting consent lives) and FailureFacts (which of its exceptions are an HTTP refusal, came from the person's own server or are the person's state) and builds a CrashReporter(settings, sink, facts).
  • Sentry. :observability depends on sentry-android at the version pinned in gradle/libs.versions.toml. Pin the same version in the app so it links one SDK. The Sentry Gradle plugin (ProGuard mapping upload) stays on the app. The library manifest sets io.sentry.auto-init=false, so the SDK starts only through SentryCrashSink.enable after consent; a host that sets the same key itself overrides it.
  • Design system strings and artwork. The loaders, the splash scene and the list status views are not in the kit yet: they use the app's strings and drawables and move when the strings do.

Icons

Config/icons-usage/<app>.json lists the icon keys one app uses. The kit packages the union of all the lists, so an app can use an icon another app added without a second vendoring step.

Scripts/update-icons.sh ../fjord-icons   # a clean fjord-icons checkout at Config/fjord-icons-revision

CI runs Scripts/check_icons_usage.py: every listed icon is carried, nothing unlisted is, and the manifest, FjordIcons.java and the five drawable densities agree. A list edited without regenerating fails on the pull request.

Build

android.builder.sdkDownload=false is set, so a build never downloads an SDK component behind your back: a missing one fails by name. A checkout needs JDK 17 and an Android SDK with platforms;android-37.0 (revision 2), build-tools;36.0.0 and platform-tools 37.0.1. CI installs exactly these, verified by hash, with .forgejo/scripts/install-jdk.sh and .forgejo/scripts/install-android-sdk.sh; run the same two scripts (they write to $HOME and $GITHUB_ENV/$GITHUB_PATH) or install the same components with sdkmanager.

Checks

./gradlew spotlessCheck detekt assembleDebug assembleRelease testDebugUnitTest lintDebug, then the icon check above, and the source-size check (150-line target, 200-line limit per file; see AGENTS.md): cd .source-size/tool && python3 -B -m source_size -C ../.. check --base origin/main --worktree. CI runs both on the Linux Android runners (JDK 17 and the Android SDK come from the Forgejo package registry, the way fjord-android installs them).

Versions

Tags are semantic versions of this repository. A host app pins an exact tag. The first tag is 0.1.0.