The Challenge Brief Explained

What is the Challenge Brief?

The challenge brief is your project specification. It tells you:

• What the project should do
• What users should be able to accomplish
• What features are required
• What bonus challenges are available

You'll find the brief on the challenge page before you start and in your Challenge Hub after unlocking.

Understanding User Stories

The heart of every brief is a set of user stories. These describe the functionality from an end user's perspective.

The "Users Should Be Able To..." Format

User stories typically follow this pattern:

"Users should be able to view the optimal layout depending on their device's screen size"

This tells you:

• Who: Users (anyone visiting your site)
• What: View the optimal layout
• Context: Depending on device screen size

Breaking Down User Stories

Let's analyze some common user stories:

"Users should be able to see hover states for all interactive elements on the page"

This means:

• All buttons must have hover effects
• All links must have hover styles
• Any clickable element needs visual feedback
• You should check the active-states.jpg design for guidance

"Users should be able to submit their email address using an input field"

This requires:

• An input field of type="email"
• A submit mechanism (button or form submission)
• Likely some validation

"Users should be able to receive an error message when the form is submitted if the input field is empty"

This requires:

• Form validation logic
• An error state design
• Appropriate error message display
• Prevention of empty submissions

Multiple User Stories

Complex challenges have multiple user stories. Treat each one as a checklist item:

Users should be able to:
- [ ] View the optimal layout for the site depending on their device's screen size
- [ ] See hover states for all interactive elements on the page
- [ ] Filter jobs by categories (Role, Level, Languages, Tools)
- [ ] Clear all filters

What the Brief Tells You

The brief explicitly defines certain aspects of your project.

Required Functionality

Any user story in the brief is required. Your solution should fulfill all stated requirements. This includes:

• Layout requirements (responsive design)
• Interactive behaviors (hover states, clicks)
• Form functionality (validation, submission)
• Data display (if working with APIs or JSON)
• Accessibility considerations (when specified)

Data Requirements

Some challenges include data files (often JSON):

• "Use the data from the local data.json file"
• "Fetch data from the provided API endpoint"
• "Display all items from the products array"

What's Up to You

The brief intentionally leaves many decisions to you. This is where you demonstrate your skills and make creative choices.

Technical Approach

You decide:

• HTML structure - How to organize your markup semantically
• CSS methodology - BEM, utility classes, CSS modules, etc.
• JavaScript patterns - How to structure your code
• Build tools - Webpack, Vite, Parcel, or none at all

Frameworks and Libraries

Depending on what you're learning, you can use:

• CSS frameworks - Tailwind, Bootstrap, or vanilla CSS
• JavaScript frameworks - React, Vue, Svelte, or vanilla JS
• Component libraries - If they make sense for the project
• Any other tools - Sass, TypeScript, etc.

Note: All challenges are technology agnostic, meaning you can complete them using whichever tools you want to practice.

Implementation Details

The brief doesn't dictate:

• Variable and function names
• File organization
• Number of CSS files
• Whether to use CSS Grid or Flexbox
• Animation timing and easing
• Exact breakpoints (unless specified)

Quality Enhancements

You can always add:

• Smooth animations and transitions
• Loading states
• Better error handling
• Performance optimizations
• Enhanced accessibility features

Required Features vs. Bonus Features

Many challenges have two tiers of requirements.

Required Features

These are the core user stories. Your solution must include all of these to be considered complete. They're usually listed under:

"Your users should be able to:"

Bonus Features

Bonus challenges are optional but encouraged. They're typically introduced with:

"Ideas to test yourself"

Or listed under:

"Bonus:"

Examples of bonus features:

• "Add a dark mode toggle"
• "Make it a full-stack application"
• "Add data persistence with localStorage"

Tip: Complete all required features first, then tackle bonuses if you want to extend the project. A polished solution without bonuses is better than a buggy solution that attempted everything. However, the bonus features and customizations are where you can truly make the project your own and create even more impressive portfolio pieces.

Creative Freedom Within Constraints

Frontend Mentor challenges balance structure with creative freedom.

What We Recommend Following

• All user stories must be implemented
• Visual design should closely match the provided designs
• Specified colors and fonts from the style guide
• Stated functionality and behaviors

Where You Have Freedom

• Technical implementation choices
• Code organization and architecture
• Animations and micro-interactions
• Additional features beyond the brief
• Performance optimizations
• Accessibility enhancements

Making Good Creative Decisions

When you have freedom, make choices that:

1. Enhance user experience - Smooth animations, helpful feedback
2. Improve accessibility - Keyboard navigation, screen reader support
3. Demonstrate your skills - Clean code, good patterns
4. Stay consistent - Match the design's visual language

Common Questions About Requirements

"Can I change the design?"

Minor deviations for accessibility or technical reasons are fine. Document significant changes in your README. Don't redesign the entire project.

"What if I can't implement something?"

Try your best. Submit what you have. Mention in your README what you struggled with. The community can help.

"Do I need to use the exact colors?"

Yes, use the style guide colors. That's part of matching the design.

"Can I add features not in the brief?"

Absolutely! Extra features show initiative. Just make sure required features work first.

"What if the brief is unclear?"

Check if others have asked about it in the challenge comments. If still unclear, make a reasonable decision and document your interpretation.

"Do I need to support all browsers?"

Target modern browsers (Chrome, Firefox, Safari, Edge). You don't need to support Internet Explorer.

Reading the Brief: A Workflow

Here's a systematic approach to understanding any challenge brief:

1. First read - Get the overall picture of what you're building
2. List the user stories - Write them out as a checklist
3. Identify required vs. bonus - Prioritize your work
4. Note specific requirements - Colors, fonts, data sources
5. Identify unknowns - What's not specified? Those are your decisions
6. Plan your approach - Decide on your tech stack and structure
7. Build systematically - Work through user stories one by one
8. Review against the brief - Before submitting, verify all requirements

Example: Analyzing a Brief

Let's look at a sample brief:

The Challenge

Your challenge is to build out this tip calculator app and get it looking as close to the design as possible.

Your users should be able to:

• View the optimal layout for the app depending on their device's screen size
• See hover states for all interactive elements on the page
• Calculate the correct tip and total cost of the bill per person

Want an extra challenge? Try building it with a framework/library of your choice!

Analysis:

| Aspect | Requirement | | --- | --- | | Responsive design | Required | | Hover states | Required | | Tip calculation logic | Required | | Using a framework | Optional (bonus) | | Choice of framework | Up to you | | How to structure calculations | Up to you | | Animation for results | Up to you |

---

Understanding the brief sets you up for success. The next guide covers how to host your solution so you can submit it for feedback.