Package Exports

govbr-ds-ui-helper
govbr-ds-ui-helper/dist/index.esm.js
govbr-ds-ui-helper/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (govbr-ds-ui-helper) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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-helper

Via 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>

yarn add govbr-ds-ui-helper

Browser 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 install

Scripts

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 Storybook

Testing

npm run test              # Run all tests
npm run test:coverage     # Generate coverage report
npm run test:watch        # Watch mode

Contributing

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

⚠️ Important: This is an unofficial community project. GOVBR is a trademark of the Brazilian Federal Government.

Support

📧 Email: raphael_f@live.com
💬 Issues: GitHub Issues
📚 Official GOVBR Documentation: https://gov.br/ds/components
🐛 Issues: GitHub Issues

_{Built with ❤️ by the community for Brazilian developers}
_{⚠️ This is an unofficial community tool}