Western Friend Django Development

Development guidelines for Western Friend (westernfriend.org), a Quaker publication website that provides resources and support for Quaker communities and individuals seeking to live out their faith in the world.

Project Overview

Western Friend is built with Django and Wagtail CMS, using modern tooling and accessibility-first design principles.

Instructions

Package Management

1. **Always use `uv` for package management, never `pip`**

- Install packages: `uv add <package-name>`

- Sync dependencies: `uv sync`

- Never use `pip install` commands

2. **Run tests using Django's test framework**

- Use Django management command: `manage.py test <path-to-specific-test>`

- Do NOT use `unittest` or `pytest` directly

- Django's test framework is the standard for this project

Accessibility Standards

Follow strict accessibility guidelines:

1. **Implement WCAG 2.1 compliance**

- Follow [W3C Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG21/)

- Follow [W3C Accessible Rich Internet Applications (ARIA) 1.1](https://www.w3.org/TR/wai-aria-1.1/)

2. **Ensure keyboard accessibility**

- All interactive elements must be keyboard accessible

- Test navigation using only keyboard (Tab, Enter, Arrow keys)

3. **Use ARIA roles and attributes**

- Apply appropriate ARIA roles to elements

- Use ARIA labels for screen reader support

Semantic HTML Markup

Use semantic HTML throughout the codebase:

1. **Structure elements**

- `<header>` for headers (not `<div class="header">`)

- `<nav>` for navigation (not `<div class="nav">`)

- `<main>` for main content

- `<footer>` for footer content

- `<section>` for content sections

- `<article>` for articles or blog posts

- `<aside>` for sidebars or related content

2. **Content elements**

- Use semantic headings (`<h1>`, `<h2>`, etc.) to structure content hierarchically

- `<figure>` and `<figcaption>` for images with captions

- `<time>` for dates and times

- `<address>` for contact information

3. **Accessibility requirement**

- Ensure all interactive elements are accessible via keyboard navigation

- Ensure compatibility with screen readers

CSS and Styling

1. **Use Tailwind CSS 4.x with daisyUI 5.x**

- All new styles must use Tailwind CSS and daisyUI components

- Bootstrap CSS is legacy code being phased out—do not add new Bootstrap styles

- Fetch latest Tailwind CSS 4.x and daisyUI 5.x style rules using Context7 tool when needed

2. **Global styles location**

- Define all global styles in `/theme/static_src/src/styles.css`

- `styles.css` is the main entry point for all CSS

- Include global styles for: body, headings, links, and site-wide elements

- Avoid duplicating global styles in components—reuse existing global styles

3. **Tailwind prose class**

- Wrap content using Wagtail `richtext` filter in a `prose` class

- The `prose` class applies Tailwind CSS typography styles to rich text content

- This is necessary because `richtext` filter output cannot be manually styled

4. **UI Icons**

- Use Bootstrap Icons package for all icons

- Icon class format: `bi bi-<icon-name>`

- Maintain icon consistency across the entire project

Examples

Adding a package

```bash

uv add django-extensions

uv sync

```

Running tests

```bash

python manage.py test articles.tests.test_views

```

Semantic HTML structure

```html

<header>

<nav>

<ul>

<li><a href="/">Home</a></li>

</ul>

</nav>

</header>

<main>

<article>

<h1>Article Title</h1>

<time datetime="2026-02-07">February 7, 2026</time>

<p>Article content...</p>

</article>

<aside>

<h2>Related Content</h2>

</aside>

</main>

<footer>

<address>

Contact us at [email protected]

</address>

</footer>

```

Rich text with prose

```html

<div class="prose">

{{ page.body|richtext }}

</div>

```

Using icons

```html

<i class="bi bi-house-door" aria-hidden="true"></i>

<span class="sr-only">Home</span>

```

Important Notes