Adding custom fonts and icons to SuiteCommerce requires more than uploading files to an image folder. We need to place assets in a location that survives deployment, load them through the active theme or extension, map them correctly in CSS, and verify that the storefront still performs and remains accessible. The exact implementation differs between SuiteCommerce and SuiteCommerce Advanced, but the underlying process is consistent.
To add fonts and icons to SuiteCommerce, store the assets in the project’s supported static asset structure, reference them through the active theme or extension, define the font or icon rules in CSS, and deploy through the same build process used for the rest of the storefront. For fonts, use `@font-face` with the correct formats and weights. For icons, use an SVG sprite, individual SVG files, or a maintained icon font, then test loading, fallback behavior, responsive layouts, and accessibility before publishing.
This guide focuses on the implementation details that matter when adding custom typography and icon systems to SuiteCommerce and SuiteCommerce Advanced, including a practical distinction between source-controlled SCA projects and extension-based storefronts. If you need the general process for browser icons, our guide on adding a custom favicon to a SuiteCommerce storefront covers that separate use case.
What needs to be decided before adding fonts and icons
Before changing code, identify the storefront architecture, the asset formats, and the release path. A font or icon update that works locally can fail in production if the deployment process excludes static files, rewrites asset URLs, or serves the wrong MIME type.
The first decision is whether the storefront is based on SuiteCommerce with extensions and theme configuration, or SuiteCommerce Advanced, where source code, modules, templates, and deployment artifacts are typically managed in a project structure. Both platforms support custom presentation assets, but they do not always use the same file locations or build commands.
Next, document the assets you intend to use:
Font family name and intended fallback fonts
Available font weights and styles
Font file formats, such as WOFF2 and WOFF
Icon format, such as SVG, SVG sprite, PNG, or icon font
Licensing and redistribution requirements
Required language subsets or Unicode ranges
Light and dark background requirements
A useful implementation detail is that WOFF2 should normally be the primary webfont format because it provides efficient compression and broad modern browser support. WOFF provides a fallback for environments that do not support WOFF2. Avoid adding every possible font format unless your browser support requirements justify the extra files and testing burden.
Also decide whether the new font is a brand font, a utility font, or a replacement for the entire storefront typography system. Replacing every text style creates a larger regression surface than applying a custom typeface to headings, navigation, or selected merchandising components.
How to add custom fonts to SuiteCommerce and SCA
The core process has four parts: include the files, declare the font, assign the correct weights, and verify the browser’s behavior. The files themselves do not change the storefront until the active theme or extension loads the stylesheet containing the declarations.
1. Place the font files in the supported asset structure
For a modern SuiteCommerce implementation, place font files inside the active theme or a custom extension that is included in the deployment. For SuiteCommerce Advanced, place them in the project’s source-controlled asset structure used for theme styles and static resources.
Do not upload a font as an unrelated file in the NetSuite File Cabinet and assume that a production template will automatically reference it. A File Cabinet asset can be useful when the project architecture specifically supports that delivery method, but the reference must be stable, accessible to the storefront, and included in the deployment process.
A typical custom structure might resemble:
Theme/
Styles/
_fonts.scss
_variables.scss
main.scss
Fonts/
brand-regular.woff2
brand-medium.woff2
brand-bold.woff2
Images/
Templates/The directory names vary by implementation. The important principle is that the font files belong to the same maintainable source structure as the stylesheet that references them.
If the storefront uses Sass or another preprocessing step, keep the font declarations in a partial such as `_fonts.scss` and import that partial into the primary stylesheet. If the storefront uses compiled CSS directly, update the appropriate CSS file and confirm the build includes the new declarations.
2. Define each font weight with @font-face
Use one `@font-face` declaration for each real weight and style that the storefront will render. Do not declare a single file as every weight. When a browser needs bold text but the stylesheet says the regular file supports weights from 100 through 900, the browser may create synthetic bolding that looks uneven and affects layout.
@font-face {
font-family: "Brand Sans";
src: url("../Fonts/brand-regular.woff2") format("woff2"),
url("../Fonts/brand-regular.woff") format("woff");
font-style: normal;
font-weight: 400;
font-display: swap;
}
@font-face {
font-family: "Brand Sans";
src: url("../Fonts/brand-medium.woff2") format("woff2"),
url("../Fonts/brand-medium.woff") format("woff");
font-style: normal;
font-weight: 500;
font-display: swap;
}
@font-face {
font-family: "Brand Sans";
src: url("../Fonts/brand-bold.woff2") format("woff2"),
url("../Fonts/brand-bold.woff") format("woff");
font-style: normal;
font-weight: 700;
font-display: swap;
}The `font-display: swap` property allows fallback text to render while the custom font loads. This supports a usable first render, but it can also create a visible shift when the final font replaces the fallback. Choose fallback fonts with similar proportions and measure important components such as navigation, product cards, and checkout fields.
The `font-family` name inside `@font-face` is an internal CSS identifier. It does not need to match the file name, but it must be used consistently throughout the theme.
3. Apply the font through theme variables
Avoid scattering the font family across individual templates. Define it through the theme’s typography variables when the project has a variable system. This keeps the implementation easier to maintain and lets the team change the font without searching through every component.
$font-family-base: "Brand Sans", Arial, sans-serif;
$font-family-heading: "Brand Sans", Arial, sans-serif;
body {
font-family: $font-family-base;
}
h1,
h2,
h3,
h4 {
font-family: $font-family-heading;
}For a more selective change, apply the font only to the intended component classes. For example, a storefront might use the brand font for headings and retain a highly readable system stack for dense account or checkout content.
Do not use a custom font for icon glyphs and ordinary text under the same family name. That approach makes fallback behavior difficult to understand and creates problems for screen readers, copy and paste, and browser rendering.
4. Use unicode-range when the font has language subsets
A specific optimization that generic font guides often omit is `unicode-range`. If a font provider supplies separate Latin, Cyrillic, or extended character subsets, `unicode-range` lets the browser request only the file needed for the characters on a page.
@font-face {
font-family: "Brand Sans";
src: url("../Fonts/brand-latin.woff2") format("woff2");
font-style: normal;
font-weight: 400;
font-display: swap;
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC,
U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074,
U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215,
U+FEFF, U+FFFD;
}Only use ranges that match the files. An incorrect range can cause missing characters or unexpected fallback fonts. If the storefront serves one language and the font is small, omitting `unicode-range` is simpler and often preferable.
How to add icons without creating accessibility problems
Icons should communicate a visual meaning without becoming an invisible barrier for keyboard and screen-reader users. The best format depends on how the icon is used.
Use inline SVG for controls that need accessible names or dynamic styling. SVG gives precise control over size, color, stroke, and viewbox behavior. Use an SVG sprite for repeated decorative icons when the project supports it. Use an icon font only when an existing design system depends on it, because icon fonts behave like text and require additional accessibility and rendering precautions.
Inline SVG for interactive controls
An inline SVG is appropriate for a search button, cart control, menu trigger, or other element where the icon is part of the control’s visible identity.
<button class="header-search-button" type="button" aria-label="Search">
<svg class="icon icon-search" aria-hidden="true" focusable="false"
viewBox="0 0 24 24">
<use href="#icon-search"></use>
</svg>
</button>The button has an accessible name through `aria-label`, while the SVG is marked `aria-hidden="true"` because it is decorative inside the already-labelled control. If the SVG itself conveys the only accessible name, use a visible or programmatically associated label instead of hiding it.
The `focusable="false"` attribute helps prevent the SVG from becoming an unexpected focus target in older browser environments. The exact behavior still depends on the surrounding element and browser, so test keyboard navigation rather than relying on markup alone.
SVG sprites for repeated storefront icons
An SVG sprite stores symbols in one reusable resource. Individual icons can then be referenced with ``. This reduces repeated markup and creates a consistent naming system for icons.
<svg class="icon icon-account" aria-hidden="true" focusable="false">
<use href="/assets/icons.svg#account"></use>
</svg>Check the generated URL after deployment. Relative paths that work in a local project can fail when SuiteCommerce is deployed under a different site path or when static assets receive a generated URL. Inspect the network request and confirm that the response is an SVG, not an HTML error page.
For decorative icons, use `aria-hidden="true"`. For standalone icon buttons, provide an accessible name through a visible text label, an associated label, or `aria-label`. Never rely on a tooltip as the only name for a control.
Icon fonts and their limitations
Icon fonts map private-use Unicode characters to glyphs. They are compact and familiar in older design systems, but they introduce several problems:
A missing font can display an unrelated square or character.
Screen readers may announce the underlying character.
Font smoothing differs between operating systems.
Baseline alignment can vary between browsers.
CSS pseudo-elements can hide the icon’s meaning from maintainers.
If an icon font is required, define it separately from text fonts and add explicit accessibility handling:
@font-face {
font-family: "Storefront Icons";
src: url("../Fonts/storefront-icons.woff2") format("woff2");
font-weight: normal;
font-style: normal;
font-display: block;
}
.icon-cart::before {
content: "\e901";
font-family: "Storefront Icons";
font-style: normal;
font-weight: normal;
speak: none;
}Use icon fonts for decorative elements, not as the only content of an important button. A cart button still needs an accessible label such as “Shopping cart,” regardless of whether its visual symbol comes from SVG or a font.
How SuiteCommerce Advanced changes the implementation
SuiteCommerce Advanced requires stricter source control because the storefront is commonly assembled from modules, templates, Sass files, and deployment configuration. The safest approach is to treat fonts and icons as application assets, not as one-off administrative uploads.
In SCA, identify the active theme and the module or extension responsible for the component that will use the asset. Then confirm where that theme expects static files and how the build process copies them into the deployable output. If an extension owns the component, keep its CSS and icons within that extension where possible. If the asset is global, place it in the shared theme structure and document the dependency.
A font declaration that points to `../Fonts/brand.woff2` is only correct if that relative path remains valid after compilation. Build tools can flatten, copy, or fingerprint files. Therefore, inspect the compiled CSS and the final browser request, not just the source file.
SCA teams should also consider cache invalidation. If the file name remains `brand.woff2` after a new version is deployed, a CDN or browser can continue serving an older asset. Use the project’s established versioning or fingerprinting strategy. Do not manually add random query strings to some assets while leaving the rest of the deployment unversioned, because that creates inconsistent cache behavior.
The project’s existing deployment process also matters. If the release workflow compiles Sass, packages extensions, validates templates, and uploads a defined set of files, a new font directory must be included in that process. A local success is not evidence that the production package contains the font.
How to test fonts and icons before publishing
Testing should cover asset delivery, visual rendering, accessibility, and responsive behavior. Browser developer tools provide the fastest way to find problems.
Open the Network panel and filter for `font`, `woff`, `woff2`, and `svg`. Confirm that each request returns a successful response, the expected content type, and a reasonable file size. A `200` response is not enough if the response body is actually an HTML login page or an error document.
In the Computed styles panel, confirm that the intended font family and weight are applied. The browser’s rendered font information, available in modern developer tools, can show which actual file is being used. This catches a common error where a stylesheet declares `font-weight: 600` but only a 400 file exists, causing synthetic styling or fallback rendering.
Test the following storefront areas:
Global body text, headings, navigation, and buttons
Product listing and product detail pages
Search results, filters, and quick views
Cart, checkout, login, and account pages
Validation messages, alerts, and empty states
Mobile breakpoints and high-density displays
Check long product names and translated or unusual characters. A new font can change line wrapping enough to alter card heights, navigation width, modal dimensions, and checkout layouts. Icon changes need the same review because a different viewbox or baseline can shift buttons and alignment.
Use keyboard-only navigation to confirm that icons do not create extra focus stops. Test with a screen reader for icon-only controls, form labels, validation messages, and status notifications. Accessibility is not complete because the icon looks correct.
Common problems when loading custom assets
The most common failure is a 404 caused by an incorrect relative path. This happens when the CSS file moves during compilation or when the production asset base URL differs from the local environment. Fix the path in the source structure, then validate the compiled output.
A CORS error indicates that the font is being requested from a different origin without the required access policy. Keep fonts on the same approved storefront origin when possible. If cross-origin delivery is required, configure the asset host to permit the storefront origin and verify the response headers.
A font-weight mismatch produces synthetic bolding or a browser fallback. Declare only the weights the files actually contain, and use the same numeric weight in the CSS rules that consume them.
A flash of unstyled text, or FOUT, occurs when fallback text appears before the webfont loads. A flash of invisible text, or FOIT, occurs when text is hidden while the font loads. `font-display: swap` favors visibility, but it does not eliminate layout shift. Improve the result by selecting a compatible fallback and preloading only the most important font file when performance testing justifies it.
An icon that appears as a square usually means the font or SVG did not load, the glyph code is wrong, or the SVG reference points to the wrong file. Inspect the network request and the computed `font-family` before changing the markup.
If fonts are being loaded from a third-party provider, review privacy, availability, licensing, and performance requirements. Self-hosting approved files inside the SuiteCommerce project gives the deployment team more control, but it also makes the team responsible for license compliance and asset maintenance.
When to involve a SuiteCommerce developer
A developer should handle the change when the storefront uses SuiteCommerce Advanced, multiple themes, a custom extension framework, a compiled build, or a controlled release pipeline. Professional review is also appropriate when the font license restricts web embedding, the icon system affects checkout, or the implementation needs language subsets and performance tuning.
We can help review the asset structure, identify the correct SuiteCommerce or SCA customization point, and test the deployment path. If the change touches broader NetSuite data, order, or customer workflows, our NetSuite integration services provide a separate route for reviewing connected systems. For an implementation discussion, contact Versich about your SuiteCommerce storefront.
Conclusion
Adding fonts and icons to SuiteCommerce and SuiteCommerce Advanced is a front-end engineering task, not simply an asset upload. The reliable approach is to keep files in the supported theme or extension structure, define fonts with accurate weights and fallbacks, use accessible SVG or carefully managed icon fonts, and validate the compiled production assets.
SuiteCommerce Advanced requires particular attention to source control, build output, deployment packaging, and cache invalidation. Across both architectures, browser network checks, responsive testing, keyboard navigation, and screen-reader verification should be part of the release process. When those details are handled correctly, custom typography and icons strengthen the storefront identity without creating avoidable performance, accessibility, or maintenance problems.
