Contributing Reference Implementations

Guidelines for contributing production-quality examples to the showcase.

Issue Tracking: We use JIRA for issue tracking. All contributions should reference a JIRA ticket.

What is a Reference Implementation?

Complete, production-quality examples that demonstrate best practices

Real-world patterns

How to solve common problems in scientific applications

Component composition

How to combine multiple components effectively

Data handling

Patterns for displaying and interacting with domain-specific data

Accessibility

WCAG 2.1 AA compliance in practice

Before You Start

Open a JIRA ticket first — Create a ticket in JIRA describing the reference implementation you want to build. Include the use case, which components it will demonstrate, and optionally a sketch or wireframe.
Check existing implementations — Ensure your idea doesn't duplicate existing examples.
Claim the ticket — Assign the JIRA ticket to yourself to avoid duplicate effort.

Contribution Process

1Fork and Branch

git checkout main
git pull origin main
git checkout -b ref-impl/your-implementation-name

2Create Your Implementation

Place your reference implementation in src/pages/ with this structure:

src/pages/your-implementation/
├── index.astro           # Main page entry
├── _components/          # Implementation-specific components
│   └── YourComponent.tsx
└── _data/                # Mock data (if needed)
    └── mockData.ts

Use TypeScript with strict type checking

Follow existing code style (Prettier + ESLint)

Ensure responsive design

Support both light and dark themes

3Write Tests

All reference implementations must include tests. We use Playwright for browser-based testing.

4Submit Your Pull Request

Target the main branch
Fill out the PR template completely
Link to the related JIRA ticket
Include screenshots or recordings
Ensure all CI checks pass

Testing Requirements

All contributions require functional, accessibility, and visual regression tests using Playwright and axe-core

Functional TestsRequired

Create functional tests in tests/e2e/your-implementation.spec.ts

import { test, expect } from '@playwright/test';

test.describe('Your Implementation', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/your-implementation');
  });

  test('should render the main content', async ({ page }) => {
    await expect(page.getByRole('heading', { name: 'Title' })).toBeVisible();
  });

  test('should handle user interaction', async ({ page }) => {
    await page.getByRole('button', { name: 'Action' }).click();
    await expect(page.getByText('Expected result')).toBeVisible();
  });
});

Accessibility TestsRequired

Create accessibility tests using @axe-core/playwright in tests/a11y/your-implementation.spec.ts

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test.describe('Your Implementation - Accessibility', () => {
  test('should not have any automatically detectable a11y issues', async ({ page }) => {
    await page.goto('/your-implementation');
    
    const accessibilityScanResults = await new AxeBuilder({ page }).analyze();
    
    expect(accessibilityScanResults.violations).toEqual([]);
  });

  test('should not have accessibility issues in dark mode', async ({ page }) => {
    await page.goto('/your-implementation');
    await page.emulateMedia({ colorScheme: 'dark' });
    
    const accessibilityScanResults = await new AxeBuilder({ page }).analyze();
    
    expect(accessibilityScanResults.violations).toEqual([]);
  });

  test('should pass WCAG 2.1 AA on mobile', async ({ page }) => {
    await page.setViewportSize({ width: 375, height: 667 });
    await page.goto('/your-implementation');
    
    const accessibilityScanResults = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
      .analyze();
    
    expect(accessibilityScanResults.violations).toEqual([]);
  });
});

Visual Regression TestsRequired

Create visual tests in tests/visual/your-implementation.spec.ts

import { test, expect } from '@playwright/test';

test.describe('Your Implementation - Visual', () => {
  test('should match snapshot - default state', async ({ page }) => {
    await page.goto('/your-implementation');
    await expect(page).toHaveScreenshot('default.png');
  });

  test('should match snapshot - dark mode', async ({ page }) => {
    await page.goto('/your-implementation');
    await page.emulateMedia({ colorScheme: 'dark' });
    await expect(page).toHaveScreenshot('dark-mode.png');
  });

  test('should match snapshot - mobile viewport', async ({ page }) => {
    await page.setViewportSize({ width: 375, height: 667 });
    await page.goto('/your-implementation');
    await expect(page).toHaveScreenshot('mobile.png');
  });
});

Running Tests

# Run all tests
npm run test

# Run specific test file
npm run test -- tests/e2e/your-implementation.spec.ts

# Run accessibility tests
npm run test -- tests/a11y/

# Update visual snapshots
npm run test -- --update-snapshots

Maintenance Expectations

By contributing, you commit to maintaining your implementation

Respond to PR comments

Within 1 week

Keep your implementation updated

When dependencies are upgraded (React, Astro, component library), fix breaking changes and update tests

Fix failing tests

Blocking issues: 1 week | Non-blocking: 2 weeks

If unresponsive, maintainers may modify or remove the implementation

Review related PRs

Help review changes that affect your implementation

CI Checks

All PRs must pass these checks

Check	Description
`lint`	ESLint and Prettier formatting
`typecheck`	TypeScript strict mode compilation
`test:e2e`	Playwright functional tests
`test:a11y`	axe-core accessibility tests
`test:visual`	Playwright visual regression tests
`build`	Production build succeeds

Getting Help

Questions

Open a ticket in JIRA with the question label

Bugs

File a ticket in JIRA with reproduction steps

Feature ideas

Open a ticket in JIRA with the enhancement label