source-apps

The Source library for Android

Add the library dependency

Add the dependency to build.gradle.kts for the consuming module:

implementation("com.gu.source:source-android:<version>")

[!note] See here if you need to build and bundle the library as a local repository.

Using the library

The library provides design presets and components.

The design presets are available name spaced under the com.gu.Source object, e.g. Source.Typography.HeadlineBold15.

API documentation is here..

Typography presets

Typography presets include fontFamily, fontSize, lineHeight, fontWeight, fontStyle in a single token. All typography tokens with their previews are listed here

The library bundles app font files, so they are not separately required in consumer apps.

Use typography presets directly in a Text component.

Text(
    text = "The world's leading liberal voice",
    // Using Source typography preset
    style = Source.Typography.TextEgyptianItalic14,
)

Core palette colours

Core palette colours are available for direct use in components through Source.Palette. Preview all available colours here.

Text(
    text = "The world's leading liberal voice",
    // Using Source palette colours
    color = Source.Palette.Brand400,
)

Buttons

Four core button components are available - SourceButton, SourceIconButton, PlainSourceButton and SourceBaseIconButton.

Themed buttons

The first two source buttons have preset style and size variants corresponding to Source specifications. Both Core and Reader Revenue themes are provided. The latter two use Source defined sizing but can be used for custom colour schemes.

Core theme	Reader revenue theme

Usage examples

Using SourceButton:

SourceButton(
    text = "Sign in",
    priority = SourceButton.Priority.PrimaryOnWhite,
    onClick = {},
    size = SourceButton.Size.Small,
)

Using SourceIconButton with a Material Icon:

SourceIconButton(
    icon = Icons.Default.Person,
    priority = SourceButton.Priority.SecondaryOnBlue,
    contentDescription = null,
    onClick = {},
    size = SourceButton.Size.Medium,
)

Using SourceIconButton with a drawable resource:

SourceIconButton(
    painter = painterResource(R.drawable.ic_person),
    priority = SourceButton.Priority.SecondaryOnBlue,
    contentDescription = null,
    onClick = {},
)

Base buttons

The plain and base buttons are intended for when custom colour schemes are needed. These do not use preconfigured priority or theme. They expect to be directly be provided with ButtonColours. (PlainSourceButton is available from version 0.2.1, SourceBaseIconButton is available from 0.3.0)

Usage examples

PlainSourceButton(
    text = "Culture themed",
    onClick = {},
    modifier = Modifier.align(CenterHorizontally),
    buttonColours = ButtonColours(
        border = AppColour(
            light = Source.Palette.Culture200,
            dark = Source.Palette.Culture800,
        ),
        container = AppColour(
            light = Source.Palette.Culture800,
            dark = Source.Palette.Culture200,
        ),
        content = AppColour(
            light = Source.Palette.Culture200,
            dark = Source.Palette.Culture800,
        ),
    ),
)

SourceBaseIconButton(
    buttonColours = buttonColours,
    size = SourceButton.Size.Small,
    onClick = { },
) {
    Icon(
        imageVector = Source.Icons.Base.ChevronRight,
        contentDescription = null,
        modifier = it,
    )
}

Pager progress indicators

The PagerProgressBar component is used to denote progress as a user flips through the items in a HorizontalPager. It is typically used for image carousels.

The progress bar is styled to match Source specifications. It is expected to be placed below the pager.

Usage example

Column(
    modifier = modifier .widthIn(max = 695.dp),
) {
    HorizontalPager(
        state = pagerState,
        modifier = Modifier
            .aspectRatio(695 / 544f)
            .clip(RoundedCornerShape(16.dp)),
    ) { page ->
        SampleImage(
            randomKey = page,
            modifier = Modifier.fillMaxWidth(),
        )
    }
    
    // Place the bar below the pager
    PagerProgressBar(pagerState = pagerState)
}

Custom progress indicators

A lower level component PagerProgressIndicator is also available. It provides a lot more options for customising appearance of the indicators.

Usage example:

Column(modifier = Modifier.padding(8.dp)) {
    HorizontalPager(state = pagerState) {
        Box(
            modifier = Modifier
                .size(400.dp)
                .background(Source.Palette.Neutral86, RoundedCornerShape(8.dp)),
        ) {
            Text(
                text = (it + 1).toString(),
                style = Source.Typography.Titlepiece70,
                modifier = Modifier.align(Alignment.Center),
                color = Source.Palette.Neutral46,
            )
        }
    }
    
    // Place indicator below the pager, style it and set alignment explicitly
    PagerProgressIndicator(
        pagerState = pagerState,
        selectedIndicatorColour = Source.Palette.Sport500,
        unSelectedIndicatorColour = Source.Palette.Sport500.copy(alpha = 0.3F),
        indicatorShape = CutCornerShape(8.dp),
        maxIndicatorCount = 7,
        numberOfItemsToScale = 5,
        modifier = Modifier
            .padding(top = 8.dp)
            .align(Alignment.CenterHorizontally),
    )
}

---

Building and using directly

As a bundled repo

1. Build the library Run

   ./gradlew :source:publishReleasePublicationToGusourceRepository
   

   This will produce the library output at /source/build/gusource/.

2. Copy the built library to the news app Copy the library the built folder from /source/build/gusource/ to the android-news-app/src/main/libs/maven folder in the android-news-app repo.

3. Update the version number in the news app If the library version has changed, update it in the version catalog for the news app.

From maven local

1. Build the library Run

   ./gradlew :source:publishToMavenLocal
   

   This will publish the library to your local maven repository.

2. Update the version number in the news app If the library version has changed, update it in the version catalog for the news app.

3. Ensure you have mavenLocal declared first in your repositories

   repositories {
       mavenLocal()
       mavenCentral()
       google()
   }
   

Other notes

1. We use the com.gu package name and group id so we can use the Guardian’s Sonatype infra for signing and publishing the library. See this comment for reference.

This site is open source. Improve this page.