search

KyleAMathews / typography.js

A powerful toolkit for building websites with beautiful design
http://kyleamathews.github.io/typography.js/
MIT License
3.82k stars 181 forks source link
css css-in-js javascript theme typography typography-engine typography-themes

readme

Typography.js Build Status Coverage Status

A powerful toolkit for building websites with beautiful design.

Install

npm install typography

Demo/playground

https://kyleamathews.github.io/typography.js

Why

The goal of Typography.js is to provide a high-level elegant API for expressing typographic design intent.

Typography is a complex system of interrelated styles. 100s of style declarations on dozens of elements must be in harmonious order. Trying one design change can mean making dozens of tedious recalculations and CSS value changes. Creating new Typography themes with CSS feels hard.

Typography.js provides a vastly simpler way to define and explore typography designs.

You provide configuration to the Typography.js JS api and it uses its Typography engine to generate CSS for block and inline elements.

Typography.js makes it easy to create designs that are unique, personal, and custom to your project.

Themes & Plugins

Sites that use Typography.js

Javascript usage

import Typography from 'typography'

const typography = new Typography({
  baseFontSize: '18px',
  baseLineHeight: 1.45,
  headerFontFamily: ['Avenir Next', 'Helvetica Neue', 'Segoe UI', 'Helvetica', 'Arial', 'sans-serif'],
  bodyFontFamily: ['Georgia', 'serif'],
  // See below for the full list of options.
})

// Output CSS as string.
typography.toString()

// Or insert styles directly into the <head> (works well for client-only
// JS web apps.)
typography.injectStyles()

Themes

We maintain 30 (and counting) themes that are ready to use on your next project. These are each published as separate NPM packages. Explore themes at http://kyleamathews.github.io/typography.js.

Using themes

Here's an example of how to use the Funston theme.

  1. First save the package to your project npm install --save typography-theme-funston
  2. Then import and pass into Typography when initializing.
import Typography from 'typography'
import funstonTheme from 'typography-theme-funston'

const typography = new Typography(funstonTheme)

Customizing themes

Themes are just javascript objects so it's easy to modify them as needed. For example, if you're using the Funston theme but want to increase the base font size slightly:

import Typography from 'typography'
import funstonTheme from 'typography-theme-funston'
funstonTheme.baseFontSize = '22px' // was 20px.

const typography = new Typography(funstonTheme)

Or you can use the imperative API overrideThemeStyles to directly set/override styles on a theme:

import Typography from 'typography'
import funstonTheme from 'typography-theme-funston'
funstonTheme.overrideThemeStyles = ({ rhythm }, options) => ({
  'h2,h3': {
    marginBottom: rhythm(1/2),
    marginTop: rhythm(2),
  }
})

const typography = new Typography(funstonTheme)

Published Typography.js Themes

Plugins

Plugins are functions that extend or modify the core typography engine. they can change how headers are styled or add specialized styles e.g. for code or tables. Currently there's one plugin available, typography-plugin-code.

To use the Code plugin, first install using NPM.

npm install --save typography-plugin-code

Then add to your theme before creating a new typography object.

import Typography from 'typography'
import CodePlugin from 'typography-plugin-code'
import sternGroveTheme from 'typography-theme-stern-grove'

sternGroveTheme.plugins = [
  new CodePlugin(),
]

const typography = new Typography(sternGroveTheme)

React.js helper components.

Typography.js includes two helper components for your React.js projects, TypographyStyle and GoogleFont. These are ideal for server-rendering.

To use, first install the package npm install --save react-typography then import them into your html.js file.

import { TypographyStyle, GoogleFont } from 'react-typography'
// Best practice is to have a typography module
// where you define your theme.
import typography from 'utils/typography'

// Inside your React.js HTML component.
<html>
  <head>
    <TypographyStyle typography={typography} />
    <GoogleFont typography={typography} />
  </head>
  <body>
    // stuff
  </body>
</html>

Using with create-react-app

If you use the default create-react-app template, the above React.js solution will not work, and the typography.injectStyles() solution will not enable Google Fonts.. A workaround is to install typography-inject-fonts and do

import Typography from 'typography'
import funstonTheme from 'typography-theme-funston'
import injectFonts from 'typography-inject-fonts'

const typography = new Typography(funstonTheme)
typography.injectStyles()
injectFonts(typography)

API

Configuration

When creating a new instance of Typography, you can pass in a configuration object. All configuration keys are optional.

overrideStyles: ({ adjustFontSizeTo, rhythm }, options, styles) => ({
  h1: {
    fontFamily: ['Montserrat', 'sans-serif'].join(','),
  },
  blockquote: {
    ...adjustFontSizeTo('19px'),
    color: gray(41),
    fontStyle: 'italic',
    paddingLeft: rhythm(13/16),
    marginLeft: rhythm(-1),
    borderLeft: `${rhythm(3/16)} solid ${gray(10)}`,
  },
  'blockquote > :last-child': {
    marginBottom: 0,
  },
})
overrideThemeStyles: ({ rhythm }, options, styles) => ({
  'h2,h3': {
    marginBottom: rhythm(1/2),
    marginTop: rhythm(2),
  }
})

Related

Developing Typography.js

Typography.js is a monorepo facilitated by Lerna.

TODO: document constants + compass-vertical-rhythm + using typgraphy.js for inline styles.

=======

Backers

Support us with a monthly donation and help us continue our activities. [Become a backer]

Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [Become a sponsor]