Custom theme using Sass for v2 - Documentation is incorrect

[edheltzel]

I kind of feel the v2 docs are a little lacking in creating a custom theme... v1 uses @import which made theming pretty simple, but with v2, the use of @forward and @use isn't ideal if you're pulling pico in as a node_module. OR this is just simply a me issue, so I'm here looking for some help and guidance.

What I'm doing is following the docs and using the Default theme as a reference, I created a copy of the default theme and moved it into my assets/styles/ directory but I keep running into an issue where:

Error: This module was already loaded, so it can't be configured using "with".
    ┌──> node_modules/@picocss/pico/scss/pico.scss
 1  │   @forward "settings";
    │   ^^^^^^^^^^^^^^^^^^^ new load
    ╵
    ┌──> src/assets/styles/themes/autopilot/_styles.scss
 4  │   @use "../../../../../node_modules/@picocss/pico/scss/settings" as *;
    │   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ original load
    ╵
   ┌──> src/assets/styles/_config.scss
8  │ ┌ @use "pico" with (
9  │ │   $css-var-prefix: "--autopilot-",
10 │ │   $enable-semantic-container: true,
11 │ │   $enable-classes: true,
12 │ │   $modules: (
13 │ │     "themes/default": false,
14 │ │   )
15 │ │ );
   │ └─^ configuration
   ╵
 pico.scss 1:1
 src/assets/styles/_config.scss 8:1                   @use
 src/assets/styles/themes/autopilot/_styles.scss 6:1  @use
 src/assets/styles/themes/_autopilot.scss 2:1         @use
 src/assets/styles/app.scss 23:2                      root stylesheet

And if I clear this out by removing the use of @use "../../settings" as *; then I get Undefined variable. for @if map.get($modules, "themes/autopilot") {

I've had to relative path to pico - even with the load Paths option set for Sass, but if I set theme/default": true and remove my custom theme import. it works as expected.

But if anyone else has a solution on creating a custom theme with v2-rc please enlighten me on how you achieved this.

[sysmat]

• I have the same problem, and lack of response from pico, I moved away from v2
• even doc at https://v2.picocss.com/docs/sass#custom-theme is not well documented
• if using https://github.com/picocss/pico/blob/v2/scss/themes as starting point you need to clone repo
• I think v2 customization is totally wrong approach and I think many people will move away from pico v2

[edheltzel]

@sysmat
The v2 documentation is lacking and needs to be updated. @lucaslarroche

I had to re-read the Sass documentation on how to use @use and @forward, but this is what I've done to get Pico working as a node_module with my custom theme.

This is my app.scss:

/**
 * App Style Sheet
 */

@use "pico" with (
  $css-var-prefix: "--autopilot-",
  $enable-semantic-container: true,
  $enable-classes: true,
  $modules: (
    "themes/default": true,
  )
);

// Theme 
@use "themes/autopilot";  // 👈 this must come after 

Then, in my custom theme, themes/autopilot/_autopilot.scss (which is just a copy of the Pico default theme), I update the imports:

// Styles
@use "autopilot/styles";

// Color schemes
@use "autopilot/schemes";

Finally, I updated the _styles.scss, _schemes.scss, _dark.scss, _light.scss by adding @forward: "pico"; and updating the `@use's with the correct paths.

// _styles.scss
@use "sass:map";
@forward "pico"; // 👈 This is needed
@use "settings" as *; 
@use "colors" as *;
@use "utils/functions";
// ... rest of the styles

// _schemes.scss
@use "sass:map";
@forward "pico";  // 👈 This is needed
@use "settings" as *;

@use "light";
@use "dark";
// ... rest of the styles

// _light.scss & _dark.scss
@use "sass:map";
@forward "pico";  // 👈 This is needed

@use "colors" as *;
@use "settings" as *;
@use "utils/box-shadow";
@use "utils/functions";
// ... rest of the styles

[sysmat]

• It is to complicated vs v1

// Import full Pico source code
@use "./node_modules/@picocss/pico/scss/pico.scss" with ($primary-500: #E65A00,
    $primary-600: #C54100,
    $primary-700: #A52D00);

[wbadart]

@edheltzel may I ask what your directory layout and sass command looked like?

[edheltzel]

@wbadart Im using a custom script for sass, looks something like:

const transformScss = (config) => {
  config.addPlugin(scss, [
    {
      sass: {
        style: "expanded",
        sourceMap: false,
        loadPaths: ["node_modules/@picocss/pico/scss", "node_modules/@picocss/pico/scss/themes/default"],
      },
    }
  ]);
};

module.exports = {
  transformScss,
};

my directory structure: ./src/assets/styles/_scss with ./src/assets/styles/app.scss

[wbadart]

gotcha, thanks very much!

[lucaslarroche]

We had to move from @import to @use because @import is now deprecated.
It's a big part of why we had to start a v2 branch, which brings many breaking changes.

I'm also learning here.

I can see at least 2 cases:

1. @use "pico"; for v2.picocss.com

Because picocss/picocss.com has sass --load-path=node_modules/@picocss/pico/scss/
in the package.json file, we only need @use "pico"; to customize pico in the main.scss file.

2. @use "@picocss/pico/scss/pico"; on the react example (see here)

I'll do more testing to understand better how @use works.
If you have any suggestions on how to update the documentation, I'm all ears.
You can also open a PR on picocss/picocss.com.

[edheltzel]

@lucaslarroche
I think the documentation needs to be updated. I'd be happy to test out theming in detail (using SSGs like Jekyl, Eleventy, Hugo), make a PR with a real solution, and update the docs.

But just to be clear, using @forward: "pioc"; in my theme files and including my custom theme after the Pico config worked for my setup allowed me to configure Pico, set new colors, add my own styles, use the mixins, and etc. The only issue was I had to leave the module "themes/default" set to true. Which isn't ideal.

[mboyea]

For anybody consuming the package with NPM in 2025, make sure to import the project explicitly with "@picocss/pico/scss/pico" (not just "pico").

src/routes/+layout.scss

@use "@picocss/pico/scss/pico" with (
  // * https://picocss.com/docs/sass
  // Theme color: amber, azure, blue, cyan, fuchsia, green, grey, indigo, jade, lime, orange, pink, pumpkin, purple, red, sand, slate, violet, yellow, zinc
  $theme-color: "orange",
  // Enable <header>, <main>, <footer> inside $semantic-root-element as containers
  $enable-semantic-container: false,
  // Enable .classes
  // .classless version if disabled
  $enable-classes: true,
  $modules: (
    // Theme
    "themes/default": true,
  ),
);
// custom theme
@use "../lib/styles/theme";

src/lib/styles/_theme.scss

@forward "@picocss/pico/scss/pico"; // ADD THIS IN ALL FILES
// Styles
@use "theme/styles";
// Colors schemes
@use "theme/schemes";

src/lib/styles/theme/_styles.scss

@forward "@picocss/pico/scss/pico"; // ADD THIS IN ALL FILES
@use "sass:map";
@use "@picocss/pico/scss/colors" as *; // UPDATE THIS IN ALL FILES
@use "@picocss/pico/scss/settings" as *; // UPDATE THIS IN ALL FILES
@use "@picocss/pico/scss/helpers/functions"; // UPDATE THIS IN ALL FILES
@use "theme-colors";
// [...]

src/lib/styles/theme/[...]

@forward "@picocss/pico/scss/pico"; // ADD THIS IN ALL FILES
// [...]