Skip to main content

UI Foundation Kit

The ACCI EAF UI Foundation Kit provides a comprehensive collection of reusable React components, design tokens, and patterns built on top of Vaadin with Hilla integration.

Overview​

The UI Foundation Kit ensures consistency across all ACCI EAF applications while providing:

  • Design System: Unified visual language and component library
  • Vaadin/Hilla Integration: Type-safe full-stack components
  • Accessibility: WCAG 2.1 AA compliant components
  • Theming: Customizable design tokens and themes
  • Internationalization: Built-in i18n support
  • Storybook: Interactive component documentation

Component Categories​

📋 Form Components​

  • Text Input: Single and multi-line text fields
  • Select: Dropdown and multi-select components
  • Checkbox/Radio: Boolean and choice selections
  • Date Picker: Date and time selection
  • File Upload: Drag-and-drop file handling
  • Form Validation: Real-time validation feedback

🧭 Navigation​

  • App Shell: Main application layout structure
  • Sidebar: Collapsible navigation panels
  • Breadcrumbs: Hierarchical navigation aids
  • Tabs: Content organization within views
  • Pagination: Large dataset navigation

📊 Data Display​

  • Data Grid: Sortable, filterable tables
  • Cards: Content containers with actions
  • Charts: Data visualization components
  • Badges: Status and count indicators
  • Progress: Loading and completion states

💬 Feedback​

  • Notifications: Toast and banner messages
  • Dialogs: Modal confirmation and input dialogs
  • Tooltips: Contextual help and information
  • Loading States: Spinners and skeleton screens

🎨 Layout​

  • Grid System: Responsive layout utilities
  • Containers: Content wrapping and spacing
  • Dividers: Visual content separation
  • Spacing: Consistent margin and padding utilities

Design Tokens​

The Foundation Kit uses design tokens for consistent styling:

/* Color Tokens */
--color-primary: #1976d2;
--color-secondary: #dc004e;
--color-surface: #ffffff;
--color-background: #fafafa;

/* Typography Tokens */
--font-family-primary: 'Inter', sans-serif;
--font-size-small: 0.875rem;
--font-size-medium: 1rem;
--font-size-large: 1.25rem;

/* Spacing Tokens */
--spacing-xs: 0.25rem;
--spacing-sm: 0.5rem;
--spacing-md: 1rem;
--spacing-lg: 1.5rem;

Usage Examples​

Basic Component Usage​

import { Button, TextField, Dialog } from '@acci-eaf/ui-foundation-kit';

function CreateTenantForm() {
const [isOpen, setIsOpen] = useState(false);
const [tenantName, setTenantName] = useState('');

return (
<>
<Button onClick={() => setIsOpen(true)}>
Create Tenant
</Button>

<Dialog isOpen={isOpen} onClose={() => setIsOpen(false)}>
<TextField
label="Tenant Name"
value={tenantName}
onChange={setTenantName}
required
/>
<Button variant="primary">Create</Button>
</Dialog>
</>
);
}

Hilla Integration​

import { useEndpoint } from '@vaadin/hilla-react';
import { TenantService } from 'Frontend/generated/endpoints';
import { DataGrid } from '@acci-eaf/ui-foundation-kit';

function TenantList() {
const tenants = useEndpoint(TenantService, (service) => service.getAllTenants());

return (
<DataGrid
items={tenants}
columns={[
{ key: 'name', header: 'Tenant Name' },
{ key: 'adminEmail', header: 'Admin Email' },
{ key: 'status', header: 'Status' }
]}
/>
);
}

Theming​

Custom Theme​

import { createTheme } from '@acci-eaf/ui-foundation-kit';

const customTheme = createTheme({
colors: {
primary: '#2563eb',
secondary: '#7c3aed'
},
typography: {
fontFamily: 'Roboto, sans-serif'
}
});

function App() {
return (
<ThemeProvider theme={customTheme}>
<YourApp />
</ThemeProvider>
);
}

Storybook Integration​

The UI Foundation Kit includes comprehensive Storybook documentation:

# Start Storybook
cd libs/ui-foundation-kit
npm run storybook

Storybook provides:

  • Interactive Examples: Try components with different props
  • Code Snippets: Copy-paste ready component usage
  • Design Tokens: Visual reference for colors, typography, spacing
  • Accessibility: Built-in accessibility testing

Development Workflow​

Adding New Components​

  1. Design: Create component designs following the design system
  2. Develop: Build the component with TypeScript and React
  3. Test: Write unit tests and accessibility tests
  4. Document: Create Storybook stories
  5. Review: Code review focusing on API design and accessibility
  6. Publish: Release as part of the Foundation Kit

Component API Guidelines​

  • Consistent Naming: Use clear, descriptive prop names
  • Type Safety: Leverage TypeScript for robust APIs
  • Accessibility: Include ARIA attributes and keyboard navigation
  • Customization: Allow theme overrides and custom styling
  • Performance: Optimize for bundle size and runtime performance

Best Practices​

  1. Composition: Build complex UIs by composing simple components
  2. Accessibility: Test with screen readers and keyboard navigation
  3. Performance: Use React.memo and lazy loading for large lists
  4. Consistency: Follow the established patterns and naming conventions
  5. Documentation: Keep Storybook stories up to date

This is a placeholder document. Detailed component documentation, design guidelines, and usage examples will be added as the UI Foundation Kit evolves.