This document will outline the attribute naming convention, style convention, and list of references and colour names for app theming.
Colour references are the base data points for the app theming. All themes will reference either a colour reference, or a direct colour hex.
For each colour defined, there will be 3 variants. Primary, Secondary, and Tertiary. These usages will vary based on the context of the colour, for example, a text colour, secondary may be used as a lighter version of the defined colour, rather than as a 'state', where as for a button, the secondary colour would be used for the 'pressed' state.
Typically, primary will refer to the default state of a colour, secondary will refer to the pressed state, and tertiary the disabled state.
For each type of colour, there should be a 'text' version that will be guaranteed to work on the colour its referencing.
The naming convention is as follows:
<what>?_<type>_<variant>
| part | description | values |
|---|---|---|
| What | (optional) What the colour is used for. Default usage is "generic/background" so is omitted. | text, or none |
| Type | Describes the colour, example "accent", "primary" | see below |
| Variant | Is a variant of the colour These are used, depending on the colour, to describe a normal/selected/disabled state, or just 3 variations of the colour | primary, secondary, tertiary |
Currently the following colours are defined; (each colour has a primary/secondary/tertiary attribute defined)
| name | description |
|---|---|
| primary | This is the primary colour, typically the main branding colour. |
| base1 | This is the main colour, used for backgrounds |
| base2 | This is a secondary colour to main, a slightly darker/lighter variant of base1 |
| base3 | This is a tertiary colour to main, possibly an invert of base1 |
| info | This is main colour used for info view (usually black) |
| caution | This is main colour used for caution view (usually yellow/beige) |
| warning | This is main colour used for warning view (usually orangish) |
| error | This is main colour used for error view (usually red) |
| success | This is main colour used for success view (usually green) |
| accent | The accent colour for primary |
| alt_accent | An alternative accent colour for primary. Used mainly for text on base1 and bordered buttons for when accent is too light. |
| shadow | Shadow colour. primary is the start colour, secondary the end colour (for gradient) |
| window | Window reference. This can either be a solid colour, or reference to a drawable |
| empty | Empty window reference. This can either be a solid colour, or reference to a drawable |
| text_window | This is text colour that should work for window |
| text_empty | This is text colour that should work for empty |
| text_primary | This is text colour that should work for primary |
| text_base1 | This is the primary text colour, should work on base1 |
| text_base2 | This is a secondary text colour, should work on base2 |
| text_base3 | This is a colour defined for when 1 and 2 are not suitable. possibly could be an invert of text1 |
| text_accent | This is the text colour that works for accent |
| text_info | This is the text colour that works for info |
| text_caution | This is the text colour that works for caution |
| text_warning | This is the text colour that works for warning |
| text_error | This is the text colour that works for error |
| text_success | This is the text colour that works for success |
These styles are standard groupings of attributes. Although the specifics may differ, the general gist of the styles should be consistent.
The naming convention is loosely as follows:
style_<what>?_<variant>
There is no 'hard and fast' convention to the naming, so long as it makes sense and has the correct references to what it is.
| part | description |
|---|---|
| style | denotes its a style reference |
| what | (optional) What the style is for i.e. text, button |
| variant | The style reference, such as title1, or primary |
Currently the following styles are defined;
| name | description |
|---|---|
| style_text | The main text style - used for all text styles by default. Uses base1 and text1 |
| style_text_window | Text style that will work on window |
| style_text_base1 | Text style that will work on base1 |
| style_text_base2 | Text style that will work on base2 |
| style_text_base3 | Text style that will work on base3 |
| style_text_accent | The accent text style - used for displaying text on a accent |
| style_text_info | The info text style - used for displaying text on a info |
| style_text_caution | The caution text style - used for displaying text on a caution |
| style_text_warning | The warning text style - used for displaying text on a warning |
| style_text_success | The success text style - used for displaying text on a success |
| style_text_error | The error text style - used for displaying text on a error |
| style_text_title1 | Title1 style (like h1) |
| style_text_title2 | Title2 style (like h2) |
| style_text_title3 | Title3 style (like h3) |
| style_text_subtitle | Subtitle style |
| style_text_heading | Heading style (for smaller headings) |
| style_text_caption | Caption style |
| style_text_body | Body text style (for copy text) |
| style_input | Main input style |
| style_input_floating | Floating style input (explore screen) |
| style_button | Main button style. Defaults using base1 and text1 |
| style_button_transparent | A transparent button using text1 |
| style_button_transparent_accent | A transparent button using accent for text colour |
| style_button_transparent_info | Transparent info style button using text_info |
| style_button_transparent_caution | Transparent caution style button using text_caution |
| style_button_rounded | A rounded style button using base1 and text1 |
| style_button_info | Info tinted style button using info and text_info |
| style_button_info_bordered | A bordered info style button using text_info for the text and border |
| style_button_caution | Caution tinted style button using caution and text_caution |
| style_button_accent | A button that uses accent and text_accent |
| style_button_accent_invert | A button that uses accent as the text colour and text_accent as the background colour |
| style_button_accent_rounded | Rounded accent button using accent and text_accent |
| style_button_accent_bordered | A bordered accent style button using accent and text_accent |
| style_button_accent_bordered_invert | A bordered button that uses text_accent for text and border. Should work on an accent background |
| style_card | Card style (with bottom shadow and paddings) |
| style_section_header | Section header view that uses primary_secondary for background and text_primary for text |
| style_navigation | The style reference for navigation drawer |
| style_navigation_item | The style reference for navigation drawer item |
| style_info | The style reference for info view block |
| style_caution | The style reference for caution view block |
| style_warning | The style reference for warning view block |
| style_error | The style reference for error view block |
| style_success | The style reference for success view block |
style_text
textColor: text_base1_primary
lineSpacingMultiplier: 1.2
fontFamily: regular_font
textSize: 16sp
style_text_title1
fontFamily: medium_font
maxLines: 1
textSize: 24sp
style_text_title2
fontFamily: medium_font
maxLines: 1
textSize: 20sp
style_text_title3
fontFamily: medium_font
maxLines: 1
textSize: 18sp
style_text_subtitle
fontFamily: regular_font
maxLines: 1
textSize: 18sp
style_text_caption
textColor: text_base1_tertiary
textSize: 14sp
style_text_body
textColor: text_base2_primary
textSize: 16sp
lineSpacingMultiplier: 1.4
style_text_heading
fontFamily: medium_font
textColor: text_base2_primary
textSize: 18sp
textSizeMax: 18sp
textSizeMin: 14sp
style_section_header
background: primary_secondary
maxLines: 1
padding: 12dp
fontFamily: medium_font
fontStyle: bold
textColor: text_primary
textSize: 18sp
Themes are android specific and will possibly not translate between platforms, but are a means to change defined attrs on a view-by-view basis (for e.g to allow
for a different divider on navigation)
Each view style should have an empty defined theme to allow for overriding. Should match the style attr name but with theme instead of style
theme_<what>?_<variant>
| part | description |
|---|---|
| theme | denotes its a theme reference |
| what | (optional) What the style is for i.e. text, button |
| variant | The style reference, such as title1, or primary |
Examples;
- theme_card
- theme_section_header
- theme_navigation
- theme_info
- theme_caution
- theme_warning
- theme_error
- theme_success
In Android there are 4 main components to "styles"
These are attribute definitions. These will be the human names for the defined style attributes, for example;
text_primarytext_accentaccent
These attributes are defined so that when an android Style is created, you can set these properties to be what they correspond to within that style, for example,
text_primary could be set to black for the main app Style, and white for a 'dark' Style.
These attributes can then be referenced in other Styles (which then views will inherit from) or directly on a view.
These colours are just colour definitions. They should be defined for each operator, then referenced for the attr that it corresponds to, for example;
<item name="bybus_primary">yellow</item>
<item name="passenger_primary">blue</item>
which can then be set for each Style
<style name="Default">
<item name="text_primary">@color/passenger_primary</item>
</style>
<style name="ByBusDefault">
<item name="text_primary">@color/bybus_primary</item>
</style>
This allows you to only reference text_primary when you want a text colour for primary and will select the right colour based on the current set Style
Styles are defined in android, like style sheets, to define set properties to reduce duplication. They can have a parent style that they further inherit properties from.
In these styles, you would set each attr to what ever colour they need to for that operator. The default style should be fully defined for each attr as the "base passenger" style
that will fallback to if an attr isnt defined for a particular style.
Themes in android are defined like styles, but behave differently. Themes are used to set properties, but will affect every sub-view within its hierarchy. Generally in these "themes"
you should redefine the attr attributes, and save property definitions for Style (such as padding, margin, etc)