Contributing

Thank you for your interest in contributing to Gerbtrace. This page covers coding conventions, the design system, and guidelines for submitting changes.

Getting started

1. Fork the repository and clone your fork.
2. Follow the Development Setup guide to get the project running locally.
3. Create a feature branch from main.
4. Make your changes and verify they work in both web and desktop modes.
5. Submit a pull request.

Code style

• TypeScript throughout the frontend
• Vue 3 Composition API with <script setup>
• Nuxt UI components preferred over native HTML controls
• Tailwind CSS for styling

Nuxt UI form controls

Use Nuxt UI form controls for consistency:

• USelect / USelectMenu instead of <select> / <option>
• URadioGroup instead of native radio groups
• UCheckbox / UCheckboxGroup instead of native checkboxes
• USwitch for boolean toggles
• UInput for text and numeric fields
• UTabs for tabbed interfaces

Keep native controls only when a Nuxt UI component cannot reasonably satisfy behavior, accessibility, or performance needs.

Sidebar design system

The sidebar panels follow a consistent UX pattern. When building or modifying a sidebar:

Information architecture

Use a 3-level structure:

1. Global quick actions (top row) – binary toggles and frequently used actions
2. Status strip – compact computed info and warnings
3. Tabbed content – group related settings by user intent, not implementation detail

Layout rules

• Use compact controls (size="xs" or size="sm")
• Prefer 2-column grids for related numeric inputs
• Use 4-column grids for side-based values (top/bottom/left/right)
• Wrap logical groups in bordered cards with rounded border p-2 space-y-2
• Every input must have a visible label with units (e.g., "Routing tool (mm)")

Behavioral rules

• Input updates should reflect on the canvas immediately
• Sidebar edits must not reset zoom or pan
• If a mode disables a feature, show disabled state with explanation
• New projects start with practical defaults
• New config fields must preserve existing projects (migration fallback)

Checklist for new sidebars

1. Define quick actions and status strip first
2. Split large forms into 2-3 intent-based tabs
3. Add explicit labels and units for every field
4. Use bordered cards for each logical group
5. Ensure toggles disable/hide dependent controls cleanly
6. Keep canvas context stable while editing
7. Add migration for every new persisted field
8. Validate with small viewport and dark mode

Package system rules

• Never invent new package types – only TPSys types are allowed
• Use PT_GENERIC for packages that do not fit the simplified parametric models
• Package geometry must follow Mycronic/TPSys 0-degree orientation
• See Package Definitions for the full type system

Config and persistence

• Sidebar controls map directly to persisted config fields
• New feature toggles require:
  1. Type update in the config schema
  2. Default in the factory function
  3. Migration fallback for existing saved data
  4. UI control wiring
  5. Geometry/render logic wiring
• This keeps local storage and Supabase JSON behavior aligned

Pull request guidelines

• Keep PRs focused on a single feature or fix
• Include a clear description of what changed and why
• Verify the CI checks pass (type check + build)
• Test in both web and desktop modes when applicable
• Update documentation in content/docs/ if your change adds or modifies user-facing behavior

Reporting issues

Use the GitHub Issues page. Include:

• Steps to reproduce
• Expected vs actual behavior
• Browser/OS version
• Screenshots or screen recordings if applicable

You can also submit bug reports directly from within Gerbtrace via the bug report button in the header.