Repository navigation
Finish reproducible brand manual and release process #3
Description
The LibreCode manual is authored in Typst and built reproducibly in CI.
Completed baseline
- Typst selected and documented in ADR
-
manual/main.typis canonical source - local build command documented
- CI build with exact Typst 0.15.1 pin
- PDF/UA-1 build target
- generated PDF uploaded as GitHub Actions artifact
- release workflow added for
v*tags - release workflow publishes manual PDF, SVG, PNG, PDF logo derivatives, and SHA256SUMS
- canonical artwork and deterministic derivative generation baseline
- basic visual manual structure exists
Completion work
Use PR #8 / docs/libresign-parity-plan.md as the implementation checklist.
Editorial
- add/how-to-use page and clarify scope
- review LibreCode-specific purpose, audience, positioning, and messaging
- document free-software values in practical language
- document cooperative identity/community participation
- expand voice and tone
- add partner/third-party use guidance
- review licensing, trademark, ownership, and official-source language
- use plain, direct Portuguese and avoid unnecessary jargon
Logo and technical diagrams
- confirm approved logo variants and formats
- refactor clear-space geometry so canonical SVG -> deterministic Python technical SVG -> Typst composition only
- remove cross-brand/dead Typst code
- confirm minimum-size rules from LibreCode-specific evidence
- add approved correct/incorrect-use examples
Typst maintainability
- replace positional TOC tuple indexes with named fields
- adopt Typstyle through
typstyle-rs/typstyle-action, pinned to full SHA - document Tinymist as recommended editor diagnostics/linter
- keep exact Typst compiler version for reproducible output
- document source-maintenance conventions
PDF accessibility
- semantic cover/document title
- semantic heading hierarchy
- linked table of contents
- PDF bookmarks
- page-top TOC destinations
- meaningful image alt text
- decorative section numbers marked as artifacts
- correct document language and reading order
- validate PDF/UA-1 independently with veraPDF
- perform human visual/accessibility review
CI and repository quality
- pin all third-party GitHub Actions to full commit SHAs with version comments
- make
scripts/check_brand.pyenforce Action pins - configure grouped weekly Dependabot updates for
github-actions - rely on the DCO GitHub App for sign-off enforcement
- preserve REUSE and brand quality checks
Licensing and publication
- add root
LICENSEwith exact CC BY-SA 4.0 text - clarify README multi-license scope
- remove placeholder
examples/if examples live directly in the manual - establish/verify mutable
latestdevelopment prerelease - visually inspect the generated manual page by page
Release gate
The manual may be used during development/homologation through the mutable latest release.
Do not create the first stable v1.0.0 simply because the manual is usable.
Before v1.0.0:
- complete external homologation/review
- incorporate accepted feedback
- verify Verify and document trademark registrations #4 registration documentation
- verify Apply canonical repository metadata #6 repository metadata
- ensure all CI/accessibility checks pass
- prepare a fresh release PR from the then-current
main - create and verify the versioned release
Distribution contract
- Git/Typst source is canonical.
- Normal CI builds expose the PDF as a temporary Actions artifact.
latestis the mutable development/homologation release.- Tagged
v*releases are permanent approved versions.
Metadata
Metadata
Assignees
Labels
No labels
Activity
vitormattos commentedon Sep 24, 2026
Toolchain decision recorded in
docs/decisions/0001-manual-toolchain.md: Typst is the accepted initial publishing stack. A minimalmanual/main.typand GitHub Actions build workflow are now in place; the remaining work is migrating and validating the complete historical manual content/assets.vitormattos commentedon Sep 24, 2026
Historical manual audit completed. The source PDF/AI-compatible document has 24 pages and covers construction grid, primary version, Pantone/CMYK/RGB colors, protection area, Krona One, 20 mm minimum reduction, color/monochrome/black applications, misuse, stationery, email signature, email marketing, and support imagery.
Important migration correction: the existing "Concepção da Marca" page is placeholder Lorem Ipsum. The new Typst manual must use the approved current brand story instead of reproducing that page.
[-]Create reproducible open-source brand manual[/-][+]Finish reproducible brand manual and release process[/+]vitormattos commentedon Sep 24, 2026
Editorial redesign implemented. Both brand manuals now share the same content architecture and editorial engine (
manual/components.typ), whilemanual/theme.typcontains brand-specific color, typography, and motif tokens. Official open-source fonts are vendored from Google Fonts under OFL-1.1 and used via--font-path source/fonts. The manuals now include full-page section openers, branded covers/back covers, logo construction/composition, primary/reversed applications, color swatches, typography specimens, clear-space guidance, minimum-size guidance, accessibility, and governance. The shared structure is documented indocs/manual-content-contract.md; open Typst reference implementations are documented in ADR 0002. Builds, Brand quality, and REUSE are passing. The remaining work in this issue is final visual QA of the latest PDFs and any last art-direction refinements before the first versioned release.vitormattos commentedon Sep 24, 2026
Visual QA pass completed against the original manual and the rendered PDF. Fixed logo framing/cropping, typography specimen line breaks, explicit clear-space construction, duplicate application markup, and clickable back-cover URL. Clear-space rules are now normative in
guidelines/visual-identity.mdas well as illustrated in the PDF. PDF/UA manual build, Brand quality, and latest publication all passed for the refined manual source.vitormattos commentedon Sep 24, 2026
Asset/manual pipeline overhaul completed. The repository now has one editable canonical
*-master.svg, one machine-readablesource/artwork/brand-assets.json, and a singlescripts/build_assets.pyused by local builds, asset CI, manual CI, the continuouslatestrelease, and versioned releases. Inkscape--export-area-drawingcomputes the real drawing bounds; safe framing, primary/reversed/monochrome variants, PNG/PDF/SVG exports, and clean-space reference glyph crops are deterministic outputs. The manual consumes only generated assets frombuild/assets/, never hand-edited derivatives. LibreCode clean space is now bound to the width of the actual D glyph from the wordmark; LibreSign uses the actual E glyph from the wordmark as the non-interference module. Visual QA confirmed the LibreCode page-7 clipping is gone and both clean-space pages use the measured canonical geometry. Current Build brand manual, Brand quality, REUSE, and Publish latest brand build workflows are green.vitormattos commentedon Sep 25, 2026
Clear-space construction was refined again using the original designer manuals as the visual reference. LibreSign now uses the actual E extracted from the wordmark as the guide glyph, recolored automatically by the asset generator; top/bottom E remain upright, side E are rotated, and all four are centered on the dashed exclusion boundary. LibreCode now shows the actual D reference explicitly as the source of X, then applies X around the mark between the inner artwork frame and outer protection frame. Both pages are generated from the canonical master via
scripts/build_assets.py; no manual derivative editing is involved. Latest PDF build, Brand quality, REUSE, and latest publication are green, and page 13 was visually inspected after rendering.vitormattos commentedon Sep 25, 2026
Implementation update:
These changes preserve the existing LibreCode-specific visual rules and do not introduce new brand decisions.
vitormattos commentedon Sep 25, 2026
Manual completion work is now fully checked off. Current
mainis347aada2c6cef901b0796377054c411822a3fd4f; CI andlatestpublication are green, and the 30-page final manual has been visually reviewed. This issue remains open only for the stable-release gate: external homologation/feedback, #4, #6, fresh release verification, and explicit stable-release approval.vitormattos commentedon Sep 25, 2026
The manual and repository are now ready for external homologation. #4 and #6 are complete, the verified trademark facts are merged, the final manual build/accessibility pipeline is green, and
docs/external-homologation.mddefines the review process. No stable release has been created. Remaining unchecked items are the external-review/accepted-feedback/stable-release steps by design.vitormattos commentedon Sep 25, 2026
Follow-up manual QA merged in #18 after external inspection found two presentation problems: the clear-space diagram was not expressing the D reference correctly, and some brand-manual prose leaked repository/build implementation details. Both are corrected; a visual misuse page was also added, and the clear-space generator is now unit-tested.