govbr-ds-ui-helper
v1.0.2
Published
Unofficial UI checker and helper for GOVBR Design System - Community tool to ensure compliance with Brazilian Federal Government UI standards
Maintainers
raphael.fontesReadme
govbr-ds-ui-helper
🇧🇷 Unofficial community UI checker and helper for GOVBR Design System
⚠️ Disclaimer: This is an unofficial community tool and is not affiliated with or endorsed by the Brazilian Federal Government or the official GOVBR Design System team.
A comprehensive toolkit to ensure compliance with Brazilian Federal Government UI standards. This package provides automated validation, corrections, and guidance for implementing the GOVBR Design System correctly.
Features
- ✅ Automated UI Validation - Scan your application for GOVBR-DS compliance
- 🔧 Smart Corrections - Apply temporary fixes and get permanent solutions
- ♿ Accessibility Focused - Built-in a11y checks following government standards
- 📊 Detailed Reporting - Visual feedback with actionable insights
- 🎨 Interactive Help System - Comprehensive guidance and best practices
- 🚀 Zero Configuration - Works out of the box
- 📦 Tree-shakable - Import only what you need
- 🔍 Developer Tools - Browser extension and dev tools integration
Installation
Via NPM (Recommended)
npm install govbr-ds-ui-helperVia CDN (Browser)
<!-- UMD Build -->
<script src="https://cdn.jsdelivr.net/npm/govbr-ds-ui-helper@latest/dist/index.umd.js"></script>
<!-- Standalone (No React dependencies) -->
<script src="https://cdn.jsdelivr.net/npm/govbr-ds-ui-helper@latest/dist/govbr-standalone.js"></script>or
yarn add govbr-ds-ui-helperBrowser Usage (No Build Step)
For developers who want to use this tool directly in the browser without a build process:
Option 1: Standalone Script (Recommended for browsers)
<!DOCTYPE html>
<html>
<head>
<title>GOVBR UI Helper</title>
</head>
<body>
<!-- Your HTML content with potential GOVBR issues -->
<button onclick="alert('test')">Button without br-button class</button>
<!-- Load the standalone script -->
<script src="https://cdn.jsdelivr.net/npm/govbr-ds-ui-helper@latest/dist/govbr-standalone.js"></script>
<script>
// Use the checker
const checker = window.GovBrUIHelper.GovBrUIChecker;
// Initialize and check
checker.initialize({ highlightIssues: true });
checker.checkAll().then(issues => {
console.log(`Found ${issues.length} issues`);
});
// Auto-fix issues
checker.fixAll().then(fixed => {
console.log(`Fixed ${fixed.length} issues`);
});
</script>
</body>
</html>Option 2: UMD Build (if you have React/MaterialUI loaded)
<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/govbr-ds-ui-helper@latest/dist/index.umd.js"></script>
<script>
const { GovBrUIChecker } = window.GovBrUIHelper;
const checker = new GovBrUIChecker();
</script>Quick Start
Basic Usage
import { GovBrUIChecker } from 'govbr-ds-ui-helper';
// Initialize and run all checks
GovBrUIChecker.start();
// Or run individual operations
GovBrUIChecker.checkAll();
GovBrUIChecker.showReport();
GovBrUIChecker.openHelp();React Component Integration
import React from 'react';
import { GovBrUIChecker, UIValidationProvider } from 'govbr-ds-ui-helper';
function App() {
return (
<UIValidationProvider>
<YourApp />
<button onClick={() => GovBrUIChecker.start()}>
Verificar Compatibilidade GOVBR-DS
</button>
</UIValidationProvider>
);
}Advanced Configuration
import { GovBrUIChecker, ValidationRules } from 'govbr-ds-ui-helper';
// Custom validation rules
const customRules: ValidationRules = {
'custom-button-check': {
rule: (el) => el.tagName === 'BUTTON' && !el.classList.contains('custom-class'),
description: 'Custom button validation',
severity: 'warning'
}
};
// Configure checker
GovBrUIChecker.configure({
rules: customRules,
autoFix: false,
reportPosition: 'top-right'
});API Reference
GovBrUIChecker
Main class for UI validation and correction.
Methods
| Method | Description | Returns |
|--------|-------------|---------|
| start() | Initialize checker and show report | void |
| checkAll() | Run all validation rules | UIIssue[] |
| fixAll() | Apply all temporary fixes | UIIssue[] |
| fixIssue(issue) | Fix specific issue | boolean |
| showReport() | Display visual report | void |
| openHelp() | Open help documentation | void |
| configure(options) | Set configuration options | void |
Configuration Options
interface CheckerConfig {
rules?: ValidationRules;
autoFix?: boolean;
reportPosition?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
theme?: 'light' | 'dark' | 'auto';
locale?: 'pt-BR' | 'en-US';
}Built-in Validation Rules
| Rule | Severity | Description |
|------|----------|-------------|
| Button without br-button | Error | Buttons must use GOVBR button classes |
| Button without type | Warning | Buttons need primary/secondary classification |
| Non-responsive tables | Error | Tables must be wrapped in responsive containers |
| Images without alt | Error | Accessibility requirement for images |
| Inputs without br-input | Warning | Form inputs should use GOVBR classes |
| Menu without trigger | Warning | Responsive menus need trigger elements |
| Cards without margins | Warning | Cards need proper spacing |
| Text overflow issues | Warning | Text truncation must be properly styled |
Components
UIValidationProvider
React context provider for managing validation state.
import { UIValidationProvider } from 'govbr-ds-ui-helper';
function App() {
return (
<UIValidationProvider config={{ autoFix: true }}>
<YourApp />
</UIValidationProvider>
);
}ValidationReport
Standalone component for displaying validation results.
import { ValidationReport } from 'govbr-ds-ui-helper';
function MyComponent() {
return (
<div>
<ValidationReport
position="bottom-right"
onClose={() => console.log('Report closed')}
/>
</div>
);
}Browser Extension
Install the GOVBR UI Helper browser extension for seamless development experience:
- Chrome: Install from Chrome Web Store
- Firefox: Install from Firefox Add-ons
- Edge: Install from Microsoft Store
Development
Setup
git clone https://github.com/Unanimad/govbr-ds-ui-helper.git
cd govbr-ds-ui-helper
npm installScripts
npm run dev # Development mode with watch
npm run build # Production build
npm run test # Run tests
npm run test:watch # Test watch mode
npm run lint # Run linter
npm run storybook # Start StorybookTesting
npm run test # Run all tests
npm run test:coverage # Generate coverage report
npm run test:watch # Watch modeContributing
We welcome contributions! Please see our Contributing Guide for details.
Development Guidelines
- Code Style: Follow the established ESLint and Prettier configuration
- Testing: Maintain 90%+ test coverage
- Documentation: Update docs for any API changes
- Accessibility: Ensure all features meet WCAG 2.1 AA standards
- Performance: Keep bundle size minimal and tree-shakable
Reporting Issues
Please use our issue template when reporting bugs or requesting features.
Roadmap
- [ ] v1.1: Advanced custom rule engine
- [ ] v1.2: Integration with popular build tools (Webpack, Vite, etc.)
- [ ] v1.3: VS Code extension
- [ ] v1.4: CI/CD integration tools
- [ ] v2.0: Full design system component library
License
MIT © Community Contributors
⚠️ Important: This is an unofficial community project. GOVBR is a trademark of the Brazilian Federal Government.
Support
- 📧 Email: [email protected]
- 💬 Issues: GitHub Issues
- 📚 Official GOVBR Documentation: https://gov.br/ds/components
- 🐛 Issues: GitHub Issues