Design System

Durable document (designated Session 370, 2026-07-13). The 4th of the four canonical project documents per the Hub methodology [[10-Three-Document-Product-Canon]] (~/Documents/ Claude/Vaults/The Hub/25 Methodology/10-Three-Document-Product-Canon.md). This is the Design System - it answers "what is the visual + interaction language the product is built in?" and is the canonical entry point the other three documents point to for the skin. Version: v1.0 (first authoring; documents the shipped skin reconciled against packages/ui and the crown-bees-design brand authority). Current shipped-skin coordinates: btt-server v61, client EAS build 24, product main 69ed4b5. Living copy: this file. Dated, version-stamped snapshots under documents/snapshots/. Companions: As-Built (as-built-spec.md - what is live), UX Flow Atlas (ux-flow-atlas.md - the desired experience per persona per flow), and To Build (next-build-spec.md - what we build next). Shape: reference-hub, not a copy. This document summarizes the design system faithfully and points to the authoritative sources (Section 8). It deliberately does NOT duplicate the token files or component source - those live once, in the skill and the code, and copying them here would create a drift surface. Reproduce from the authoritative sources named below; never re-draw from memory.

STATUS: APPROVED - canon (2026-07-15). All Design System items in this document are the settled canon baseline - the shipped skin, confirmed by Scott with Dave and Kellie (discussed 2026-07-13). Changes are tracked deltas against this baseline. The Section 8 known-drift items are accepted as-is (documented, not blocking). This is a canon document (unlike the To Build Spec and UX Flow Atlas, which remain DRAFT until further work locks); the product is still ~60-80% complete overall, so the DS may yet gain net-add components, but its current items are settled.

IP notice. The design system is the Crown Bees brand - the sole IP of Dave Hunter / Crown Bees, LLC. The crown-bees-design skill's own notice governs: *"(c) 2026 Dave Hunter / Crown Bees, LLC. All rights reserved. Confidential - not for distribution. Produced by Scott Sands (advisor) and Claude under Scott's direction, on behalf of Dave Hunter / Crown Bees, LLC. No IP claim by Scott Sands or Claude."* The Bee Team's combined IP is the app that implements this brand, per IP-NOTICE.md - not the brand itself. When BT extends the DS with app-specific components (the @btt/ui net-adds), those components are combined BT work product built in the Crown Bees brand.

The design system exists authoritatively in two layers, and they can drift. This document's first job is to name them and the rule between them.

The rule. The brand design authority governs *intent*; packages/ui governs *what is live*. Where a shipped value differs from the brand authority, that is a drift to reconcile - the implemented value is what the user sees (and so what the As-Built records), while the brand authority states what it should be. Known drift is listed in Section 8 so neither layer is read as complete on its own. New work reproduces from both: the brand authority for the rules and voice, packages/ui for the exact shipped tokens and component APIs.

Building a new screen is compose-from-the-kit, not a reskin: the live app skin already is this design system.

Two brand colors carry everything. Green is frame / heading / structure; orange is the only call-to-action color, used sparingly so it always reads as "do this."

Semantic status trio (GO / WAIT / HOLD): success green #28a745 (--cb-success / colors.success), warning amber #eb9247 (--cb-warning / colors.warning), alert red #e95050 (--cb-red / colors.red). Red also carries "sale."

Warm neutrals (never cold grey): text #222222, muted #6b6760, soft #888888, white surface #ffffff, page field #f8f8f8, cream highlight #fdf6e6, hairline border #e6e3dd, faint divider #f0ede6. (Code tokens: colors.text / textMuted / textSoft / bg / bgSoft / bgCream / border / borderSoft.)

IP / confidentiality band palette (always-on notices): parchment #fdf6e3 (--ip-bg), brown text #6b5a2c (--ip-text), gold border #ecd9a3 (--ip-border).

Status-pill tints (pale bg + saturated text), via pillTints in code:

Chart accent palette (added S209 / S242; implemented in colors.ts, see Section 8 drift note): clay #bd6b43 (early-tier / harvest / temp) + claySoft #f4e6dc; sage #74886b (mid-tier / Summer Leaf) + sageSoft #eef2e9; sky #2c5fa3 (late-tier / threshold / GDD) + skySoft #e6f0f7 / skyBorder #cfe0ee; plum #7a5ea8 (Huckleberry).

A single family: Inter (weights 400-800), loaded via @expo-google-fonts/inter in the app and Google Fonts in the skill. System-mono fallback (SF Mono, Menlo, Consolas) for code / labels only. No serif in the live app.

Font-family tokens (fontFamily in typography.ts): Inter_400Regular, Inter_500Medium, Inter_600SemiBold, Inter_700Bold, Inter_800ExtraBold.

Scale (size / weight / tracking), from fontSize + fontWeight + letterSpacing:

Display is tight and heavy; body is comfortable at 15/1.5.

• Spacing (4px base, sparse map - reproduce the exact keys), spacing token:

1:4 / 2:8 / 3:12 / 4:16 / 6:24 / 8:32 / 12:48.

• Radii, radii token: default 10, lg 14 (cards / heroes / banners), xl 20, pill 999.
• Elevation: exactly one shadow in the system - the sticky header

0 1px 4px rgba(0,0,0,0.08) (shadows.header, platform-aware via Platform.select). Cards carry NO shadow - a 1px warm border + 14px radius does the separating.

• Layout: content capped at 980px centered, 16px side gutters (--max-width / --gutter).
• Motion (minimal, quick): screen fade-in 0.18s ease (opacity 0->1, translateY 4px->0);

hover / press 0.12s ease; progress-bar width 0.4s. No bounces, loops, or parallax.

• Signature gradients (the only two): the welcome hero `linear-gradient(135deg, green ->

green-light) and the GDD progress bar linear-gradient(90deg, green -> orange)`. Everything else is a flat fill - no photography, textures, or patterns.

The implemented library lives at packages/ui/src/; import from @btt/ui. Each has a test in __tests__/. Compose screens from these; a component not already here is a net-add (flag it).

Primitives:

• Button - variants primary / outline / outlineOnDark / secondary / ghost / green / heroLight;

sizes sm / md / lg. Hover darkens to the -dark token; disabled = 0.5 opacity.

• Pill - 5 tones (Section 2 tints); toPillLabel Title-Cases + strips punctuation, all-caps

tokens survive. GO / WAIT / HOLD is DecisionBanner, not a Pill.

• Card - white fill, 1px warm border, 14px radius, no shadow; padding default 24 / tight 16.
• Typography - the Section 3 variant scale.
• DecisionBanner - the large, full-color GO / WAIT / HOLD banner (the app's most saturated

surface, reserved for the daily release call). Distinct from Pill.

• TopProgressBar - the top loading line = the header's idle orange underline.

Content components: Hero, DetailHero, StepCard, KvList, GddBar, PlantCard, AddPlantCard, AdviceItem, KnowledgeCard, BloomConfirmRow, AlertFeedRow, SpeciesAccordion, ActionDetailSheet, WeeklyTipSheet, TodayWeatherCard, WeatherGrid, HomeSummaryCards.

Charts (packages/ui/src/charts/): ChartFrame, GddYearChart, PollenGauge, VarietyTimelineChart, TempActiveBeesChart, BlossomWindowsChart (+ gdd-geometry / scale helpers).

Chrome (app-level, in apps/client, built on the kit):

• SiteHeader - green #004322 app bar on every signed-in screen: orange-bee CROWNBEES

wordmark -> Home, notifications bell -> Advice (orange unread badge), avatar -> Profile, a 3px orange bottom line (TopProgressBar). Mobile below 980px; horizontal nav row at/above 980px.

• BottomTabBar - white, mobile-only, five slots: **Home / Weather / [center orange "Ask" FAB]

/ Yard / Advice**. The FAB (54x54, orange, floating) is the Rep-AI "Ask" entry point (BT-062).

Voice (from the prototype's copy): warm, plain-spoken, confidence-building - an expert gardener, never a marketer.

• Second person, possessive: "your garden", "your bees", My Plants, your Crown Bees

cart. The app speaks as "we" (Crown Bees).

• Sentence case for body and most headings. The three decision verbs GO / WAIT / HOLD are

the only shouted words (plus all-caps status pills like BLOOM ACTIVE). Nav labels are Title Case ("My Plants", "Weather & Bees").

• Action-oriented: every screen reduces to a clear next action. Domain terms (Growing Degree

Days, cocoons, hatchery) always paired with a plain consequence.

• Concrete numbers, no vague intensifiers. Contractions used freely.

Iconography = emoji, used functionally (never decoratively). No SVG / icon-font / line-icon set - introducing one (Lucide / Heroicons / etc.) breaks from the source; flag if a true icon is unavoidable.

• Plant glyphs: apple, pear, cherry, blueberry, peach, strawberry / raspberry, almond / nut,

garden flowers.

• Status / weather: check (pass / GO), cross (fail), hourglass (wait), shield (guard), sprout,

bee, bird, and the sun / cloud / rain forecast set.

• Keep new emoji at the same functional scale (22-36px).

The mark: an apple / berry (a fruit body with two leaves holding seven seeds, one a bee) locked up with the CROWNBEES wordmark (CROWN green, BEES orange). Current selection is "Option 2" - a solid orange-disc bee (full color) / negative-space ring (reversed). Official artwork lives in assets/logos/; never recolor or rebuild it.

Logo color note: the logo's orange is the artwork's own gold-orange #F0A010 - intentionally a hair warmer than the UI action orange #e69100. Keep the logo's built-in orange; do not recolor it to the UI token. Clear space = the height of the "C" in CROWNBEES on all sides. Minimum ~120px wide (horizontal) / ~90px tall (vertical) on screen. For infinite-scale print, request the original vector from Crown Bees. Full rules: LOGO.md.

IP / confidentiality band appears on every brand surface and MUST stay visible: *"(c) 2026 Dave Hunter / Crown Bees, LLC. All rights reserved. Confidential - not for distribution."* Rendered in the parchment / brown / gold IP palette (Section 2). Blocks in assets/ip-notice.html.

Point here for exhaustive detail; reproduce from these, never from memory:

Known drift between the two layers (the implemented layer leads the brand-authority layer; reconcile when the DS is next revised):

1. Radii xl:20. packages/ui radii carries an xl: 20 step the skill's colors_and_type.css

does not list (skill has default 10 / lg 14 / pill 999). xl:20 is shipped and canonical.

1. Chart accent palette. colors.ts carries the clay / sage / sky / plum chart accents (+ their

soft tints, skyBorder) added S209 / S242; colors_and_type.css does not yet carry them. They are shipped, documented in THE-BUILD-SPEC Appendix A, and canonical - not yet back-ported to the skill CSS.

Neither drift is a defect in the app; both are the brand-authority CSS lagging shipped additions. A future DS revision should back-port them into the skill so the two layers reconcile.

This document carries its own version, decoupled from product semver. The As-Built version tracks production (it changes on every build); the design system changes far less often - only when the DS itself changes (a new token, a new @btt/ui component, a palette or type shift). So the DS version bumps on DS changes, and the shipped-skin coordinates (server release, client build, commit) are pinned in the header for reference at authoring time.

v1.0 - first authoring, Session 370 (2026-07-13). Reference-hub over the two authoritative layers, reconciled against packages/ui at product main 69ed4b5 and the crown-bees-design skill. Shipped-skin coordinates: btt-server v61, client EAS build 24.

Provenance. The design system was extracted from the Crown Bees Pollination Success App v0.1 prototype (~/Documents/Claude/Vaults/Crown Bees/Crown-Bees-Pollination-App/prototype/index.html) into the crown-bees-design skill, then implemented in packages/ui. This document consolidates the As-Built Section 4 skin summary and the THE-BUILD-SPEC Appendix A reference into the canonical DS entry point, per Scott's Session 369 direction that the Design System become the 4th canon document. It is a reference-hub (Option A), not a copy - the token files and component source remain the single source of truth in the skill and the code.

*Design System v1.0 - The Bee Team. The 4th canonical product document per the Hub Three-Document Product Canon methodology (expanded to four at Session 369-370). The design system is the Crown Bees brand (Dave Hunter / Crown Bees, LLC sole IP); the app that implements it is combined BT IP. Reference-hub over two authoritative layers - the crown-bees-design brand skill (intent) and packages/ui (what ships). Change history lives in git + the LMA records + the dated snapshots, never this footer.*