Understanding Your Starter Files

This guide explains what each file is for and how to use them effectively. Jump to the section for your challenge format:

• Design Challenge files
• Product Challenge files
• Shared files (both formats)

Design Challenge Download Package

Design Challenges provide design files, assets, and starter HTML so you can focus on translating a design into code. After extracting your downloaded ZIP file, you'll find the following structure:

challenge-name/
├── .gitignore
├── AGENTS.md
├── CLAUDE.md
├── 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 (Both Formats)

The README is your starting point and contains essential information about the challenge. Both Design Challenges and Product Challenges include one, though the contents differ.

Design Challenge READMEs include:

• Challenge description and skills required
• User stories defining the functionality your solution should have
• Overview of the files in your download
• API information (if the challenge uses an external API)
• Suggested workflow and deployment tips

Product Challenge READMEs include:

• An overview of the project and the key skills it develops: product thinking, design taste, AI collaboration, and shipping real products
• The complete project structure with descriptions of each folder
• A getting started workflow
• Guidance on working with AI tools and choosing differentiators

Tip

Always read the README first, regardless of format.

README-template.md (Both Formats)

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 Files (Design Challenges Only)

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) (Design Challenges Only)

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 (Design Challenges Only)

The starter HTML file contains the text content for your Design 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 (aria labels, alt text, etc.)

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

The assets Folder (Design Challenges Only)

This folder contains all the assets you'll need for the Design 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.

AI Agent Files (AGENTS.md and CLAUDE.md) (Both Formats)

Every challenge includes AGENTS.md and CLAUDE.md files. These are instruction files for AI coding tools like Claude, Cursor, and GitHub Copilot, helping them act as better learning companions while you work on your challenge.

What They Do

AI coding tools automatically detect and follow the instructions in these files. You don't need to configure anything — if you're using a supported tool, it will pick up the guidance on its own.

The core principle behind these files is: AI should guide your thinking, not replace it. Rather than giving you ready-made solutions, AI tools that follow these instructions will ask questions, explain concepts, and help you develop your problem-solving skills.

Tailored to Your Skill Level

The instructions adapt based on the difficulty level of the challenge:

• Newbie - Patient mentoring with step-by-step explanations and real-world analogies
• Junior - Supportive guidance that introduces debugging techniques and the reasoning behind concepts
• Intermediate - A professional peer perspective discussing trade-offs and multiple approaches
• Advanced - A senior colleague role offering probing questions and honest critique
• Guru - Peer collaboration with nuanced technical discussion and contrarian viewpoints

Do You Need to Edit These Files?

No. These files are ready to use as-is. They are designed to work silently in the background with any AI tool that supports them.

Tip

If you're not using AI coding tools, you can safely ignore these files. They won't affect your project in any way. For Product Challenges, AI collaboration is encouraged as part of the workflow — the AGENTS.md file includes full project context (spec, brand kit, and collaboration guidelines) to help AI tools understand your requirements.

How to Use Design Challenge 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

---

Product Challenge Download Package

Product Challenges have a fundamentally different structure. Instead of design files and starter HTML, you receive product specifications, design guidance, and sample data. You choose your own tech stack and make your own design decisions.

challenge-name/
├── .gitignore
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── README-template.md
├── preview.jpg
├── spec/
│   ├── product-definition.md
│   ├── core-requirements.md
│   ├── design-challenges.md
│   ├── technical-requirements.md
│   └── differentiators.md
├── guidance/
│   ├── brand-kit.md
│   ├── patterns.md
│   └── accessibility.md
├── data/
│   ├── README.md
│   └── (sample data files)
└── starter/
    ├── tokens.css
    └── tailwind.css

The spec/ Folder

The spec folder is your project specification. It replaces the user stories you would find in a Design Challenge README.

• product-definition.md - What you're building, who it's for, and why it matters. This gives you the context to make good product decisions.
• core-requirements.md - All features organized into Core (required) and Stretch (recommended) tiers. Each feature has detailed acceptance criteria.
• design-challenges.md - Open-ended features where you make the product decisions. These have no single right answer and are where your product thinking shines.
• technical-requirements.md - Database, authentication, deployment, and performance requirements. Also includes a frontend-only alternative if you'd prefer to skip backend work.
• differentiators.md - Optional enhancements that make your solution stand out. Pick 1-2 based on your interests — things like AI integration, offline support, or analytics — to customize the project and showcase specific skills.

Tip

Read the spec in order: product definition first, then core requirements. Understanding the "what" and "who" before the "how" leads to better decisions.

The guidance/ Folder

The guidance folder provides the visual and UX foundation for your design decisions.

• brand-kit.md - Colors, typography, spacing, border radius, shadows, icons, and layout tokens. This is your design system. It includes light and dark mode palettes, a complete type scale, and design inspiration from similar products.
• patterns.md - UI/UX dos and don'ts to help you make strong design decisions without a Figma file.
• accessibility.md - A WCAG checklist tailored to the challenge.

The brand kit replaces the style guide you would find in a Design Challenge. While a style guide gives you exact values to match, a brand kit gives you a foundation to build upon with your own design taste.

The data/ Folder

Contains sample data files with real-world edge cases for your implementation. The README.md in this folder documents the data structure and known edge cases you should handle.

The starter/ Folder

• tokens.css - CSS custom properties derived from the brand kit. Ready to use in any project.
• tailwind.css - Optional Tailwind CSS v4 configuration using the same tokens. Use this if you prefer Tailwind, or ignore it if you don't.

The .gitignore (Product Challenges)

The .gitignore in Product Challenges is pre-configured to exclude challenge reference files (spec/, guidance/, AGENTS.md, etc.) from your solution repository. These files are your development reference — they stay on your machine but don't belong in the finished product. Your public repository should contain your application code, completed README, sample data files, and starter tokens.

How to Use Product Challenge 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. Read the README for an overview and getting started steps

Step 2: Study the Spec

1. Read spec/product-definition.md to understand what you're building and who it's for
2. Read spec/core-requirements.md to understand all features and acceptance criteria
3. Read spec/design-challenges.md to see the open-ended features where you make the decisions
4. Review spec/technical-requirements.md for database, auth, and deployment guidance
5. Browse spec/differentiators.md and choose 1-2 that match your interests

Step 3: Review the Design Foundation

1. Study guidance/brand-kit.md for colors, typography, spacing, and inspiration
2. Review guidance/patterns.md for UI/UX guidance
3. Check guidance/accessibility.md for the accessibility checklist
4. Look at preview.jpg for a design concept showing how the brand kit comes together

Step 4: Choose Your Stack and Build

1. Choose your framework (Next.js, Nuxt, SvelteKit, Remix, etc.)
2. Set up your project with the starter CSS tokens
3. Begin with the foundation (authentication, database, core data model)
4. Build features incrementally, working through the core requirements
5. Layer in stretch features and your chosen differentiators

Common Mistakes to Avoid

• Skipping the product definition - Understanding the "who" and "why" leads to better product decisions
• Ignoring the brand kit - It provides a cohesive visual foundation so your design decisions feel intentional
• Building everything at once - Start with core features, then add stretch features and differentiators
• Neglecting the guest experience - Many Product Challenges include a guest experience so visitors can see your work without creating an account

Tips for Organization

• Keep the original files - Don't delete design images or spec files; 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, patterns, and design decisions as you work

---

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