@sqymagma/magma-theme v0.1.5

Magma themes

Los themes se utilizan para ajustar y modificar componentes y elementos de la aplicación para que se ajusten a un estilo visual y estructural específico.

Con los themes de Magma se pueden personalizar fácilmente los elementos de un sistema: tipografía, breakpoints, colores, espaciados, etc. cambiando un conjunto de primitives y eliminando así la necesidad de modificar elementos y componentes de forma individual.

Índice

• Términos
• Categorías
  • Magma Primitives
  • Custom Primitives
• Formato y estructura
• Importar un theme
• CSS Global
• Color Role Guide
• Theme Scheme

Theme Scheme

Colors

{
  color: {
    description: String,
    colors: {
      rolName: {
        value: String (Hex),
        opacity: String or Number
      },
      rolName: {
        type: "RGB",
        value: Array (length 3),
        opacity: String or Number
      },
      rolName: {
        type: "HSL",
        value: Array (length 3),
        opacity: String or Number
      },
    }
  }
}

Términos

Categorías

Un theme de Magma tienen dos categorías en sus primitives: Magma primitives y Custom primitives

• magma-primitives.js
• custom-primitives.js

Magma Primitives

Las Magma primitives deben ajustarse al formato y estructura para que puedan ser procesadas correctamente utilizando la función parseTheme() de Magma.

Es posible que algunas entradas dependan de otras. Por ejemplo la entrada textStyles necesita que estén definidas tanto fontFamilies como mediaqueries ya que precisamente lo que textStyes define son los estilos de tipografía dependiendo de los breakpoints.

Las Magma primitives son:

• colors
• fontFamilies
• textStyles
• mediaqueries
• gradients
• shadows

Ejemplo de parseado de parseTheme() en Magma primitives

La entrada:

{
color: {
colors: {
text01: {
value: "#000000",
opacity: "1.0"
}
text02: {
value: "#000000,
opacity: "0.5"
}
}
}
}

```

Obtendrá esta salida:

```

{
colors: {
text01: "#000000",
text02: "rgba(0, 0, 0, 0.5)",
}
}

Custom primitives

Las Custom primitives son simples objetos javascript que no necesitan ser parseadas por parseTheme().

Añadir unas primitives para controlar el timming de nuestras animaciones css es tan fácil como escribir:

export default {
  timmings: {
    s: "0.1s",
    m: "0.5s",
    l: "1.0s"
  }
}

Accederíamos a estas primitives con ${props => props.theme.timming.s}.

Formato y estructura

Antes mencionámos que las Magma primitives tenían un formato y estructura. Ahora veremos en qué consisten.

Color

En la primitiva color construye la paleta de colores del sistema. Lo más importantes son las entradas de colores en formato objeto. Indicando e valor en formato hexadeciamal y la opacidad en un rango de 0 a 1. También podemos especificar el color directamente en formatos HSL o RGB añadiendo además la propiedad opacity.

Si la opacidad del color es 1 podemos omitir por completo la propiedad.

Ejemplos

// Color en formato HEX
export default {
  color: {
    colors: {
      interactive01: { value: "#ffffff" },
      ...
    }
  },

// Color en formato RGB + opacity
export default {
  color: {
    colors: {
      interactive01: {
        type: "RGB",
        value: ["32", "50", "250"],
        opacity: "0.5"
      },
      ...
    }
  },

// Color en formato HSL + Opacity
export default {
  color: {
    colors: {
      interactive01: {
        type: "HSL",
        value: ["0", "50%", "50%"],
        opacity: "0.5"
      },
      ...
    }
  },

Font family

Especifica las familias de tipografías. Están definidos las entradas primary, secondary y monospace. Si existiésen más debemos añadirlas siguiendo la nombenclatura: tertiary, quaternary, etc..

  fontFamily: {
    fontFamilies: {
      primary: "Gilroy",
      secondary: "Work Sans",
      monospace: "Space Mono"
    }
  }

Mediaqueries

Las primitives mediaqueries definen los breakpoints del sistema (utilizando la mentalidad mobile-first), tanto el naming como los tamaños de los breakpoints, mínimo o mínimo y máximo.

El primer breakpoint siempre debe tener el minWidth igualado a null.

export default {
  mediaquery: {
    mediaqueries: [
      {
        label: "default",
        minWidth: null
      },
      {
        label: "s",
        minWidth: "40em"
      },
      {
        label: "m",
        minWidth: "52em"
      },
      {
        label: "l",
        minWidth: "64em"
      }
    ]
  },

Text Styles

Estas primitives definen los estilos de textos responsive

  textStyle: {
    defaultStyles: {
      fontWeight: 400,
      lineHeight: 1.4,
      letterSpacing: "0px",
      fontSize: "10px"
    },
    textStyles: [
      {
        name: "mega",
        fontSize: "60px",
        letterSpacing: "0px",
        responsive: [
          {
            breakpoint: "m",
            fontStyle: "normal",
            fontSize: "80px"
          }
        ]
      }
    ]
  },

  gradient: {
    gradients: {
      gradient01: {
        direction: "to top",
        stops: [
          {
            color: "#443CF3",
            opacity: 1.0,
            position: "0%"
          },
          {
            color: "#425FF7",
            opacity: 1.0,
            position: "100%"
          }
        ]
      }
    }
  },

  shadow: {
    shadows: {
      big: {
        x: 0,
        y: 25,
        blur: 128,
        color: "#000000",
        opacity: 0.4
      }
    }
  }
}

Magma no provee ningún theme por defecto.

Importar un theme

Para utilizar un theme como mínimo debemos importar la función parseTheme() y un theme tanto con las primitives base como con las custom primitives (opcionales)

Podemos juntar en un solo archivo las primitives base y las custom para facilitar la importación

Podemos crear los archivos de un theme desde cero o utilizando magma-cli, lo que nos permite crear unos archivos que sirven de boilerplate: magma-cli newtheme default

import React from "react"
import { ThemeProvider } from "styled-component"
import { parseTheme } from "@secuoyas/magma-theme"
import theme from "./themes/default"
import customPrimitives from "./themes/default/custom.js"

const defaultTheme = {
  ...parseTheme(theme),
  ...customPrimitives
}

const App = () => (
  <ThemeProvider theme={defaultTheme}>
    <p>Hi Magma Theme</p>
  </ThemeProvider>
)

export default App

CSS Global

Probablemente queramos unos estilos globales para toda la aplicación. Como el font-family, resets, normalize, etc..

styled-components nos provee de una función para ello: createGlobalStyle que además de añadir estilos globales nos permite temificarlos con ThemeProvider. createGlobalStyle nos crea un componente de React el cual utilizaremos dentro de nuestro component-tree para aplicar el estilo global. Lo normal es que utilizemos este componente en el raíz de nuestra aplicación.

import React from "react"
import { ThemeProvider, createGlobalStyle } from "styled-component"
import { parseTheme } from "@secuoyas/magma-theme"
import theme from "./themes/default"
import customPrimitives from "./themes/default/custom.js"

const GlobalStyle = createGlobalStyle`
  body {
    font-family: "Gilroy";
    background-color = ${props => props.theme.colors.uiBackground};
  }
`

const defaultTheme = {
  ...parseTheme(theme),
  ...customPrimitives
}

const App = () => (
  <ThemeProvider theme={defaultTheme}>
    <React.Fragment>
      <GlobalStyle />
      <p>Hi Magma Theme</p>
    </React.Fragment>
  </ThemeProvider>
)

export default App

Color role guide