The Dossyer Engineering Rules

1. The Core Principle

This means:

• No hardcoded values — use tokens (CSS variables)
• No one-off CSS — if a pattern appears twice, it's a component
• No duplicated JS logic — if a function does the same thing with different inputs, it's one function with parameters
• No inline styles — every visual decision belongs in the stylesheet as a named class

2. Rules for Every Change

Rule 0: Systems, Not Bandaids

This is the meta-rule. It governs how you approach every other rule. The difference between a bandaid and a system:

• Bandaid: "The chat citation doesn't have a link, so I'll hardcode one." → System: "Citations need a registry that resolves links, deduplicates, and assigns global numbers — build the registry, then every citation uses it."
• Bandaid: "This icon is too big, so I'll add an inline style." → System: "Icons need a sizing scale tied to companion text size — add the .icon-xs tier, document the 1.2× rule, then apply it."
• Bandaid: "The sources section needs to be collapsible, so I'll add a toggle." → System: "Sources and citations are data types with different rules — define what each is, build one render component, one collapsible section, one registry."

The test: if someone asks "why is it done this way?" the answer should be "because the system works this way" — not "because we needed to fix that one thing."

Rule 1: Token First

This applies to: hex colors, pixel values, font-family strings, timing functions, and any value that could conceivably change globally.

Rule 2: Component, Not Instance

Examples: modal overlays, dark header bars, chat input rows, citation footnotes, label typography, card hover states.

Rule 3: One Function, Multiple Contexts

The chat send flow (get input → inject user bubble → show typing → call API → render response → show suggest chip) is one algorithm. It should be one function that takes a config object: {inputId, msgsId, btnId, history, systemPrompt, chipVariant}.

Rule 4: Extend, Don't Override

Rule 5: Scale, Don't Guess

Rule 6: Version Everything

Naming Convention

Files are named: the_dossyer_vMM.NN.html — two-digit major version, two-digit minor version, with dots preserved.

What Counts as a Version Bump

• Any change to HTML, CSS, or JS in the app file = new minor version
• Content-only changes (story data, copy) = new minor version
• Support document updates (voice bible, blueprint, system rules) = versioned separately with their own vN suffix
• If multiple related fixes ship together in one pass, that's one version bump — not one per fix

Where the Version Appears

• <title> tag: Dossyer · v00.XX
• Footer: v00.XX · Prototype
• Filename: the_dossyer_v00.XX.html
• All three must match. If they don't, fix it before shipping.

Version History Convention

The blueprint document (the_dossyer_blueprint_v2.html) maintains a running version history. Each entry follows this format:

Keep entries concise — what changed and why, not how. The code itself is the how.

Support Documents

Each support document is versioned independently with a vN suffix in its filename. The blueprint maintains a running version history for the app. Support docs are updated when their scope changes — not on every app patch.

Rule 7: Audit Before Building

3. Component Registry

These are the shared components in the system. Any new feature should use these before creating new ones.

CSS Components

Utility Classes Needed

These utility classes are implemented and applied:

4. Refactoring Priority

Ordered by impact — what to consolidate first:

1. Chat send function ✓ — consolidated into sendChatMessage(config) with thin wrappers.
2. Modal system ✓ — merged into .overlay + .overlay-box with --wide/--narrow variants.
3. Dark header bar ✓ — one .bar-dark base class.
4. Utility classes ✓ — .label-mono applied via grouped selector to 20 selectors.
5. Close functions — still two parallel patterns. Low priority since they work.

5. Data Structure Rules

Story Object Schema

Every story follows this shape. All fields are required unless marked optional.

Snap Object Schema

6. Naming Conventions

7. Accessibility Rules

• Hidden elements must leave the tab order. If something is collapsed (max-height:0, display:none, off-screen via transform), its interactive children need tabindex="-1". Use a11yUpdateCollapsed(containerSelector, isExpanded) and call it from every toggle function.
• Focus rings need context. Navy outline on light backgrounds. White outline (or inset box-shadow) on dark backgrounds. Inset box-shadow inside overflow:hidden containers — outline gets clipped.
• Dynamic content needs re-initialization. a11yInteractive runs at page load. If a modal injects new interactive HTML (e.g., footnotes toggle), re-run a11yInteractive on the new selector after injection.
• Use native elements first. A <button> gets focus, keyboard, ARIA for free. Only use a11yInteractive on non-semantic elements that can't be changed to buttons.

8. Spacing & Typography Rules

• Both sides of a divider must match. If a divider separates two sections, the padding above and below it should use the same space token. Asymmetric divider spacing is always a bug.
• Fix legibility at the token layer. If text is too small, change the token value in :root — don't add font-size overrides to individual elements. The whole point of tokens is that one change fixes everything.

9. Notification System Rules

• Since banner = catch-up ("what happened while you were away"). Top position, navy. Shows story chips. Dismissible.
• Update tab = real-time doorbell ("something changed while you're reading"). Hangs from masthead, navy. Clicking scrolls to top and reveals the since banner.
• Card badges = New (red), Read (muted), Updated (navy). Same visual language as the since banner's "New" badge.
• All hover shadows use --elevation-raised. No raw var(--shadow) on hover states — use semantic elevation tokens.

10. Checklist: Before Every Change

1. Does a token exist for this value? If not, create it.
2. Does a component already handle this pattern? If yes, extend it.
3. Am I duplicating logic that exists elsewhere? If yes, parameterize.
4. Does this fix work for the next case, not just this one?
5. Is the version number updated in title and footer?
6. Are CSS braces balanced? Are JS braces balanced?
7. Are hidden elements removed from the tab order?
8. Is all text ≥ 10px?