The Challenge Brief Explained

Design Challenges and Product Challenges structure their briefs differently. This guide covers both.

Design Challenge Briefs

What is the Challenge Brief?

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

Many Design 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 are usually listed under:

"Your users should be able to:"

Bonus Features

Bonus challenges are optional but encouraged. They are 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.

---

Now that you understand Design Challenge briefs, let's look at how Product Challenges structure their requirements.

Product Challenge Specs

Product Challenges take a different approach. Instead of a single brief with user stories, you receive a spec/ folder containing multiple documents that together define the full scope of the project.

Product Definition

The product-definition.md file explains what you're building, who it's for, and why it matters. This is the first document you should read. Understanding the target users and core value proposition helps you make better product and design decisions throughout the build.

Core and Stretch Features

The core-requirements.md file organizes features into two tiers:

Core features form a complete, working product. These are required and each one includes detailed acceptance criteria that define exactly what "done" looks like. For example:

Feed Management

• Add a feed by entering its URL
• Validate that the URL points to a valid RSS or Atom feed before saving
• Display feed title, description, and favicon/icon after successful add
• ...

Stretch features take the product to the next level. They build on the core foundation and are recommended for developers who want to go deeper. Completing Core plus at least one stretch feature produces a strong portfolio piece.

Design-It-Yourself Features

The design-challenges.md file contains open-ended features where you make genuine product decisions. These have no single right answer — your solution should reflect your understanding of the users, your design taste, and thoughtful trade-offs.

Each design challenge describes a problem and asks you to design the solution. For example, a content discovery and onboarding feature might ask: How do users discover feeds worth following? What does the empty state look like? How does onboarding differ for power users vs. casual users?

You should document your approach and reasoning for each design challenge in your README.

Differentiators

The differentiators.md file offers optional enhancements that let you customize the project and showcase specific skill areas. You pick 1-2 based on your interests. Examples include AI-powered summarization, offline reading support, reading analytics, or accessibility-first design.

Differentiators are what make your solution uniquely yours across the community.

Technical Requirements

The technical-requirements.md file covers database, authentication, deployment, and performance requirements. It also includes a frontend-only alternative if you'd prefer to skip backend work.

Creative Freedom: Design Challenges vs. Product Challenges

Both challenge formats balance structure with creative freedom, but the balance is very different.

Design Challenges

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

Product Challenges

What you must follow:

• All core feature acceptance criteria must be met
• Technical requirements (database, auth, deployment)
• The brand kit provides your visual foundation

Where you have freedom:

• All design decisions - layouts, interactions, visual hierarchy, responsive behavior
• Product decisions - how features work, onboarding flows, user experience
• Technology choices - framework, database, hosting, styling approach
• Scope customization - which stretch features and differentiators to pursue
• Code organization and architecture

Product Challenges give you significantly more creative freedom than Design Challenges. The tradeoff is that you need stronger product thinking and design judgment to produce a polished result.

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 (Design Challenges) or the brand kit's tone (Product Challenges)

Common Questions About Requirements

"Can I change the design?"

For Design Challenges, minor deviations for accessibility or technical reasons are fine. Document significant changes in your README. Don't redesign the entire project. For Product Challenges, the design is entirely up to you — use the brand kit as your foundation.

"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?"

For Design Challenges, yes — use the style guide colors. That's part of matching the design. For Product Challenges, the brand kit colors are your foundation, but you have flexibility in how you apply them.

"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

Design Challenges

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 isn't 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

Product Challenges

1. Read the product definition - Understand the what, who, and why
2. Study core requirements - Review every feature and its acceptance criteria
3. Review design challenges - Think through the open-ended features
4. Check technical requirements - Understand the database, auth, and deployment needs
5. Choose your differentiators - Pick 1-2 that match your interests
6. Review the brand kit - Internalize the visual foundation
7. Plan your architecture - Choose your stack and plan your data model
8. Build incrementally - Start with the foundation, then layer features
9. Document decisions - Record your design and product reasoning in your README

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.