--- name: The Rookery description: A cool-paper field system where corvids carry knowledge through a five-job delivery sequence and two distinct feedback currents. colors: raven-navy: "#042458" route-cobalt: "#0050CC" mist-paper: "#DEE2EC" drafting-graphite: "#596A8B" signal-orange: "#DC6C36" dispatch-paper: "#F0EBE5" --- # Design System: The Rookery ## Overview **Creative North Star: "The Returning Field Dispatch"** The Rookery looks like a natural-history field manual laid over a working draft table. Cool mist-blue paper, engraved navy corvids, graphite mechanisms, and measured construction lines make the work feel studied and practical rather than mythical or corporate. The result should make the technical system clear while retaining the warmth and memory of a hand-kept field guide. Every illustration explains an operation. Huginn and Muninn carry, inspect, install, select, or return knowledge; they do not pose beside an abstract idea. Routes and mechanisms show the order of work, where observation happens, and how feedback returns. One restrained orange signal marks the intervention, dispatch, or return that matters most. Scenes may change across repository-owned explanatory visuals. Each should show the same connected system, with evidence moving forward and distinct feedback paths improving future work. **Key Characteristics:** - Cool drafting paper with faint grain, registration marks, and construction geometry. - Natural-history corvid engraving paired with graphite field mechanisms. - Cobalt paths that distinguish delivery from feedback and a scarce orange signal that explains intervention or return. - Wide, calm compositions with enough negative space to survive GitHub rendering at reduced sizes. - Characters whose physical action carries the meaning of the explanation. ## Colors Navy signals authority, cobalt shows the sequence, and blue-gray defines supporting structure. Reserve orange for the moment that changes the state of the work. ### Primary - **Raven Navy:** Use for corvid engraving, dominant titles, strong outlines, and the darkest explanatory labels. - **Route Cobalt:** Use for delivery paths, feedback currents, sequence arrows, stage numbers, and supporting banner copy. It should guide the eye, not become a broad decorative fill. ### Secondary - **Signal Orange:** Use only for dispatch seals, active interventions, pressure points, and the return into another pass. ### Neutral - **Mist Paper:** The default ground for repository-owned illustrations. Keep it cool and lightly textured so dark engraving remains crisp. - **Drafting Graphite:** Use for secondary mechanisms, hatching, folds, measurements, and quiet construction detail. - **Dispatch Paper:** Use for carried notes, envelopes, and evidence artifacts that need to separate from the cool ground. ### Named Rules **The Orange Means Intervention Rule.** Orange identifies the action, handoff, or return that changes the state of the workflow; it is never a general-purpose accent. **The Ink Hierarchy Rule.** Raven Navy explains the subject, Route Cobalt explains movement, and Drafting Graphite explains supporting structure. ## Typography **Display Font:** Didot for the primary title in repository-owned banners. **Supporting Font:** Baskerville Semibold for subtitles and diagram labels; a compact bold sans-serif is acceptable only for dense explanatory labels where it is demonstrably easier to read. **Character:** Type should feel printed into a field guide, not overlaid by a product interface. The repository's Markdown body remains native to GitHub; this typography guidance applies to repository-owned visual assets. ### Hierarchy - **Display:** Large, high-contrast serif titles with compact line spacing. Use only for the identity or subject of a wide banner. - **Subtitle:** Smaller, weightier serif text in Route Cobalt. Keep it declarative and short enough to read when the image is scaled down. - **Diagram Label:** Compact, sturdy lettering placed directly beside its stage or mechanism. Numbering should reinforce the path rather than act as decoration. ### Named Rules **The Printed-In Rule.** Lettering must share the illustration's ink hierarchy and perspective while remaining real typography; never ask the raster artwork layer to render essential copy. **The Family Restraint Rule.** Use one display treatment and one explanatory treatment within an asset. Name an exact font family only when the editable source uses it. **The Layered Type Rule.** Keep essential lettering as real typography over a text-free illustration plate, retain the editable source, and export the shipped raster losslessly. The workflow banner keeps its illustration and typography in separate production layers. `docs/assets/the-rookery-workflows-banner-artwork.webp` holds the text-free working bench and its two return cables. `docs/assets/the-rookery-workflows-banner.svg` adds the Didot title, Baskerville supporting copy and labels, delivery arrows, and return arrowheads. The shipped WebP is a lossless render of that editable source, so later copy changes should update the vector text layer rather than regenerate the illustration. The README banner follows the same pattern. `docs/assets/the-rookery-readme-banner-artwork.webp` holds the text-free artwork; `docs/assets/the-rookery-readme-banner.svg` adds the Didot title and the Baskerville tagline, “A field guide to how I build with AI.” Its matching WebP is the lossless rendered asset used by the README. The testing diagrams use self-contained HTML sources in `docs/assets/testing-flow.html` and `docs/assets/testing-safeguards.html`. Their matching SVGs carry the styles and real typography into the Markdown page. The safeguards view embeds the approved Muninn artwork from `docs/assets/muninn-descending-delivery.png`: he flies in to deliver a learned check to the testing layer. Keep that artwork separate from the editable labels, and update the HTML source before exporting its SVG. ## Layout The README introduces Huginn and Muninn with the overflowing-notebook scene in `docs/assets/huginn-and-muninn.svg`. Huginn brings one more field note while Muninn makes room for it. The SVG embeds `docs/assets/huginn-and-muninn-artwork.png` and keeps their names, roles, and caption as editable Baskerville text. Update the vector text for copy changes and preserve the separate artwork plate. The README banner uses a wide landscape canvas (1600 × 640). The workflow banner is 1600 × 704 to give its tagline and delivery labels more vertical space. They depend on large silhouettes, sparse text, and generous negative space so the image retains a clear reading when GitHub scales it to the content column. Choose dimensions for future explanatory visuals based on where people will view them. Do not reuse dimensions from a removed asset format by default. A banner should make its main elements clear at first glance. Give the title a clear area, make the corvid's action dominant, and place a route or mechanism across the remaining space. Other explanatory visuals should concentrate on one job or relationship at a time. The mechanism should be readable before the texture, and the subject should face or move into the next meaningful area of the composition. The approved workflow banner uses a working bench. Five distinct mechanisms carry Research through Plan, Design, Build, and Ship from left to right. Huginn brings a field note to the research lens while Muninn works at the repair clamp on the right. Their labels sit on clear paper above the mechanisms, with Research shifted away from Huginn's head. A cobalt cable returns improvements to the bench, and a separate orange cable passes through the learning notebook. The adjacent prose explains how Maintain creates repository memory and Learn returns a better question to Research. This arrangement is specific to the workflow explanation, not a template for every future asset. **The Causal System Rule.** Show the five delivery jobs as an ordered sequence and each feedback process as its own path to the stages or input it changes. Never force distinct feedback loops into a false serial sequence, and never flatten the system into repeated equal containers. **The Reduced-Size Test.** At ordinary GitHub content width, the five-job delivery order, repository-wide improvement path, and return of a better question to Research must remain understandable before a reader zooms into the engraving detail. ## Elevation & Depth The illustrations show physical depth without glossy card shadows, bloom, or floating UI layers. Depth comes from engraved hatching, paper folds, perspective, overlap, line-weight changes, and the contrast between dark subjects and pale field geometry. **The Drawn Depth Rule.** Create depth with physical overlap, perspective, and line density; do not simulate it with product-UI drop shadows or glow. ## Shapes Organic corvid silhouettes break against precise field geometry. Circular route nodes, seals, apertures, calibration rings, and return loops repeatedly mark the state of the work. Straight-edged jigs, gates, frames, and folded paper give each abstract job a physical form. Corners follow the depicted material. Cut paper may soften; wood and metal keep constructed edges. Do not apply one generic rounded-card radius throughout the scene. **The Mechanism Has Consequence Rule.** Every aperture, gate, jig, ring, or bridge must make the stage's operation clearer; remove decorative machinery that does not change the explanation. ## Do's and Don'ts ### Do: - **Do** give Huginn or Muninn an action essential to the explanation, such as carrying a dispatch, operating a mechanism, inspecting a handoff, or returning a signal. - **Do** use Route Cobalt and shape or direction together, so paths remain understandable without color. - **Do** distinguish the Delivery Sequence, Repository Learning Loop, and Personal Learning Loop by position, labels, direction, and mechanism as well as color. - **Do** keep Signal Orange scarce and attach it to one meaningful intervention or return. - **Do** preserve calm negative space and a strong silhouette before adding paper grain, coordinates, hatching, or registration marks. - **Do** write meaningful alt text that states the mechanism, sequence, and return represented by the image. ### Don't: - **Don't** turn the workflow into a generic equal-card flowchart or consulting-deck diagram. - **Don't** present Research, Plan, Design, Build, Ship, Maintain, and Learn as one seven-step serial loop; Maintain and Learn are distinct feedback loops with different destinations. - **Don't** reuse the unfolded field map as the default composition for unrelated visuals. - **Don't** pose a raven beside an idea it is not performing; removing the bird should break the explanation. - **Don't** use broad orange fills, multiple competing accents, glossy gradients, or interface-style shadows. - **Don't** drift into novelty mascot art or Norse-fantasy ornament that overwhelms the technical mechanism. - **Don't** imply that the system learns autonomously; the return mythology supports the operator's deliberate learning loop.