Document vendored SVG sprite icons and offline binary assets

This commit is contained in:
mchus committed 2026-11-01 21:13:14 +03:00
1 parent 714447aa06
commit d8dab9bab5
3 files changed
+45 -2

No files matched your search

+5 -1
View File
@@ -1,6 +1,6 @@
# Contract: Application Binary
Version: 1.1
Version: 1.2
## Purpose
@@ -13,6 +13,10 @@ See `README.md` for deployment examples and a sample config template.
- When the agent deploys or runs commands on a host, the application lives in `/appdata/<appname>/`.
- Do not suggest alternate default install paths such as `/opt`, `/usr/local/bin`, or `~/`.
- The binary must be self-contained. Templates, static assets, config templates, and DB migrations are embedded with `//go:embed` or an equivalent application-owned mechanism.
- Startup and local UI operation must work without public internet access. Vendor and
embed all required third-party assets and code; do not require a CDN, remote font,
package download, package manager or separately installed UI library at runtime.
Configured remote data sources may require connectivity for their own operations.
- The application creates its config automatically on first run if it does not exist yet.
- Default config path:
- single-user mode: `~/.config/<appname>/config.yaml`
@@ -10,3 +10,20 @@ Canonical reference files (full, production version of the style) are in `assets
Do not maintain a separate "starter" copy of the CSS anywhere; `assets/view.css` is the
single source. For a new app, copy it and delete unused rules.
## Icon workflow
Choose a named icon from [Lucide](https://lucide.dev/icons/), copy its SVG
geometry into the project's shared sprite and retain the upstream license.
Preserve the paths; give the symbol a stable application action alias.
Render the symbol through the shared icon template, for example:
```html
<button class="icon-btn" title="Download diagnostic log" aria-label="Download diagnostic log">
{{template "icon" "scroll"}}
</button>
```
The icon template emits an SVG with a local `use href="#i-scroll"` reference.
The sprite, template and CSS ship inside the binary. The browser never fetches
Lucide or another asset host. Adding an icon does not add a runtime dependency.
+23 -1
View File
@@ -1,6 +1,6 @@
# Contract: Web Visual Baseline
Version: 1.1
Version: 1.2
## Scope
@@ -60,6 +60,28 @@ Copy `assets/view.css` as the starting stylesheet and adapt tokens; do not rewri
- Clear primary buttons for the main action on a screen.
- Simple alert/error boxes with border + tinted background.
## Icons and Offline Assets
- Use ready-made SVG icons from Lucide for new actions. Do not draw icon paths,
generate pictograms with AI, or mix icon families within the same interface.
Reuse the project's existing icon aliases and shared rendering helper.
- Vendor the SVG geometry and its license in the source tree. Record the icon
name and upstream source. Downloading an asset is a development step only.
- Collect icons in one local SVG sprite of named `symbol` elements. Render them
through one shared template/helper using `svg` and `use`; do not paste a new
SVG body into each button or page. Preserve the library's geometry.
- Use a 24 x 24 viewBox, `fill="none"`, `stroke="currentColor"`, stroke width 2,
round line caps and joins. Size and color come from shared icon/button CSS.
- An icon-only action needs both `title` and `aria-label`. Decorative SVGs have
`aria-hidden="true"` and must not receive keyboard focus.
- Embed all UI assets in the application binary: templates, scripts, styles,
icons, fonts and any third-party UI code. Go applications use `go:embed` and
serve these assets themselves. System fonts are allowed without downloads.
- The application and its UI must start and work without access to public
websites. No CDN, remote font, external icon service, package manager or
separately installed UI library may be a runtime prerequisite. Explicit
connections to configured application data sources are a separate concern.
## Data Formatting
- Money: no minor units (no cents/kopecks) — round to whole currency units for