`incremental.design/theme`

Make your prototypes look just like an iOS, MacOS, tvOS, Android, Windows, GTK (linux) app.

If you design apps for a living, you probably have to prototype user interfaces for a variety of desktop and mobile platforms - each of which have their own, unique visual language. You don't have time to re-skin the same prototype for each platform. With @incremental.design/theme, you don't have to.

Make your prototypes look like native apps, without writing a single line of CSS:

The Theme object generates all of the CSS rules you need to make your prototype's UI components look just like a native app. All you need to do is choose a Platform, a Layout, and a Style, and it will generate all the CSS rules that your component needs to match your favorite platform's visual language.

Reskin your components, with just one setting:

Just swap out the platform, and all of the styles will update instantly.

Add dark mode to your prototypes, without a single line of code:

Every style in the Theme object has a light mode and dark mode. Best of all, the theme object automatically updates your prototype's styles to match your operating system's color scheme.

Installation:

Usage:

If you've ever prototyped a native app, you've probably spent more hours than you can count coaxing CSS into something that resembles the Apple human interface guidelines, material design guidelines, or fluent design guidelines. The Theme class takes care of that for you. Even better, it describes all of these visual languages with a simple, common vocabulary: platforms, layouts, styles, tints, and states. When you use Theme, you don't have to manually write hundreds of CSS selectors. All you need to do is describe the element you want to style in these five terms, and Theme will generate the corresponding CSS for you.

A platform is the visual language of an operating system. A visual language is the combination of styles that make a platform recognizable, familiar, and distinct from its contemporaries. Ergo, the visual language of iOS is different from that of MacOS, Android or Windows. Theme ships with six preset platforms:

`ios`	the visual language of iOS and iPadOS
`macos`	the visual language of macOS
`tvos`	the visual language of tvOS
`android`	the visual language of Android
`windows`	the visual language of Windows
`gtk`	the visual language of Linux (Gnome)

A layout is a set of rules that dictate the position of text and foreground shapes relative to a background shape.

Each of the platforms in Theme contains the following layouts:

Layout	iOS	macOS	tvOS	Android	Windows	GTK	Web
`inline`
`small`
`smallVertical`
`smallWithItemLeft`
`smallWithItemRight`
`medium`
`mediumVertical`
`large`
`massive`

Some preset themes also contain additional layouts that are specific to that theme. When you supply a platform to Theme.platform(), it will return a list of all of the layouts that the platform contains.

A style is a set of CSS rules that position and shade a specific piece of text, or a specific foreground or background shape within a background shape.

Every layout contains just three types of styles: text, fill and background. After all, virtually every user interface component in any design system can be described in terms of its text, fill, and background.

All of the layouts contain some combination of the following styles:

Type	Styles
`text` sets the color and size of the text it styles.	`textLabel`
	`textLabelIcon`
	`textFootnote`
	`textInput`
	`textInputIcon`
	`textItem`
`fill` positions the corresponding `text` within itself. E.g. `fillFootnote` positions `textFootnote`. sets the color, shape and size of the `text`'s fill. Note that some text styles have variants. A variant is an alternate type treatment that varies the opacity, color, weight, or other property of the text style. Variants improve the legibility of the characters that they style. The most common variant is the 'icon' variant: E.g. `textLabel` has the variant `textLabelIcon`. The corresponding `fillLabel` positions both of them.	`fillLabel`
	`fillFootnote`
	`fillInput`
	`fillItem`
`bg` positions `fill`s atop the element's background. sets the color, shape and size of the element's background.	`bgFloating`
	`bgExpanded`
	`bgNormal`

Some layouts may contain styles that aren't listed here. When you supply one of the preset layouts to Theme.platform(<platform>).layout(), you will receive a list of the styles within the layout.

A tint is an adjustment to a style that signifies a change in the application's data. Every style function accepts the following tints:

tint	what it signifies
`none`	Interacting with the component does not do anything to the application data.
`active`	Interacting with the component will change the application data in a way that can be undone and redone.
`progress`	Interacting with the component will initiate a change in the application data that will take at least a few seconds to complete.
`warn`	Interacting with the component will initiate a change in the application data that CANNOT be undone.
`success`	The previous interaction with the component has completed.
`fail`	The previous interaction with the component has been canceled.

A state is an adjustment to a style that reflects user interaction. Every style function accepts the following states:

`none`	The component is not being interacted with.
`hovered`	The component is occluded by a pointer, such as a mouse cursor or fingertip.
`pressed`	The component is depressed by a pointer.
`toggled`	the component remains pressed after a pointer has released it.
`focused`	A component's contents can receive input from a keyboard or a pointer.

Apply a preset theme:

The Theme class is a tree of styles, grouped by platforms, then by layouts,and then by styles. To access a style, you need to select the platform and layout to which that style belongs, as follows:

Choose one of ios, macos, tvos, android, windows, gtk or web, and supply it to Theme.platform:

const {layout, layouts} = Theme.platform('ios')

console.log(layout) // function
console.log(layouts) // ['inline', 'small', 'smallVertical', 'smallWithItemLeft', 'smallWithItemRight', 'medium', 'mediumVertical', 'large', 'massive']

Choose one of inline, small, smallVertical, smallWithItemLeft, smallWithItemRight, medium, mediumVertical, large, or massive and insert it into Theme.platform(...).layout:

const {style, styles, tints, states, modes} = Theme.platform('ios').layout('inline');

console.log(style);  // function

console.log(styles); // {
                     //    text:
                     //       [  'textDisclosureLeft',
                     //          'textIndicator',
                     //          'textIndicatorIcon',
                     //          'textLabel',
                     //          'textInputPlaceholder',
                     //          'textInputFilled',
                     //          'textValidator',
                     //          'textValidatorIcon',
                     //          'textInputStepperIcon',
                     //          'textAction',
                     //          'textActionDisclosure',
                     //          'textDisclosureRight',
                     //          'textDisclosureRightIcon'
                     //       ],
                     //    fill:
                     //       [  'fillDisclosureLeft',
                     //          'fillIndicator',
                     //          'fillLabel',
                     //          'fillInput',
                     //          'fillValidator',
                     //          'fillInputStepper',
                     //          'fillAction',
                     //          'fillDisclosureRight'
                     //       ],
                     //    bg:
                     //       [
                     //          'bgInline'
                     //       ]
                     // }

console.log(tints);  // [
                     //    'none',
                     //    'active',
                     //    'progress',
                     //    'success',
                     //    'warn',
                     //    'fail',
                     // ]

console.log(states); // [
                     //    'none',
                     //    'hovered',
                     //    'pressed',
                     //    'toggled',
                     //    'toggledHovered',
                     //    'toggledPressed',
                     //    'focused'
                     // ]

console.log(modes);  // [
                     //    'light',
                     //    'dark'
                     // ]

Chose one of the styles that Theme.platform(...).layout(...) returned, and insert it into Theme.platform(...).layout(...).style. You can also optionally insert one of the tints, states and modes into this function.

const CSSRules = Theme.platform('ios').layout('smallWithInline').style('textLabel','active','hovered')

console.log(CSSRules)   // {
                        //    'font-family': 'SF Pro Text, SF Pro Icons, Helvetica Neue, Helvetica, Arial, sans-serif',
                        //    'font-size': '17pt',
                        //    'font-weight': 400,
                        //    'color': 'rgba(0, 25, 39, 0.7)',
                        //    'mix-blend-mode': 'normal',
                        //    'letter-spacing': '-0.43pt',
                        //    'line-height': '22pt',
                        //    'text-align': 'left',
                        //    'align-self': 'start',
                        // }

Customise a preset theme

Make an entirely new theme:

use theme to build visual language break the language into properties, rather than CSS rules

use theme to style prototypes

use theme to build visual language break the language into properties, rather than CSS rules

How `incremental.design/theme` works:

why solve this problem? there are so many different CSS frameworks out there - many of which can be themed to match whatever platform you want to mimic

this isn't a wholesale replacement for your favorite CSS library. It can actually be used right alongside it! It's really meant to be good at two things, reskinning between platforms, and describing the look of user interface elements in a css-agnostic way. In theory, you can take the values in a theme.plaform, and generate XML that can be used in Sketch app, or NSSstrings that can be used on iOS. This is more than a collection of styles: it's a generator.

Repository Structure:

[ ] List each file, and what it does. [ ] Identify whether you are open to pull requests for a specific file or not.

File or Folder	What does it do?	When should you modify it?