Template Customization

You should now have a basic understanding of what Astro and Alpine.js are doing. You are now ready to setup the project to start developing. We've been talking about Astro for ages but you'll quickly see how fast it is to setup your project. In your terminal window, change directory to the root of the project:

cd path/to/my/project/

Then start by running the project. Run the following command. It will also launch a development server in your browser window :

pnpm dev

When the dev server starts, you can click the link that just popped in your terminal to open your browser. That's it, your project is now running. Every change you make to the .astro or .scss files will trigger a code compilation and a browser refresh. Really easy isn't it?

Native Dark Mode

Houseo comes with a native Dark mode. This means that everything is pre-styled for dark mode. You don't have to worry about it, when you turn it on, the colors change seamlessly. Dark mode styling is made through a global .is-dark class added to the page body element. Dark mode is toggled on the body with javascript. In another type of implementation, the body would have to be rendered by the server with the proper class before being served to the client, based on the user selection.

Color system

While everyone is familiar with traditional Sass variables like $color, we chose to drop this format to take advantage of the power of native CSS-vars. To support this, we had to make several major changes in the way we handle the compilation of the different color palettes.

The main Bulma framework is built with traditional Sass variables and does not support CSS-vars. We had to find a solution for this. Therefore, we decided to enhance our existing Bulma package with this Bulma plugin: https://github.com/wtho/bulma-css-vars. This plugin fully supports CSS-vars and patches the initial Bulma code base, making possible this implementation.

There are 2 specific SCSS sub-folders that handle this in /src/styles: styles/bulma-generated/ and styles/css-variables. The first one is automatically rendered by a Node.js utility and is in charge of generating all the Bulma variables, based on your configuration. The second one holds all other CSS variables that are used throughout the template.

Changing the main color

If you need to change the Houseo main color, you need to go through a short compilation step. The main color is generated from an HSL format. This means that you will need to define your Houseo primary color in HSL format for it to work. Here are the different steps you need to go through:

• Choose a primary color for your project. It can be in hex or rgb format, it doesn't matter. Let's go for the example with a purple color like #6621cf.
• In any colorpicker of your choice, transform your color into an HSL color with a value for each attribute, Hue, Saturation and Luminance. In our case this would result in 264°, 73%, 47%.
• Open bulma-css-vars.config.js. In that file replace the values of the primary: hsl(x, x, x) block with the values you got one step earlier. You can also change the default values of some basic Bulma variables like dark, link, info etc...
• You also need to change the value of the primary variable inside /src/styles/css-variables/_colors.scss to complete the color setup.
• You can even define a different color for primary inside /src/styles/css-variables/_colors-dark.scss to handle how the colors render in dark mode.
• Once you're done with that, you're ready to run a utility to generate all your colors.
• In your terminal, run the pnpm build:update-bulma-colors.
• Tada! You are now done and all your new colors have been generated for you.

CSS vars syntax

CSS variables use a different syntax than Sass variables. Declaring a new CSS variable is like this:

Declaration

// :root is an alias for html element but with higher priority
:root {
  --myVariable: #fff;
}

// Change how this variable behaves in dark mode
.is-dark {
  --myVariable: #000;
}

// we can override the variable value inside a class scope
.my-red-variable {
  --myVariable: red;
}

<!-- we can also override the variable value inside a style scope -->
<span style="--myVariable: blue">
  <!-- ... -->
</span>

Usage

.my-variable-color {
  color: var(--myVariable);
}

Custom CSS Helpers

Reference the helper SCSS files to learn more about all the available custom helpers, "custom helpers" meaning they are not included in the default Bulma distribution. Please note that the Bulma spacing helpers have been removed and replaced by our own. You can explore src/styles/utilities/utilities.scss and src/styles/abstracts/helpers.scss to get a grasp on available helpers.