Optimizely Configured Commerce (Spire) is a strong platform for creating content-rich ecommerce sites, especially suited for wholesalers and manufacturers. Alongside powerful e-commerce features like product recommendations and fast ordering, it supports extensive storefront customization with blogs, case studies, forums, and other content types.
To build clean, scalable, and maintainable websites on Optimizely Configured Commerce, it’s crucial to follow these essential frontend coding standards and best practices.
- Maintaining clean, standardized frontend code ensures scalable, accessible, and high-performing websites.
- Optimizely Spire emphasizes structured, reusable components instead of raw HTML or inconsistent styling.
- Adopting consistent coding conventions across HTML, CSS, and component design keeps projects maintainable and easy to scale.
The suggested coding standards for Spire’s frequently used frontend elements are listed below.
Wrapper Elements (div)
Using generic wrappers like <div> can lead to unnecessary nesting and less maintainable code. Prefer styled components to create clear, consistent, and scalable layouts.
-
-
Less preferable options
<div class="container">…</div> <Typography as="div">…</ Typography >
-
Recommended options
<StyledWrapper className="container">…</StyledWrapper>
-
Heading(h1-h6, p, span, strong)
Use the Typography component with the correct “as” prop for all headings and text elements to ensure semantic HTML, accessibility, and consistent styling.
Note: If you don’t specify the “as” prop, Typography defaults to rendering as a <span>
-
-
Less preferable options
<h2> Title</h2> <div class="heading">…</div>
-
Recommended options
<Typography as="h2">…</Typography>
-
Anchor/Button
For navigation and actions, avoid mixing raw tags. Use dedicated components to keep interactions accessible, consistent, and semantically correct.
-
-
Less preferable options
<a href="/url">…</a> <button><a href="/url">…</a></button> <button class="btn btn-primary">…</button>
-
Recommended options
<Link href="url">…</Link> <Clickable href="url">…</Clickable> <Button variant="primary">…</Button>
-
Image
Avoid raw <img> tags and use image components that provide better accessibility and responsive handling for consistent and maintainable layouts.
-
-
Less preferable options
<img src="/images/logo.png" alt="Logo" />
-
Recommended options
<Img src="/images/logo.png" altText={translate(“Logo")} />
-
Table Elements(table, thead, tbody, th, td)
Avoid using raw HTML tables or div-based layouts. Instead, use table components to maintain semantic markup, improve accessibility, and ensure consistent styling.
-
-
Less preferable options
<div style="display:table;width:100%"> <div style="display:table-row;font-weight:bold"> <div style="display:table-cell;padding:8px">…</div> </div> </div> <table> <tr><th>…</th></tr> <tr><td>…</td></tr> </table> -
Recommended options
<DataTable> <DataTableHead> <DataTableHeader>Date</DataTableHeader> </DataTableHead> <DataTableBody> <DataTableRow><DataTableCell>2025-06-28</DataTableCell></DataTableRow> </DataTableBody> </DataTable>
-
Row/Column
By preventing inline styles, ensuring clean, responsive layouts, and maintaining a consistent grid structure throughout the project, GridContainer and GridItem help you avoid hard-coded rows, columns, or improper nesting.
-
-
Less preferable options
<div class="row"> <div class="column" style="width: 50%;">Left content</div> <div class="column" style="width: 50%;">Right content</div> </div> <GridContainer> <GridItem width={[12, 12, 12, 12, 12]}> <GridItem width={[12, 12, 12, 6, 6]}>… </GridItem> <GridItem width={[12, 12, 12, 6, 6]}>… </GridItem> </GridItem> </GridContainer> <GridContainer> <StyledWrapper> <GridItem width={[12, 12, 12, 6, 6]}>…</GridItem> </StyledWrapper> <GridItem width={[12, 12, 12, 6, 6]}>…</GridItem> </GridContainer> -
Recommended options
<GridContainer> <GridItem width={[12, 12, 12, 6, 6]}>… </GridItem> <GridItem width={[12, 12, 12, 6, 6]}>…</GridItem> </GridContainer> <GridContainer> <GridItem width={[12, 12, 12, 12, 12]}> <GridContainer> <GridItem width={[12, 12, 12, 6, 6]}>… </GridItem> <GridItem width={[12, 12, 12, 6, 6]}>… </GridItem> </GridContainer> </GridItem> </GridContainer> <GridContainer> <GridItem width={[12, 12, 12, 12, 12]}> <GridContainer> <GridItem width={[12, 12, 12, 6, 6]}>… </GridItem> <GridItem width={[12, 12, 12, 6, 6]}>… </GridItem> </GridContainer> <StyledWrapper>…</StyledWrapper> </GridItem> </GridContainer>
-
Hidden/VisuallyHidden
Avoid using inline styles or custom classes to hide content. Instead, use dedicated components like Hidden or VisuallyHidden to ensure accessibility and consistent behavior.
-
-
Less preferable options
<div style="display: none;">…</div> <span style="position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; border: 0; clip: rect(0, 0, 0, 0); overflow: hidden;">…</span> <span class="visually-hidden">…</span>
-
Recommended options
<Hidden below="md">…</Hidden> <VisuallyHidden>…</VisuallyHidden>
-
Translation
Always wrap translatable text with the translate() function to ensure localization support, avoid hardcoded strings, and make the UI adaptable to different languages.
-
-
Less preferable options
<Typography>Translatable Text</Typography>
-
Recommended options
<Typography>{translate(" Translatable Text")}</Typography>
-
GridItem and GridContainer – Spacing
Use the gap property on GridContainer to manage spacing between columns, rather than manually adding padding or margins. This ensures cleaner, more consistent, and maintainable layouts.
-
-
Less preferable options
customGridContainer: { css: css` > div > div {padding: 8px;} `,} -
Recommended options
customGridContainer: {gap: 16}
-
Breakpoints
Customize your breakpoints to avoid repeating identical values. This promotes consistency, reduces redundancy, and supports a scalable layout aligned with your design system.
-
-
Less preferable options
breakpoints: { keys: ["xs", "sm", "md", "lg", "xl"], values: [0, 320, 768, 1024, 1024], maxWidths: [390, 768, 1024, 1024, 1440], }, -
Recommended options
breakpoints: { keys: ["xs", "sm", "md", "lg", "xl"], values: [0, 576, 768, 992, 1200], maxWidths: [540, 540, 720, 960, 1140] }, const customTheme = { ...baseTheme, breakpoints: { ...baseTheme.breakpoints, values: [0, 800, 1200], // Custom breakpoint widths maxWidths: [520, 720, 1100] // Max container widths per range }, }
-
Icons
Avoid hardcoding color values in SVG files. Instead, use currentColor to allow icons to inherit the surrounding text color, ensuring consistency with the theme and simplifying theming.
-
-
Less preferable options
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"> <path d="M16.59 8.59L12 13.17L7.41 8.59L6 10L12 16L18 10Z" fill="#f00"/> </svg>
-
Recommended options
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"> <path d="M16.59 8.59L12 13.17L7.41 8.59L6 10L12 16L18 10Z" fill="currentColor"/> </svg>
-
Writing CSS for Dynamically Generated Classes and Selectors
Avoid targeting hashed or auto-generated class names. Instead, use stable selectors or “data-attributes” to ensure maintainable and predictable styling, and to prevent breakage when class names change.
-
-
Less preferable options
.girEbT .GridItemStyle-sc-1qhu4nt {…} [class*="GridItemStyle—sc--"], [class*="GridItemStyle--"], [class*="GridItemStyle-"] {…} -
Recommended options
[class*="GridItemStyle"] {…} .testClassName {…} [data-test-selector=”testSelector”] {…}
-
Conclusion
- Utilize built-in Optimizely Spire components like Tabs, Accordions, Checkboxes, Radios, and Form Fields to maintain clean, standardized code.
- Following consistent frontend coding standards guarantees projects that are scalable, maintainable, and accessible.
- Writing modular, reusable code minimizes technical debt, fosters better collaboration, and enhances overall user experience.
- Embracing these best practices ensures your projects are future-ready and easier to maintain over time
Source: Read MoreÂ