Styleguide
Class Naming Guidelines (BEM)
This project uses a clear BEM structure (Block — Element — Modifier) to keep the system consistent, scalable, and easy to edit.
Structure
- Block: A standalone component, such as home-hero, services-list, or project-item.
- Element: A child inside a block. Elements are written as block__element, for example home-hero__heading-wrap, home-hero__description, or project-item__media.
- Modifier: A stylistic variation of a block or element. Written as block–modifier, such as button–ghost or card–highlight.
Naming Rules
- All class names are lowercase and use hyphens.
- Elements only exist within their parent block.
- Modifiers only change appearance, not structure.
- Names are always semantic, not visual — for example:
- correct: home-hero__description
- incorrect: home-hero__text-small
- Utility classes are minimal and global, such as spacing tokens, flex/grid helpers, and typography utilities.
Example (based on the Home Hero section)
The section home-hero is the block.
Inside it you find elements such as:
home-hero__container,
home-hero__grid,
home-hero__heading-wrap,
home-hero__heading,
home-hero__info,
home-hero__description,
home-hero__button-wrap.
Section-Level Consistency
Each major section on a page is treated as a block. All content inside the section follows the same BEM pattern.
For example, in the Services section you will find names like
services,
services__container,
services__item,
services__item-heading,
services__item-description,
and modifiers like services__item–featured.
Utility Classes (u--…) — Global Modifiers
In addition to BEM, the project includes a small set of global Utility Classes, marked with the prefix u--.
These classes are not part of the BEM structure. They are global helpers used to adjust layout, spacing, sizing, or alignment at a system level.
Why Utilities Are Used
- They complement BEM without interfering with it
- They offer quick layout adjustments
- They ensure consistent spacing and sizing across pages
- They never alter semantic meaning — only layout behavior
Examples of Utility Classes
- u--container-xxl
- u--text-large
- u--padding-4xl
Utility classes are reusable across all sections and can be added to any block or element when additional layout control is needed.
Why BEM?
- Predictable structure for easy editing
- Reusable blocks and elements
- Clean scalability for CMS-driven pages
Typography Guidelines
This project uses a fully variable, token-based typography system. All text styles are defined through Font Variables to ensure consistency, scalability, and easy global adjustments.
Font Families
- primary-family: Satoshi — used for headings and display text
- secondary-family: satoshi — used for buttons, labels, navigation, and body text
Text Styles
Each text style (e.g., text-button, text-nav, text-label, text-display) is controlled by a small set of variables:
- Font size: responsive via clamp()
- Line height: set in % for consistent vertical rhythm
- Letter spacing: tuned per style
- Font family: primary or secondary
- Font weight: optimized per use case (e.g., 600 for buttons, 700 for display)
How to Update Typography
To adjust the entire site:
- Go to Variables → Font
- Modify the values inside each text token (size, weight, spacing, family)
- All components update automatically, including CMS-driven content
System Principles
- Headings use the primary family for character
- UI and body text use the secondary family for readability
- Letter spacing and line height are tuned for a modern 2026 look
- All sizing uses clamp() for smooth scaling across breakpoints
Color Guidelines
All colors in this project are managed through Color Variables to ensure consistent theming and easy global updates. The palette is designed for a modern dark UI with clear contrast, subtle surfaces, and a soft accent color.
How the system works
- Colors are grouped by purpose (Surface, Buttons, Text, Accent, Borders, States).
- Every component in the site references these color tokens.
- Changing a token updates all connected elements automatically.
How to customize colors
- Open Variables → Colors.
- Adjust only the token values inside the group Base Colors.
- Avoid deleting tokens—always replace the value.
- Keep the contrast between background + text tokens for accessibility.
- The accent color controls highlights, interactions, and hover states across the site.
Best practices
- Update base-accent first to match your brand.
- Adjust base-light/Base-dark if you want a lighter or darker theme.
- all other colors adapt automatically as long as tokens remain in place.
- For consistent theming, keep the number of unique hues minimal.
SVG Icons — How They Work
This template uses inline SVG icons added via Embed elements. Embedding SVGs inline ensures that icons remain fully styleable, lightweight, and perfectly sharp on all screens.
How icons are set up
Embedding SVGs inline ensures that icons:
- fill="currentColor" / stroke="currentColor" → the icon automatically matches the parent text color
- width="currentWidth" & height="currentHeight" → the icon scales based on the parent element’s dimensions
- A consistent viewBox, ensuring uniform sizing across the system
This allows icons to inherit styling from their wrapper without editing the SVG code.
How to replace an icon
- Select the Embed element containing the icon.
- Replace the <svg>…</svg> code with your new SVG.
- Ensure the SVG attributes use: fill="currentColor", width="currentwidth", height="currentheight"
- Keep the same viewBox ratio (e.g. 0 0 24 24) to maintain layout consistency.
How to style icons
- Adjust color by styling the parent (e.g. using color-text-high, color-text-main, or color-accent).
- Adjust size using the parent’s typography or utility classes (e.g. width/height utilities).
- No edits inside the SVG required.
