Skip to content

Improved custom theme instructions #558

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nonprofittechy merged 2 commits into from
Sep 18, 2025
Merged

Improved custom theme instructions #558

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f35d167
Improved custom theme instructions; removed obsolete guidance on boot…
nonprofittechy Sep 18, 2025
2697e6d
Fix typo
nonprofittechy Sep 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 75 additions & 82 deletions docs/components/ALThemeTemplate/althemetemplate_overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
id: althemetemplate_overview
title: |
ALThemeTemplate: Applying a Custom Theme or Brand
sidebar_label: ALThemeTemplate
Customizing look and feel
sidebar_label: Customizing look and feel
slug: overview
---

Expand All @@ -11,27 +11,67 @@ slug: overview
The [ALThemeTemplate](https://github.com/SuffolkLITLab/docassemble-ALThemeTemplate)
repository is a template for a "brand" package that you can use for your own organization.

You can use this as the starting point for your own customizations, or decide which of the customizations
below you want to implement for your organization.

## Visual customization

You can customize Docassemble, and Assembly Line interviews, with a Bootstrap 5 theme.

### Customizing the logo and title for Assembly Line interviews

You should also customize the:

* [Title](../AssemblyLine/magic_variables.md#al_organization_title)
* [Home page](../AssemblyLine/magic_variables.md#al_organization_homepage)
* and [logo](../AssemblyLine/magic_variables.md#al_logo)

### Creating a custom CSS theme with Bootstrap.build
### Creating a custom theme

If you want to build a custom theme, encompassing colors, fonts, button styles and other
options that are configurable with css, you can:
options that are configurable with css, you can create a custom Bootstrap theme.

To use a custom theme with Docassemble, you:

1. Create a .scss file with your customized variables.

* If you only want to customize colors, use [Huemint](https://huemint.com/bootstrap-basic/).
* For more complex customization, including fonts and button shape, use [bootstrap.build](https://bootstrap.build/).

2. Compile the theme using a tool like the ALDashboard.

#### Use Huemint to make a .scss file that customizes colors only

Visit [Huemint](https://huemint.com/bootstrap-basic/). Create a color pallette that you like.

Scroll to the bottom of the page and copy the SCSS code that looks like this:

```scss
$white: #ffffff;

$theme-colors: (
"light": #cfd6d1,
"dark": #090807,
"primary": #760076,
"secondary": #f92e42,
"info": #9e8412,
"success": #00a167,
"warning": #d9cd00,
"danger": #e63300,
);
```

#### Or use Bootstrap.build to customize fonts, buttons, and more

To customize other elements of the theme, including fonts and button shapes,
you need a more full-featured build tool. [bootstrap.build](https://bootstrap.build/) can customize
every Bootstrap option.

1. build one from Bootstrap 5 source
1. start with a theme generator tool like [bootstrap.build](https://bootstrap.build/)
and in some cases, add some custom CSS to make it work with Docassemble.
:::warning Bootstrap.build cannot compile a working theme for you

Using bootstrap.build is the simplest option for most authors.
It is important that you only use Bootstrap.build to make a _SCSS_ file. Do not download
a bootstrap.css file from this site.
:::

1. Visit the [bootstrap.build](https://bootstrap.build/) website.
1. Click the button to open the Builder
Expand All @@ -42,94 +82,50 @@ Using bootstrap.build is the simplest option for most authors.
* Under Typography, customize any fonts that you wish to use
* Under forms, you may want to customize button size and rounded edges
1. Click the "export theme" button (it may be hidden behind a banner at the top of the page) and choose the
"bootstrap.min.css" option. Rename this theme to be more specific. Optionally, download the `_variables.scss` file
so that you can easily load and adjust your settings in future.
"`_variables.scss`" option.

Next, you will need to make a small adjustment to the theme generated by bootstrap.build.
Copy and paste the code below into the `bootstrap.min.css` file (or your new file name).
#### Compile your theme using the ALDashboard tool

```css
.visually-hidden {
clip: rect(0 0 0 0);
clip-path: inset(50%);
height: 1px;
overflow: hidden;
position: absolute;
white-space: nowrap;
width: 1px;
}

.bg-dark {
background-color: #1a73e8!important; /* replace with your desired nav bar color */
}
```

Add this theme to your Docassemble playground using the Folders | Static menu.
Inside the AssemblyLine's [ALDashboard](https://github.com/SuffolkLITLab/docassemble-ALDashboard) tool,
visit the Compile Bootstrap Theme widget.

You can then reference your new file by adding a bootstrap theme feature to your interview:

```yaml
features:
bootstrap theme: bootstrap.min.css
```
The link should be /start/ALDashboard/compile_bootstrap on your server. If you are associated with the Suffolk LIT Lab and have an account on
the Suffolk Development server, you can visit a [live version of the tool](https://apps-dev.suffolklitlab.org/start/ALDashboard/compile_bootstrap)
to try it out.

### Creating a custom theme from source instead of with a theme generator
Click continue to acknowledge the minimum system version of your Docassemble server.

While the above instructions to use bootstrap.build can work well in most
circumstances, you may run into small interface bugs introduced by the theme
generator. If you prefer more control over building the theme, you can create
a custom theme from the bootstrap source code. The Bootstrap documentation
[covers the details of theming](https://getbootstrap.com/docs/5.1/customize/overview)
if you want to take this approach.
Either copy and paste the snippet you copied from Huemint.com, or open the `_variables.scss` file you exported
from Bootstrap.build and copy and paste its contents. The `_variables.scss` file is a simple text file
that can be opened in any editor.

Create a new `custom.scss` file anywhere on your computer to contain the SASS/CSS styles for your branding.
Detailed instructions on what this file can contain are in the [Bootstrap
documentation](https://getbootstrap.com/docs/5.1/customize/sass/#importing).
**Add the `@import "bootstrap";` line to the end of the Dashboard text entry field.** This is required
for your theme to compile.

You can use a [color theme generator](https://huemint.com/bootstrap-basic/) like
[Huemint.com](https://huemint.com/bootstrap-basic/) to make sure that you have a
consistent set of all 9 Bootstrap variables. When you use the color theme
generator, at the bottom of the page, you will see a small snippet of code that
you can copy into the `customs.scss` file.
If you changed the `$primary` color (from the default blue), it usually also makes sense to directly set the
value of `$blue` to the same value you chose for `$primary`. (Docassemble uses `$blue` for the section navigation,
and it usually looks better if it is the same color as the next/continue button).

For example, your new `custom.scss` might look like this:
Here is an example of working contents for a custom theme in the Dashboard window:

```scss
// Custom.scss
// Option A: Include all of Bootstrap

// Include any default variable overrides here (though functions won't be available)

$white: #ffffff;
$blue: #760076;

$theme-colors: (
"light": #d8e2a5,
"dark": #1b1b1b,
"primary": #25dec6,
"secondary": #375b5a,
"info": #d74d72,
"success": #0cb545,
"warning": #f4ca0b,
"danger": #fa043c,
"light": #cfd6d1,
"dark": #090807,
"primary": #760076,
"secondary": #f92e42,
"info": #9e8412,
"success": #00a167,
"warning": #d9cd00,
"danger": #e63300,
);

// Note: we placed our custom.scss file in the bootstrap path for simplicity,
// so we use a different path than in the bootstrap documentation
// @import "../node_modules/bootstrap/scss/bootstrap";
@import "bootstrap";

// Then add additional custom code here
```

Once you have written your `custom.scss` file, you can use the
[ALDashboard](https://github.com/SuffolkLITLab/docassemble-ALDashboard) (which you can [install on
your docassemble server](../../get_started/installation.md#install-aldashboard))
to compile a custom Bootstrap theme. If you are associated with the Suffolk LIT Lab and have an account on
the Suffolk Development server, you can visit a [live version of the tool](https://apps-dev.suffolklitlab.org/start/ALDashboard/compile_bootstrap)
to try it out.

At the end of the tool, you can view what all of the different bootstrap components will look like with your theme.
If you want to change any of the colors, you can go back and edit your "custom.scss" file and regenerate the bootstrap theme.
The ALDashboard widget will let you see a preview of your theme so you can see what it will look like in Docassemble.

![A screenshot that says "Your file is compiled! You can view and copy your file, or download it directly by right clicking the link to save it as a CSS file". Below are examples of Bootstrap components like buttons and nav bars.](../../assets/dashboard-bootstrap-example.png)

Expand Down Expand Up @@ -211,15 +207,13 @@ features:

The favicon will be updated whenever a new page loads in your interview, overriding the server's default favicon for that specific interview only.


### Using dark mode

Docassemble by default will show an alternate "dark mode" version of your interview to
users who request it, usually with a browser or OS setting. You can set your browser
or OS to use dark mode by following [these instructions](https://support.google.com/chrome/answer/9275525?hl=en&co=GENIE.Platform%3DDesktop#zippy=) to see what your interview looks like.



### Using custom fonts in the frontend

You can use custom webfonts with Docassemble, just like you can with any other web
Expand Down Expand Up @@ -267,7 +261,6 @@ Make sure that you have a license for each font you want to install.
The first step is to locate the .otf or .ttf file representing the font that you want to use
inside your Word template (note that these are often in c:\windows\fonts\)


#### Use the ALDashboard to install the font

The [ALDashboard](https://github.com/suffolklitlab/docassemble-ALDashboard) tool has a
Expand Down