\section{Source organization and reproducibility}
\textsf{gradbars} uses PGF/TikZ for inline data graphics. The editable runtime
modules live in \texttt{sty/}; the generated \texttt{gradbars.dtx} bundles the
same modules with this source guide. Generate it with
\texttt{texlua scripts/source.lua}. Check for drift with the
\texttt{--check} option. The \texttt{l3build check} target extracts every module using docstrip and
compares its contents with the runtime sources (line endings and trailing
whitespace are normalized).

Run \texttt{tex gradbars.ins} in the source archive directory, retaining its
\texttt{sty/README.md} directory marker. All 22 matching runtime modules are
extracted into \texttt{sty/}, not the source root; no shell escape is needed.
Plain \TeX{} cannot create a missing directory. Install the
complete set together. Run \texttt{pdflatex gradbars.dtx} from the repository
root for this guide; the illustrated bilingual manuals are built separately by
\texttt{l3build doc}. The default driver prints the guide
only. Replace \cs{OnlyDescription} with \cs{AlsoImplementation} in a working
copy to inspect the complete implementation with \textsf{l3doc}.

\section{Four responsibilities}
User commands and keys select data and scoped settings. The model validates
input, resolves shared scales, and produces normalized geometry. The TikZ
renderer draws paths and labels from that geometry. Integration modules manage
alternative text, table measurement and external formatting.

The model uses normalized positions in $[0,1]$ after the configured overflow
policy. It retains raw input separately. Zero, start, stop and endpoint are
not formatted labels. Projection to physical dimensions happens in the drawing
font context so that \texttt{em}/\texttt{ex} retain their established meaning.
The private \cs{\_\_gradbars\_render\_tikz:} function is the default backend
boundary, not a public callback. No second backend is supplied.

\section{Stable extension contract}
The public library, scalar type and numeric formatter registration commands
documented in \texttt{docs/stability.md} are stable in version 1.
Library registration is global and loading is confined to the preamble;
repeated loading is harmless. Type and formatter names cannot be replaced.
Scalar callbacks receive a validated number or \texttt{NA}. Formatter
callbacks receive a display number, precision and number format; the engine
appends units separately. Opaque formatters cannot participate in decimal
alignment. Private variables and functions are not covered by the contract.

\section{Validation and accessibility}
Run \texttt{l3build check} and \texttt{texlua scripts/check.lua} for semantic
and three-engine regression tests. Run \texttt{texlua scripts/pdf-check.lua}
on a current tagging-capable TeX distribution to verify Figure descriptions,
measurement suppression and table header spans/scopes using its pdfe library. Automatic alternative text does not establish PDF/UA
conformance for a complete table or document.

The optional \texttt{tblrlibgradbars.sty} is included in the same docstrip
source. With tabularray 2025C or newer, \verb|\UseTblrLibrary{gradbars}| loads
cell helpers and dedicated columns. Its public trial hooks suspend tagging
during measurement; fixed and X widths are tested in the PDF structure checks.

The Chinese and English manuals contain tutorials, option and library
references, rendered examples and source. The developer reference documents
the private data boundary; \texttt{docs/migration-v1.0.0.md} documents upgrade
and compatibility rules. The build and archive checks are separate, allowing
validation without creating a CTAN zip.

\section{Distribution and legend additions}
Optional \texttt{distribution} and \texttt{legend} libraries implement scoped
statistics and shared explicit visual configurations. Type-7 quantiles and
observed whiskers are separate from display formatting. Table tagging creates
logical rows before rendering; repeated tagged headers require LuaLaTeX and
become artifacts after the first page by default. An explicit describe mode
rebuilds each header with new marked content under the same logical cells.
Explicit multilevel header associations use actual structure IDs. See \texttt{docs/accessibility.md} for
limits, and \texttt{docs/migration-v1.1.0.md} for the complete matching runtime.

\section{Domain recipes and public backends}
The opt-in reports library packages correlation, ablation and metric layouts.
The backend module publishes scalar schema~1, capability negotiation and a
scoped native continuation while keeping model storage private. Compound
graphics require native rendering or an explicit fallback. The third-party
starter in \texttt{docs/libraries/starter/} includes public-only source, a
minimum-version guard, an example and a three-engine checker.