B2BEA.org Rebuild design-system-governance-spec

Full legacy body rendered for humans

B2BEA.org Design System Governance Spec

Source of record: RedKey Supabase Studio artifact.

• Project: B2BEA.org Rebuild
• Project ID: a820dd0c-6cef-4133-bfbd-d802fd806e44
• Artifact: design-system-governance-spec
• Version: 1
• Status: draft
• Updated: 2026-05-08

Purpose

Prevent rogue CSS and page-by-page design drift while the B2BEA design system is still actively being improved by a designer.

The system is not visually final. The governance contract is final enough for implementation: product/page code must consume approved design-system tokens, components, and scoped exceptions instead of inventing raw CSS.

Core Rule

Visual values may evolve. Styling authority cannot sprawl.

No route, page, feature, or one-off component may define its own raw colors, type scale, button/card/form styles, shadows, radii, grid primitives, or hero/header systems outside the approved design-system boundary.

Allowed Styling Paths

| path | allowed_for | requirements |

| --- | --- | --- |

| design tokens | colors, typography, spacing, radius, shadows, borders, breakpoints, z-index, motion | Stable semantic token names. Values may change as designer improves the system. |

| design-system components/classes | buttons, fields, cards, filters, nav, page headers, tables, badges, empty states, modals, layout primitives | Must live in the shared design-system package/stylesheets. |

| approved custom exception wrapper | home, major campaign pages, signature editorial, approved custom HTML imports | Must declare custom_treatment, owner, reason, CSS scope, QA profile, and review/expiration path. |

| local layout composition | page-specific ordering and content layout using design-system primitives | May compose approved classes/components but cannot introduce new primitive styles. |

Disallowed Styling

• Raw hex, rgb, hsl, font-size, box-shadow, border-radius, and brand color values in page or feature files.
• Inline style attributes except for safe dynamic values explicitly approved by component contract.
• Page-specific button, card, field, badge, table, nav, hero, or modal implementations.
• CSS files named for a route/page unless registered as an approved custom exception.
• Duplicate public/admin/member/vendor/company shells with independent style systems.
• Unscoped custom HTML import CSS.

Token Stability Model

Implementation must use semantic token names, not final visual assumptions.

Examples:

• Use --b2bea-color-primary, not #00196C in page code.
• Use --b2bea-surface-muted, not #F5F5F5 in page code.
• Use --b2bea-radius-card, not 12px in page code.
• Use --b2bea-title-standard, not a route-specific clamp value.

Candidate values from the designer may live behind token names such as candidate or experimental only inside the design-system boundary. Product/page code must not import candidate values directly.

CSS Ownership Boundaries

| owner | can define tokens | can define components | can define page CSS | notes |

| --- | --- | --- | --- | --- |

| design system | yes | yes | no, except examples | Canonical styling authority. |

| public Eleventy templates | no | no | only composition utilities from system | Uses system classes/tokens. |

| app layer surfaces | no | no | only composition utilities from system | Admin/private surfaces use compact operational variants. |

| custom imports | no global tokens | no global components | yes, scoped only | Requires registry and QA approval. |

Required Audit Checks

Slice 0 must add an automated design governance audit that fails on:

• raw hex colors outside approved design-system files
• inline style= in templates/components outside approved allowlist
• route/page CSS files without custom exception registration
• class names matching page-specific primitive patterns such as *-button, *-card, *-field, *-hero outside the design-system boundary
• duplicate definitions for buttons, cards, fields, badges, nav, page headers, and tables outside approved files
• custom HTML import CSS missing a route-scoped wrapper selector

Custom Exception Record

Every approved custom styling exception must have:

{
  "route": "/example",
  "custom_treatment": "campaign_custom",
  "owner": "B2BEA",
  "reason": "Major campaign landing page",
  "css_scope": ".custom-example-page",
  "qa_profile": "custom_public",
  "review_required_by": "2026-06-30",
  "allowed_css_files": ["custom-example-page.css"]
}

Designer Handoff Model

The designer can change visual values by updating token values, component variants, and approved component specs. Engineering should not block on final visual values as long as the token/component contract is stable.

When the designer changes the system:

1. Update design-system tokens/components.

2. Run design governance audit.

3. Run visual smoke checks for representative page families.

4. Avoid changing route/page code unless the component contract changed.

Acceptance Criteria

• Implementation has a clear no-rogue-CSS rule before Slice 0 build starts.
• Designer improvements flow through token/component updates, not page CSS rewrites.
• Public Eleventy and app-layer surfaces share the same styling authority.
• Custom pages can exist, but only through explicit scoped exception records.
• Automated checks can fail builds for ungoverned CSS.