ForgeBot rule comparison · Share Preview × ForgeFX Design System

Where The Dark Heading Regression Came From

A comparison of the two rule sets shows an integration contract gap: the design system provides both light and dark modes, while Share Preview told generated dark reports to import the design system without requiring the dark-mode switch.

Design CSSdual-mode tokens
Share Previewimport guidance
Missing Linkdark mode opt-in
Rootintegration gap

Executive Verdict

The root problem sits at the seam between the skills. The ForgeFX design system is internally coherent: it defaults to light-mode foreground tokens and exposes dark-mode tokens under data-theme="dark". The Share Preview workflow adopted the design stylesheet for dark reports but failed to say “turn dark mode on.”

forgefx-design-system

What it says correctly

  • Use warm Forge-black / Hot Black for dark surfaces.
  • Use Warm White for text on dark surfaces.
  • Always include the master design stylesheet first when creating visual artifacts.
  • The stylesheet includes a dark theme block that changes --fg to Warm White.
forgefx-design-system

What it does not say loudly enough

  • The master stylesheet defaults to light-mode tokens.
  • Global h1/h2/h3 rules set color: var(--fg).
  • A dark page must add data-theme="dark" or override headings after import.
share-preview

What it says correctly

  • Use clean preview.forgefx.dev URLs for Slack-visible pages.
  • Use ForgeFX design for generated reports and internal artifacts.
  • Prefer linking or inlining the design system stylesheet.
  • Use official logo assets and warm ForgeFX styling.
share-preview

Where the regression entered

  • It instructed agents to import the live design stylesheet.
  • It also pushed warm dark report shells.
  • Before the new patch, it did not mention the dark-theme opt-in.

Rule Collision Chain

1

Share Preview says generated reports should use ForgeFX design.

2

Share Preview says to link or inline colors_and_type.css.

3

The report uses a dark brown ForgeFX shell.

4

The stylesheet default --fg is light-mode dark gray.

5

Global heading rules apply dark gray to h1/h2.

Side-by-Side Reproduction

BROKEN: stylesheet imported, no dark theme

Dark Gray Heading

This represents the Dave report failure: #131820 text on #261B13 ground, around 1.06:1 contrast.

FIXED: dark theme or local override

Warm White Heading

This uses Warm White on the same dark ground, around 15.50:1 contrast.

Evidence From The Rules

SourceRuleEffectRisk
ForgeFX Design System skill“Always include colors_and_type.css first.”Good brand consistency.Imports global heading styles before local page CSS must consciously override color.
ForgeFX Design System visual ruleDark surfaces use warm darks and warm-white text.Correct target appearance.Guidance is visual, not explicit about the required CSS switch.
Design stylesheetDefault --fg is --steel-900 / #131820.Correct for light pages.Wrong for standalone dark pages unless dark mode is enabled.
Design stylesheeth1/h2/h3 use color: var(--fg).Consistent semantic typography.Overrides body text color and catches uncolored headings.
Share Preview skillGenerated reports should use ForgeFX design and link the stylesheet.Correct brand default.Before patch, missed data-theme="dark" for dark report shells.

Fix Priority

Primary fix: update Share Preview guidance and templates because that workflow is the generator that combines a dark report shell with the shared stylesheet. Secondary fix: add a warning or example in ForgeFX Design System docs that dark standalone pages require data-theme="dark". Do not change the design stylesheet default to dark; that would break light-mode marketing pages.