Developer Guide

Onboarding for
New Developers

Everything you need to understand the Hinbuna Kurdi project, set up your environment, and start designing screens following our established brand system. Read through each section before creating your first screen.

Last updated: Mar 2026 ~15 min read 9 sections + timeline
Roadmap

Project Timeline

8-week plan: February → March 2026 — From foundation to launch, and beyond.

Overview
February 2026 March 2026
Phase Feb 3 Feb 10 Feb 17 Feb 24 Mar 3 Mar 10 Mar 17 Mar 24
P1 Foundation
Done
P2 MVP Screens
Now
P3 Tickets
W3
P4 Build
2 weeks
P5 Testing
2 weeks
P6 Ezmuna
W8
P7 Roadmap
→

Hinbuna Kurdi (Hinbûna Kurdî) is a Kurdish language learning platform — starting with Kurmanji at A1–B1 levels, with more dialects planned. Full project overview, tech stack, team, and scope are in the project docs.

Source of truth: _docs/01-project-overview.md — Project overview, tech stack, team, scope, and 32-screen breakdown.

Check the Design Gallery for the full screen list with current status.

Step 1: Clone the Repository

bash 
git clone git@github.com:adar-schule/hinbuna-kurdi.git
cd hinbuna-kurdi

Step 2: Understand the Folder Structure

directory 
hinbuna-kurdi/
├── .ai/                   ← LLM workspace (rules, sessions)
│   ├── README.md          ← Boot sequence for AI assistants
│   ├── rules/             ← Shared standards (workflow, coding)
│   └── sessions/          ← Session tracking (kanban-style)
├── mockup/                ← HTML design files (THIS IS WHERE YOU WORK)
│   ├── index.html         ← Design gallery entry point
│   ├── onboarding.html    ← This guide
│   ├── shared/            ← Theme system (light/dark, colors)
│   └── ...
├── _docs/                 ← Project documentation (source of truth)
│   ├── 09-design-decisions.md   ← Colors, typography, workflow, checklist
│   └── ...
├── _material/             ← Learning materials (von Mamoste curriculum)
├── frontend/              ← React app (later phase, don't touch yet)
├── CLAUDE.md              ← AI assistant entry point & project config
└── .github/workflows/     ← Auto-deploys mockup/ to GitHub Pages

Your workspace is the mockup/ folder. That is where all HTML design files live. The _docs/ folder has the brand system and layout specifications you will reference.

Step 3: Open in Your Editor

Open the repo in VS Code, Cursor, or your preferred editor. If using Claude Code, navigate to the repo root.

Step 4: Preview HTML Files

Simply open any .html file directly in your browser. For mobile-accurate previews:

  1. Open Chrome DevTools (Cmd+Opt+I on macOS, F12 on Windows)
  2. Click the device toolbar toggle (or press Cmd+Shift+M)
  3. Set width to 375px (iPhone SE)
  4. Review the design at mobile width first, then expand to check responsiveness

We use AI coding assistants for development. The workflow rules, coding standards, git conventions, and session management are all documented in the AI development workflow doc.

Source of truth: _docs/08-ai-development-workflow.md — Three-phase workflow, context management, coding standards, and git conventions.

Getting Started with AI Tools

This project includes an .ai/ folder with LLM-agnostic workspace configuration:

  • .ai/README.md — Boot sequence for any AI assistant
  • .ai/rules/ — Shared standards (workflow, coding)
  • .ai/sessions/ — Session tracking so AI picks up where you left off
  • CLAUDE.md — Entry point for Claude Code (other tools may use their own config)

Before your first session: Read the project's entry file (CLAUDE.md or equivalent) and follow the boot sequence in .ai/README.md. This ensures your AI assistant understands the project rules.

The full 10-step screen creation workflow and quality checklist live in the design decisions doc.

Source of truth: _docs/09-design-decisions.md — Screen Creation Workflow & Quality Checklist sections.

All brand rules — color system (light + dark), typography, component patterns, and anti-patterns — are maintained in the design decisions doc.

NEVER reference Duolingo — not in prompts, designs, code, comments, or comparisons. This is a serious, structured language learning platform. Not gamified, not playful, not cartoon-style.

Source of truth: _docs/09-design-decisions.md — Colors, typography, components, anti-patterns, and dark/light mode rules.

Primary Tool: AI Coding Assistant

We use an AI coding assistant (e.g. Claude Code, Cursor, Copilot) to generate production-grade HTML screen designs. Any tool that can read project files and generate code works.

  • Read the design decisions doc (_docs/09-design-decisions.md) before generating any screen
  • Reference the prompt file and base template for each screen
  • Iterate in the editor — review in browser — refine

Available MCP Integrations

These optional integrations can speed up the workflow (setup depends on which AI tool you use):

  • Google Stitch MCP — Generate quick visual inspiration or reference screens. Useful if you are stuck on a layout.
  • Playwright MCP — Browser testing and screenshot automation
  • context7 — Documentation lookup for libraries and APIs

Visily Pro

Armanc has a Visily Pro account. The previous design workflow used Visily for AI-generated screens. That workflow is paused but existing Visily designs can be used for visual comparison. Ask Armanc if you need access.

Preview Workflow

The simplest way to preview your work:

  1. Open the HTML file directly in Chrome
  2. Open DevTools → Toggle device toolbar
  3. Set width to 375px (iPhone SE)
  4. Check both light and dark versions side by side

Screens are prioritized into three tiers. Always work in order: P0 first, then P1, then P2. Within each tier, follow the listed order.

Priority Screens
P0
Do first		 Public: P1 Landing, P2 Pricing, P3 Login, P4 Register
Student: S1 Dashboard, S2 Course List, S3 Module View, S4 Unit View, S5 Lesson View, S6 Activity, S7 Result, S8 Complete
Teacher: T1 Content Dashboard, T2 Course/Module, T3 Unit Editor, T4 Lesson Editor, T5 Activity Editor
P1
Then		 Public: P5 Forgot Password
Student: S9 Profile, S10 Settings
Teacher: T6 Materials, T7 Students Overview
Admin: A1 Admin Dashboard, A2 User Mgmt, A3 User Detail, A4 Content Mgmt, A5 Subscriptions
P2
Later		 Public: P6 About
Student: S11 Achievements, S12 Leaderboard
Teacher: T8 Student Detail
Admin: A6 System Settings

Tip: Check the Design Gallery for real-time status. Any screen marked "Done" has been completed and can be used as a reference for consistency.

Full git workflow — branch naming, commit format, PR titles, and workflow rules — is documented in the AI development workflow doc.

Source of truth: _docs/08-ai-development-workflow.md — Section 2: Git & Commit Conventions.

Ask Armanc first before pushing to remote or creating PRs, especially if you are new to the project. Never commit directly to main.

Run through this checklist after every screen before committing. Click each item to mark it checked (for your own tracking — state is not saved). Source: _docs/09-design-decisions.md

  • Background color correct? Light: cream #FDF8F3 / Dark: deep forest #1A2024
  • NOT matrix green? Dark mode = warm forest at night, not hacker terminal
  • Gold accents present? At least one gold element #D4A843 on the screen
  • Text readable? Sufficient contrast between text and background
  • Buttons correct? Green + cream (light) / Gold + dark (dark)
  • Cards have subtle separation? Shade difference, not harsh borders
  • Typography correct? Nunito for headings, Inter for body text
  • Kurdish text correct? Characters ê, î, û, ç, ş display properly
  • Mobile width? 375px base, responsive to wider screens
  • Header consistent? Logo left, globe + toggle + action right
  • No flag icons? Language picker uses text labels, monochrome
  • Sections flow naturally? Visual rhythm, not stacked blocks with equal gaps
  • Touch targets 44px+? All interactive elements large enough to tap
  • CSS animations present? Hover states, fade-ins, smooth transitions
  • Self-contained? Single HTML file, only Google Fonts as external dependency

If all 15 items pass, your screen is ready to commit. If any item fails, fix it before pushing. Consistency across all 32 screens is what makes the design system work.