Page Design + Status Colors
One-line intent: give every item inside an LDD a small color chip so you can see at a glance what's locked, what's pending, and what still needs an answer — without reading a single sentence.
TL;DR
The pitch in two paragraphs
Right now every LDD is a wall of text in shades of gray. Decisions sit next to open questions sit next to risks, all visually identical — you have to read each one to know what state it's in. That's slow, and for a 30-doc set with hundreds of decisions across them, it doesn't scale.
This proposal adds a 6-color status system that shows the state of every item at a glance. Locked things glow green. Pending things glow yellow. Open questions glow red. New things glow blue. Things needing update glow amber. Things you're unsure about glow purple. It also tightens a few section names and adds a structured change-history table at the bottom of every LDD.
What it would look like (live mock)
Below is a hypothetical Decisions section rendered with the proposed color system. The content is real (from LDD-30) but the chips and left-border colors are new. Scroll past this once to get the feel before reading the rest of the proposal.
3 Zone 1 — first-floor mechanical room Locked
Dimensions: 10' E–W × 7' N–S, ~70 SF clear interior slab footprint. Functions as primary fluid + thermal + wet utility core for the main building.
17 Hot water — Everyday Mode Pending review
Under low occupancy: heat pump handles primary water heating, thermal energy stored in indirect tank, tankless booster inactive. Engineer review needed for heat pump model selection (Sanden, SANCO2, Chiltrix, etc.) — must coordinate with LDD-05 if shared system.
3a Indirect storage tank capacity Open question
50, 80, or 119 gallon? Needs to be sized against peak simultaneous demand from LDD-10 fixture count — that calculation hasn't been done yet. Blocks Zone 1 equipment rough-in.
4 Zone 2 — second-floor laundry / ops core New in v6.0
Primary electrical distribution hub + solar inverter zone. Locating panel + inverter upstairs shortens solar DC wire runs and preserves clean separation from wet utility systems. Introduced in Peter's 2026-05-17 revision.
— LDD-15 mech room AI render Needs update
The current render depicts the OLD east-wall allocation (electrical subpanel + battery enclosure on right). v6.0 moves both out. Render needs regeneration from the updated Codex prompt. Priority: HIGH — marquee render for the mech room.
22 Single-source hydronic ecosystem preference Unsure
Where practical, primary hydronic components should originate from the same manufacturer ecosystem as the heat-pump hydro-block. Peter flagged "where practical" as soft — the spec doesn't say what to do when single-source produces a worse-fit component. Needs a clearer fallback rule.
Six items, six states, one glance. Compare that to the current LDD-30 page where the same content is all visually identical gray boxes — you'd have to read every one to know which need attention.
The six status states (legend)
These match the existing sidebar status dots exactly — same six colors, same vocabulary. So a yellow chip on a decision inside the Mech Core LDD corresponds to the yellow dot on "Mech core master" in the sidebar. Once you learn one, you've learned both.
Why color status, not color section
A natural first impulse is to color the sections of an LDD — Decisions section green-bordered, Open Items yellow-bordered, Risks red-bordered. I'd argue against this:
The trap with too many colors
Once everything has a color, nothing has a color. The eye stops parsing it as meaning and treats it as decoration. We already have a tight semantic palette (green / yellow / amber / red / blue / purple) for status. Adding a second axis of colors for section type dilutes the status signal — and the section type is already communicated clearly by the heading.
Better: keep section identity in headings, use color exclusively for status. Then a glance at any page tells a real story (lots of yellow = lots of pending review; mostly green = bid-ready) instead of just "yep, that's a Decisions section."
Section name tweaks
While we're at it, several of the current section headings could be tighter. None of these are urgent — they're polish, not architecture. But if we're refactoring anyway, this is the cheap moment to do them.
| Today | Recommended | Why |
|---|---|---|
| One-line intent | Headline | Architectural-monograph register. Peter will know it instantly. (Backup options: The point, TL;DR.) |
| Why this matters | (keep) | Already plain. |
| Design intent · AI render | Render | Drop "AI" — irrelevant to the reader. The FPO badge already says it's a working render. |
| Locked decisions | Decisions | "Locked" is redundant once each decision has its own status chip. |
| Open items / engineer review | Open items | Shorter. The "engineer review" nature lives in chips on individual items. |
| Cross-references | (keep) | Already clear. |
| Cost drivers | (keep) | Already direct. |
| Air-gap concerns | Risks | "Air-gap" is project-specific jargon for "things that could fall through the cracks." Risks is universal and reads instantly. |
| Diagram | (keep) | Already clear. |
| Status | Status & history | Merged with the new change-history block proposed below. |
Change history at the bottom of every LDD
The version info is currently buried in the top status banner ("v6.0 adopted 2026-05-17"). Pulling it out into a structured table at the bottom of every LDD makes the revision arc readable at a glance — no git archaeology needed.
Example using LDD-29's actual history:
| Version | Date | Author | Summary |
|---|---|---|---|
| v1.0 Current | 2026-05-17 | Peter Shin | Revision adds gym athletic floor system (§25 build, §26 finish, §27 striping). Subsequent cards renumbered +3. Treated as v1.0 errata rather than v1.1 bump. |
| v1.0 | 2026-05-16 | Peter Shin | Initial synthesis email — unifies seven gym sub-LDDs (04, 08, 12, 22, 25, 26, 27) under the "calm industrial Great Hall" thesis. |
A few design decisions inside this table format:
- Manual, not auto-from-git. Git commits are too noisy. A human-curated changelog reads like a story; a git log reads like a screenshot.
- Newest at top. The eye reads "what's current, who, when" first.
- One-sentence summaries. No detail dumps — the body of the LDD is the detail. The changelog is the index to revisions.
- Current version gets a chip. Reading down the table, you see the current version glow blue (or whatever color we pick for "current"), older versions sit muted below.
How this connects to the bigger refactor
This proposal is the visual half of the work outlined in the LDD Rebuild Proposal. The other half is the structural work: categorization (Master strategies / Building systems / Zones / Elements / Materials / Process), uniform data blocks, machine-readable metadata. The two work hand-in-hand:
- The structural refactor turns each LDD into a uniform record so a future wiki migration is a port rather than a rewrite.
- The visual refactor (this proposal) makes those uniform records actually scannable by humans — color encodes state, headings stay simple, change history is structured.
You can adopt either independently. The structural refactor without the visual changes still helps future tooling. The visual refactor without the structural one is mostly cosmetic. Doing both together is what gets us to a doc set that's both human-readable and machine-portable.
What I'd love your input on
- Does the six-status taxonomy fit how you actually think about decisions? Specifically: is the distinction between "Open question" and "Unsure" useful, or are they functionally the same to you? If they collapse into one, we drop down to five states (which is cleaner).
- Which name do you prefer for the one-liner section — "Headline," "TL;DR," or "The point"? The current "One-line intent" can go either way.
- Are you OK with "Risks" replacing "Air-gap concerns"? The current term is evocative but specific to this project; "Risks" is what an engineer or banker would expect to see.
- For the change-history table — do you want this on every LDD or only on the master strategies? Adding it everywhere is more work but more uniform; adding it only to strategies (29, 30) keeps the focused sub-LDDs leaner.
- For implementation order: would you rather see the status chips applied first (every existing decision gets a chip — high visibility, mostly mechanical) or the section name tweaks first (touches every LDD but is invisible to anyone who didn't read this proposal)?
None of this needs to be decided today, but knowing your direction on these five sharpens what we build next.