delorex/test-repo
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): add new assignment projects and update existing content

Browse Source
This commit is contained in:
sanbuphy
2026-03-26 11:20:31 +08:00
parent f6454b0342
commit 7d6c2cbf9c
24 changed files with 4536 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/stage-2/assignments/2.1-fullstack-app/index.md
+205 -1
View File
@@ -1,3 +1,207 @@
# Build Your First Modern App: Full-Stack Application
> This chapter is currently being written. Stay tuned...
::: tip Goal
Turn a prototype idea into a small but complete web application with a real frontend, backend logic, persistent data, and a public deployment link.
:::
At this point, the goal is no longer just “make a page look right.” The goal is to make the core product loop actually work: a user opens the app, does something meaningful, triggers backend logic, stores or reads data, and gets a result that still exists the next time they come back.
You do not need to build a huge platform. A small product with a clear scope and a fully working flow is a much better submission than a large project full of unfinished features.
This assignment is meant to connect the Stage 2 path:
- [UI Design](../../frontend/2.2-ui-design/)
- [From Design Prototype to Project Code](../../frontend/2.6-design-to-code/)
- [Modern Component Libraries](../../frontend/2.7-modern-component-library/)
- [From Database to Supabase](../../backend/2.2-database-supabase/)
- [Using LLMs to Write API Code](../../backend/2.3-ai-interface-code/)
- [Git and GitHub Workflow](../../backend/2.4-git-workflow/)
- [How to Deploy Web Applications](../../backend/2.5-zeabur-deployment/)
## 1. Assignment Goal
Build a **working, demoable, publicly accessible** full-stack web app.
Your project should have:
1. **A clear user and use case**
- You should be able to explain who the product is for and what problem it solves.
2. **A complete product loop**
- The key action must go beyond frontend mock data and trigger real backend or database behavior.
3. **A real engineering handoff**
- The code should live in a repo, secrets should be handled correctly, and someone else should be able to understand how the project works.
Good project directions include:
- upgrading a Stage 1 prototype into a real application
- extending [Hogwarts Portraits](../../frontend/2.5-hogwarts-portraits/) into a more complete product
- building a small AI utility such as a writing tool, summarizer, or research workspace
- building a lightweight vertical tool such as a CRM, scheduling tool, or learning assistant
## 2. Minimum Requirements
| Area | Minimum Requirement | Notes |
| --- | --- | --- |
| Product scope | One clear core workflow | Example: create and save content, upload and process input, create a character and chat |
| Frontend | At least 2 pages, or 1 complex main page plus 1 supporting page | Desktop-ready is required |
| States | Handle loading, empty, and error states | Do not build happy-path only |
| Data | At least 1 core table, ideally 2 related entities | Example: `users` + `projects`, `characters` + `messages` |
| Backend | At least 3 real API endpoints or equivalent server-side capabilities | Express, Next.js route handlers, or edge functions are all acceptable |
| Persistence | Core user actions must be saved and retrievable | Not just mock data |
| Delivery | A GitHub repo and a public online link | Vercel or Zeabur are recommended |
| Documentation | A readable `README.md` | Include purpose, stack, setup, and env vars |
## 3. Recommended Stack
You can use any reasonable stack, but if you want the safest path, this combination works well:
| Layer | Recommended Option |
| --- | --- |
| Frontend | React / Next.js or Vue |
| Component library | shadcn/ui, Ant Design, HeroUI, or Element Plus |
| Data and auth | Supabase |
| Backend | Next.js route handlers, Express, or Supabase Edge Functions |
| Deployment | Vercel or Zeabur |
For a first full-stack project, “frontend + Supabase + a small amount of server logic” is usually the fastest way to a successful submission.
## 4. Suggested Workflow
### 4.1 Write the core task in one sentence
Before coding, answer:
> What is the single most important thing a user should be able to do in this app?
Examples:
- upload text, generate a summary, and save it to history
- create a character profile and continue chatting with it
- add a customer lead and review its status later
If that sentence is still vague, the scope is probably too wide.
### 4.2 Plan the structure first
Sketch:
- what pages you need
- the most important module on each page
- which actions read data
- which actions write data
This will make AI-assisted implementation much more stable.
### 4.3 Start with mock data
A practical order is:
1. build the frontend structure with mock data
2. connect real backend logic
3. replace mock data with real persistence
This keeps the debugging surface much smaller.
### 4.4 Starter prompt for AI IDEs
```text
Help me build a deployable full-stack web app for [your use case].
Do not generate everything at once. First break the project into:
1. page structure and routes
2. data model design
3. API or server-side capability design
4. frontend component breakdown
5. environment variable and deployment setup
Requirements:
- Use [React/Next.js/Vue + your component library + Supabase/Express]
- Prioritize a working MVP over over-engineering
- Tell me which files to create
- Include loading, empty, error, and validation states
```
## 5. Deliverables
Please submit:
1. **A GitHub repository link**
2. **A public online link**
3. **A `README.md`**
- project name and one-line description
- target users and use case
- tech stack
- main features
- local setup steps
- environment variable notes
4. **A short demo asset**
- ideally a 60 to 90 second video, or a few key screenshots/GIFs
Useful optional additions:
- database schema or ER diagram
- API notes or endpoint list
- design/architecture explanation
- a short iteration log
## 6. Evaluation Checklist
Your project is in good shape if:
- a user can complete a real end-to-end flow
- key actions create visible changes in the system
- data still exists after refresh
- backend failures do not crash the UI
- you can explain the product clearly in about one minute
## 7. Bonus Ideas
You can go further with:
- authentication and multi-user support
- real AI capabilities with streaming or retries
- better UI quality with a modern component library
- monitoring, logging, or analytics
- basic tests
- payment or subscription flows
- mobile adaptation
## 8. Common Mistakes
### 8.1 The scope is too large
If your first version requires auth, admin tools, payments, workflow builders, knowledge bases, and multi-user collaboration all at once, the project is probably too big.
### 8.2 The frontend looks good, but nothing is real
That may still be a useful frontend exercise, but not a strong full-stack assignment. This project should include real persistence and server-side behavior.
### 8.3 Secrets are committed into the repo
API keys and database secrets belong in environment variables, not in frontend source code.
### 8.4 Only testing the happy path
Manually test:
- empty input
- duplicate actions
- network failure
- missing data
- permission errors
That is where the most useful product fixes usually appear.
## 9. Final Advice
Treat this assignment as your first real product delivery exercise, not as a feature-count competition.
What matters most is not how many tools you used, but whether you can:
- define a clear product goal
- use AI tools to move from idea to implementation
- deliver something another person can understand, try, and reproduce
::: tip Next
After this assignment, continue with [Assignment 2: Modern Frontend Component Library + Trae](../2.2-modern-frontend-trae/) to push the interface quality even further.
:::
docs/en/stage-2/assignments/2.2-modern-frontend-trae/index.md
+280 -1
View File
@@ -1,3 +1,282 @@
# Assignment 2: Modern Frontend Component Library + Trae Practice
> This chapter is currently being written. Stay tuned...
::: tip Goal
Use Trae or another AI IDE together with a modern component library to build a frontend that feels like a real product rather than a classroom demo.
:::
The previous assignment focused on full-stack completeness. This one focuses on frontend quality: structure, consistency, interaction, responsiveness, and iteration.
Many first frontend projects can “work” but still feel unfinished:
- the layout is usable, but visually inconsistent
- buttons, forms, drawers, and tables do not feel like one system
- the desktop version is acceptable, but narrow screens fall apart
- AI can generate a first version quickly, but the result still looks generic
This assignment is about pushing past that first draft.
Suggested review chapters:
- [From Design Prototype to Project Code](../../frontend/2.6-design-to-code/)
- [Upgrade Your Interface with Modern Component Libraries](../../frontend/2.7-modern-component-library/)
- [Make Interfaces Beautiful with LLMs and Skills](../../frontend/2.4-llm-skills-beautiful/)
- [Reference UI Design Specifications and Multi-Product UI Design](../../frontend/2.3-multi-product-ui/)
## 1. Assignment Goal
Build a frontend project with:
- a clear use case
- a structured layout
- a consistent design language
- real interaction patterns
- code organized in reusable components
Possible project types:
- a landing page
- a logged-in product workspace
- a dashboard or admin interface
- an AI tool interface
- a multi-module content management page
## 2. Required Tools
You should use:
- **Trae** or another AI coding IDE
- **at least one modern component library**
Examples:
- React: `shadcn/ui`, `Ant Design`, `HeroUI`, `Material UI`
- Vue: `Element Plus`, `Naive UI`, `Ant Design Vue`
The important part is not just naming a library. The library should meaningfully improve the project's structure and polish.
## 3. Minimum Requirements
| Area | Minimum Requirement | Notes |
| --- | --- | --- |
| Page scope | At least 2 pages, or 1 complex main page plus 1 supporting page | Example: dashboard + detail page |
| Component library | Use at least 1 real component library | It should appear in the actual implementation |
| Component breakdown | At least 5 reusable components or clearly separated modules | Navigation, filters, table area, modal, summary cards, etc. |
| Interaction | At least 3 interaction types | Form validation, modal/drawer, tabs, menus, filters, pagination, chart switching, etc. |
| States | Include at least 3 of the following: loading, empty, error, success feedback | Important for product realism |
| Responsiveness | Desktop-ready, with reasonable narrow-screen handling | Full mobile support is a bonus |
| Data | Real APIs or structured mock data | Even mock data should be organized well |
| Delivery | Repo link + public deployment | GitHub + Vercel/Zeabur is recommended |
## 4. Suggested Project Directions
### 4.1 Product landing page
Good for practicing visual hierarchy and presentation.
Suggested sections:
- hero
- feature cards
- workflow
- testimonials
- pricing
- FAQ
- footer
Good library options: `HeroUI`, `Material UI`
### 4.2 AI tool workspace
Good for layout, state design, and interaction.
Suggested sections:
- sidebar
- top toolbar
- input area
- result area
- history panel
- settings modal
Good library options: `shadcn/ui`, `Element Plus`
### 4.3 Dashboard / admin interface
Good for dense information layout and component composition.
Suggested sections:
- summary cards
- charts
- filters
- data table
- details drawer or modal
- pagination and status tags
Good library options: `Ant Design`, `Element Plus`
## 5. Suggested Workflow
### 5.1 Decide three things first
Before opening Trae, write down:
1. what kind of product you are building
2. why you chose this component library
3. which 3 modules matter most on the page
That clarity will make AI-generated output far better.
### 5.2 Generate the first structural version
In the first round, focus on layout, component structure, data shape, and core interactions rather than visual perfection.
Example prompt:
```text
Help me build a frontend project for [product type] using [component library].
For the first version, focus on:
1. page structure
2. component breakdown
3. mock data structure
4. core interactions
5. responsive layout foundations
Please split the code into reasonable page and component files.
```
### 5.3 Use later rounds for polish
Once the first version works, iterate on:
- spacing and layout rhythm
- visual hierarchy
- button priority
- hover/focus/disabled states
- status colors, icons, and tags
- narrow-screen adaptation
This is often where the project begins to feel like a real product.
### 5.4 Add the missing product details
Do not skip:
- loading buttons during submission
- empty-state messaging
- fallback UI for failed requests
- confirmation and feedback for save/delete/export flows
- scroll and overflow behavior in dense layouts
These details often create the biggest quality jump.
## 6. Starter Prompt Template
```text
Help me build a frontend interface for [project name] using [component library].
The style should feel [modern / professional / lightweight / consumer / enterprise].
Target users:
- [who uses this]
Page goal:
- [the most important task on this page]
Layout:
- left side: ...
- top area: ...
- main content: ...
- right side / bottom: ...
Interaction requirements:
- include several of: modal, drawer, filters, form validation, charts, pagination
- include loading, empty, and error states
- desktop-first, with narrow-screen handling
Implementation requirements:
- clear component breakdown
- mock data in separate files or modules
- do not generate one giant page file
- build structure first, then improve visuals iteratively
```
## 7. Deliverables
Please submit:
1. **A GitHub repository link**
2. **A public online link**
3. **A `README.md`**
- what the page or product is
- which component library you used and why
- the main modules included
- how to run it locally
4. **Screenshots or a short demo**
- at minimum, show the main desktop view
- if you handled responsiveness, include a narrow-screen view too
Useful optional additions:
- before/after comparison between first draft and final result
- the prompts that helped you most
- one UI detail you are especially proud of
## 8. Evaluation Checklist
Your project is strong if:
- the first screen clearly communicates what the product is
- the layout feels organized even when the page contains a lot of information
- controls feel consistent across the page
- the code is broken into understandable parts
- interactions feel intentional rather than decorative
- the result feels like a product, not a collage of screenshots
## 9. Bonus Ideas
You can go further with:
- real API integration
- theme tokens or dark/light theme switching
- reusable layout primitives
- charts, skeleton loaders, or richer data states
- accessibility improvements such as focus states and semantic structure
- a short design rationale
## 10. Common Mistakes
### 10.1 Focusing only on “looking better”
Modern frontend quality is not just visuals. It also includes clarity, usability, state handling, and structure.
### 10.2 Copying default component library examples too closely
A component library is a foundation, not the final identity of the product.
### 10.3 Generating everything at once
Complex interfaces are usually better when built in stages:
1. structure
2. modules
3. polish
4. details
## 11. Final Advice
Do not treat AI as a one-shot page generator. Treat it as a collaborative frontend partner.
The most useful pattern is usually:
- you define the direction
- AI creates the first version
- you critique the result
- AI refines it
- you keep making product decisions
That is how you move from “a page that exists” to “a frontend worth shipping.”
::: tip Next
If this assignment goes well, revisit [the full-stack assignment](../2.1-fullstack-app/) and upgrade that product with the frontend quality you built here.
:::