Understanding Your Starter Files

Overview of the Download Package

After extracting your downloaded ZIP file, you'll find the following (or similar) structure:

challenge-name/
├── .gitignore
├── README.md
├── README-template.md
├── index.html
├── preview.jpg
├── style-guide.md
├── assets/
│   ├── fonts/
│   │   └── (font files organized by family)
│   └── images/
│       └── (optimized image assets)
└── design/
    ├── desktop-design.jpg
    ├── mobile-design.jpg
    └── (additional state files as needed)

Let's explore each component in detail.

README.md

The README is your starting point and contains essential information about the challenge.

What's Inside

• Challenge description - What you're building and the skills required
• User stories - The functionality your solution should have
• What's included - Overview of the files in your download
• API information - Setup instructions if the challenge uses an external API
• Building guidance - Suggested workflow and approach
• Deployment tips - Recommended hosting platforms
• Submission instructions - How to share your completed work

Tip: Always read the README first. The user stories define exactly what your solution needs to do.

README-template.md

This is a template for your own README. When you complete the challenge, you should replace the original README.md with a customized version based on this template.

Your custom README should include:

• Screenshot of your solution
• Links to your live site and repository
• Your process and what you learned
• Technologies you used
• Any questions you have for the community

design Folder

The design folder contains visual references for your build.

Desktop and Mobile Designs

• desktop-design.jpg - The full desktop layout
• mobile-design.jpg - How the layout adapts for mobile screens

Use these to understand:

• Overall page structure and layout
• Element positioning and alignment
• Visual hierarchy and spacing
• How components relate to each other

State Files

Many challenges include additional images showing various UI states:

• hover-state.jpg - How elements look when hovered
• focus-state.jpg - Focus styles for keyboard navigation
• loading-state.jpg - Loading indicators
• error-state.jpg - Error messages and styling
• Other states specific to the challenge

Note: The specific state files vary by challenge. Check your design folder to see what's included.

preview.jpg

A smaller preview image in the root folder. This is used as an image for the README and can be ignored during project build.

Style Guide (style-guide.md)

The style guide is your reference for visual consistency. It contains the exact values you need to match the design.

Layout Widths

## Layout

The designs were created to the following widths:

- Mobile: 375px
- Desktop: 1440px

These are the design sizes. Your solution should be responsive and work across all screen sizes.

Colors

The style guide lists all colors used in the design, typically in HSL format:

## Colors

### Primary
- Blue 500: hsl(233, 67%, 56%)

### Neutral
- Neutral 900: hsl(243, 96%, 9%)
- Neutral 0: hsl(0, 0%, 100%)

Typography

Font information includes:

• Font family - The specific Google Font to use
• Font weights - Which weights are needed (300, 500, 700, etc.)
• Base font size - Usually for body text

## Typography

### Body Copy
- Font size: 18px

### Font
- Family: [DM Sans](<https://fonts.google.com/specimen/DM+Sans>)
- Weights: 300, 500, 600, 700

Tip: The style guide often includes a link to upgrade to Pro for Figma access, which provides exact measurements and a full design system.

index.html

The starter HTML file contains the text content for your challenge.

What's Included

• Basic HTML5 boilerplate with viewport meta tag
• Favicon link
• Page title
• All text content (headings, paragraphs, labels, button text)
• Attribution footer

What You'll Add

The content is provided as plain text. You need to:

• Add semantic HTML structure (header, main, section, article, etc.)
• Wrap content in appropriate elements
• Add classes for styling
• Link your CSS file(s)
• Add any JavaScript files
• Implement accessibility attributes (e.g., aria-labels, alt text).

This approach lets you focus on building layouts and components while ensuring you have the correct content.

The assets Folder

This folder contains all the assets you'll need for the challenge.

assets/fonts/

Contains font files organized by font family. Each family has its own subfolder with the necessary font files.

You can either:

• Use these local font files with @font-face
• Link to Google Fonts directly (the style guide includes the link)

assets/images/

Contains all image assets, already optimized for web use:

• Favicon
• Logo files (often SVG)
• Icons for UI elements
• Background images
• Any photographs or illustrations

The images are:

• Compressed for fast loading
• Sized appropriately for the design
• Named clearly for easy reference
• In the correct format (SVG for icons, WebP/PNG for photos)

Tip: Don't resize or recompress these images. They're already optimized.

.gitignore

A pre-configured gitignore file for common files and folders that shouldn't be committed to version control.

How to Use These Files Effectively

Step 1: Set Up Your Project

1. Extract the ZIP to your projects folder
2. Open the folder in your code editor
3. Initialize a Git repository (git init)
4. Make your first commit with the starter files

Step 2: Study the Materials

1. Read the README completely, especially the user stories
2. Open both design images and compare desktop vs mobile
3. Review all state files in the design folder
4. Note the colors and fonts from the style guide
5. Scan through index.html to see what content you're working with

Step 3: Plan Your Approach

Before writing code:

1. Identify the major sections of the layout
2. Note which elements repeat or share styles
3. Plan your CSS class naming convention
4. Decide if you need any JavaScript and what it should do

Step 4: Build Systematically

1. Start with mobile layout (mobile-first approach)
2. Add CSS custom properties for colors and fonts from the style guide
3. Build one section at a time
4. Add responsive breakpoints for larger screens
5. Implement interactive states last

Common Mistakes to Avoid

• Skipping the README - The user stories define what you need to build
• Ignoring the style guide - Guessing colors leads to inconsistency
• Modifying provided images - They're already optimized
• Starting without a plan - A few minutes of planning saves hours of refactoring

Tips for Organization

• Keep the original files - Don't delete design images; you'll reference them often
• Define your architecture - Whether you're using plain HTML and CSS or building a complex app using a framework, ensure you define a clear architecture and file separation based on your needs
• Use meaningful commits - Track your progress with descriptive Git messages
• Take notes - Jot down measurements and patterns as you work

---

Now that you understand your starter files, the next guide will show you how to work effectively with the design files.