Skip to main content

Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
UI Governance Guide

This guide defines enforceable frontend governance for GrantMaster. The goal is consistency through reuse, not redesign.

​
Scope

Applies to all feature UI in src/:
  • pages
  • feature components
  • workflow dashboards
  • extension surfaces integrated into the main app shell

​
Non-Negotiable Rules

  1. Use design-system primitives before building local UI.
  2. Prefer shared surface primitives (Surface*) for page-level structure.
  3. Keep feature code styling minimal and token-aligned.
  4. Route loading, empty, and error states through shared patterns.
  5. Treat lint warnings as migration work, not optional style notes.

​
Canonical Patterns

​
Controls

  • Use Button for actions and icon actions.
  • Use Input for all text-like fields.
  • Use design-system Select primitives (Select or SelectCompat) instead of raw controls.

​
Page and Surface Structure

  • Use PageLayout + PageHeader for page shells.
  • Use SurfaceSection, SurfaceToolbar, SurfaceMetricGrid, SurfaceNotice, and SurfaceEmptyState for recurring page structures.

​
Data States

  • Empty states use EmptyState or SurfaceEmptyState.
  • Loading states use SkeletonLoader presets or approved surface skeletons.
  • Error states use shared wrappers (DataStateWrapper, AsyncBoundary, or page-level standardized error treatment).

​
Status and Semantics

  • Use StatusBadge + mapDomainStatus for status chips.
  • Semantic tones map to:
    • info -> primary-*
    • success -> emerald-*
    • warning -> amber-*
    • danger/error -> rose-*

​
Spacing Baseline

Use one predictable rhythm:
  • xs: gap-1 / p-1
  • s: gap-2 / p-2
  • m: gap-3 / p-3 (or --page-group-gap)
  • l: gap-4 / p-4
  • xl: gap-6 / p-6 (or --page-section-gap)
Do not mix unrelated spacing values in the same surface unless required by component API constraints.

​
Lint Enforcement

Current custom lint rules enforce key governance constraints, including:
  • no raw button/input usage in design-system files
  • no mixed legacy token palette usage
  • no status badge bypass
  • warnings for plain-text empty states, ad-hoc pulse skeletons, and manual page <h1> usage
When adding new patterns, add a lint rule and documentation update in the same PR.

​
Governance Reporting Command

Run this command to generate a warning leaderboard for governance migration work: npm run lint:governance:report Outputs:
  • JSON report: tmp/eslint-phase1-governance.json
  • Markdown report: artifacts/ui-governance-warnings.md

​
PR Checklist

  • Reused existing component/surface primitives where possible
  • No new raw HTML controls where design-system equivalents exist
  • Empty/loading states use shared primitives
  • Colors and semantics use tokenized mapping
  • Page-level headings use PageHeader or SurfacePageHeader