Asset Naming Conventions Aligning file names with component structure

This document outlines the conventions for naming assets in Blocktail projects, focusing on CSS files and related resources. These conventions align with Blocktail's overall naming philosophy to enhance project organization and developer efficiency.

1. Consistency with Block Names: Asset names should align with the blocks they relate to, using underscores for word separation.
2. Semantic Clarity: Names should clearly indicate the purpose or content of the asset.
3. Predictability: Naming patterns should be consistent across different asset types.
4. Scalability: Naming conventions should accommodate both small-scale and large-scale projects.

For internal files created following the Blocktail methodology, it is recommended to use underscores (_) for word separation in CSS file names. This ensures that the file names directly correspond to the main block or component they style, aligning with Blocktail’s block naming conventions for improved clarity and ease of pairing.

For matrix and context styles, use the same naming convention as blocks:

• Matrix: [name].css 
  • e.g., matrices/main_template.css or matrix--main_template.css for matrix[main_template])
• Context: [name].css 
  • (e.g., contexts/featured_content.css or context--featured_content.css for context[featured_content])

When working with existing codebases or third-party libraries that predominantly use hyphens (-) in file names, it is recommended to maintain this pattern. This approach helps avoid unnecessary fragmentation and ensures consistency with established naming conventions in your project.

Blocktail serves as a methodology for best practices, but it emphasizes flexibility to accommodate various development environments. The use of underscores in file names should be adopted only if it enhances the overall structure, pairing, and consistency of the project. If hyphens are dominant in your current codebase, continuing with that approach is perfectly acceptable.

For smaller projects, it may be more efficient to use consolidated CSS files:

• matrix.css: Contains styles for all matrices
• context.css: Contains styles for all contexts
• blocks.css: Contains styles for blocks and general styles

styles/
|── matrix.css
|── context.css
|── main.css

For larger projects, consider a more granular approach:

• Individual files for each matrix, context, and major block
• Use a build process to concatenate and minify files for production

styles/
|── _variables.scss
|── _mixins.scss
|── matrices/
│   |── _main_template.scss
│   |── _landing_page.scss
|── contexts/
│   |── _featured_content.scss
│   |── _sidebar.scss
|── blocks/
│   |── _product_card.scss
│   |── _main_nav.scss
│   |── _blog_post.scss
|── main.scss

Using underscores (_) for partials in preprocessors like SASS or LESS is recommended for partial identification, avoiding direct compilation, and adhering to preprocessor conventions.

In main.scss, import all other files:

@import 'variables';
@import 'mixins';
@import 'matrices/main_template';
@import 'matrices/landing_page';
// ... other imports

This structure allows for better management of nested styles and maintains organization, especially when dealing with complex block structures and mutations.

There are cases where developers may need to create stand-alone pages or microsites outside of the existing codebase, often under tight deadlines. These pages or extensions are sometimes built by separate teams, where adherence to the main codebase’s guidelines can't always be dictated or enforced. By using Blocktail’s methodology for these builds, teams can better manage technical debt and ensure these additions maintain a clean, organized structure while minimizing disruption to the larger project.

When building microsites, it’s recommended to isolate the CSS assets into a dedicated directory for the project. This keeps the new styles contained, avoiding interference with the rest of the project.

Example Structure:

For a promotion microsite, such as a "Gen AI" campaign, you could structure the files as follows:

styles/
|── gen_ai/
│   |── matrix.css
│   |── context.css
│   |── blocks/[name].css
│   |── ui--agents.css

Or, for a more complex microsite:

styles/
|── gen_ai/
│   |── matrix.css
│   |── context--blog.css
│   |── context--virtual_events.css
│   |── blocks/[name].css
│   |── ui--agents.css

Isolated Structure: Organizing all assets for a stand-alone microsite or project into a separate folder ensures that styles are encapsulated, avoiding style conflicts with the rest of the codebase.

Controlled Technical Debt: Isolating the microsite files prevents the introduction of unnecessary fragmentation into the main project, preserving the integrity of the existing code.

Scalability: This structure allows the stand-alone project to scale independently, while the main project remains unaffected.

Flexibility: This approach aligns with Blocktail’s flexible methodology, allowing for unique project requirements without sacrificing organization or maintainability.

Tails

Tails are always scoped to their blocks and must be nested within the respective block files. This ensures proper encapsulation and maintains the relationship between blocks and their sub-components.

Example:

/* In product_card.css */
.product_card {
  /* Block styles */
  
  .-title {
    /* Tail styles for title */
  }
  
  .-description {
    /* Tail styles for description */
  }
}

Mutations

Mutations, which modify the state or behavior of a block, context, or matrix, should also be retained within their respective block files. Keeping mutations in the same file improves cohesion and helps prevent the fragmentation of styles. This approach simplifies updates and reduces the risk of style conflicts or overlooked changes during future development.

Example:

.product_card {
  /* Block styles */
  
  &.--featured {
    /* Mutation styles for featured state */
  }
}

While it's strongly recommended to keep mutations within their respective block files, in cases of significant technical debt or cross-block mutations, a separate mutation file may be necessary:

styles/
|── blocks/
│   |── product_card.css
|── mutations/
│   |── featured_product.css  
|    /* or */
|── mutations.css

Use this approach sparingly to avoid fragmentation and cross-block contamination. The preferred practice remains keeping mutation styles within corresponding block files.

When naming image files, use descriptive names that clearly indicate their content and purpose. Use underscores to separate words for better readability and to align with the naming conventions of other assets.

• hero_background.jpg
• product_thumbnail_default.png
• icon_user_profile.svg
• logo_main.png
• nav_icon--expanded.svg
• nav_icon--collapsed.svg
• theme_icon.svg
• theme_icon--dark.svg
• theme_icon--light.svg

• Maintain Consistency: Apply the same naming convention across all assets in the project.
• Use Lowercase: Asset names should generally be in lowercase to avoid case-sensitivity issues across different operating systems.
• Avoid Special Characters: Stick to alphanumeric characters and underscores. Avoid special characters to ensure cross-platform compatibility.
• Be Descriptive but Concise: Names should convey the asset’s purpose or content, but avoid excessively long filenames.
• Consider File Structure: Organize assets logically in a directory structure that complements the naming convention, grouping related assets together.
• Scalability: For small projects, a more consolidated file structure may be appropriate, while larger projects may benefit from a granular structure where assets are categorized by feature, page, or component.
• Documentation: Document the naming conventions and file structure to provide guidance for other developers on your team.
• Automated Enforcement: Use linters or build tools to automate and enforce consistent naming conventions throughout the project.

The asset naming conventions in Blocktail projects are designed to improve code organization, enhance developer efficiency, and maintain consistency with Blocktail’s broader naming philosophy. These guidelines should be applied flexibly, adapting to the needs of individual projects while upholding the core principles of clarity, consistency, and predictability.

By scaling from consolidated file structures in smaller projects to granular structures in larger ones, Blocktail accommodates a variety of development scenarios, ensuring that your codebase remains maintainable and scalable as projects grow.