From 9b08a7315651c7c64df713517dc6ac820bdb9e08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Javi=20Mart=C3=ADn?= Date: Fri, 30 Aug 2024 17:31:35 +0200 Subject: [PATCH] Update documentation for CSS customization --- docs/en/customization/css.md | 57 ++++++++++++++++++++++++++++-------- docs/es/customization/css.md | 57 ++++++++++++++++++++++++++++-------- 2 files changed, 88 insertions(+), 26 deletions(-) diff --git a/docs/en/customization/css.md b/docs/en/customization/css.md index 3d923da9a..c6c90d23b 100644 --- a/docs/en/customization/css.md +++ b/docs/en/customization/css.md @@ -1,27 +1,58 @@ -# Styles with CSS +# Customizing styles with CSS -In order to make changes to any CSS selector (custom style sheets), you can add them directly at `app/assets/stylesheets/custom.scss`. For example to change the header color (`.top-links`) you can just add: +Consul Democracy uses stylesheets written using [Sass](http://sass-lang.com/guide) with the SCSS syntax and placed under the `app/assets/stylesheets/` folder. -```css -.top-links { - background: red; +In order to make changes to styles, you can add them directly to a file under `app/assets/stylesheets/custom/`. Alternatively, you can use the `app/assets/stylesheets/custom.scss` file. + +For example, to change the margin of the footer, create an `app/assets/stylesheets/custom/layout.scss` file with the following content: + +```scss +.footer { + margin-top: $line-height; } ``` -If you want to change any [foundation](http://foundation.zurb.com/) variable, you can do it at the `app/assets/stylesheets/_custom_settings.scss` file. For example to change the main application color just add: +This will overwrite the `margin-top` property applied to the `.footer` selector. -```css -$brand: #446336; +Note that CSS precedence rules still apply, so if there's a rule defining the `margin-top` property for the `body .footer` selector, the code above will be ignored. So, to effectively overwrite properties for certain elements, use the exact same selector used in the original code. + +## Sass variables + +Consul Democracy uses variables and functions defined by the [Foundation framework](http://foundation.zurb.com/) and adds a few other variables. In order to overwrite these variables, use the `app/assets/stylesheets/_consul_custom_overrides.scss` file. For example, to change the background color of the footer, add: + +```scss +$footer: #fdfdfd; ``` -We use [SASS, with SCSS syntax](http://sass-lang.com/guide) as CSS preprocessor. +The variables you can override are defined in the `_settings.scss` and `_consul_settings.scss` files. -Also you can check your scss files syntax with +To define new variables, you can use the `app/assets/stylesheets/_custom_settings.scss` file. -```bash -scss-lint +## CSS variables + +In multi-tenant applications, Sass variables have a limitation: their value will be the same for every tenant. + +So, for the most commonly customized colors, Consul Democracy provides CSS variables, which allow you to define different colors for different tenants. + +For example, you can customize the brand, buttons, links and main layout colors for just the main tenant with: + +```scss +.tenant-public { + --anchor-color: #372; + --anchor-color-hover: #137; + --brand: #153; + --brand-secondary: #134a00; + --button-background-hover: #fa0; + --button-background-hover-contrast: #{$black}; + --footer: #e6e6e6; + --main-header: #351; + --top-links: var(--main-header); + --subnavigation: #ffd; +} ``` +Check the `app/assets/stylesheets/custom/tenants.scss` file for more information. + ## Accessibility -To maintain accessibility level, if you add new colors use a [Color contrast checker](http://webaim.org/resources/contrastchecker/) (WCAG AA is mandatory, WCAG AAA is recommended). +To maintain an appropriate accessibility level, if you add new colors, use a [Color contrast checker](http://webaim.org/resources/contrastchecker/) (WCAG AA is mandatory, WCAG AAA is recommended). diff --git a/docs/es/customization/css.md b/docs/es/customization/css.md index 95fc1739f..3641cd317 100644 --- a/docs/es/customization/css.md +++ b/docs/es/customization/css.md @@ -1,27 +1,58 @@ -# Estilos con CSS +# Personalización de estilos con CSS -Si quieres cambiar algun selector CSS (de las hojas de estilo) puedes hacerlo en el fichero `app/assets/stylesheets/custom.scss`. Por ejemplo si quieres cambiar el color del header (`.top-links`) puedes hacerlo agregando: +Consul Democracy usa hojas de estilo escritas utilizando [Sass](http://sass-lang.com/guide) con la sintaxis SCSS y ubicadas en el directorio `app/assets/stylesheets/`. -```css -.top-links { - background: red; +Para cambiar estilos, puedes añadirlos directamente en algún fichero bajo `app/assets/stylesheets/custom/`. Como alternativa, puedes usar el fichero `app/assets/stylesheets/custom.scss`. + +Por ejemplo, para cambiar el margen del pie de página, crear el archivo `app/assets/stylesheets/custom/layout.scss` con el siguiente contenido: + +```scss +.footer { + margin-top: $line-height; } ``` -Si quieres cambiar alguna variable de [foundation](http://foundation.zurb.com/) puedes hacerlo en el fichero `app/assets/stylesheets/_custom_settings.scss`. Por ejemplo para cambiar el color general de la aplicación puedes hacerlo agregando: +Esto sobrescribirá la propiedad `margin-top` del selector `.footer`. -```css -$brand: #446336; +Las reglas de precedencia de CSS siguen aplicándose en ese caso, con lo que si hay una regla definiendo la propiedad `margin-top` para el selector `body .footer`, el código anterior será ignorado. Por lo tanto, para sobrescribir propiedades de ciertos elementos de forma adecuada, usa exactamente el mismo selector utilizado en el código original. + +## Variables de Sass + +Consul Democracy utiliza variables y funciones definidas en el [framework Foundation](http://foundation.zurb.com/) y añade algunas variables más. Para sobrescribir estas variables, usa el archivo `app/assets/stylesheets/_consul_custom_overrides.scss`. Por ejemplo, para cambiar el color de fondo del pie de página, añade: + +```scss +$footer: #fdfdfd; ``` -Usamos un preprocesador de CSS, [SASS, con la sintaxis SCSS](http://sass-lang.com/guide). +Las variables que puedes sobrescribir están definidas en los ficheros `_settings.scss` y `_consul_settings.scss`. -Además puedes comprobar la sintaxis de tus ficheros scss con: +Para definir nuevas variables, puedes usar el fichero `app/assets/stylesheets/_custom_settings.scss`. -```bash -scss-lint +## Variables de CSS + +En aplicaciones multientidad, las variables de Sass tienen una limitación: su valor será el mismo para todas las entidades. + +Debido a esto, para los colores más frecuentemente personalizados, Consul Democracy proporciona variables de CSS, con las que puedes definir diferentes colores para diferentes entidades. + +Por ejemplo, puedes personalizar los colores de los principales elementos de la aplicación así como de enlaces y botones con: + +```scss +.tenant-public { + --anchor-color: #372; + --anchor-color-hover: #137; + --brand: #153; + --brand-secondary: #134a00; + --button-background-hover: #fa0; + --button-background-hover-contrast: #{$black}; + --footer: #e6e6e6; + --main-header: #351; + --top-links: var(--main-header); + --subnavigation: #ffd; +} ``` +Echa un vistazo al archivo `app/assets/stylesheets/custom/tenants.scss` para más información. + ## Accesibilidad -Para mantener el nivel de accesibilidad, si añades colores nuevos utiliza un [Comprobador de contraste de color](http://webaim.org/resources/contrastchecker/) (WCAG AA es obligatorio, WCAG AAA es recomendable) +Para mantener el nivel de accesibilidad, si añades colores nuevos, utiliza un [comprobador de contraste de color](http://webaim.org/resources/contrastchecker/) (WCAG AA es obligatorio, WCAG AAA es recomendable).