[Bug]: Invalid class names for variable fonts with weight property (next/font/local)

[Chiman2937]

Describe the bug

Problem

When using next/font/local with the weight property for variable fonts, Storybook generates invalid CSS class names containing spaces:

<style id="classnames-font-e25342">
  .font-e25342-45 920 {  /* ❌ Invalid: contains space */
    font-family: font-e25342;
    font-weight: 45 920; {  /* ❌ Invalid: contains space */
  }
  .__variable_font-e25342-45 920 {  /* ❌ Invalid: contains space */
    --font-primary: 'font-e25342';
  }
</style>

These invalid class names prevent the font from being applied.

Workaround

Removing the weight property fixes the issue:

export const primary = localFont({
  src: '../assets/fonts/PretendardVariable.woff2',
  variable: '--font-primary',
  display: 'swap',
  // weight: '45 920'  // ❌ Removed to make it work
});

This allows the font to load correctly in Storybook, but it's not ideal because:

• WebKit-based browsers may render incorrect font weights
• The variable font weight range information is lost
• The Next.js documentation specifies that variable fonts use weight as a string range (e.g., '100 900')

The same configuration with weight property works correctly in Next.js production builds

Questions

Is there a valid solution other than removing the weight property?

Reproduction link

N/A

Reproduction steps

1. Create a local font with weight property for variable font:

import localFont from 'next/font/local';

export const primary = localFont({
  src: '../assets/fonts/PretendardVariable.woff2',
  variable: '--font-primary',
  display: 'swap',
  weight: '45 920'  // Variable font weight range
});

2. Apply the font in Storybook preview.tsx(for test)

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
  decorators: (Story) => (
    <div className={primary.className}>
      <Story />
    </div>
  ),
};

3. Inspect the generated CSS in browser DevTools

<style id="font-face-font-e25342">
  @font-face {
    font-family: font-e25342;
    src: url(./src/assets/fonts/PretendardVariable.woff2);
  }
</style>

<style id="classnames-font-e25342">
  .font-e25342-45 920 {  /* ❌ Invalid: contains space */
    font-family: font-e25342;
    font-weight: 45 920;
  }
  .__variable_font-e25342-45 920 {  /* ❌ Invalid: contains space */
    --font-primary: 'font-e25342';
  }
</style>

Please let me know if you need any additional information.

System

Storybook Environment Info:

  System:
    OS: Windows 11 10.0.26100
    CPU: (12) x64 12th Gen Intel(R) Core(TM) i5-12400F
  Binaries:
    Node: 22.14.0 - C:\Program Files\nodejs\node.EXE
    npm: 10.9.2 - C:\Program Files\nodejs\npm.CMD <----- active
  Browsers:
    Edge: Chromium (140.0.3485.54)
  npmPackages:
    @storybook/addon-a11y: ^10.0.5 => 10.0.5
    @storybook/addon-docs: ^10.0.5 => 10.0.5
    @storybook/nextjs: ^10.0.5 => 10.0.5
    eslint-plugin-storybook: ^10.0.5 => 10.0.5
    storybook: ^10.0.5 => 10.0.6

Additional context

No response

[dosubot]

Hi @Chiman2937! I'm Dosu and I’m helping the storybook team.

Storybook currently generates font class names by concatenating the weight string as-is, so spaces in the weight (like '45 920') result in invalid CSS selectors and break font application source.

There’s no official workaround or config to sanitize the weight string in Storybook. The only reliable options right now are:

• Use a single weight value (e.g. '400') or omit the weight property for local fonts.
• If you need a variable font range, you can try replacing spaces with a dash (e.g. '45-920'), but this is not semantically correct for CSS and may not work as intended for variable fonts.
• For full variable font support, consider loading your font via a custom CSS file or in .storybook/preview-head.html and applying the font-family and font-weight via global styles or CSS variables, instead of relying on the generated className source.

If you need to preserve the variable font weight range, the best workaround is to manage the font loading and CSS outside of the Storybook font loader, and apply the font using standard CSS selectors.

Let me know if you need an example of the CSS workaround or want help with a custom setup.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[Chiman2937]

@dosu

Regarding the workaround you suggested:

While defining fonts separately for Storybook (via custom CSS or preview-head.html) would work, I don't think this is an ideal approach because:

• It requires maintaining duplicate font configurations (one for Next.js, one for Storybook)
• It creates inconsistency between the production app and Storybook

Suggestion:

I've reviewed the Storybook documentation regarding Next.js font support limitations, but I don't see my specific case mentioned there. The unsupported features listed are:

• Font loaders configuration in next.config.js
• fallback, adjustFontFallback, preload, and display options

However, the weight property for variable fonts is not listed as unsupported.

If variable font weight ranges (e.g., '45 920') are intentionally not supported, this should be explicitly documented in the limitations section.
Alternatively, if this is a bug, the class name generation should be fixed to handle spaces in the weight value (perhaps by replacing spaces with hyphens or underscores).

Please let me know if I missed anything in the documentation. I'd be happy to contribute if my suggestions would be helpful.

[dosubot]

You didn't miss anything in the documentation—there's no mention of variable font weight ranges or the weight property being unsupported in Storybook's Next.js integration, and no guidance on handling spaces in weight values for class names. This isn't an intentional limitation; it's a bug in how Storybook generates class names from the weight property, which leads to invalid CSS when the value contains spaces (like '45 920') see code reference.

No recent PRs or discussions address this, and the only workarounds are the ones you already found—none ideal, as they require duplicating font config and break consistency see docs.

Your suggestion to either document this as a limitation or fix the class name generation (by sanitizing the weight value) is spot on. If you're interested in contributing, maintainers would likely welcome a PR for either a documentation update or a code fix. If you want, I can help outline what a code or docs change might look like. Let me know how you'd like to proceed.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[Chiman2937]

@dosu

Suggestion

Code Fix

Sanitize the weight value in the getClassName() function to replace spaces with hyphens:

function getClassName({ styles, weights, fontFamily }: Options) {
  const font = fontFamily.replaceAll(' ', '-').toLowerCase();
  const weight = isNextCSSPropertyValid(weights) ? weights[0] : null;
  
  // ❌ Bug: weight contains '45 920', creating invalid class name
  return `${font}${weight ? `-${weight}` : ''}`;
}

Suggested fix:

const weight = isNextCSSPropertyValid(weights) 
  ? weights[0]?.replaceAll(' ', '-')  // ✅ Sanitize spaces
  : null;

This would generate valid class names like font-e25342-45-920 instead of font-e25342-45 920.

[dosubot]

Your suggested fix—replacing spaces with hyphens in the weight value when generating class names—is a solid solution and aligns with best practices for CSS selector validity. The current implementation only sanitizes the font family, so adding this for weight will resolve the bug with variable font ranges in Storybook's Next.js integration see code reference.

No other properties besides weight and style are currently used in class name generation, but if style could ever contain spaces, it would also need similar handling. For maintainability, you might consider a general sanitization utility for all class name components.

There are no known side effects for font loading or matching in Storybook or Next.js from this change, since the weight value in the class name is only for selector construction—actual font-weight in CSS remains unchanged.

If you decide to contribute, updating the code as you suggested would be a straightforward and helpful fix.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[Chiman2937]

@dosu

I'd like to contribute to fixing this issue. Is there anything else I should do, or should I just wait for a maintainer's response?

[dosubot]

You can go ahead and submit a pull request with your proposed fix—there’s no requirement to wait for a maintainer’s response or to open an issue first for this type of bug fix. Just reference the problem clearly in your PR description and follow the usual contribution guidelines: write clear commit messages, add tests if relevant, and keep your changes focused on the bug. Storybook welcomes code contributions for bug fixes and features, and you can find more details in their contribution docs.

If you want feedback or to discuss your approach before submitting, you can also chat in the Discord #contributing channel.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[Chiman2937]

@dosu

I analyzed the Storybook source code and identified the following issues.
I originally specified the weight property at the top level of the localFont object:

export const primary = localFont({
  src: '../assets/fonts/PretendardVariable.woff2',
  variable: '--font-primary',
  display: 'swap',
  weight: '45 920',
});

However, in the source code, weight is only added to the font-face when the src property is an array:

//code\frameworks\nextjs\src\font\webpack\loader\utils\get-css-meta.ts
const getFontFaceCSS = () => {
    if (typeof localFontSrc === 'string') {
      const localFontPath = join(parentFolder, localFontSrc).replaceAll('\\', '/');

      return `@font-face {
          font-family: ${id};
          src: url(.${localFontPath});
          ${fontDeclarations}
      }`;
    }
    return localFontSrc
      .map((font) => {
        const localFontPath = join(parentFolder, font.path).replaceAll('\\', '/');
        // console.log(`font weight: ${font.weight}`);
        return `@font-face {
          font-family: ${id};
          src: url(.${localFontPath});
          ${font.weight ? `font-weight: ${font.weight};` : ''}
          ${font.style ? `font-style: ${font.style};` : ''}
          ${fontDeclarations}
        }`;
      })
      .join('');
  };

Therefore, I found that declaring the local font as follows resolves the issue:

export const primary = localFont({
  src: [{ path: '../assets/fonts/PretendardVariable.woff2', weight: '45 920' }],
  variable: '--font-primary',
  display: 'swap',
});

While this workaround solves the problem, it differs from Next.js behavior and needs improvement.

First suggestion: Add weight to font-face even when src is a string

//code\frameworks\nextjs\src\font\webpack\loader\utils\get-css-meta.ts
const getFontFaceCSS = () => {
    if (typeof localFontSrc === 'string') {
      const localFontPath = join(parentFolder, localFontSrc).replaceAll('\\', '/');
      return `@font-face {
          font-family: ${id};
          src: url(.${localFontPath});
          ${weight ? `font-weight: ${weight};` : ''}
          ${style ? `font-style: ${style};` : ''}
          ${fontDeclarations}
      }`;
    }

This allows weight to be properly registered in the font-face even when specified at the top level of the localFont object.

Second suggestion: Modify classNamesCSS as follows

Looking at the classNamesCSS in the getCSSMeta function, it always specifies the font-weight property when weights exist. However, if weight is set to '45 920', this becomes an invalid CSS property. Variable font weight ranges are only valid inside @font-face declarations. When applied to actual elements, a specific single value within that range must be used.
Therefore, modifying classNamesCSS as follows will add weight to className only when it's a static weight value:

const classNamesCSS = `
    .${className} {
      font-family: ${options.fontFamily};
      ${isNextCSSPropertyValid(options.styles) ? `font-style: ${options.styles[0]};` : ''}
      ${isNextCSSPropertyValid(options.weights) && !options.weights[0]?.includes(' ')
        ? `font-weight: ${options.weights[0]};` 
        : ''}
    }

    ${
      options.variable
        ? `.${variableClassName} { ${options.variable}: '${options.fontFamily}'; }`
        : ''
    }
  `;

By examining the module CSS files generated by next/font/local in a Next.js app, we can see this matches the actual behavior.

Next.js app Test

1. Setting variable weight at the top level of localFont object

export const primary = localFont({
  src: '../assets/fonts/PretendardVariable.woff2',
  variable: '--font-primary',
  display: 'swap',
  weight: '45 920',
});

Result: The following CSS file is generated:

//primary_29573dc5.module.css
@font-face {
    
    font-family: 'primary';
    src: url('@vercel/turbopack-next/internal/font/local/font?{%22path%22:%22../assets/fonts/PretendardVariable.woff2%22,%22preload%22:true,%22has_size_adjust%22:true}') format('woff2');
    font-display: swap;
    font-weight: 45 920;
}

@font-face {
    font-family: 'primary Fallback';
    src: local("Arial");
    ascent-override: 93.76%;
    descent-override: 23.75%;
    line-gap-override: 0.00%;
    size-adjust: 101.55%;
}

.className {
    font-family: 'primary', 'primary Fallback';
    
}

.variable {
    --font-primary: 'primary', 'primary Fallback';
}

2. Setting static weight at the top level of localFont object

export const primary = localFont({
  src: '../assets/fonts/PretendardVariable.woff2',
  variable: '--font-primary',
  display: 'swap',
  weight: '100',
});

Result: The following CSS file is generated:

//primary_279ed3c3.module.css
@font-face {
    
    font-family: 'primary';
    src: url('@vercel/turbopack-next/internal/font/local/font?{%22path%22:%22../assets/fonts/PretendardVariable.woff2%22,%22preload%22:true,%22has_size_adjust%22:true}') format('woff2');
    font-display: swap;
    font-weight: 100;
}

@font-face {
    font-family: 'primary Fallback';
    src: local("Arial");
    ascent-override: 93.76%;
    descent-override: 23.75%;
    line-gap-override: 0.00%;
    size-adjust: 101.55%;
}

.className {
    font-family: 'primary', 'primary Fallback';
    font-weight: 100;
}

.variable {
    --font-primary: 'primary', 'primary Fallback';
}

Please let me know if there are any issues with this analysis.

[dosubot]

Your analysis is correct and your suggestions are technically sound. Storybook's current implementation does not match Next.js for top-level weight handling: when src is a string, font-weight is not added to the @font-face rule, and the class name generation does not sanitize spaces in the weight value, leading to invalid CSS selectors and properties reference.

Your proposed changes—to add font-weight and font-style to the @font-face rule for string src, and to only include font-weight in the class selector when it's a static value—would bring Storybook's behavior in line with Next.js and resolve the issue. There's no evidence of intentional divergence or any related open issues or PRs addressing this, and your approach matches best practices for CSS and font loading.

You can move forward with a PR for these changes. If you want to be thorough, consider adding a test case for variable font weights to ensure the fix works as intended.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}