Contributing to Webui

Thank you for your interest in contributing to Webui! We're an open-source design-to-code platform built by developers, for developers. This guide outlines the standards, workflows, and best practices to ensure smooth collaboration.

🛠️ Local Development Setup

Before you begin, ensure your environment meets the following requirements:

• Node.js: v18.0.0 or higher
• Package Manager: pnpm v8+ (recommended) or npm
• Git: v2.30+ with husky and lint-staged configured

The development server will start at http://localhost:3000. Hot module replacement is enabled for instant feedback.

📁 Project Structure

Webui uses a monorepo architecture managed by Turborepo. Key directories include:

🌿 Branching & Workflow

We follow a simplified Gitflow model optimized for rapid iteration:

1. Create a feature branch from main: git checkout -b feature/your-feature-name
2. Make changes incrementally. Squash commits before opening a PR.
3. Prefix your branch name with: feat/, fix/, docs/, or refactor/
4. Never commit directly to main. All changes require review.

✍️ Commit Conventions

We use Conventional Commits to automate changelogs and versioning. Structure your messages as:

Types: feat, fix, docs, style, refactor, perf, test, chore

Example: feat(ui): add responsive grid system with auto-layout

🎨 Code Standards

Consistency is key. Our tooling enforces these rules automatically via pre-commit hooks:

• TypeScript: Strict mode enabled. No any types without justification.
• ESLint: Airbnb + React + TypeScript configs. Linting runs on save.
• Prettier: 2-space indentation, trailing commas, single quotes.
• JSX: Functional components, arrow functions, explicit prop types.
• Imports: Auto-sorted by @trivago/prettier-plugin-sort-imports

♿ Accessibility Requirements

Webui is committed to WCAG 2.1 AA compliance. All components must:

• Include proper ARIA attributes when native semantics are insufficient
• Support keyboard navigation and focus management
• Maintain color contrast ratios of at least 4.5:1
• Be tested with screen readers (VoiceOver, NVDA, JAWS)

Run pnpm test:a11y to automatically audit your changes.

📤 Submitting Pull Requests

Before opening a PR, ensure your branch is up to date with main and all checks pass. Your PR description should follow this template:

PR Checklist

• ✓ All unit & integration tests pass
• ✓ No console warnings or errors
• ✓ Documentation updated (if API changes)
• ✓ Performance benchmarked (if heavy computation)
• ✓ Security reviewed (if handling user data)

👀 Review Process

Every PR requires at least two approvals from core maintainers. Reviewers will check for:

1. Code quality & adherence to standards
2. Test coverage & edge cases
3. Performance implications
4. Documentation completeness
5. Alignment with project roadmap

Reviews are constructive. If feedback is requested, respond promptly and keep the conversation focused on the code. We squash and merge after approval.

🤝 Community Guidelines

We foster an inclusive, respectful environment. By contributing, you agree to:

• Be professional and constructive in all communications
• Respect diverse viewpoints and experiences
• Focus on what's best for the community
• Report unacceptable behavior to maintainers@webui.io

Violations may result in temporary or permanent removal from the project.

❓ FAQ

How do I request a new feature?

Open a Discussion on GitHub. Vote on existing proposals to help prioritize the roadmap.

Can I contribute translations?

Yes! Check the /packages/i18n directory and follow our localization guide. PRs for new languages are welcome.

How often are releases published?

We release bi-weekly on Tuesdays. Minor patches may drop sooner for critical fixes.

💬 Need Help?

Stuck on something? Join our community channels: