DEV Community

川口晃世（Kosei Kawaguchi）
川口晃世（Kosei Kawaguchi）

Posted on

Engineering a Japanese Exam-Prep Handout with LuaLaTeX and tcolorbox

#tutorial #design #academic #japan

Measured headers, drawing layers, and page-break states for a dense three-page mathematics booklet.

Hi, I'm KKTeX. I publish LaTeX packages on CTAN and maintain a private toolkit for producing books and teaching materials.

In the shorter companion article, I treated a Japanese exam-preparation handout as information design. This article opens the implementation.

The result is a three-page LuaLaTeX document:

Page 1 of the technical handout

Page 2 of the technical handout

Page 3 of the technical handout

The design is original. Tetsuryokukai is a useful public reference point for Japan's highly selective juku—private after-school education—culture, but this is not a reproduction of its material, and I am not claiming that it uses TeX. The organization publicly describes itself as a University of Tokyo preparation school for students in six-year secondary programs (official profile). The wider social context is also substantial: the OECD describes private after-school lessons as a pervasive part of Japanese education (OECD overview).

The technical problem is independent of any one institution:

How do we build a compact visual language that remains stable when titles change, solutions grow, and boxes cross pages?

The frame grammar grows from two families in my private toolkit: ascolorbox4, which cuts a rule with its title and combines different rail styles, and later ornate-frame experiments with explicit corner geometry. I call this production variant the Rinceau Frame / 唐草額. It keeps the dotted outer boundary, title interruption, inward quarter-circle corners, and four terminals of ascolorbox4, then rebuilds the terminals as compact C-scroll and palmette ornaments. The result deliberately looks like a Western book frame, but the ornament remains outside the mathematics.

I will focus on four implementation decisions, followed by two editorial ones.

1. Model pedagogical roles, not appearances

The document does not contain a generic FancyBox. It contains components named after their jobs:

\LessonHeading{11}{LECTURE}{A Moving Minimum}

\begin{DrillBox}
  {PROBLEM 18}{Quadratic Optimization}[3]
  ...
\end{DrillBox}

\begin{StrategyBox}
  ...
\end{StrategyBox}

\begin{SolutionBox}{SOLUTION}
  ...
\end{SolutionBox}

\begin{KeyPointBox}{STRUCTURAL MAP / 見通し}
  ...
\end{KeyPointBox}
Enter fullscreen mode Exit fullscreen mode

This matters when a book grows.

If an editor later decides that every strategy should use a left rule instead of a filled background, the content files do not change. If every problem needs a difficulty marker, the DrillBox interface already has one.

The markup carries semantics; the style file carries the visual system.

The implementation uses \DeclareTColorBox rather than a collection of copied \newtcolorbox definitions. Its xparse-style argument specification gives each component a small, explicit interface:

\DeclareTColorBox{DrillBox}{m m O{2} O{}}{
  ...
}
Enter fullscreen mode Exit fullscreen mode

Here:

  • the first mandatory argument is the problem number;
  • the second is the topic;
  • the first optional argument selects the 基礎 / 標準 / 発展 level;
  • the final optional argument accepts ordinary tcolorbox overrides.

2. Preserve a grammar, not a screenshot

The design started by treating ascolorbox4 as a set of invariants:

  1. the title cuts the top rail;
  2. a dotted boundary sits outside a solid rail;
  3. every corner turns through an inward quarter-circle;
  4. every corner has a visible terminal.

For the Western vocabulary, I studied public-domain museum material rather than tracing a modern border. The Metropolitan Museum's ornamental designs show scrolling acanthus, palmettes, garlands, and pearl strips; Cooper Hewitt's catalog describes frame designs built from rinceaux, flowers, scrolls, shells, rosettes, and bead-like rails (Met example, Cooper Hewitt frame design, Cooper Hewitt ornament album). I reduced that vocabulary to one mirrored C-scroll and a three-leaf palmette small enough for a study booklet.

The title is attached to the frame instead of positioned with an absolute coordinate:

attach boxed title to top left={
  xshift=10mm,
  yshift=-\tcboxedtitleheight/2
},
boxed title style={
  colback=white,
  colframe=white,
  boxrule=0pt,
  left=2mm,
  right=2mm
},
borderline={.55pt}{2.7pt}{ehBlue,dotted},
Enter fullscreen mode Exit fullscreen mode

The white title field is not a badge pasted over the frame. It is a controlled interruption: the solid and dotted rails disappear behind it, then resume at title.east.

The main rail is a single path:

\draw[ehAccent,line width=.72pt,
      line cap=round,line join=round]
  ([xshift=2mm]title.east|-frame.north east)
  --([xshift=-7mm]frame.north east)
  arc[start angle=180,end angle=270,radius=7mm]
  --([yshift=7mm]frame.south east)
  arc[start angle=90,end angle=180,radius=7mm]
  --([xshift=7mm]frame.south west)
  arc[start angle=0,end angle=90,radius=7mm]
  --([yshift=-7mm]frame.north west)
  arc[start angle=270,end angle=360,radius=7mm]
  --([xshift=-2mm]title.west|-frame.north west);
Enter fullscreen mode Exit fullscreen mode

A second, thinner antique-gold path is inset by 2 mm. That pair reads as picture-frame molding. The outer dotted borderline preserves the lighter rail contrast of ascolorbox4.

This follows a principle I use throughout my Japanese Qiita articles:

If an ornament depends on a box, derive it from the box. If it depends on a title, derive it from the title.

The geometry can therefore survive a new title, a taller solution, or a different page width.

3. Put each line on the correct drawing layer

An advanced tcolorbox is easier to reason about as a layer stack:

finish
overlay
content
underlay
interior
frame
shadow
Enter fullscreen mode Exit fullscreen mode

The title box has its own corresponding layers.

The navy rail, gold inset molding, and four ornaments belong in the underlay: they must sit below the mathematics. The difficulty marker belongs in an overlay, because its white field intentionally knocks out a small portion of the top rail.

\DeclareTColorBox{DrillBox}{m m O{2} O{}}{
  enhanced,
  breakable,
  empty,
  sharp corners,
  title={#1\hspace{2.2mm}
    {\color{ehGold}/}\hspace{2.2mm}#2},
  left=9mm,
  right=9mm,
  top=5mm,
  bottom=5mm,
  borderline={.55pt}{2.7pt}{ehBlue,dotted},
  underlay unbroken={\ehFrameUnbroken},
  underlay first={\ehFrameFirst},
  underlay middle={\ehFrameMiddle},
  underlay last={\ehFrameLast},
  overlay unbroken and first={
    % the 基礎 / 標準 / 発展 marker
  }
}
Enter fullscreen mode Exit fullscreen mode

empty removes the default skin. The component then draws only the parts of the selected grammar:

  • one rounded solid rail;
  • one thinner inset molding;
  • one dotted offset boundary;
  • one title interruption;
  • four C-scroll and palmette terminals;
  • a 基礎 / 標準 / 発展 level chip.

This avoids a common failure mode: drawing a custom frame on top of a default frame and then chasing tiny disagreements in corner radius and line position.

4. A breakable box has four drawings

The solution box is allowed to grow. Therefore it cannot have one frame path.

tcolorbox exposes four states:

unbroken  one-page box
first     first fragment of a broken box
middle    intermediate fragment
last      final fragment
Enter fullscreen mode Exit fullscreen mode

The fragment drawings are assigned accordingly:

underlay unbroken={\ehFrameUnbroken},
underlay first={\ehFrameFirst},
underlay middle={\ehFrameMiddle},
underlay last={\ehFrameLast},
Enter fullscreen mode Exit fullscreen mode

The first fragment draws the title, top corners, and vertical continuations. A middle fragment draws only two pairs of vertical rails. The last fragment draws the bottom corners and closes the frame.

\newcommand{\ehFrameLast}{%
  \draw[ehAccent,line width=.72pt,
        line cap=round,line join=round]
    (frame.north east)
    --([yshift=7mm]frame.south east)
    arc[start angle=90,end angle=180,radius=7mm]
    --([xshift=7mm]frame.south west)
    arc[start angle=0,end angle=90,radius=7mm]
    --(frame.north west);
  \ehFrameBottomCorners
}
Enter fullscreen mode Exit fullscreen mode

The direction of those arcs matters. The last fragment is traced from the right edge to the left edge, matching the angle sequence used by the original ascolorbox4. Reversing the path without also reversing the angles makes the bottom rail leave the corner diagonally—a defect that can hide in a one-page test and appear only after a forced page break.

On the middle fragment, there are no fake corners and no repeated ornament. Treating the four states as separate drawings is not an optimization. It is the correct model.

5. Keep visual weight scarce

The page uses eight named colors, each with a narrow role:

\definecolor{ehInk}{HTML}{202428}
\definecolor{ehMuted}{HTML}{667085}
\definecolor{ehLine}{HTML}{AEB5BF}
\definecolor{ehPale}{HTML}{F3F4F6}
\definecolor{ehAccent}{HTML}{34435F}
\definecolor{ehBlue}{HTML}{8292AE}
\definecolor{ehGold}{HTML}{A37B3C}
\definecolor{ehVermilion}{HTML}{B4442E}
Enter fullscreen mode Exit fullscreen mode
  • ehInk carries mathematics and hard structure;
  • ehAccent carries navigation and the main frame rail;
  • ehBlue carries the dotted offset boundary;
  • ehGold carries the inset molding and palmette leaves;
  • ehLine remains available for quiet separators;
  • ehPale is limited to secondary label fields.
  • ehMuted carries running metadata;
  • ehVermilion appears only in advanced-level and answer signals.

The point is not to make every component visibly different. The point is to make different components recognizable without making the page compete with itself.

6. Design the return visit

The third PDF page is a review page, not another full solution.

Its prompts ask:

  • What does “for every real x” become?
  • Which variable is currently being optimized?
  • Do strict inequalities exclude the endpoints?
  • Is the claimed maximum attained?

This is a typesetting decision as much as a teaching decision. A weekly booklet is a retrieval system. Numbering, labels, and stable component shapes help a student find a previous method quickly.

That is why a dense handout can benefit from stronger visual structure than a conventional textbook chapter.

Compilation environment

I compiled the specimen with LuaLaTeX and ltjsarticle. When recreating the example from these excerpts, place the component definitions in exam-handout.sty beside technical-handout.tex, then run:

lualatex -interaction=nonstopmode -halt-on-error technical-handout.tex
Enter fullscreen mode Exit fullscreen mode

The example uses ltjsarticle, matching my Japanese material workflow. The visible content is mostly English, but the component labels can contain Japanese micro-labels such as 要点 and 見通し without changing the geometry.

The box system is built on tcolorbox, whose current CTAN release supports framed boxes, split content, and breakable material.

Two tools from the same desk

Disclosure: these are my projects.

Evolton converts a photographed mathematics problem into a polished solution PDF. It is useful when the finished explanation needs the visual discipline of a reference book.

Evolton interface and solution-PDF examples

MathHover keeps formula entry close to the cursor, so mathematical writing does not have to pause for a separate editor.

MathHover formula panel showing a completed limit and integral

The deeper lesson is simple: a teaching-material style should not be a collection of attractive boxes. It should be a small visual language whose components survive the text ranges and page lengths they were designed for—and expose clear guard rails when content exceeds them.

Top comments (0)