{
  "id": "2026-05-07-b2bea-org-design-system-spec-v4-ac02bceb81",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-05-07-b2bea-org-design-system-spec-v4.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.721Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "B2BEA.org V1 Design System Spec",
  "summary": "B2BEA.org V1 Design System Spec Source of record: RedKey Supabase Studio artifact. Project: B2BEA.org Rebuild Project ID: a820dd0c 6cef 4133 bfbd d802fd806e44 Artifact: design system spec Artifact ID: 4c3651ac 9a69 4117 a355 750b61f540c9 Version: 4 Status: draft Updated: 2026 05 07T13:29:22.717+00:00 Scope Revision Note Added separate local B2BEA design syst...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "B2BEA.org V1 Design System Spec",
      "level": 1,
      "body": "Source of record: RedKey Supabase Studio artifact.\n\n- Project: `B2BEA.org Rebuild`\n- Project ID: `a820dd0c-6cef-4133-bfbd-d802fd806e44`\n- Artifact: `design-system-spec`\n- Artifact ID: `4c3651ac-9a69-4117-a355-750b61f540c9`\n- Version: `4`\n- Status: `draft`\n- Updated: `2026-05-07T13:29:22.717+00:00`"
    },
    {
      "title": "Scope",
      "level": 2,
      "body": "```json\n{\n  \"rule\": \"Exceptions still must satisfy accessibility, metadata, responsive, and production QA rules.\",\n  \"in_scope\": [\n    \"public non-home pages\",\n    \"admin dashboard/pages\",\n    \"member profile/dashboard\",\n    \"vendor portal\",\n    \"company workspace\",\n    \"auth/account pages\",\n    \"academy/course pages\",\n    \"jobs/events/survey/forms surfaces\"\n  ],\n  \"exceptions\": [\n    \"home page\",\n    \"blog pages where intentionally editorial\",\n    \"resource pages where intentionally custom\",\n    \"custom HTML imports approved by publishing model\"\n  ]\n}\n```"
    },
    {
      "title": "Revision Note",
      "level": 2,
      "body": "Added separate local B2BEA design-system checkout and GitHub repo reference."
    },
    {
      "title": "Acceptance Criteria",
      "level": 2,
      "body": "- Every in-scope page has one recognizable B2BEA design-system page/header pattern.\n- All in-scope fields/search/selects/textareas use the B2BEA design-system field contract.\n- All in-scope pills/badges use B2BEA design-system active/inactive states.\n- No standard page title exceeds the standard page title scale unless marked as article/marketing exception.\n- Admin/portal pages use compact operational typography and do not use large marketing heroes.\n- Cards do not nest inside decorative cards; panels use consistent borders/radius/shadows.\n- Mobile text fits without overlap and controls keep stable dimensions.\n- A visual QA pass covers desktop and mobile for each page family before launch."
    },
    {
      "title": "Next Artifacts",
      "level": 2,
      "body": "- surface-specs\n- sanity-schema-spec\n- custom-html-import-spec\n- qa-release-readiness-spec"
    },
    {
      "title": "Open Questions",
      "level": 2,
      "body": "- Which blog/resource page families are intentional exceptions versus should be normalized?\n- Should admin and portal surfaces share the same component package or use denser variants?\n- Do we keep Material Symbols or move to a React icon library during rebuild?\n- What screenshot baseline set represents every page family?"
    },
    {
      "title": "Tokens",
      "level": 2,
      "body": "```json\n{\n  \"colors\": [\n    {\n      \"name\": \"primary\",\n      \"usage\": \"headers, primary buttons, active pills, focus ring\",\n      \"value\": \"hsl(226 100% 21%) / #00196C\"\n    },\n    {\n      \"name\": \"primary_dark\",\n      \"usage\": \"primary hover states\",\n      \"value\": \"#001458\"\n    },\n    {\n      \"name\": \"accent\",\n      \"usage\": \"accent buttons, badges, highlights\",\n      \"value\": \"hsl(6 80% 59%) / #EB5444\"\n    },\n    {\n      \"name\": \"accent_dark\",\n      \"usage\": \"accent hover states\",\n      \"value\": \"#d94333\"\n    },\n    {\n      \"name\": \"background\",\n      \"usage\": \"page background\",\n      \"value\": \"hsl(0 0% 100%)\"\n    },\n    {\n      \"name\": \"card\",\n      \"usage\": \"cards and panels\",\n      \"value\": \"hsl(0 0% 100%)\"\n    },\n    {\n      \"name\": \"secondary_muted\",\n      \"usage\": \"muted sections and outline hover\",\n      \"value\": \"hsl(0 0% 96%)\"\n    },\n    {\n      \"name\": \"border_input\",\n      \"usage\": \"borders, inputs, table dividers\",\n      \"value\": \"hsl(220 13% 88%)\"\n    },\n    {\n      \"name\": \"muted_foreground\",\n      \"usage\": \"subtitles, metadata, secondary navigation\",\n      \"value\": \"hsl(226 30% 45%)\"\n    }\n  ],\n  \"typography\": [\n    {\n      \"token\": \"font_display\",\n      \"value\": \"Open Sans, system-ui, sans-serif\"\n    },\n    {\n      \"token\": \"font_body\",\n      \"value\": \"Open Sans, system-ui, sans-serif\"\n    },\n    {\n      \"token\": \"body\",\n      \"value\": \"16px base, normal letter spacing, line-height 1.6-1.75 depending context\"\n    },\n    {\n      \"token\": \"ui_text\",\n      \"value\": \"0.875rem / 14px, weight 600-700 for controls\"\n    },\n    {\n      \"token\": \"metadata\",\n      \"value\": \"0.75rem / 12px, weight 700 for pills/badges\"\n    }\n  ],\n  \"radius_shadow_spacing\": [\n    {\n      \"token\": \"radius\",\n      \"value\": \"0.75rem / 12px\"\n    },\n    {\n      \"token\": \"radius_sm\",\n      \"value\": \"calc(radius - 4px) / 8px\"\n    },\n    {\n      \"token\": \"pill_radius\",\n      \"value\": \"999px\"\n    },\n    {\n      \"token\": \"shadow_sm\",\n      \"value\": \"0 1px 3px rgba(0, 25, 108, 0.06)\"\n    },\n    {\n      \"token\": \"shadow_md\",\n      \"value\": \"0 8px 30px -8px rgba(0, 25, 108, 0.10)\"\n    },\n    {\n      \"token\": \"container\",\n      \"value\": \"min(100%, 1400px), 2rem side padding\"\n    }\n  ]\n}\n```"
    },
    {
      "title": "Decisions",
      "level": 2,
      "body": "| id | topic | decision |\n| --- | --- | --- |\n| DS-DEC-001 | Design authority | Lovable is the foundation/reference seed for the V1 design system; the final authority is the hardened B2BEA design system defined by this artifact and follow-on component/page specs. |\n| DS-DEC-002 | Intentional exceptions | Home page, blog, and resource pages may remain custom where explicitly approved; all other surfaces must converge on the hardened B2BEA design-system rules derived from, but not limited to, the Lovable foundation. |\n| DS-DEC-003 | Typography | Use the B2BEA design-system typography contract defined here for display and body. Lovable/Open Sans is a starting reference, not an irreversible final font decision; remove legacy Hanken Grotesk dependency from target page families unless explicitly retained for an exception. |\n| DS-DEC-004 | Page title scale | Standard page hero titles use clamp(2.25rem, 4vw, 3.75rem). Article/editorial hero titles may use clamp(2.75rem, 6vw, 5rem). Full marketing hero titles may use clamp(3rem, 7vw, 6rem) only on approved hero pages. |\n| DS-DEC-005 | Forms/search/filters | All fields, selects, search inputs, filters, and pills use the B2BEA design-system control contract; the Lovable 2.5rem field/control height, 0.875rem text, 0.75rem radius, and blue focus ring are baseline values to retain or deliberately revise in the final token/component pass. |"
    },
    {
      "title": "Components",
      "level": 2,
      "body": "| contract | component |\n| --- | --- |\n| Blue header block for standard pages; centered content; title clamp(2.25rem,4vw,3.75rem); subtitle 1.125rem; max inner width 64rem. | Page hero |\n| White/background hero; breadcrumb 0.875rem; title clamp(2.75rem,6vw,5rem); excerpt 1.25rem; media aspect 1200/630. | Article/editorial hero |\n| 1px border, 12px radius, white background, small blue-tinted shadow; hover may lift -2px only for clickable cards. | Cards |\n| 2.5rem min height, 1px input border, 12px radius, white background, 0.5rem 0.75rem padding, 14px text, blue 3px focus ring. | Fields |\n| Same field contract; icon left at 0.875rem; input left padding 2.25rem; page toolbar search max width 42rem. | Search bars |\n| 2.5rem min height, 12px radius, 14px Open Sans, 700 weight; primary blue, accent coral, outline white with border. | Buttons |\n| 2rem min height, 999px radius, 12px text, 700 weight; active pills use primary blue; badges use accent tint. | Pills and badges |\n| Use card/panel container, 1px borders/dividers, 14px cells, muted metadata, sticky or clear table headers where long. | Tables |\n| Empty/loading/error/success states use card/panel treatment, concise heading, useful action, no unstyled browser defaults. | States |\n| Two-bar restored header remains; B2BEA design-system nav/button/dropdown styling governs future header work, using Lovable as the initial baseline unless intentionally revised. | Navigation |"
    },
    {
      "title": "Logo Assets",
      "level": 2,
      "body": "```json\n{\n  \"count\": 10,\n  \"cloudflare\": {\n    \"rule\": \"Always use Brett's Cloudflare account for B2BEA.org assets.\",\n    \"namespace\": \"design-system/logos\",\n    \"r2_bucket\": \"b2bea-guest-packs\",\n    \"account_id\": \"3333630b9c90c49aef56730d9513c19f\",\n    \"account_name\": \"Brett Sinclair DNS\"\n  },\n  \"source_zips\": [\n    \"/Users/justinking/Downloads/Default-20260506T201500Z-3-001.zip\",\n    \"/Users/justinking/Downloads/Horizontal-20260506T201458Z-3-001.zip\"\n  ],\n  \"local_repo_path\": \"/Users/justinking/Vaults/Projects/b2bea-org-design-system/logos\"\n}\n```"
    },
    {
      "title": "Source Repo",
      "level": 2,
      "body": "```json\n{\n  \"b2bea_site_repo\": \"/Users/justinking/Vaults/Projects/B2BEA-org-new\",\n  \"design_system_repo\": \"C:/Users/jstnk/Downloads/cc/projects/b2bea/b2bea-org-design-system\"\n}\n```"
    },
    {
      "title": "Source Files",
      "level": 2,
      "body": "- src/assets/css/lovable-system.css\n- src/assets/css/style.css\n- src/assets/css/portal.css\n- src/assets/css/admin.css\n- src/assets/css/search.css\n- src/_includes/layouts/base.njk\n- src/_includes/partials/nav.njk"
    },
    {
      "title": "Page Patterns",
      "level": 2,
      "body": "| layout | pattern |\n| --- | --- |\n| blue page hero, optional toolbar with search/filter, constrained content grid/table, consistent empty/error states | Standard index/list page |\n| hero or header card, metadata/badges, main content plus optional sidebar, related items/action panel | Detail page |\n| compact header, tabs or sidebar navigation, dense tables/forms, clear status pills, no marketing-scale type | Admin/portal workspace |\n| single clear title, fields in consistent grid, inline validation, primary action plus secondary cancel/back, success/error state | Form workflow |"
    },
    {
      "title": "Standard Sizes",
      "level": 2,
      "body": "```json\n{\n  \"controls\": \"0.875rem text, 2.5rem min-height\",\n  \"subtitle\": \"1.125rem standard / 1.25rem editorial or marketing hero\",\n  \"card_padding\": \"1.25rem default, denser variants allowed for admin tables\",\n  \"pills_badges\": \"0.75rem text, 2rem min-height\",\n  \"article_page_title\": \"clamp(2.75rem, 6vw, 5rem)\",\n  \"standard_page_title\": \"clamp(2.25rem, 4vw, 3.75rem)\",\n  \"full_marketing_hero_title\": \"clamp(3rem, 7vw, 6rem), exception only\"\n}\n```"
    },
    {
      "title": "Drift To Remove",
      "level": 2,
      "body": "- Legacy Hanken Grotesk heading dependency on target pages.\n- Negative letter spacing in standard headings and controls.\n- Oversized H1s outside approved article/marketing hero contexts.\n- Mixed field radii of 4px, 6px, 8px, 10px, 14px on target pages.\n- Search/filter controls with dark modal styling outside intentional search overlay.\n- Page-specific card/button styles that duplicate B2BEA design-system component contracts.\n- Marketing/landing page scale in admin, portal, profile, and operational surfaces."
    },
    {
      "title": "Design System Repo",
      "level": 2,
      "body": "```json\n{\n  \"note\": \"Separate checkout created on 2026-05-07. This is the B2BEA design-system source; Lovable remains only the original foundation/reference.\",\n  \"repo_url\": \"https://github.com/b2bea-org/b2bea-org-design-system.git\",\n  \"human_brief\": \"design.md\",\n  \"current_head\": \"d83614a\",\n  \"source_files\": [\n    \"b2bea.css\",\n    \"b2bea.design.json\",\n    \"design-system.json\",\n    \"design.md\",\n    \"examples/standard-page.html\",\n    \"recipes/standard-public-page.md\",\n    \"designer-review/design-board.html\",\n    \"designer-review/component-state-matrix.md\",\n    \"designer-review/page-family-checklist.md\",\n    \"checks/audit-b2bea.js\",\n    \"logos/\"\n  ],\n  \"canonical_css\": \"b2bea.css\",\n  \"repo_local_path\": \"/Users/justinking/Vaults/Projects/b2bea-org-design-system\",\n  \"pattern_reference\": \"/Users/justinking/Vaults/Projects/dreamborn-design-system\",\n  \"machine_readable_files\": [\n    \"design-system.json\",\n    \"b2bea.design.json\"\n  ],\n  \"local_repo_path_windows\": \"C:/Users/jstnk/Downloads/cc/projects/b2bea/b2bea-org-design-system\",\n  \"local_repo_path_mac_legacy\": \"/Users/justinking/Vaults/Projects/b2bea-org-design-system\"\n}\n```"
    },
    {
      "title": "Implementation Notes",
      "level": 2,
      "body": "- Target CSS should collapse compatibility selectors into reusable component classes during rebuild.\n- B2BEA design-system tokens should be the design-token source before page-specific CSS is authored; Lovable tokens are only the initial foundation/reference.\n- Legacy CSS can remain temporarily but must not define new target behavior.\n- Custom HTML imports can be visually custom but still must consume page metadata, analytics, and accessibility rules."
    }
  ],
  "html_path": "artifacts/2026-05-07-b2bea-org-design-system-spec-v4-ac02bceb81.html",
  "json_path": "artifacts/2026-05-07-b2bea-org-design-system-spec-v4-ac02bceb81.json"
}