# Finance UI Pattern Library

> Production UI patterns, design tokens, role-conditioned shells, drilldown primitives, reconciliation triage layout, print stylesheet patterns, status taxonomy components, and money-cell components for Chwezi finance and accounting products. Use when designing or building any finance / accounting screen, dashboard, report, print layout, mobile cashier flow, accountant ledger surface, reconciliation UI, close board, return-pack viewer, or audit-ready export across any consumer engine. Auto-load when the user requests UI / UX work that touches money, inventory, payroll, tax, banking, mobile money, POS, statutory compliance, or accounting records.

- Skill: `peterbamuhigire/finance-ui-pattern-library` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add peterbamuhigire/finance-ui-pattern-library`
- Raw SKILL.md: https://api.skillmd.com/api/skills/peterbamuhigire/finance-ui-pattern-library/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: peterbamuhigire (https://skillmd.com/u/peterbamuhigire)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/peterbamuhigire/finance-ui-pattern-library

---


# Finance UI Pattern Library

## Overview

This skill is the production reference for finance and accounting UI in the Chwezi system. It enforces the doctrine in `doctrine/references/design-system-finance-accounting.md`, `design-anti-patterns.md`, `role-conditioned-shell.md`, `status-taxonomy.md`, and `print-fidelity.md`. It provides design tokens, component contracts, lint rules, and worked examples.

## Required first reads

Before generating any finance UI:

1. `doctrine/accounting-finance-doctrine.md`
2. `doctrine/references/design-system-finance-accounting.md`
3. `doctrine/references/design-anti-patterns.md`
4. `doctrine/references/role-conditioned-shell.md`
5. `doctrine/references/status-taxonomy.md`
6. `doctrine/references/print-fidelity.md`
7. This skill's `references/tokens.md` and `references/components.md`.

## Scope

This skill applies to:

- Any HTML / CSS / React / Vue / Svelte / mobile-native finance UI.
- Print stylesheets.
- Email and notification finance-content templates.
- PDF report renderers.
- Dashboard tiles.
- Documentation / marketing pages that show product screenshots.

## Workflow

1. Identify the surface mode (workflow / ledger / auditor read-only / configuration).
2. Confirm the role(s) that will use the screen.
3. Pull the relevant component contracts from `references/components.md`.
4. Apply the tokens from `references/tokens.md`.
5. Add the role-conditioned shell wrapper.
6. Include the drilldown affordance on every money figure.
7. Apply the status taxonomy.
8. Add the print stylesheet for any report or evidence pack.
9. Run the lint script in `references/lint-checks.md` before merging.
10. Record a screenshot in the PR.

## Components shipped

The `references/components.md` file documents:

- `MoneyCell` — tabular numerals, currency code, sign colouring (signed columns only), drilldown.
- `NetTaxGrossTriplet` — three adjacent cells; never collapsed.
- `StatusChip` — uses controlled taxonomy; works in monochrome print.
- `PeriodChip` — top-bar period state chip.
- `EntityBookSwitcher` — multi-entity / multi-book switcher.
- `RoleSwitcher` — when the user has multiple roles.
- `EnvironmentBanner` — non-prod environment banner.
- `DrilldownBreadcrumb` — Report → Account → Journal → Line → Source → Evidence.
- `PostingForm` — net / tax / gross fields, evidence dropzone, audit-log preview.
- `ReconciliationTriage` — two-pane layout with centre actions and ageing.
- `LedgerGrid` — dense grid; keyboard-first; sticky headers and totals.
- `CloseBoard` — close tasks with owner, due, evidence, status.
- `ReturnPackViewer` — period selector, line mapping, source documents, evidence.
- `AuditExport` — read-only ledger with watermark.
- `PrintHeader`, `PrintFooter`, `SignOffBoxes`.
- `EvidenceDropzone` — inline on posting forms.

## Lint rules (excerpt)

The lint script in `references/lint-checks.md` rejects:

- `<button>` with destructive verb on a posted record.
- `text-green` / `text-red` / `bg-green` / `bg-red` outside semantic-state contexts.
- Money rendering without `font-variant-numeric: tabular-nums`.
- A summary tile without an `onClick` / `Link` affordance to source.
- A status string not matching the controlled taxonomy.
- A report page without `@media print` styles.

## What forbidden patterns are caught

This skill enforces 32 patterns from `design-anti-patterns.md` automatically; the remaining 26 require human review.

## Auto-loading

This skill is referenced from each engine's `AGENTS.md` "Finance & Accounting Trigger" block. When the request is UI-flavoured (HTML, CSS, JSX, mobile native code, screen mock, dashboard, report, print) and finance scope is detected, this skill is loaded automatically alongside the doctrine.

## Files

- `SKILL.md` — this file.
- `references/tokens.md` — token JSON and CSS variables.
- `references/components.md` — full component contracts.
- `references/lint-checks.md` — checklist and grep / AST patterns.
- `references/print-stylesheet-template.md` — copy-paste `@media print` template.
- `examples/cashier-record-sale.md` — full mock of a workflow-surface screen.
- `examples/ledger-trial-balance.md` — full mock of a ledger-surface screen.
- `examples/reconciliation-triage.md` — full mock of the reconciliation UI.

Last reviewed: 2026-05-12. Next review due: 2026-11-12.

## Prerequisites

- Load `doctrine/accounting-finance-doctrine.md` before applying this skill.
- Load `governance/finance-accounting-quality-gate.md` when the output is a release, client artefact, SRS, SDS, proposal, business plan, or implementation plan.
- Use `doctrine/source-register/` for final statutory, tax, payroll, FX, EFRIS, eTIMS, or authority-template values.

## Inputs

| Artifact | Produced by | Required? | Validation |
|---|---|---|---|
| Finance context map | `finance-module-audit` | Required | Entity, framework, jurisdiction, modules, users, and deployment context are named. |
| Doctrine baseline | Doctrine owner | Required | Doctrine version and reporting framework are stated. |
| Source-register snapshot | `tax-statutory-source-register-and-country-packs` | Required for final statutory output | Entries are `verified-current` or reviewer-approved `verified-with-caveat`. |
| Ledger/posting context | `ledger-posting-engine-core` | Required when postings are affected | Posting boundary, CoA mappings, control accounts, dimensions, and period state are known. |

## Outputs

| Artifact | Consumed by | Acceptance evidence |
|---|---|---|
| Skill-specific decision record | Implementer, reviewer, quality gate | Scope, assumptions, chosen treatment, rejected alternatives, and caveats are recorded. |
| Implementation or workflow contract | Software, SRS, SDS, proposal, or business-plan engine | Contract names inputs, outputs, controls, evidence, and failure conditions. |
| Acceptance evidence | Finance quality gate | Tests, fixtures, examples, source links, reviewer sign-off, or evidence-pack references are present. |
| Plain-language explanation | Client, owner, manager, operator | Business meaning is stated before technical accounting treatment where client-facing. |

## Decision Rules

- Prefer IFRS for SMEs for typical SME entities unless full IFRS, local law, donor requirements, or client policy requires otherwise.
- Treat every money-touching workflow as ledger, control, reconciliation, evidence, and reporting scope.
- Do not finalize statutory values without source-register support and reviewer status.
- Use business-language output for operators and accountant-language output for ledger, reporting, and audit users.
- Escalate uncertain framework, tax, or statutory interpretations to the required reviewer role instead of presenting them as final.

## Acceptance Evidence

- Inputs and outputs above are present or explicitly marked not applicable.
- Relevant quality-gate blockers have been checked and no blocker remains unresolved.
- Examples or fixtures cover at least one happy path and one failure or caveat path for this skill's domain.
- Reviewer role, review date, and open caveats are recorded for release-grade artefacts.

## Anti-Patterns

- Treating draft planning assumptions as final statutory or accounting facts.
- Hiding tax, payroll, FX, or authority-template caveats in prose instead of source-register state.
- Producing technically correct accounting output without a plain-language layer for non-accountant users.
- Closing a remediation or implementation item without observable evidence.

## Required References

- `doctrine/accounting-finance-doctrine.md`.
- `governance/finance-accounting-quality-gate.md`.
- `docs/reference-manifest.md` for declared reference states.
- Domain-specific references listed earlier in this skill.

## Examples

- Include at least one normal workflow example for this skill's domain.
- Include at least one exception, rejection, reversal, stale-source, or reviewer-caveat example where the domain can fail.

## Review Metadata

Last reviewed: 2026-05-15. Next review due: 2026-11-15.