> For the complete documentation index, see [llms.txt](https://gyrinx.gitbook.io/gyrinx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gyrinx.gitbook.io/gyrinx/explanation/frontend-development.md).
# Frontend Development
Gyrinx follows a server-rendered approach using Django templates with Bootstrap 5 for styling. The frontend emphasizes simplicity, accessibility, and mobile-first design.
## Technology Stack
### Core Technologies
* **Django Templates** - Server-side rendering with template inheritance
* **Bootstrap 5** - CSS framework for responsive design
* **SCSS** - CSS preprocessing for maintainable styles
* **Vanilla JavaScript** - Minimal client-side interactivity
### Build Tools
* **npm** - Package management and build scripts
* **SCSS compilation** - CSS preprocessing
* **No bundlers** - Keep it simple with direct file serving
## Template Architecture
### Template Hierarchy
```
templates/
├── core/layouts/
│ ├── base.html # Root template with , ,
│ ├── page.html # Simple content pages
│ └── foundation.html # Minimal template for special cases
├── core/includes/
│ ├── back.html # Standard back button component
│ ├── fighter_card.html # Fighter display component
│ └── ... # Other reusable components
└── core/
├── list.html # Page-specific templates
├── campaign.html
└── ...
```
### Template Usage Patterns
**Full Page Layout**
```django
My Page Title
Page Content
```
**Simple Content Page**
```django
Simple Page
Simple content without navigation complexity
```
**Back Button Navigation**
```django
```
## Styling with Bootstrap 5
### Mobile-First Approach
All designs start with mobile layout and scale up:
```html
```
### Common Bootstrap Patterns
**Cards for Content Grouping**
```html
```
## SCSS Development
### File Structure
```
n23/core/static/core/scss/
├── styles.scss # Main entry point
├── _variables.scss # Custom Bootstrap variables
├── _components.scss # Custom component styles
└── _utilities.scss # Utility classes
```
### Build Process
```bash
# Build the stylesheets for both editions
npm run css
# Watch for changes and rebuild
npm run watch
# Lint SCSS
npm run css-lint
```
`npm run css` builds one stylesheet per edition, and `npm run watch` rebuilds both when a template or stylesheet changes:
| Edition | Source | Output |
| ------- | -------------------------------------------- | ---------------------------------------------- |
| n23 | `n23/core/static/core/scss/` (Sass) | `n23/core/static/core/css/styles.css` |
| n26 | `n26/designsystem/assets/app.css` (Tailwind) | `n26/designsystem/static/designsystem/app.css` |
Both outputs are generated: gitignored, built into the Docker image, and never committed. `./scripts/dev.sh` builds them on startup, so you only need to run `npm run css` by hand if you are not using it.
n26's build scans the edition's templates for the classes it emits, which is why editing a template — not just a stylesheet — changes its output. The directories it scans are named explicitly at the top of `app.css`; automatic detection is switched off, because it reaches the whole repository and pulls n23's Bootstrap class names into n26's stylesheet.
### Custom Styling Approach
* Override Bootstrap variables rather than writing custom CSS
* Use Bootstrap utility classes when possible
* Create component-specific styles only when needed
```scss
// _variables.scss - Override Bootstrap defaults
$primary: #your-brand-color;
$font-family-base: 'Your-Font', sans-serif;
// _components.scss - Custom components
.fighter-card {
@extend .card;
.fighter-name {
@extend .card-title;
color: $primary;
}
}
```
## JavaScript Usage
### Minimal JavaScript Philosophy
Gyrinx uses minimal JavaScript, favoring server-side rendering and simple form submissions.
### When to Use JavaScript
* Form enhancements (show/hide fields)
* Client-side validation feedback
* Simple interactive elements (dropdowns, modals)
* Progressive enhancement only
### JavaScript Patterns
```javascript
// Progressive enhancement
document.addEventListener('DOMContentLoaded', function() {
// Only enhance if JavaScript is available
const enhancedElements = document.querySelectorAll('.js-enhance');
enhancedElements.forEach(element => {
// Add JavaScript behavior
});
});
// Avoid JavaScript dependencies for core functionality
// Core features must work without JavaScript
```
## Form Handling
### Django Form Integration
```python
# forms.py
class ListForm(forms.ModelForm):
class Meta:
model = List
fields = ['name', 'content_house', 'public']
widgets = {
'name': forms.TextInput(attrs={'class': 'form-control'}),
'content_house': forms.Select(attrs={'class': 'form-select'}),
'public': forms.CheckboxInput(attrs={'class': 'form-check-input'}),
}
```
```django
```
### Custom Form Rendering
```django
{{ form.name }}
{{ form.name.errors }}
```
## Static File Management
### Development
```bash
# Collect static files for development
manage collectstatic --noinput
# Files are served by Django in development
DEBUG=True # in settings_dev.py
```
### Production
* WhiteNoise serves static files
* Files are collected during deployment
* CSS is compiled from SCSS in build process
### File Organization
```
n23/core/static/core/
├── css/
│ └── styles.css # Compiled from SCSS
├── js/
│ └── index.js # Minimal JavaScript
├── img/
│ ├── brand/ # Logos and branding
│ └── content/ # Game-related images
└── scss/
└── ... # Source SCSS files
```
## Performance Considerations
### Template Performance
* Use \`
\` efficiently\
\- Cache template fragments with \`\`\
\- Minimize database queries in templates
### CSS Performance
* Minimize custom CSS
* Use Bootstrap utilities to reduce file size
* Optimize images for web delivery
### JavaScript Performance
* Load JavaScript at end of ``
* Use event delegation for dynamic content
* Avoid large JavaScript frameworks
## Accessibility
### Built-in Bootstrap Accessibility
* Use semantic HTML elements
* Leverage Bootstrap's ARIA attributes
* Ensure keyboard navigation works
### Custom Accessibility
```html
```
## Testing Frontend Code
### Template Testing
```python
@pytest.mark.django_db
def test_list_template_renders():
client = Client()
user = User.objects.create_user(username="test", password="test")
response = client.get("/lists/")
assert response.status_code == 200
assert "Lists" in response.content.decode()
```
### CSS Testing
* Visual regression testing (manual)
* Cross-browser testing on common devices
* Mobile responsiveness testing
### JavaScript Testing
* Manual testing for progressive enhancement
* Ensure core functionality works without JavaScript
## Future Considerations
### htmx Integration
While not currently used, htmx could add interactivity:
```html
```
### Performance Monitoring
* Consider adding Core Web Vitals monitoring
* Monitor CSS bundle size growth
* Track JavaScript execution time
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://gyrinx.gitbook.io/gyrinx/explanation/frontend-development.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.