ui-guidelines - SKILL.md Agent Skill

name: ui-guidelines description: > HMIS UI development guidelines for JSF/XHTML pages. Use when creating or modifying XHTML pages, PrimeFaces components, page layouts, forms, buttons, panels, datatables, or any frontend/UI work. Covers page structure, layout patterns, panel best practices, form inputs, button styling, responsive design, and accessibility rules. user-invocable: true

HMIS UI Development Guidelines

When working on any UI/XHTML task, follow these rules and patterns.

Critical Rules

UI-ONLY CHANGES: When UI improvements are requested, make ONLY frontend/XHTML changes
KEEP IT SIMPLE: Use existing controller properties and methods - avoid introducing filteredValues, globalFilter, or new backend logic
FRONTEND FOCUS: Stick to HTML/CSS styling, PrimeFaces component attributes, and layout improvements
ERP UI RULE: Use h:outputText instead of HTML headings (h1-h6)
PRIMEFACES CSS: Use PrimeFaces button classes, not Bootstrap button classes
XHTML STRUCTURE: HTML DOCTYPE with ui:composition and template inside h:body
XML ENTITIES: Always escape ampersands as & in XHTML attributes

Page Skeleton

<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:h="http://xmlns.jcp.org/jsf/html"
      xmlns:p="http://primefaces.org/ui"
      xmlns:f="http://xmlns.jcp.org/jsf/core"
      xmlns:ui="http://xmlns.jcp.org/jsf/facelets">
<h:head>
    <title>Page Title</title>
</h:head>
<h:body>
    <ui:composition template="/resources/template/template.xhtml">
        <ui:define name="content">
            <h:form>
                <!-- Page content -->
            </h:form>
        </ui:define>
    </ui:composition>
</h:body>
</html>

Layout and Typography

Use PrimeFaces components for interaction and Bootstrap utilities for layout (row, col-*, d-flex, spacing)
Prefer p:panelGrid for grid with header; only use p:panel when you need facets/panel styling
Use h:outputText and p:outputLabel for headings/labels instead of HTML heading tags
Keep screens dense and business-focused

Panel Structure

Use f:facet name="header" for panel-related actions
Use p:panelGrid columns="2" layout="tabular" for label-value pairs
Avoid over-nesting; place dataTable directly in panel content

Forms and Inputs

Align labels with p:outputLabel + PrimeFaces components; include for attributes
Heavy operations (reports, exports) use ajax="false" for file downloads
Include descriptive title attributes on interactive elements

Buttons

Navigation: ui-button-info ui-button-outlined
Save/Submit: ui-button-success
Delete/Cancel: ui-button-danger
Secondary actions: ui-button-warning or ui-button-secondary
Always add icons: Use Font Awesome (fa fa-*) icons

For complete reference

Read developer_docs/ui/comprehensive-ui-guidelines.md for the full UI handbook including responsive design, accessibility, datatables, dialogs, and more.