Warm paper, forest green, and restrained terracotta for technical articles, evidence-led reports, knowledge cards, and architecture diagrams.
English · 中文
An agent skill and reusable static design kit. No build step or runtime dependency for everyday use.
## Table of contents - [What is it?](#what-is-it) - [Why use it?](#why-use-it) - [Core concepts](#core-concepts) - [Structure](#structure) - [Quick start](#quick-start) - [Features and use cases](#features-and-use-cases) - [Configuration](#configuration) - [Integration and extension](#integration-and-extension) - [Safety and evidence boundaries](#safety-and-evidence-boundaries) - [FAQ](#faq) - [Achieved roadmap](#achieved-roadmap) - [Contributing](#contributing) - [License](#license) - [Maintainer role](#maintainer-role) ## What is it? Forest Editorial Design 1.0.0 is a collection of agent instructions, CSS tokens and components, four HTML templates, and offline examples. Use it when you explicitly want this editorial theme—not as a general frontend framework or a rule that every green interface should follow. The kit emphasizes readable Chinese technical content, continuous article prose, explicit evidence, and clear limitations. It also works without an agent: open the HTML files or reuse the CSS directly. The nine HTML pages—five examples and four templates—use local resources and system font fallbacks. The README's decorative badges are embedded as self-contained SVGs and render without any network dependency; the HTML pages do the same. Three original reference images are **not distributed** because redistribution permission has not been established. Historical numeric CSV/JSON sampling records remain available; they do not make the original inputs publicly available or independently reproduce the image measurements. See [NOTICE.md](NOTICE.md) and [color provenance](references/color-provenance.md). ## Why use it? | Common problem | An ad hoc approach | This kit's approach | |---|---|---| | Articles, reports, and diagrams drift visually | Restyle each page separately | Shared semantic tokens and component CSS | | Decorative cards fragment a long explanation | Put every paragraph in a panel | Continuous prose, with selective emphasis | | A polished report appears to certify its data | Show unlabeled demonstration metrics | Preserve scope, status, sources, and limitations | | Sharing a page depends on hosted fonts or scripts | Assume the reader is online | Local CSS, system fonts, and rendered SVG | | Palette claims lack provenance | Treat every sampled pixel as a design token | Separate observations, historical summaries, and recommendations | **The goal is consistent presentation without making the underlying evidence appear stronger than it is.** ## Core concepts - **Editorial hierarchy:** section label → title → context → main content → conclusion and limitations → sources. - **A small visual vocabulary:** forest `#193C35`, page `#F5F2EA`, card `#FCFAF6`, sage `#E7EDD9`, and restrained terracotta `#A35436`. Fine borders and whitespace replace decorative shadows. - **Semantic tokens over raw colors:** `--fe-bg-page`, `--fe-text`, and related variables describe intended roles. `--fe-raw-*` records observed or historical palette values, not universal text-color recommendations. - **Readable text:** the recommended body, secondary, and accent text tokens are darker than some historical palette colors. Supported contrast-pair checks are not whole-page accessibility certification. - **Evidence has levels:** historical decoded pixel statistics, inferred design choices, and implementation recommendations are different claims. A bitmap cannot prove a source font, original design-file color, or business result. ## Structure ```text forest-editorial-design/ ├── README.md ├── README.zh-CN.md ├── INSTALL.md ├── CONTRIBUTING.md ├── SECURITY.md ├── LICENSE ├── NOTICE.md ├── SKILL.md ├── VERIFICATION.md ├── MANIFEST.sha256 ├── agents/ │ └── openai.yaml ├── assets/ │ ├── design-tokens.css │ ├── components.css │ ├── architecture-mermaid.svg │ └── sampling/ │ ├── samples.json │ ├── reference-01-all-colors.csv │ ├── reference-02-all-colors.csv │ └── reference-03-all-colors.csv ├── references/ │ ├── design-spec.md │ ├── typography.md │ ├── components.md │ ├── layouts.md │ ├── diagrams.md │ └── color-provenance.md ├── templates/ │ ├── article.html │ ├── report.html │ ├── cards.html │ ├── architecture.html │ └── architecture.mmd ├── examples/ │ ├── index.html │ ├── article.html │ ├── report.html │ ├── cards.html │ └── architecture.html └── scripts/ ├── validate.py └── sample_colors.py ``` This tree focuses on the reusable kit and its public documentation; release-administration files may also be present. | Path | Responsibility | |---|---| | `SKILL.md`, `agents/openai.yaml` | Agent workflow, theme boundaries, and selector metadata | | `assets/design-tokens.css`, `assets/components.css` | Palette, typography, spacing, components, responsive and print styles | | `assets/architecture-mermaid.svg` | Pre-rendered diagram for offline reuse | | `assets/sampling/` | Historical numeric evidence: RGB histograms and regional measurements | | `references/` | Detailed design, layout, typography, diagram, and provenance guidance | | `templates/`, `examples/` | Four content patterns, a gallery, and Mermaid source | | `scripts/validate.py` | Python standard-library public-package validation | | `scripts/sample_colors.py` | Optional resampling of separately supplied authorized images | | `MANIFEST.sha256`, `VERIFICATION.md` | File-integrity inventory and recorded verification scope | | `INSTALL.md`, `CONTRIBUTING.md`, `SECURITY.md` | Installation, change workflow, and safe vulnerability reporting | | `LICENSE`, `NOTICE.md` | MIT terms and rights/provenance boundaries | There is intentionally no public `assets/references/` image directory. ## Quick start ### Requirements | Task | Requirement | |---|---| | View or reuse pages | A modern browser; no dependency installation or build | | Use as an agent skill | An agent that supports this skill format; installation/discovery is host-specific | | Validate the package | Python 3.9+; standard library only | | Resample colors, optionally | `uv`, its script-compatible Python runtime, and the pinned Pillow dependency declared in the sampling script; first use may need network access | ### 1. Open the gallery Extract the source archive into a new folder, then open [examples/index.html](examples/index.html) in a browser. Keep `examples/`, `templates/`, and `assets/` in their existing relative positions. No local web server is necessary. The source ZIP is named `forest-editorial-design.zip` and contains a top-level `forest-editorial-design/` directory. This is a source/skill archive, not a Python wheel or an installed service. See [INSTALL.md](INSTALL.md) for portable extraction and optional user-level skill installation without overwriting an existing copy. ### 2. Validate the extracted source From the package root: ```sh python3 -B scripts/validate.py ``` The validator is designed to check public-package structure, local references, CSS tokens, supported contrast pairs, numeric evidence consistency, and the SHA-256 manifest **without the omitted images**. A successful run exits with status 0 and a `PASS` summary; failures need investigation. This command does not certify browser rendering, agent discovery, image rights, or independent reproduction of the historical image measurements. Actual recorded checks and their limitations belong in [VERIFICATION.md](VERIFICATION.md). ### 3. Use the skill or a template After optional skill installation, ask your agent: ```text Use $forest-editorial-design to turn the following technical retrospective into offline-readable HTML. Preserve every fact, limitation, and source. Do not invent missing results. Keep example data labeled as examples. ``` Without an agent, start from `templates/article.html`, `report.html`, `cards.html`, or `architecture.html` and replace the demonstration content with your own material. ## Features and use cases | Use case | Start here | Content to preserve | |---|---|---| | Technical article | [Article template](templates/article.html) | Context, continuous reasoning, sources, and limitations | | Test or evaluation report | [Report template](templates/report.html) | Scope, environment, sample, actual execution status, assertions, and evidence | | Knowledge or insight card | [Card template](templates/cards.html) | One core point, a short sequence, source, and qualification | | Architecture or process | [Architecture template](templates/architecture.html) | Nodes, edges, direction, conditions, feedback, legend, and boundaries | | Theme overview | [Offline gallery](examples/index.html) | Palette and component demonstrations—not production results | The templates are filled layout examples, not blank forms. Replace their titles, prose, metrics, and source notes; retain an explicit example label until real evidence is supplied. Cards use 1080px as a working image-width recommendation, not a mandatory webpage width or a recovered original-image specification. ## Configuration There is no environment file, API key, package manager setup, or build configuration for everyday use. Customize CSS variables in your own copy, after loading the token and component stylesheets: ```css /* Load after design-tokens.css and components.css. */ :root { --fe-prose-max: 760px; --fe-page-max: 1120px; --fe-size-body: 16px; --fe-leading-body: 1.75; } ``` These are existing defaults, shown as extension points. Use the semantic variables for role-based changes. Changing colors requires checking the affected foreground/background pairs again; changing font size or content requires checking wrapping, mobile width, and print pagination. Fonts are local fallbacks, so exact glyph metrics vary by operating system. No font files are bundled. Read [typography](references/typography.md) and [design rules](references/design-spec.md) before changing the theme. ## Integration and extension - **Static site:** copy the two CSS files, load tokens before components, and adapt a template's `.fe-theme`, `.fe-page`, and content classes. Preserve relative asset links or update them deliberately. - **Single-file HTML:** inline both stylesheets in the same order and embed required SVG or other authorized resources. Linking back to an installed skill directory is not portable. - **Diagram workflow:** edit [templates/architecture.mmd](templates/architecture.mmd) in a Mermaid-capable tool. Rendering new Mermaid output requires that tool; viewing the provided HTML/SVG does not require the Mermaid runtime. Follow [diagram guidance](references/diagrams.md). - **PDF or image export:** use your browser's print or screenshot facilities, then inspect the actual exported file for Chinese text, clipping, and pagination. Export quality is not guaranteed across browsers or downstream image compression. ### Optional color resampling Normal use and public-package validation do not need this step. Supply your own **authorized original inputs** in `./private-reference-images`, using the historical names `reference-01.jpg`, `reference-02.png`, and `reference-03.png`. The documented regions are tied to those original files; unrelated replacements do not reproduce the historical measurements. ```sh uv run --script scripts/sample_colors.py --input-dir ./private-reference-images --output-dir ./sampling-output ``` The script declares a pinned Pillow dependency using inline script metadata; no full Python package installation is needed. `uv` may download Python or dependencies. Keep both input and output directories outside the public distribution; the relative directories above are temporary local working locations, not files to add to the archive. Compare new outputs separately rather than silently overwriting historical evidence. Only separately authorized, byte-identical original inputs can support an independent comparison with those historical records; the public source package alone cannot. ## Safety and evidence boundaries - The original three reference images are omitted, and MIT does not grant rights to them. Do not reintroduce them, their thumbnails, or other unlicensed media into a contribution or release. - Historical CSV/JSON records support numeric consistency checks, not recovery of the images or verification of unavailable original bytes. A recorded input hash is provenance, not a substitute for the input. - Example reports and diagrams are layout demonstrations. Do not present their content as your own executed tests, business outcomes, or third-party endorsements. - Validate generated HTML before opening or sharing it when it contains untrusted content. Static templates are not an HTML sanitizer or a security sandbox. - The contrast checks cover supported token pairs, not every user customization, assistive technology, or WCAG criterion. - Never include credentials, personal data, private conversation identifiers, or machine-specific absolute paths in public examples, logs, screenshots, or archives. - Checksums help detect file changes against a trusted manifest; an unsigned manifest does not establish publisher identity or prove the absence of malicious content. For vulnerability reporting, follow [SECURITY.md](SECURITY.md). For redistribution details, read [NOTICE.md](NOTICE.md). ## FAQ **Do I need Node.js, a server, or Python to view the pages?** No. Open the HTML files locally. Python 3.9+ is needed only for package validation; optional resampling has its separate dependency path. **Why are the original images missing?** Redistribution permission has not been established. Public source distribution intentionally excludes them while retaining historical numeric provenance. The package cannot reproduce their measurements without separately authorized original inputs. **Does the offline badge mean everything works without a network?** It describes the nine HTML pages. Obtaining an agent or `uv`, and downloading the optional sampling dependency may require a network connection. **Can I use only the CSS?** Yes. The design kit is usable independently of the agent skill. Keep the applicable MIT copyright and permission notice when redistributing covered code. **Why is a font different on another machine?** The CSS uses local system fallback fonts. It does not identify or distribute the original reference-image fonts. **Does a validator pass mean my report is correct or my installation is discovered?** No. It checks the package, not your claims, actual agent invocation, visual quality, or all accessibility requirements. Host discovery must be confirmed in your own environment. **What if I edit the public files?** Their manifest hashes will change. Review your edits, regenerate the manifest as described in [CONTRIBUTING.md](CONTRIBUTING.md), and validate again. Regeneration alone is not verification. ## Achieved roadmap These checked items describe implemented scope, not a promise of future releases: - [x] Reusable CSS tokens and components for the Forest Editorial theme. - [x] Article, report, card, and architecture templates with five offline example pages. - [x] Mermaid source and pre-rendered SVG for diagram reuse. - [x] Historical numeric color-provenance records with explicit external-input limitations. - [x] Agent instructions, installation guidance, and a Python standard-library validator. No release schedule, hosting service, or future compatibility commitment is implied. See [VERIFICATION.md](VERIFICATION.md) for what was actually exercised, rather than interpreting this list as a test report. ## Contributing Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing changes. Keep the two READMEs aligned, preserve evidence boundaries and offline behavior, and provide authorized material only. If the repository host enables issues or pull requests, use those interfaces for non-sensitive proposals. No particular remote URL or enabled community feature is assumed here. ## License The distributed project material is licensed under the [MIT License](LICENSE), copyright **2026 Forest Editorial Design contributors**, subject to the scope and provenance notes in [NOTICE.md](NOTICE.md). The omitted original reference images are not licensed by this project's MIT grant. Recipients are responsible for rights to content they add. ## Maintainer role The **Forest Editorial Design maintainers** collectively review contributions, rights/provenance questions, verification records, and release contents. No personal contact or remote repository identity is asserted here. Use the actual repository hosting interface if available; security-sensitive communication must follow [SECURITY.md](SECURITY.md), not a public issue containing sensitive details.