# HUST Beamer

[![LaTeX CI](https://github.com/fusang991/hust-beamer/actions/workflows/latex.yml/badge.svg)](https://github.com/fusang991/hust-beamer/actions/workflows/latex.yml)

An unofficial Huazhong University of Science and Technology Beamer theme,
implemented as a coherent presentation system on top of
[Moloch](https://ctan.org/pkg/moloch).

> Status: preview (`v0.7.1`). The public commands may still change before the
> first stable release.

[View the compiled demonstration](https://github.com/fusang991/hust-beamer/blob/main/output/pdf/demo.pdf).
CTAN release archives also include a local copy at `example/demo.pdf`.

The theme targets 16:9 academic presentations and is tested with XeLaTeX and
LuaLaTeX. Ordinary slides separate a wide, compact title field from a narrower
inset reading field. School identity stays strong on the cover, section
dividers, and closing page, then steps aside around the argument.

## Design principles

- Use a `10 mm` physical safe grid for branded pages, then a deliberate
  `12 mm → 17 mm` title/body step on ordinary slides.
- Concentrate school identity on the cover, section dividers, and closing page;
  ordinary footers contain pagination only.
- Treat the cover, outline, section divider, content, and closing slide as
  distinct page families with shared typography and anchors.
- Reserve the darker structural blue for compact identity cues, pagination,
  navigation, and full brand pages. A separate brighter component blue appears
  only in primary box title bands; ordinary page titles stay neutral.
- Keep ordinary body headings, metrics, formulas, code, tables, and diagrams
  neutral. Colored box title bands are the explicit bounded exception.
- Reserve HUST red for alerts, failures, and corrective feedback.
- Keep cards flat and semantic. Prefer open rows, columns, tables, and diagrams
  when a filled panel is not doing useful work.
- Support Chinese-led, Chinese/English metadata without duplicating it on every
  slide.
- Bundle static vector renditions of the official HUST emblem and Chinese
  standard name; no runtime `hustvisual` installation is required.

The maintained visual rules are documented in [`DESIGN.md`](DESIGN.md).

## Ordinary-frame geometry

The standard frame is intentionally split into two spatial layers:

- title field: `x = 12 mm`, maximum width `136 mm`;
- section label and title occupy fixed vertical slots; frame subtitles are
  intentionally not rendered;
- no decorative rule appears below the title;
- body field: `x = 17 mm`, width `115 mm`;
- the first visible body content normally begins around `25–30%` of the page
  height.

The `5 mm` horizontal step and the air between the title field and body are
part of the master, not spacing that individual frames should cancel. For
fixed-width demo columns, keep the declared column widths at or below `110 mm`
in total so Beamer retains a useful inter-column gap.

## Color contract

Page blue belongs to the page skeleton, while the reference-derived component
colors are confined to compact box title bands. The theme enforces that rule
in its defaults:

- structural blue: frame label, page number, outline navigation, cover,
  section divider, and closing page;
- box components: bright blue for a primary title band, pink for a secondary
  title band, nearly neutral body washes, and gold first-level markers inside
  those boxes only;
- neutral content: page titles, ordinary headings, kickers, metrics, formulas,
  open-list markers, tables, code syntax, and self-authored diagrams;
- neutral surfaces: white, very light gray, pale box washes, and gray borders;
- semantic red: alerts and corrective feedback only.

Data graphics may define an independent palette when color encodes data, but
neither the structural blue nor the box blue may be reused as an automatic
series color.

## Installation

For project-local use, copy the five `*.sty` files and the complete `assets/`
directory into the root of your presentation project. You can then load the
theme normally:

```latex
\usetheme{hust}
```

To install the theme for your user account, locate your personal TeX tree:

```sh
kpsewhich -var-value=TEXMFHOME
```

Create `tex/latex/hust-beamer/` below that directory, then place the five
theme files and `assets/` inside it:

```text
TEXMFHOME/
└── tex/latex/hust-beamer/
    ├── beamerthemehust.sty
    ├── beamercolorthemehust.sty
    ├── beamerfontthemehust.sty
    ├── beamerinnerthemehust.sty
    ├── beamerouterthemehust.sty
    └── assets/
```

Run `mktexlsr` if your TeX distribution does not discover the new files
immediately.

## Requirements

- XeLaTeX or LuaLaTeX
- Beamer and Moloch
- `ctex` for Chinese presentations
- Fira Sans and Fira Mono

On a current TeX Live installation:

```sh
tlmgr install beamer moloch ctex fandol fira
```

The vector identity assets are included in [`assets/`](assets/). If that
directory is moved, point the theme to its new location:

```latex
\hustsetassetpath{path/to/assets}
```

## Minimal example

```latex
\documentclass[aspectratio=169,fontset=fandol]{ctexbeamer}

\usetheme{hust}

\setsansfont{Fira Sans}
\setCJKsansfont{FandolHei-Regular}[BoldFont=FandolHei-Bold]

\title{报告标题}
\subtitle{Presentation subtitle}
\author{张同学}
\institute{华中科技大学}
\date{\today}

\hustsetdepartment{人工智能与自动化学院}
\hustsetdepartmenten{School of Artificial Intelligence and Automation}
\hustsetevent{博士学位论文答辩}
\hustseteventen{PhD Dissertation Defense}

\begin{document}
\maketitle

\hustsetsectionnote{本章的一句话主张。}
\section{引言}

\begin{frame}{第一张内容页}
  Hello, HUST!
\end{frame}
\end{document}
```

## Cover image

The cover uses a `60 mm` HUST-blue identity field beside a quiet paper-colored
content field. An optional photograph can replace the base of the blue field:

```latex
\hustsetcoverimage[trim=0 8mm 0 8mm,clip]{figures/campus.jpg}
\maketitle
```

The image is center-cropped to the `60:90` identity field and receives a strong
blue overlay so the inverse brand remains readable. Portrait crops work best;
normal `graphicx` options such as `trim` and `clip` are forwarded unchanged.
Call `\hustclearcoverimage` to restore the solid-blue field.

## Core items and boxes

Lists and boxes use Beamer's native environments, so ordinary presentation
code receives the HUST styling without a custom component framework.

Use `itemize` for parallel claims and `enumerate` for an actual sequence.
First-level list markers are neutral and strong; nested levels become smaller
and quieter. The optional `\hustitem` helper creates a bold lead followed by a
muted supporting line and accepts normal Beamer overlay specifications:

```latex
\begin{itemize}
  \hustitem{结论先行}{每项先给观点，再补充一行依据。}
  \hustitem<2->{层级克制}{次级信息只补充条件或例外。}
\end{itemize}
```

Boxes use two recurring split-band visual families. Both join a narrow title
band directly to a pale reading surface and remain square, flat, borderless,
and shadow-free:

```latex
\begin{block}{核心信息与结论}
  Primary explanation, comparison, summary, or future work.
\end{block}

\begin{exampleblock}{定义、公式与局部强调}
  A model, formula, evidence region, or secondary emphasis.
\end{exampleblock}

\begin{alertblock}{风险与失败}
  A real limitation, warning, or failure state.
\end{alertblock}
```

`block` uses the bright-blue title band; `exampleblock` uses the pink title
band. `alertblock` stays in the pink family but switches its title and marker
to semantic red, so pink alone never means warning. Box titles and bodies use
a restrained Roman/Song voice, while first-level bullets use the local gold
marker seen in the reference. Open lists outside boxes remain neutral.

A slide normally needs no more than one primary box or two related compact
boxes. Do not alternate blue and pink merely for decoration.

## Public commands

| Command | Purpose |
| --- | --- |
| `\hustsetdepartment{...}` | Chinese unit name on the cover |
| `\hustsetdepartmenten{...}` | English unit name on the cover |
| `\hustsetdepartmentshort{...}` | Legacy unit alias retained for source compatibility; not rendered in ordinary footers |
| `\hustsetevent{...}` | Chinese presentation type above the cover title |
| `\hustseteventen{...}` | English presentation type above the cover title |
| `\hustsetsectionnote{...}` | One-sentence claim on the next section divider |
| `\hustsetcoverimage[...]{...}` | Set the optional cover photograph |
| `\hustclearcoverimage` | Restore the solid-blue cover identity field |
| `\hustsetassetpath{...}` | Set the directory containing vector assets |
| `\hustsetlogo{...}` | Override the automatic emblem |
| `\hustbrandmark[height]` | Render the active emblem |
| `\hustbrandmarkinverse[height]` | Render the inverse emblem |
| `\hustwordmark[width]` | Render the blue Chinese standard name |
| `\hustwordmarkinverse[width]` | Render the white Chinese standard name |
| `\hustkicker{...}` | Render a compact neutral editorial label |
| `\hustitem{title}{note}` | Render a two-level item inside a native list |
| `\hustmetric{value}{label}` | Render an open metric with supporting evidence |
| `hustoutlinepage` | Structured outline environment |
| `\hustoutlineitem{number}{title}{note}` | Numbered outline or conclusion row |
| `\hustclosing{title}{subtitle}{detail}` | Closing content on a standout frame |

`\hustsetsectionnote` is one-shot: place it immediately before the relevant
`\section`. Keep the optional outline-page title to one short line, and use the
environment inside a plain, top-aligned frame:

```latex
\begin{frame}[plain,t]
  \begin{hustoutlinepage}
    \hustoutlineitem{01}{问题与目标}{一句话说明}
    \vspace{2mm}
    \hustoutlineitem{02}{方法}{一句话说明}
  \end{hustoutlinepage}
\end{frame}
```

## Build

From the repository root:

```sh
latexmk -xelatex example/demo.tex
latexmk -lualatex example/demo.tex
```

The compiled example is written to `output/pdf/demo.pdf`.

To clean intermediate build files:

```sh
latexmk -c example/demo.tex
```

## Support

Report reproducible problems and feature requests through
[GitHub Issues](https://github.com/fusang991/hust-beamer/issues). Include the
TeX engine, TeX Live version, a minimal source example, and the relevant log
excerpt.

Maintainer: Wang Yang (王阳).

## Branding and license

This is an unofficial community project and is not endorsed or maintained by
Huazhong University of Science and Technology. Follow the
[official HUST visual identity guidelines](https://vi.hust.edu.cn/) when using
school marks and identity assets.

Theme code is released under CC BY-SA 4.0. See [LICENSE](LICENSE) and
[NOTICE.md](NOTICE.md). HUST names, emblems, wordmarks, and other institutional
identity elements are expressly excluded from that license grant and remain
subject to the rights and policies of their respective rights holders.