ui-ux-design-system

UI/UX Design System Skill

Purpose

This skill defines the design system for the CIA platform, ensuring consistent Vaadin component usage, accessibility compliance, responsive design patterns, and a cohesive user experience for political data visualization. It provides reusable patterns for the web-widgets module.

When to Use This Skill

Apply this skill when:

• ✅ Creating new Vaadin views or components
• ✅ Modifying existing UI layouts or navigation
• ✅ Implementing data visualization dashboards
• ✅ Adding interactive political data charts
• ✅ Ensuring WCAG 2.1 AA accessibility compliance
• ✅ Designing responsive layouts for mobile devices
• ✅ Reviewing UI pull requests for consistency

Do NOT use for:

• ❌ Backend service logic without UI impact
• ❌ Database schema changes
• ❌ Build or deployment pipeline changes

Design Principles

1. Political Neutrality — UI must not favor any party through color, placement, or emphasis
2. Data First — Prioritize clarity of political data over decorative elements
3. Accessibility — WCAG 2.1 AA compliance for all components
4. Consistency — Reuse design system components, avoid one-off styling
5. Performance — Lazy load data, minimize DOM complexity
6. Responsive — Support desktop (primary), tablet, and mobile viewports

Component Library Patterns

Layout Components

// ✅ Standard page layout pattern
public class PoliticianOverviewView extends VerticalLayout {

    public PoliticianOverviewView() {
        setSizeFull();
        setPadding(true);
        setSpacing(true);

        // Page header with breadcrumb
        add(createPageHeader("Politician Overview"));

        // Content area with responsive grid
        HorizontalLayout content = new HorizontalLayout();
        content.setSizeFull();
        content.add(createFilterPanel(), createDataGrid());
        content.setFlexGrow(1, createDataGrid());
        add(content);
    }
}

Data Grid Pattern

// ✅ Consistent grid configuration
public Grid<PoliticianSummary> createPoliticianGrid() {
    Grid<PoliticianSummary> grid = new Grid<>(PoliticianSummary.class, false);

    // Column configuration with consistent ordering
    grid.addColumn(PoliticianSummary::getFirstName)
        .setHeader("First Name").setSortable(true).setAutoWidth(true);
    grid.addColumn(PoliticianSummary::getLastName)
        .setHeader("Last Name").setSortable(true).setAutoWidth(true);
    grid.addColumn(PoliticianSummary::getParty)
        .setHeader("Party").setSortable(true).setAutoWidth(true);
    grid.addColumn(new NumberRenderer<>(PoliticianSummary::getAttendanceRate,
        "%.1f%%")).setHeader("Attendance").setSortable(true);

    // Lazy loading
    grid.setPageSize(50);
    grid.setMultiSort(true);

    // Accessibility
    grid.getElement().setAttribute("aria-label", "Politician data table");

    return grid;
}

Chart Components

// ✅ Politically neutral color scheme for party charts
public static final Map<String, String> PARTY_COLORS = Map.of(
    "S", "#E8112d",    // Socialdemokraterna
    "M", "#52BDEC",    // Moderaterna
    "SD", "#DDDD00",   // Sverigedemokraterna
    "C", "#009933",    // Centerpartiet
    "V", "#DA291C",    // Vänsterpartiet
    "KD", "#000077",   // Kristdemokraterna
    "L", "#006AB3",    // Liberalerna
    "MP", "#83CF39"    // Miljöpartiet
);

// Always include party label, never rely on color alone (accessibility)

Notification Pattern

// ✅ Consistent notification usage
public class NotificationHelper {

    public static void showSuccess(String message) {
        Notification.show(message, 3000, Notification.Position.BOTTOM_START)
            .addThemeVariants(NotificationVariant.LUMO_SUCCESS);
    }

    public static void showError(String message) {
        Notification.show(message, 5000, Notification.Position.BOTTOM_START)
            .addThemeVariants(NotificationVariant.LUMO_ERROR);
    }

    public static void showInfo(String message) {
        Notification.show(message, 3000, Notification.Position.BOTTOM_START)
            .addThemeVariants(NotificationVariant.LUMO_PRIMARY);
    }
}

Responsive Design

Breakpoints

Responsive Pattern

// ✅ Responsive layout using Vaadin's FormLayout
FormLayout form = new FormLayout();
form.setResponsiveSteps(
    new FormLayout.ResponsiveStep("0", 1),     // Mobile: 1 column
    new FormLayout.ResponsiveStep("768px", 2),  // Tablet: 2 columns
    new FormLayout.ResponsiveStep("1024px", 3)  // Desktop: 3 columns
);

Accessibility Integration

WCAG 2.1 AA Requirements

// ✅ Accessible component patterns
public class AccessibleDashboard extends VerticalLayout {

    public AccessibleDashboard() {
        // Landmark roles
        getElement().setAttribute("role", "main");
        getElement().setAttribute("aria-label", "Political Dashboard");

        // Heading hierarchy
        H1 title = new H1("Dashboard");
        title.getElement().setAttribute("tabindex", "0");
        add(title);

        // Data tables with proper headers
        Grid<Data> grid = createGrid();
        grid.getElement().setAttribute("aria-label", "Voting records");

        // Charts with text alternatives
        Div chart = createChart();
        chart.getElement().setAttribute("aria-label",
            "Bar chart showing voting attendance by party");
        chart.getElement().setAttribute("role", "img");
    }
}

Accessibility Checklist

• ✅ Color contrast ratio ≥ 4.5:1 for normal text
• ✅ Color contrast ratio ≥ 3:1 for large text
• ✅ All interactive elements keyboard navigable
• ✅ ARIA labels on all custom components
• ✅ Form fields have associated labels
• ✅ Focus indicators visible (never outline: none)
• ✅ Skip navigation link for keyboard users
• ✅ Text alternatives for all charts and images
• ✅ Error messages associated with form fields
• ✅ No information conveyed by color alone

Naming Conventions

CSS Class Names

.cia-[component]-[modifier]

Examples:
.cia-dashboard-header
.cia-politician-grid
.cia-chart-container
.cia-filter-panel--collapsed
.cia-nav-item--active

View Class Names

[Entity][Action]View.java

Examples:
PoliticianOverviewView.java
CommitteeDetailView.java
VotingHistoryView.java
PartyComparisonView.java

Design System Governance

Adding New Components

1. Check if an existing Vaadin component meets the need
2. Check if a CIA design system pattern exists
3. If custom component needed, document in this skill
4. Include accessibility attributes from the start
5. Add responsive breakpoint handling
6. Write Playwright UI tests for the component

Component Review Criteria

• ✅ Follows existing design system patterns
• ✅ Uses standard CIA color scheme
• ✅ Meets WCAG 2.1 AA accessibility
• ✅ Responsive across all breakpoints
• ✅ Politically neutral presentation
• ✅ Lazy loads data for large datasets
• ✅ Has appropriate ARIA labels

References

• Vaadin Design System
• WCAG 2.1 Guidelines
• Vaadin Accessibility Guide
• Swedish Riksdag Party Information