Design Guidelines

Overview

This guide provides comprehensive guidelines for designers working with Chassis Assets. Follow these practices to ensure consistent, optimized, and properly organized assets across all brands and platforms.

Design Philosophy

Chassis Assets is built on the principle that design systems must serve multiple brands efficiently without sacrificing brand identity. Assets are managed in a platform-neutral source format and automatically transformed for each target platform.

• Shared by default: Common assets live in source/default/ to minimize duplication
• Override when needed: Brand-specific assets override defaults only when they differ
• Single source of truth: Each asset exists once, reducing maintenance burden and repository size
• Automatic conventions: Platform-specific naming and formats are handled by the build system

This approach allows teams to scale from a single brand to dozens without exponentially increasing complexity.

File Organization

Assets are organized in a hierarchical structure:

source/
├── default/          -> Shared assets for all brands (fallback)
│   ├── [app]/        -> Application-specific folders (e.g., docs, test)
│   │   └── [type]/   -> Asset type folders (e.g., fonts, images, icons)
│   └── ...           -> Other applications
└── [brand]/          -> Brand-specific overrides
    └── [app]/        -> Application-specific folders
        └── [type]/   -> Same structure as default for overrides

Key concepts:

• Default folder: Contains assets shared across all brands
• Brand folders: Override defaults with brand-specific versions
• App folders: Separate assets by application context
• Type folders: Organize by asset type (fonts, images, icons)

Override System

The build system automatically resolves assets by checking for brand-specific versions first, then falling back to defaults. This priority order ensures brand customization while avoiding duplication:

1. Brand-specific asset: source/[brand]/[app]/[type]/file.ext
2. Default asset: source/default/[app]/[type]/file.ext

Only add brand-specific versions when they actually differ from defaults. For example, if all brands use the same logo, place it in source/default/ rather than duplicating it in each brand folder.

Naming Conventions

Consistent naming conventions are crucial for the build system to correctly process and distribute assets across platforms. Use these conventions in your source files—the build system automatically applies platform-specific naming (such as snake_case for iOS/Android) during distribution.

Do:

• ✅ Use lowercase letters
• ✅ Use hyphens to separate words: hero-background.jpg
• ✅ Be descriptive: illustration-onboarding-step-1.svg
• ✅ Include variant suffixes: logo-light.svg, logo-dark.svg
• ✅ Include resolution variants: hero-image.png, hero-image@2x.png, hero-image@3x.png

Don't:

• ❌ Use spaces: Hero Background.jpg
• ❌ Use underscores: hero_background.jpg
• ❌ Use special characters: hero@background.jpg
• ❌ Use generic names: image1.jpg, icon.svg

Asset Types

For detailed specifications, refer to the dedicated documentation for each asset type:

Font Files

Font files with proper format support for web, iOS, and Android platforms. Includes integration with Chassis Tokens typography system.

Recommended formats

Go to Font Guidelines for detailed font management practices.

Image Files

Bitmap graphics including photos, illustrations, and UI elements with resolution variants for different display densities.

Recommended formats

Go to Image Guidelines for detailed image management practices.

Icon libraries

Distribution of icon assets generated by Chassis Icons, including SVG sprites, icon fonts, and CSS files.

Recommended formats

Go to Icon Guidelines for detailed icon management practices.

Other Assets

Additional asset types including videos, audio files, documents, and data files needed across applications.

Go to Other Asset Guidelines for detailed management practices.

Git Workflow

Maintain a clean history and facilitate collaboration through pull requests with clear and descriptive commit messages.

This repository uses Git LFS to store binary assets (fonts and images). Run git lfs install once on your machine before cloning or pulling to ensure LFS pointers are resolved correctly.

• Use a Git GUI tool (e.g., GitHub Desktop, SourceTree) for visual staging and commit management
• Create branches for new features or asset additions (e.g., feature/onboarding-assets)
• Stage only relevant asset files to avoid committing unrelated changes
• Write descriptive commit messages that explain the purpose of the asset changes (e.g., "Add onboarding illustration for web")

Adding New Assets

Add new assets to the appropriate source directory following the naming conventions:

# 1. Create/update asset in design tool
# 2. Export to source directory
# 3. Stage changes
git add source/default/docs/images/onboarding.svg

# 4. Commit with descriptive message
git commit -m "Add onboarding illustration"

# 5. Push to remote
git push origin feature/onboarding

Brand-Specific Assets

Create brand overrides only when assets differ from defaults:

# Add brand override
git add source/brand-a/docs/images/onboarding.svg
git commit -m "Add Brand A onboarding illustration"
git push

Review Process

The review process ensures that all new assets meet quality standards and adhere to guidelines.

1. Create pull request with assets
2. Request review from design system team
3. Address feedback
4. Merge after approval

Best Practices

Follow these common patterns for asset organization and naming to maintain consistency.

Directory Structure

The directory structure provides context; filenames should be descriptive but not redundant.

✅ Correct:

source/brand-a/docs/images/hero.jpg   -> Full context in path

❌ Wrong:

source/images/hero.jpg                -> Missing brand and app context
source/brand-a/hero.jpg               -> Missing app folder
source/default/brand-a-hero.jpg       -> Incorrect: brand name in filename

Semantic Naming

Names should describe what the asset represents, not its visual appearance.

✅ Correct:

hero-background.jpg                   -> Describes purpose
illustration-onboarding.png           -> Clear context
button-primary.svg                    -> Semantic meaning

❌ Wrong:

image1.jpg                            -> Not descriptive
My Image.png                          -> Contains spaces
red_button.svg                        -> Describes appearance, not purpose

File Duplication

Only create brand-specific versions when the asset actually differs.

✅ Correct:

source/default/docs/images/logo.svg   -> Single shared version

❌ Wrong:

source/default/docs/images/some-logo.svg
source/brand-a/docs/images/some-logo.svg   -> Identical copy
source/brand-b/docs/images/some-logo.svg   -> Identical copy

Pre-Commit Checklist

Before committing assets to the repository:

• Files follow naming conventions (lowercase, hyphens, descriptive)
• Assets are placed in correct directory structure
• Files are optimized for size and performance
• Resolution variants are provided where appropriate
• Assets work in both light and dark modes (if applicable)
• Licenses verified for distribution (if applicable)
• No unnecessary files or design sources are included
• Git commit message clearly describes the changes

Related Resources

• Font Assets - Font guidelines
• Image Assets - Image guidelines
• Icons - Icon guidelines
• Other Assets - Other asset guidelines
• Web Applications - Web usage