contributor-catalyst · shashwat4543 · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -0,0 +1,50 @@
+# Contributing to Contributor Catalyst
+
+Thanks for helping build this site. It's a plain HTML/CSS/JS project with no build step, so you can go from clone to change in a couple of minutes.
+
+## Before you start
+
+- Check the [open issues](../../issues) for something to work on, or open a new one with the right template ([bug](../../issues/new?template=bug-report.yml), [feature](../../issues/new?template=feature-request.yml), [content task](../../issues/new?template=content-task.yml)).
+- Comment on the issue to claim it. If it's unclear or under-specified, ask questions there before writing code.
+- For anything beyond a typo fix, wait for a mentor to confirm the approach before investing significant time.
+
+## Setup
+
+1. Clone the repo: `git clone https://github.com/contributor-catalyst/website.git`
+2. Open `index.html` directly in a browser, or serve the folder with any static server (e.g. `python3 -m http.server`).
+3. No `npm install`, no build step. Edit HTML/CSS/JS files directly and refresh the browser to see changes.
+
+## Coding conventions
+
+- **HTML**: use semantic elements (`<nav>`, `<main>`, `<article>`, `<section>`, headings in order) instead of generic `<div>`s wherever one fits.
+- **CSS**: add new styles to the relevant file in `assets/css/`; keep selectors scoped to the component/page you're touching rather than adding global overrides.
+- **JS**: keep scripts framework-free and in `assets/js/`; prefer small, named functions over inline handlers.
+- **JSON data** (`data/*.json`): match the existing schema for that file exactly — same keys, same nesting — so the JS that renders it doesn't break. If you need a new field, say so in your issue/PR rather than adding it silently.
+- **Images**: add descriptive `alt` text for every content image; decorative images should use `alt=""`.
+
+## Accessibility standards
+
+This site is built to be usable with a keyboard and a screen reader. Before opening a PR:
+
+- Every image has meaningful `alt` text (or `alt=""` if purely decorative).
+- Headings are in a logical order (no skipping from `<h2>` to `<h4>`).
+- Interactive elements (links, buttons, nav toggles) are reachable and operable via keyboard (Tab/Shift+Tab/Enter).
+- Color choices maintain reasonable contrast against their background.
+- New landmarks/regions (`nav`, `main`, etc.) are labeled if there's more than one of the same type on a page.
+
+## Testing your change
+
+There's no automated test suite, so testing is manual:
+
+1. Open every page you touched directly in a browser.
+2. Tab through the page with your keyboard only and confirm focus order makes sense and nothing is unreachable.
+3. If you changed a JSON file, confirm the page that consumes it still renders (check the browser console for errors).
+4. If you changed layout/CSS, check at a narrow (mobile) width as well as desktop.
+5. Click every link you added or touched to confirm it resolves.
+
+## Opening your pull request
+
+- Fill out the PR template completely — reviewers use it to decide what to check first.
+- Keep PRs focused on one issue; unrelated cleanup should be its own PR.
+- Link the issue you're closing (`Closes #123`).
+- A mentor will review first; once approved, a maintainer merges and the site redeploys automatically via `.github/workflows/deploy.yml`.
diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -30,6 +30,22 @@ body:
       label: Expected behavior
     validations:
       required: true
+  - type: input
+    id: page
+    attributes:
+      label: Page or URL
+      description: Which page is affected? (e.g. /gallery/, /cohorts/year-4.html)
+      placeholder: /gallery/
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Browser / device
+      description: What were you using when you saw this? Include OS if relevant.
+      placeholder: e.g. Chrome 126 on macOS, Safari on iPhone 15
+    validations:
+      required: true
   - type: textarea
     id: screenshots
     attributes:
@@ -39,9 +55,21 @@ body:
     id: a11y
     attributes:
       label: Accessibility impact
+      description: Does this affect keyboard navigation, screen readers, or contrast?
       options:
         - None known
         - Minor
         - Major
     validations:
       required: true
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Severity
+      description: How much does this block users or contributors?
+      options:
+        - Low (cosmetic)
+        - Medium (annoying but workable)
+        - High (broken/blocking)
+    validations:
+      required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Contributing guide
+    url: https://github.com/contributor-catalyst/website/blob/main/.github/CONTRIBUTING.md
+    about: Read this first if you're new — setup, conventions, and how to claim an issue.
+  - name: Browse open issues
+    url: https://github.com/contributor-catalyst/website/issues
+    about: Not sure which template fits, or stuck mid-task? Comment on a related open issue instead of filing a blank one.
diff --git a/.github/ISSUE_TEMPLATE/content-task.yml b/.github/ISSUE_TEMPLATE/content-task.yml
@@ -28,6 +28,17 @@ body:
     attributes:
       label: Source materials
       description: Links, docs, slides, or media files.
+  - type: dropdown
+    id: effort
+    attributes:
+      label: Estimated effort
+      description: Helps contributors pick a task that fits their available time.
+      options:
+        - Small (under 1 hour)
+        - Medium (a few hours)
+        - Large (multiple sessions)
+    validations:
+      required: true
   - type: textarea
     id: done
     attributes:

diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml
@@ -31,3 +31,14 @@ body:
     attributes:
       label: Needed assets/content
       description: Note logos, bios, photos, or links needed.
+  - type: dropdown
+    id: a11y_considered
+    attributes:
+      label: Accessibility considered?
+      description: Does this feature introduce new interactive elements, images, or color choices that need a11y review?
+      options:
+        - "N/A - no new UI"
+        - "Yes, and I've noted requirements above"
+        - "Not yet - needs review"
+    validations:
+      required: true
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,14 +1,34 @@
 ## Summary
 
-Briefly explain what this PR changes.
+Briefly explain what this PR changes and why.
 
-## Checklist
+## Type of change
 
-- [ ] I tested pages locally (open the edited HTML files in browser).
-- [ ] I used semantic headings and landmarks where needed.
-- [ ] I added/updated alt text for images.
-- [ ] I updated JSON content using the existing schema.
-- [ ] I linked related issue(s).
+- [ ] Content update (cohorts, outputs, partners, gallery, about)
+- [ ] Bug fix
+- [ ] New feature/section
+- [ ] Other (describe above)
+
+## Accessibility checks
+
+- [ ] Images have meaningful `alt` text (or `alt=""` for decorative images).
+- [ ] Headings use a logical order (no skipped levels).
+- [ ] New/changed interactive elements are reachable and usable via keyboard only.
+- [ ] Color/contrast choices remain readable against their background.
+- [ ] New landmarks/regions are labeled if more than one of the same type exists on the page.
+
+## Content checks
+
+- [ ] Copy is spell-checked and free of placeholder/lorem ipsum text.
+- [ ] All new/changed links were clicked and resolve correctly.
+- [ ] JSON content follows the existing schema for that file (no renamed/missing keys).
+- [ ] Content is accurate and attributed correctly (names, dates, credits).
+
+## Testing
+
+- [ ] I tested the affected pages locally (opened the edited HTML files in a browser).
+- [ ] I tabbed through the page with keyboard only and confirmed focus order makes sense.
+- [ ] I checked the page at both mobile and desktop widths, if layout/CSS changed.
 
 ## Related issue
 

diff --git a/README.md b/README.md
@@ -33,14 +33,33 @@ This repo includes `.github/workflows/deploy.yml` to deploy from `main` to GitHu
 2. Set **Build and deployment** source to **GitHub Actions**.
 3. Push changes to `main`; deployment runs automatically.
 
-## Contribution workflow
-
-1. Pick or claim an issue from the Issues tab.
-2. Create a branch from `main`.
-3. Make small, focused changes.
-4. Open a pull request using the PR template.
-5. A mentor reviews and approves your pull request.
-6. The maintainer merges it after mentor approval.
+## Contributing
+
+New here? Read this section before opening an issue or PR — it covers the full path from "I want to help" to "my change is merged."
+
+### Quick start (first-time contributors)
+
+1. Read [`CONTRIBUTING.md`](.github/CONTRIBUTING.md) for coding conventions, accessibility standards, and testing steps.
+2. Fork the repo (or clone directly if you have write access) and follow [Local setup](#local-setup-no-build-tools) above.
+3. Browse [open issues](../../issues) and look for the [`good first issue`](../../issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label if this is your first contribution.
+4. Comment on the issue to claim it before starting work, so two people don't duplicate effort.
+
+### Workflow
+
+1. Pick or claim an issue from the Issues tab. If no issue exists for what you want to change, [open one first](../../issues/new/choose) using the appropriate template — this keeps work visible and avoids duplicated effort.
+2. Create a branch from `main` (e.g. `git checkout -b fix/gallery-alt-text`).
+3. Make small, focused changes that match the issue's scope. Prefer several small PRs over one large one.
+4. Test locally per [`CONTRIBUTING.md`](.github/CONTRIBUTING.md#testing-your-change) — open the affected pages in a browser and check keyboard navigation.
+5. Open a pull request using the PR template, and complete every checklist item (or explain why an item doesn't apply).
+6. Link the PR to its issue (`Closes #123`) so it closes automatically on merge.
+7. A mentor reviews and approves your pull request; respond to review comments with follow-up commits rather than force-pushing over history.
+8. The maintainer merges it after mentor approval, and GitHub Pages deploys automatically from `main`.
+
+### Getting help
+
+- Unsure where to start? Ask in the issue you're interested in — a mentor will point you in the right direction.
+- Found a bug but don't have time to fix it? [File a bug report](../../issues/new?template=bug-report.yml) instead of leaving it undocumented.
+- Stuck mid-PR? Open it as a draft and describe what you're blocked on; reviewers can jump in before it's finished.
 
 ## Yearly update checklist