@sqymagma/magma-theme

v0.1.5

Published

2 years ago

Magma components

Downloads

0High
0Medium
0Low

mariantonia

react styled-components components

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

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

| Termino | Definición | Ejemplo | | ---------- | -------------------------------------------------------------------------------------- | ------------------ | | Theme | Un set único de primitives con un valor específico | Default | | Primitives | El código identificador de un rol. Son universales y no pueden cambiar en cada theme | interactive01 | | Roles | El rol para el uso del primitive. Los roles pueden cambiar por cada theme | Fondo para botones |

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

| Primitive | Role | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | interactive01 | Color primario de interacción.Color para botones primarios. | | interactive02 | Color secundario de interacción.Color para botones secundarios. | | interactive03 | Color de contraste 4.5:1 de interacción.Color para botones terciarios. | | interactive04 | Color de contraste 3:1 de interacción.Elementos seleccionados.Elementos activos.Color para iconos acentuados. | | text01 | Color de texto primario.Cuerpo de texto.Encabezados. | | text02 | Color de texto secundario.Etiquetas de formularios.Texto de ayuda. | | text03 | Color de texto terciario. | | text04 | Color de texto placeholder. | | textOnInteractive01 | Texto en interactivos 01 | | textOnInteractive02 | Texto en interactivos 02 | | textOnInteractive03 | Texto en interactivos 03 | | textOnInteractive04 | Texto en interactivos 04 | | ui-background | Color de fondo por defecto para página. | | ui01 | Color de fondo primario para contenedoresColor de fondo secundario para página. | | ui02 | Color de fondo secundario para contenedoresColor de fondo primario para página (probablemente igual que ui-background). | | ui03 | Borde sutil.Color de fondo terciario. | | ui04 | Borde contraste medio.Elemento de contraste 3:1. | | ui05 | Borde alto contraste.Elemento de contraste 4.5:1.Elementos enfatizados | | link01 | Color para link principal | | link02 | Color para link secundario | | link03 | Color para link terciario | | support01 | Error | | support02 | Warning | | support03 | Information | | support04 | Sucess | | field01 | Color de fondo para inputs. | | field02 | Color de fondo para inputs que estén sobre ui02. | | inverse01 | Color inverso para textos.Color inverso para iconos. | | inverse02 | Color de fondo alto contraste.Elementos de alto contraste. | | disabled01 | Campos desactivados.Fondos desactivados (botones..)Bordes desactivados. | | disabled02 | Elementos desactivados en disabled01.Etiquetas desactivadasTexto desactivado en disabled01.Iconos desactivados. | | --- | --- | | interactive01Hover | Hover para interactive01 | | interactive02Hover | Hover para interactive02 | | interactive03Hover | Hover para interactive03 | | interactive01Active | Active para interactive01 | | interactive02Active | Active para interactive02 | | interactive03Active | Active para interactive03 | | interactive01Focus | Focus para interactive01 | | interactive02Focus | Focus para interactive02 | | interactive03Focus | Focus para interactive03 | | link01Hover | Color para Hover link principal | | link02Hover | Color para Hover link secundario | | link03Hover | Color para Hover link terciario | | link01Active | Color para Active link principal | | link02Active | Color para Active link secundario | | link03Active | Color para Active link terciario |